draft-07 hay 2020-12
Kết luận: 2020-12 là bản hiện hành và bổ sung $defs, prefixItems cùng unevaluatedProperties, nhưng nhiều công cụ vẫn chỉ nói draft-07. Hãy chọn theo những gì toàn bộ chuỗi công cụ của bạn hỗ trợ.
Tóm lại: dùng 2020-12 cho dự án mới, quay về draft-07 ngay khi có validator, trình sinh mã hay công cụ OpenAPI nào chỉ hỗ trợ nó, và luôn ghim bản nháp bằng $schema.
Trả lời ngắn: 2020-12 cho công việc mới, draft-07 khi một thành phần cũ buộc phải vậy.
Dòng thời gian
| Bản nháp | Năm | Đáng chú ý |
|---|---|---|
| draft-04 | 2013 | id thay cho $id; vẫn phổ biến ở các API cũ |
| draft-06 | 2017 | const, propertyNames |
| draft-07 | 2018 | if/then/else, readOnly, contentMediaType; tương thích tốt nhất |
| 2019-09 | 2019 | $defs thay cho definitions, unevaluatedProperties |
| 2020-12 | 2020 | prefixItems, $dynamicRef; khuyến nghị hiện hành |
2020-12 cải thiện gì
Tuple mảng không còn là trường hợp đặc biệt. draft-07 diễn đạt "phần tử đầu là A, phần tử hai là B" bằng items: [{...}, {...}] kèm additionalItems. 2020-12 dùng prefixItems cho schema theo vị trí và items cho phần còn lại.
$defs là tên chuẩn. Công cụ viết sau năm 2019 mặc định tìm ở đó.
unevaluatedProperties hoạt động với composition. Với allOf, additionalProperties: false sẽ từ chối những trường được định nghĩa bởi các nhánh anh em. unevaluatedProperties: false chỉ xét những thuộc tính thực sự được toàn bộ schema đánh giá, đúng với nhu cầu của composition.
Khi nào draft-07 là câu trả lời đúng
| Tình huống | Lý do |
|---|---|
| OpenAPI 3.0 | Đối tượng schema của nó là tập con của draft-04/07 |
| Validator cũ (ajv 6, một số thư viện Java) | Chúng không biết prefixItems hay $dynamicRef |
| Nền tảng áp đặt một phiên bản | Một số nền tảng low-code và gateway ghim nó |
| Trình sinh mã dừng ở bản 07 | Từ khóa lạ bị bỏ qua mà không báo |
Hãy kiểm tra trực tiếp trường hợp cuối: đưa một schema dùng prefixItems cho validator của bạn. Nếu nó chấp nhận mà không phàn nàn thay vì báo từ khóa không xác định, thì nó đang bỏ qua ràng buộc — kết quả nguy hiểm nhất trong tất cả.
Trộn các phiên bản
Luôn khai báo $schema. Giá trị mặc định khác nhau: ajv giả định draft-07, một số thư viện Python giả định 2020-12. Cùng một tệp khi đó sẽ validate khác nhau ở hai nơi.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/order.json",
"type": "object"
}
Đừng $ref xuyên các bản nháp. Hành vi là không xác định.
Nâng cấp theo lô. Hai bản nháp trong một repository biến "quy tắc nào áp dụng ở đây" thành kiến thức truyền miệng.
Câu hỏi thường gặp
Làm sao kiểm tra validator của tôi có hỗ trợ 2020-12 không?
Đưa một schema dùng prefixItems cho validator. Lỗi từ khóa không xác định nghĩa là nó không hỗ trợ bản nháp; chấp nhận mà không báo gì nghĩa là nó đang bỏ qua ràng buộc, điều này còn tệ hơn.
Vì sao một dự án nên dùng một bản nháp duy nhất?
Hai bản nháp trong một repository biến "quy tắc nào áp dụng ở đây" thành kiến thức truyền miệng. Hãy nâng cấp theo lô để mọi tệp chia sẻ cùng một cách hiểu.
Tôi có nên luôn khai báo $schema không?
Có. Giá trị mặc định khác nhau: ajv giả định draft-07 còn một số thư viện Python giả định 2020-12, nên cùng một tệp có thể validate khác nhau ở hai nơi.