Cách tạo JSON Schema
- Dán một ví dụ JSON tiêu biểu. Mảng có nhiều phần tử cho kết quả tốt nhất, vì các phần tử của nó được gộp lại thành một schema.
- Chọn phiên bản schema (draft 2020-12 hoặc draft-07) và quyết định có đánh dấu thuộc tính là bắt buộc, nhận diện định dạng và không cho phép thuộc tính thừa hay không.
- Sao chép hoặc tải schema về, sau đó tinh chỉnh thủ công – ví dụ thêm mô tả, enum hoặc giá trị minimum và maximum.
Công cụ suy ra những gì từ JSON
| Ví dụ JSON | Schema |
|---|---|
"ada@example.com" | {"type": "string", "format": "email"} |
"2026-05-01T10:00:00Z" | định dạng date-time (cả date, time, uri, uuid, ipv4) |
42 / 4.5 | "integer" / "number" |
| khóa có mặt trong mọi đối tượng | được liệt kê trong required |
| khóa bị thiếu ở một số phần tử mảng | tùy chọn (không có trong required) |
[1, "a", null] | "items": {"type": ["string", "integer", "null"]} |
| đối tượng lẫn với giá trị đơn | anyOf với một schema cho mỗi loại |
JSON Schema là gì?
JSON Schema là một bộ từ vựng dùng để mô tả và kiểm tra cấu trúc của dữ liệu JSON: có những thuộc tính nào, mỗi thuộc tính thuộc kiểu gì, thuộc tính nào bắt buộc và giá trị nào được phép. Nó được dùng cho hợp đồng API trong OpenAPI, file cấu hình, tạo biểu mẫu tự động và kiểm tra đầu ra có cấu trúc của các mô hình AI. Phiên bản hiện tại là 2020-12; draft-07 vẫn được nhiều công cụ cũ hỗ trợ. Đặc tả được công bố tại json-schema.org.
Tinh chỉnh schema đã tạo
- Thêm
titlevàdescriptionđể ghi chú ý nghĩa của từng trường. - Giới hạn giá trị bằng
enum,minimum,maximum,maxLengthhoặcpattern. - Đánh dấu Không cho phép thuộc tính thừa (
additionalProperties: false) để từ chối các khóa lạ. - Kiểm tra dữ liệu bằng Ajv trong JavaScript hoặc gói
jsonschematrong Python.
Câu hỏi thường gặp
Nên dùng phiên bản JSON Schema nào?
Hãy dùng draft 2020-12 cho dự án mới – đây là phiên bản hiện hành và là nền tảng của OpenAPI 3.1. Chọn draft-07 nếu trình kiểm tra hoặc công cụ của bạn chưa hỗ trợ 2020-12.
Tại sao mọi thuộc tính của tôi đều là bắt buộc?
Với chỉ một đối tượng mẫu, mọi thuộc tính đều có mặt nên tất cả đều được đánh dấu là bắt buộc. Hãy dùng một mảng gồm nhiều ví dụ khác nhau, hoặc tắt Đánh dấu thuộc tính là bắt buộc.
Công cụ có nhận diện được enum hoặc khoảng giá trị không?
Không. Một ví dụ không thể cho biết nói chung những giá trị nào được phép, nên enum, giá trị minimum, maximum và pattern phải được thêm thủ công.
Làm sao để kiểm tra JSON theo schema?
Hãy dùng thư viện kiểm tra như Ajv cho JavaScript hoặc jsonschema cho Python. Nhiều trình soạn thảo code cũng tự kiểm tra file JSON theo schema được tham chiếu trong thuộc tính $schema của nó.