draft-07 ou 2020-12
L’essentiel : 2020-12 est la version courante et ajoute $defs, prefixItems et unevaluatedProperties, mais beaucoup d'outils ne parlent encore que draft-07. Choisissez selon ce que toute votre chaîne d'outils prend en charge.
L'essentiel : utilisez 2020-12 pour les nouveaux projets, repassez à draft-07 dès qu'un validateur, générateur de code ou outil OpenAPI ne le prend en charge que lui, et épinglez toujours le draft avec $schema.
Réponse courte : 2020-12 pour les nouveaux travaux, draft-07 quand un vieux composant l'impose.
Chronologie
| Draft | Année | Notable |
|---|---|---|
| draft-04 | 2013 | id au lieu de $id ; encore courant dans les anciennes API |
| draft-06 | 2017 | const, propertyNames |
| draft-07 | 2018 | if/then/else, readOnly, contentMediaType ; meilleure compatibilité |
| 2019-09 | 2019 | $defs remplace definitions, unevaluatedProperties |
| 2020-12 | 2020 | prefixItems, $dynamicRef ; recommandation actuelle |
Ce que 2020-12 améliore
Les tuples de tableau cessent d'être un cas spécial. draft-07 exprime « le premier élément est A, le second est B » avec items: [{...}, {...}] plus additionalItems. 2020-12 utilise prefixItems pour les schémas spécifiques à la position et items pour le reste.
$defs est le nom standard. L'outillage écrit après 2019 regarde là par défaut.
unevaluatedProperties fonctionne avec la composition. Avec allOf, additionalProperties: false rejette les champs définis par des branches sœurs. unevaluatedProperties: false ne considère que les propriétés réellement évaluées par tout le schéma, ce dont la composition a besoin.
Quand draft-07 est la bonne réponse
| Situation | Raison |
|---|---|
| OpenAPI 3.0 | Son objet de schéma est un sous-ensemble draft-04/07 |
| Validateurs plus anciens (ajv 6, certaines bibliothèques Java) | Ils ne connaissent pas prefixItems ni $dynamicRef |
| Une plateforme impose une version | Certaines plateformes low-code et passerelles l'épinglent |
| Générateurs de code qui s'arrêtent à 07 | Les mots-clés inconnus sont ignorés silencieusement |
Testez le dernier cas directement : donnez un schéma prefixItems à votre validateur. S'il passe sans se plaindre au lieu de rapporter un mot-clé inconnu, il ignore la contrainte — le résultat le plus dangereux de tous.
Mélanger les versions
Déclarez toujours $schema. Les défauts diffèrent : ajv suppose draft-07, plusieurs bibliothèques Python supposent 2020-12. Le même fichier valide alors différemment à deux endroits.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/order.json",
"type": "object"
}
Ne faites pas de $ref entre drafts. Le comportement est indéfini.
Mettez à niveau par lots. Deux drafts dans un même dépôt transforment « quelles règles s'appliquent ici » en connaissance tribale.
FAQ
Comment vérifier si mon validateur prend en charge 2020-12 ?
Donnez un schéma qui utilise prefixItems au validateur. Une erreur de mot-clé inconnu signifie qu'il ne prend pas en charge le draft ; passer silencieusement signifie qu'il ignore la contrainte, ce qui est pire.
Pourquoi un projet devrait-il utiliser un seul draft ?
Deux drafts dans un même dépôt transforment « quelles règles s'appliquent ici » en connaissance tribale. Mettez à niveau par lots pour que chaque fichier partage la même interprétation.
Faut-il toujours déclarer $schema ?
Oui. Les défauts diffèrent : ajv suppose draft-07 tandis que plusieurs bibliothèques Python supposent 2020-12, donc le même fichier peut valider différemment à deux endroits.