draft-07, nebo 2020-12
Shrnutí: 2020-12 je aktuální a přidává `$defs`, `prefixItems` a `unevaluatedProperties`, ale mnoho nástrojů stále umí jen draft-07. Vybírejte podle toho, co podporuje celý váš nástrojový řetězec.
Stručně: pro nové projekty použijte 2020-12, přepněte se na draft-07 ve chvíli, kdy jakýkoli validátor, generátor kódu nebo nástroj OpenAPI podporuje jen ten, a vždy zafixujte návrh pomocí $schema.
Krátká odpověď: 2020-12 pro novou práci, draft-07, když to vynutí stará složka.
Časová osa
| Návrh | Rok | Pozoruhodné |
|---|---|---|
| draft-04 | 2013 | id místo $id; stále běžný ve starších API |
| draft-06 | 2017 | const, propertyNames |
| draft-07 | 2018 | if/then/else, readOnly, contentMediaType; nejlepší kompatibilita |
| 2019-09 | 2019 | $defs nahrazuje definitions, unevaluatedProperties |
| 2020-12 | 2020 | prefixItems, $dynamicRef; aktuální doporučení |
Co 2020-12 zlepšuje
N-tice polí přestávají být speciálním případem. draft-07 vyjadřuje „první prvek je A, druhý je B“ pomocí items: [{...}, {...}] plus additionalItems. 2020-12 používá prefixItems pro schémata specifická podle pozice a items pro zbytek.
$defs je standardní název. Nástroje psané po roce 2019 tam hledají ve výchozím nastavení.
unevaluatedProperties funguje s kompozicí. S allOf odmítne additionalProperties: false pole definovaná sourozeneckými větvemi. unevaluatedProperties: false uvažuje jen vlastnosti skutečně vyhodnocené celým schématem, což je přesně to, co kompozice potřebuje.
Kdy je draft-07 správnou odpovědí
| Situace | Důvod |
|---|---|
| OpenAPI 3.0 | Jeho objekt schématu je podmnožinou draft-04/07 |
| Starší validátory (ajv 6, některé Java knihovny) | Neznají prefixItems ani $dynamicRef |
| Platforma nařizuje verzi | Některé low-code platformy a brány ji zafixují |
| Generátory kódu, které končí u 07 | Neznámá klíčová slova se tiše ignorují |
Poslední případ otestujte přímo: předejte validátoru schéma s prefixItems. Pokud projde bez stížnosti, místo aby nahlásil neznámé klíčové slovo, omezení ignoruje – což je nejnebezpečnější výsledek ze všech.
Míchání verzí
Vždy deklarujte $schema. Výchozí hodnoty se liší: ajv předpokládá draft-07, několik Python knihoven předpokládá 2020-12. Stejný soubor se pak na dvou místech validuje odlišně.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/order.json",
"type": "object"
}
Nedělejte $ref napříč návrhy. Chování je nedefinované.
Upgradujte v dávkách. Dva návrhy v jednom repozitáři mění „která pravidla tady platí“ v kmenové znalosti.
Časté dotazy
Jak zjistit, zda můj validátor podporuje 2020-12?
Předejte validátoru schéma, které používá prefixItems. Chyba neznámého klíčového slova znamená, že návrh nepodporuje; tiché projítí znamená, že omezení ignoruje, což je horší.
Proč má jeden projekt používat jediný návrh?
Dva návrhy v jednom repozitáři mění „která pravidla tady platí“ v kmenové znalosti. Upgradujte v dávkách, aby každý soubor sdílel stejnou interpretaci.
Mám vždy deklarovat $schema?
Ano. Výchozí hodnoty se liší: ajv předpokládá draft-07, zatímco několik Python knihoven předpokládá 2020-12, takže stejný soubor se na dvou místech může validovat odlišně.