draft-07 o 2020-12
In sintesi: 2020-12 è quella attuale e aggiunge $defs, prefixItems e unevaluatedProperties, ma molti strumenti parlano ancora solo draft-07. Scegli in base a ciò che supporta l'intera toolchain.
In sintesi: usa 2020-12 per i nuovi progetti, torna a draft-07 nel momento in cui qualsiasi validatore, generatore di codice o strumento OpenAPI supporta solo quello, e fissa sempre il draft con $schema.
Risposta breve: 2020-12 per i nuovi lavori, draft-07 quando un componente vecchio lo impone.
Cronologia
| Draft | Anno | Notevole |
|---|---|---|
| draft-04 | 2013 | id invece di $id; ancora comune nelle API più vecchie |
| draft-06 | 2017 | const, propertyNames |
| draft-07 | 2018 | if/then/else, readOnly, contentMediaType; migliore compatibilità |
| 2019-09 | 2019 | $defs sostituisce definitions, unevaluatedProperties |
| 2020-12 | 2020 | prefixItems, $dynamicRef; raccomandazione attuale |
Cosa migliora 2020-12
Le tuple degli array smettono di essere un caso speciale. draft-07 esprime "il primo elemento è A, il secondo è B" con items: [{...}, {...}] più additionalItems. 2020-12 usa prefixItems per gli schema specifici per posizione e items per il resto.
$defs è il nome standard. Gli strumenti scritti dopo il 2019 lo cercano lì per impostazione predefinita.
unevaluatedProperties funziona con la composizione. Con allOf, additionalProperties: false rifiuta i campi definiti dai rami sorelli. unevaluatedProperties: false considera solo le proprietà davvero valutate dall'intero schema, che è ciò di cui la composizione ha bisogno.
Quando draft-07 è la risposta giusta
| Situazione | Motivo |
|---|---|
| OpenAPI 3.0 | Il suo oggetto schema è un sottoinsieme di draft-04/07 |
| Validatori più vecchi (ajv 6, alcune librerie Java) | Non conoscono prefixItems o $dynamicRef |
| La piattaforma impone una versione | Alcune piattaforme low-code e gateway la fissano |
| Generator di codice che si fermano al 07 | Le parole chiave sconosciute vengono ignorate silenziosamente |
Testa direttamente l'ultimo caso: passa uno schema prefixItems al tuo validatore. Se passa senza lamentarsi invece di segnalare una parola chiave sconosciuta, sta ignorando il vincolo — l'esito più pericoloso di tutti.
Mescolare le versioni
Dichiara sempre $schema. I default differiscono: ajv assume draft-07, diverse librerie Python assumono 2020-12. Lo stesso file quindi si valida diversamente in due posti.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/order.json",
"type": "object"
}
Non fare $ref tra draft diversi. Il comportamento è indefinito.
Aggiorna a lotti. Due draft in un repository trasformano "quali regole si applicano qui" in conoscenza tribale.
FAQ
Come verifico se il mio validatore supporta 2020-12?
Passa al validatore uno schema che usa prefixItems. Un errore di parola chiave sconosciuta significa che non supporta il draft; il passaggio silenzioso significa che sta ignorando il vincolo, il che è peggio.
Perché un progetto dovrebbe usare un unico draft?
Due draft in un repository trasformano "quali regole si applicano qui" in conoscenza tribale. Aggiorna a lotti così ogni file condivide la stessa interpretazione.
Devo dichiarare sempre $schema?
Sì. I default differiscono: ajv assume draft-07 mentre diverse librerie Python assumono 2020-12, quindi lo stesso file può validarsi diversamente in due posti.