Comprendre JSON Schema : Validez vos données comme un pro

Avez-vous déjà eu un bug où votre API renvoyait "42" (une chaîne) au lieu de 42 (un nombre) et tout en aval cassait ? Ou quelqu'un a envoyé une requête sans un champ obligatoire et votre app a planté au lieu de renvoyer une erreur utile ? JSON Schema existe précisément pour prévenir ce genre de problèmes.

Pensez-y comme un plan pour vos données JSON — il décrit quelle forme les données doivent avoir et attrape tout ce qui ne correspond pas.

À quoi ressemble JSON Schema

JSON Schema est lui-même écrit en JSON (méta, non ?). Voici un schéma simple pour un objet utilisateur :

Cela dit : « J'attends un objet avec un name requis (chaîne non vide) et un email (format email valide), plus un age optionnel (entier entre 0 et 150). » Si quelqu'un envoie {"name": "", "email": "not-an-email"}, le validateur détectera les deux problèmes.

Construire des schémas étape par étape

Commencez par le type. Chaque schéma commence par "type" : object, array, string, number, integer, boolean ou null.

Ajoutez des contraintes. Pour les chaînes : minLength, maxLength, pattern (regex). Pour les nombres : minimum, maximum, multipleOf. Pour les tableaux : minItems, maxItems, uniqueItems. Le guide officiel JSON Schema a la liste complète.

Marquez les champs requis. Utilisez le tableau "required" au niveau objet. Ne listez que les champs qui doivent être présents — ne rendez pas tout obligatoire sauf si vous le pensez vraiment.

Définissez des objets imbriqués. Nichez simplement les définitions de schéma dans "properties". Voici un utilisateur avec une adresse :

Ce pattern sur le code postal ? Il garantit que seuls les codes postaux américains à 5 chiffres sont acceptés. Ce genre de validation en conditions réelles empêche les données indésirables de se glisser dans votre base de données.

Pourquoi vous devriez vraiment l'utiliser

Validation d'API : Validez les corps de requêtes entrantes en bordure de votre API. Les mauvaises données sont rejetées avec des messages d'erreur clairs avant de toucher votre logique métier. La plupart des frameworks le supportent — Ajv pour JavaScript est ultra rapide.

Validation de configuration : Validez les fichiers de config au démarrage de votre app. Échouez rapidement avec un clair « il manque le champ database.host dans votre config » plutôt qu'une exception cryptique de pointeur null 5 minutes plus tard.

Documentation : JSON Schema sert de documentation vivante. Des outils comme Swagger UI génèrent la doc API directement depuis les schémas.

Génération de code : Générez des interfaces TypeScript, des structs Go ou des dataclasses Python depuis votre schéma. Écrivez-le une fois, utilisez-le partout.

Tests : Validez les réponses d'API dans votre suite de tests pour détecter les régressions automatiquement.

Démarrer en 30 secondes

Le moyen le plus rapide pour commencer ? Générez un schéma à partir de données JSON existantes. Collez un exemple de réponse JSON dans notre JSON Schema Generator — il analysera les données et produira un schéma que vous pourrez affiner. Ensuite, utilisez notre JSON Schema Validator pour le tester contre des données réelles.

Vous pouvez aussi valider par programme. Voici un exemple rapide en Node.js avec Ajv :

Pour Python, découvrez la bibliothèque jsonschema. Pour Java, il y a everit-json-schema. Pratiquement tous les langages ont un bon support — consultez la liste complète des implémentations.

Fonctionnalités avancées de Schema à connaître

Une fois les bases maîtrisées, JSON Schema offre des fonctionnalités puissantes qui rendent la validation complexe possible.

oneOf, anyOf, allOf — Combiner des schémas :

Parfois un champ peut être l'un de plusieurs types. Par exemple, une API pourrait accepter soit un ID de type chaîne, soit un ID numérique :

Ce schéma accepte à la fois {"id": "PRD-1234"} et {"id": 42} mais rejette {"id": -1} ou {"id": "invalid"}.

$ref — Définitions de schéma réutilisables :

Au fur et à mesure que vos schémas grandissent, vous voudrez éviter de répéter les mêmes définitions. Le mot-clé $ref vous permet de référencer des définitions partagées :

Maintenant, billing_address et shipping_address utilisent exactement les mêmes règles de validation. Modifiez la définition address une seule fois, et les deux champs sont mis à jour. C'est essentiel pour garder les grands schémas maintenables.

additionalProperties — Verrouiller vos objets :

Par défaut, JSON Schema autorise les propriétés supplémentaires non listées dans properties. Ce n'est souvent PAS ce que vous voulez — des champs inattendus pourraient indiquer un bug client ou une incompatibilité de version. Définissez "additionalProperties": false pour rejeter les champs inconnus :

Avec ce schéma, {"name": "Alice", "email": "[email protected]", "admin": true} serait rejeté car admin n'est pas une propriété définie.

Erreurs courantes avec JSON Schema

Même les développeurs expérimentés font ces erreurs en écrivant des schémas :

1. Oublier que required est au niveau de l'objet, pas de la propriété. Ceci est faux :

La bonne façon est :

2. Utiliser "type": "number" quand vous voulez dire "type": "integer". Le type number accepte les décimaux comme 3.14, tandis que integer n'accepte que les nombres entiers. Si votre champ est un compteur ou un ID, utilisez integer.

3. Ne pas spécifier format pour les motifs courants. JSON Schema a des validateurs de format intégrés pour email, uri, date-time, ipv4, ipv6, uuid et plus. Utilisez-les au lieu d'écrire des regex complexes.

4. Tout rendre obligatoire. Ne marquez les champs comme requis que s'ils doivent vraiment être présents. Sur-contraindre votre schéma rend l'évolution de l'API plus difficile — ajouter un nouveau champ optionnel est un changement non cassant, mais vous perdez cette flexibilité si tout est obligatoire.

Exemple concret : Schéma de produit E-Commerce

Regardons un schéma pratique que vous pourriez utiliser pour une API de produits :

Ce schéma impose que chaque produit ait un nom (1-200 caractères), un prix positif et une catégorie d'une liste fixe. Les tags sont optionnels mais doivent être des chaînes uniques avec un maximum de 10. Le mot-clé enum est incroyablement utile pour les champs qui ne doivent accepter que des valeurs spécifiques.

Versions de JSON Schema : Quel Draft utiliser

JSON Schema est passé par plusieurs drafts — chacun publié en tant qu'Internet-Draft IETF — et cela peut être déroutant pour les débutants. Voici un aperçu rapide :

Pour les nouveaux projets, utilisez 2020-12 (le plus récent). Si vous travaillez avec une base de code existante, vérifiez quel draft votre validateur supporte. La plupart des validateurs modernes comme Ajv supportent le Draft 7 et ultérieur.

Intégrer JSON Schema dans votre workflow

Voici une approche pratique pour ajouter la validation JSON Schema à une API Express.js :

Ce pattern vous offre une validation automatique des requêtes avec des messages d'erreur clairs. L'option allErrors: true garantit que toutes les erreurs de validation sont signalées en une fois, pas seulement la première.

Essayez vous-même

Prêt à ajouter la validation de schéma à votre projet ? Commencez avec ces outils :

• JSON Schema Generator — Collez n'importe quelles données JSON et obtenez un schéma généré automatiquement. Parfait pour bootstrapper des schémas à partir d'exemples de réponses API.
• JSON Schema Validator — Testez votre schéma contre des données réelles pour vous assurer qu'il détecte ce qu'il doit et autorise ce qu'il doit.
• JSON Validator — Vérifiez rapidement que votre JSON est syntaxiquement valide avant de vous soucier de la validation de schéma.

JSON Schema peut sembler être du travail supplémentaire au départ, mais il se rentabilise de nombreuses fois en attrapant les bugs à la frontière de votre système plutôt qu'au plus profond de votre logique métier.