Validation JSON Schema : guide complet des drafts et regles

Qu'est-ce que JSON Schema ?

JSON Schema est un vocabulaire pour annoter et valider des documents JSON. Il définit la structure, les types et les contraintes qu'un document JSON doit respecter. Considérez-le comme un contrat — le schéma décrit à quoi ressemblent des données valides, et les validateurs vérifient si un document est conforme à ce contrat.

JSON Schema est écrit en JSON lui-même, ce qui le rend lisible par les machines et indépendant du langage. Il est pris en charge par des validateurs dans tous les principaux langages de programmation (JavaScript/Ajv, Python/jsonschema, Java/everit, Go/gojsonschema) et est utilisé pour la validation d'API, les fichiers de configuration et la génération de formulaires.

Bases de JSON Schema

Les mots-clés fondamentaux définissent la structure des documents JSON valides.

• type — spécifie le type JSON autorisé : string, number, integer, boolean, object, array ou null. La contrainte la plus fondamentale.
• properties et required — pour les objets, « properties » définit le schéma de chaque champ et « required » liste les champs obligatoires. Les champs absents de « required » sont facultatifs par défaut.
• enum et const — « enum » restreint une valeur à un ensemble fixe de choix, tandis que « const » la restreint à une seule valeur exacte. Utile pour les champs de statut, les catégories et les options de configuration.
• pattern et format — « pattern » valide les chaînes avec une expression régulière. « format » fournit une validation sémantique comme « email », « uri », « date-time » et « ipv4 » sans regex.

Ces mots-clés de base couvrent la plupart des besoins de validation. Un schéma simple peut définir un type objet avec une propriété « name » (string) obligatoire et une propriété optionnelle « age » (integer, minimum 0).

Fonctionnalités avancées du schéma

Pour les exigences de validation complexes, JSON Schema propose la composition, les références et la logique conditionnelle.

• $ref références — réutilisez les définitions de schéma en les référençant avec $ref. Pointez vers des définitions dans le même document ($ref: #/$defs/Address) ou des fichiers externes. Élimine les doublons dans les grands schémas.
• allOf / anyOf / oneOf — mots-clés de composition qui combinent plusieurs schémas. « allOf » exige que tous les sous-schémas correspondent, « anyOf » en exige au moins un, et « oneOf » en exige exactement un. Utile pour les types polymorphes.
• if / then / else — schémas conditionnels qui appliquent différentes règles de validation selon les valeurs des données. Par exemple, si le pays est « US », le code postal doit correspondre à un modèle à 5 chiffres, sinon tout format est autorisé.
• additionalProperties — contrôle si un objet peut contenir des propriétés non listées dans « properties ». Définissez sur false pour une validation stricte ou sur un schéma pour contraindre les propriétés supplémentaires.

Versions du brouillon de schéma

JSON Schema a évolué à travers plusieurs versions de brouillon, chacune ajoutant de nouvelles fonctionnalités et affinant le comportement existant.

• Draft-04 — la première version largement adoptée. A introduit $ref, required en tant que tableau et les mots-clés de validation de base. Encore utilisé dans de nombreux systèmes legacy et OpenAPI 3.0.
• Draft-06 — a ajouté le mot-clé const, propertyNames, contains pour les tableaux et les schémas booléens (true/false comme schémas valides). Des ajouts mineurs mais utiles.
• Draft-07 — a ajouté la logique conditionnelle if/then/else, les annotations readOnly/writeOnly et les mots-clés d'encodage de contenu. La version de brouillon la plus populaire aujourd'hui.
• 2019-09 (Draft 2019-09) — restructuration majeure. A introduit $defs (remplaçant definitions), $anchor, unevaluatedProperties et le système de vocabulaire. Mieux adapté à la conception de schémas à grande échelle.
• 2020-12 (Draft 2020-12) — le dernier brouillon stable. Références dynamiques affinées, prefixItems ajouté pour la validation de tuples (remplaçant items en tant que tableau) et formats de sortie améliorés. Recommandé pour les nouveaux projets.

Cas d'utilisation courants

JSON Schema est utilisé partout où des données JSON doivent être validées ou documentées.

• Validation d'API — validez les corps de requête et les paramètres de requête par rapport aux schémas dans le middleware Express/Fastify. Les spécifications OpenAPI/Swagger intègrent JSON Schema pour la définition de contrats d'API.
• Validation de configuration — validez les fichiers de configuration d'application (JSON, YAML converti en JSON) au démarrage. Détectez les fautes de frappe et les champs manquants avant qu'ils ne causent des erreurs d'exécution.
• Génération de formulaires — des outils comme react-jsonschema-form et vue-jsonschema-form génèrent automatiquement des formulaires HTML à partir de définitions JSON Schema, incluant les règles de validation et les widgets UI.
• Génération de code — générez des interfaces TypeScript, des structs Go ou des dataclasses Python à partir de définitions JSON Schema. Maintient les types synchronisés avec les contrats d'API.

Erreurs de validation courantes

Lors de la validation de JSON par rapport à un schéma, voici les erreurs les plus fréquentes que vous rencontrerez.

• Incompatibilité de type — le type de la valeur ne correspond pas à la contrainte « type » du schéma. Exemples courants : string là où un number est attendu, null pour un champ non nullable, ou un objet là où un tableau est requis.
• Champs obligatoires manquants — l'objet JSON ne contient pas une propriété listée dans le tableau 'required'. Les validateurs signalent quel champ spécifique est absent.
• Échec du motif — une valeur de chaîne ne correspond pas à l'expression régulière 'pattern'. Cela détecte souvent les formats d'e-mail invalides, les numéros de téléphone ou les identifiants personnalisés qui ne suivent pas le motif attendu.
• Échec de résolution $ref — le schéma fait référence à un autre schéma via $ref qui ne peut pas être trouvé. Cela se produit lorsqu'une entrée $defs est manquante, que le chemin est incorrect ou que les fichiers de schéma externes ne sont pas accessibles.

Foire aux questions

Quel brouillon JSON Schema devrais-je utiliser pour les nouveaux projets ?

Utilisez Draft 2020-12 pour les nouveaux projets, sauf contraintes particulières. Il offre le plus de fonctionnalités (prefixItems pour les tuples, unevaluatedProperties, références dynamiques) et la meilleure qualité de spécification. Si vous avez besoin de la compatibilité OpenAPI 3.0, utilisez Draft-04. Pour la prise en charge la plus large des bibliothèques, Draft-07 est le choix le plus sûr — presque tous les validateurs le supportent.

Comment réutiliser des schémas dans plusieurs fichiers ?

Utilisez $ref pour référencer des schémas par URI. Pour les définitions locales, placez les schémas réutilisables sous $defs dans le même fichier et référencez-les avec $ref: '#/$defs/NomDuSchéma'. Pour les références inter-fichiers, utilisez des URI relatifs ($ref: './address.json') ou absolus. La plupart des validateurs supportent la résolution $ref locale et distante.

JSON Schema peut-il valider des objets imbriqués ?

Oui. Définissez des schémas imbriqués dans les 'properties' de l'objet parent. Chaque propriété imbriquée peut avoir son propre type, ses champs obligatoires et ses règles de validation. Pour les structures profondément imbriquées, utilisez $ref pour garder le schéma lisible. Il n'y a pas de limite à la profondeur d'imbrication — le validateur valide récursivement chaque niveau.