Le guide complet de JSON Schema (Draft 7)
JSON Schema est un contrat pour vos données : il déclare quelles propriétés doivent exister, quels types elles ont et quelles valeurs sont autorisées. Ce guide couvre les mots-clés essentiels de la Draft 7 avec un exemple d'API concret.
Qu'est-ce que JSON Schema ?
Un JSON Schema est lui-même un document JSON qui décrit la forme d'autres données JSON. Utilisez-le pour valider les charges utiles d'API, documenter les formats attendus, générer du code (TypeScript, Go) et intercepter les mauvaises données avant qu'elles n'atteignent votre logique métier.
Mots-clés essentiels
Le mot-clé type contraint une valeur à string, number, boolean, null, object ou array. properties et required décrivent la forme des objets ; items décrit les éléments des tableaux.
{
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1 },
"age": { "type": "number", "minimum": 0, "maximum": 150 },
"email": { "type": "string", "format": "email" }
},
"required": ["name", "email"]
}Au-delà de type : enum restreint à un ensemble fixe, const exige une valeur exacte, pattern correspond à une expression régulière, minLength/maxLength bornent la longueur des chaînes, et additionalProperties: false interdit les clés inconnues.
Un schéma d'API concret
Voici un schéma pour un point de terminaison d'enregistrement d'utilisateur. Remarquez comment chaque contrainte sert aussi de documentation, et comment required + additionalProperties: false rendent le contrat strict.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"username": { "type": "string", "pattern": "^[a-zA-Z0-9_]{3,30}$" },
"email": { "type": "string", "format": "email" },
"password": { "type": "string", "minLength": 8 },
"acceptTerms": { "type": "boolean", "const": true }
},
"required": ["username", "email", "password", "acceptTerms"],
"additionalProperties": false
}Bonnes pratiques
Déclarez $schema pour que les validateurs sachent quelle version vous ciblez. Ajoutez des champs description, que les éditeurs et la documentation d'API affichent. Préférez format (email, uri) aux expressions régulières maison. Utilisez additionalProperties: false pour les API strictes, et laissez-le ouvert quand l'extensibilité compte. N'imbriquez pas les schémas trop profondément ; factorisez avec $ref et definitions.
FAQ
- Quelle version de JSON Schema ce guide couvre-t-il ?
- La Draft 7, la version la plus largement prise en charge. Elle couvre type, properties, required, items, enum, const, minimum/maximum, minLength/maxLength, pattern, format, additionalProperties, minItems/maxItems et uniqueItems.
- TypeScript remplace-t-il JSON Schema ?
- Non. Les types TypeScript sont effacés à la compilation et n'offrent aucune validation à l'exécution. Pour les charges utiles d'API, utilisez JSON Schema (ou Zod) pour valider à l'exécution, et générez éventuellement les types TypeScript à partir de celui-ci.
- Puis-je générer automatiquement un schéma à partir de JSON ?
- Oui. Déduisez un schéma à partir de données d'exemple, puis affinez-le en ajoutant des contraintes (required, pattern, limites de longueur). La génération vous donne un point de départ, et il vous reste à finir le contrat.
Articles associés
Qu'est-ce que JSON ? Le guide complet pour débutants →
JSON (JavaScript Object Notation) est un format d'échange de données léger, facile à lire pour les humains et à analyser pour les machines. Apprenez la syntaxe, les types de données et la structure qui font tourner les API modernes.
L'histoire de JSON : de 2000 au standard de l'industrie →
Suivez JSON depuis l'idée de Douglas Crockford en 2001, en passant par son adoption par Yahoo, jusqu'à devenir le standard ECMA-404 qui fait tourner 90 % des API modernes.
Exemples JSON en 7 langages : JavaScript, Python, Go, Rust, PHP, Java, C# →
Des exemples prêts pour la production d'analyse et de sérialisation JSON dans sept langages, avec gestion des erreurs et bonnes pratiques.