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 toujours $schema pour que les validateurs sachent quelle version vous ciblez. Ajoutez des champs description — ils deviennent de la documentation API en direct. Préférez format (email, uri) aux expressions régulières faites maison. Utilisez additionalProperties: false pour les API strictes, mais autorisez-le lorsque l'extensibilité compte. Évitez les schémas profondément imbriqués — 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, pas un contrat terminé.
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.