draft-07 czy 2020-12
Podsumowanie: 2020-12 jest aktualne i dodaje $defs, prefixItems i unevaluatedProperties, ale wiele narzędzi nadal mówi tylko draft-07. Wybierz według tego, co wspiera cały twój łańcuch narzędzi.
Najważniejsze: używaj 2020-12 dla nowych projektów, wróć do draft-07 w momencie, gdy dowolny walidator, generator kodu lub narzędzie OpenAPI wspiera tylko niego, i zawsze przypnij draft przez $schema.
Krótka odpowiedź: 2020-12 dla nowej pracy, draft-07, gdy zmusza do tego stary komponent.
Kalendarium
| Draft | Rok | Wyróżnia się |
|---|---|---|
| draft-04 | 2013 | id zamiast $id; nadal częsty w starszych API |
| draft-06 | 2017 | const, propertyNames |
| draft-07 | 2018 | if/then/else, readOnly, contentMediaType; najlepsza zgodność |
| 2019-09 | 2019 | $defs zastępuje definitions, unevaluatedProperties |
| 2020-12 | 2020 | prefixItems, $dynamicRef; obecna rekomendacja |
Co poprawia 2020-12
Krotki tablic przestają być przypadkiem specjalnym. draft-07 wyraża „pierwszy element to A, drugi to B” przez items: [{...}, {...}] plus additionalItems. 2020-12 używa prefixItems dla schematów zależnych od pozycji, a items dla reszty.
$defs to standardowa nazwa. Narzędzia pisane po 2019 szukają tam domyślnie.
unevaluatedProperties działa z kompozycją. Przy allOf additionalProperties: false odrzuca pola zdefiniowane przez sąsiednie gałęzie. unevaluatedProperties: false rozważa tylko właściwości faktycznie ocenione przez cały schemat, czego potrzebuje kompozycja.
Kiedy draft-07 jest właściwą odpowiedzią
| Sytuacja | Powód |
|---|---|
| OpenAPI 3.0 | Jego obiekt schematu to podzbiór draft-04/07 |
| Starsze walidatory (ajv 6, część bibliotek Java) | Nie znają prefixItems ani $dynamicRef |
| Platforma wymusza wersję | Część platform low-code i bram pinuje ją |
| Generatory kodu kończące się na 07 | Nieznane słowa kluczowe są po cichu ignorowane |
Ostatni przypadek przetestuj bezpośrednio: podaj walidatorowi schemat z prefixItems. Jeśli przechodzi bez zastrzeżeń, zamiast zgłaszać nieznane słowo kluczowe, to ignoruje ograniczenie — najbardziej niebezpieczny wynik ze wszystkich.
Mieszanie wersji
Zawsze deklaruj $schema. Domyślności się różnią: ajv zakłada draft-07, kilka bibliotek Pythona zakłada 2020-12. Ten sam plik waliduje się wtedy inaczej w dwóch miejscach.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/order.json",
"type": "object"
}
Nie rób $ref między draftami. Zachowanie jest niezdefiniowane.
Aktualizuj partiami. Dwa drafty w jednym repozytorium zamieniają „które reguły tu obowiązują” w wiedzę plemienną.
FAQ
Jak sprawdzić, czy mój walidator wspiera 2020-12?
Podaj walidatorowi schemat używający prefixItems. Błąd nieznanego słowa kluczowego znaczy, że nie wspiera draftu; ciche przejście znaczy, że ignoruje ograniczenie, co jest gorsze.
Dlaczego jeden projekt powinien używać jednego draftu?
Dwa drafty w jednym repozytorium zamieniają „które reguły tu obowiązują” w wiedzę plemienną. Aktualizuj partiami, aby każdy plik dzielił tę samą interpretację.
Czy zawsze deklarować $schema?
Tak. Domyślności się różnią: ajv zakłada draft-07, a kilka bibliotek Pythona zakłada 2020-12, więc ten sam plik może walidować się inaczej w dwóch miejscach.