Ce que JSON Schema résout réellement
L’essentiel : Schema régit la structure et les types, pas le sens métier. Il bloque les champs manquants, les types faux et les énumérations hors plage, tandis que des règles comme un montant supérieur à zéro restent dans le code.
L'essentiel : laissez JSON Schema imposer structure, types, plages et formats, tandis que les règles inter-champs, les invariants métier et l'état externe restent dans le code ; adoptez-le pour les API publiques et les charges utiles partagées, pas pour un service interne à cinq champs.
Il répond à « ces données ont-elles la bonne forme », pas « ces données ont-elles du sens ».
Ce qu'il fait bien
Complétude structurelle. Quels champs doivent exister, si les extras sont autorisés (required, additionalProperties).
Types. port en nombre ou en chaîne, tags en tableau ou en scalaire. Cela seul supprime beaucoup de code défensif dans les systèmes multi-langages.
Plages. enum, minimum/maximum, longueur de chaîne et de tableau.
Formats. format pour les dates, e-mails, URI et UUID, avec des validateurs qui les appliquent.
Imbrication. Chaque niveau d'objets et de tableaux reçoit ses propres contraintes, et les erreurs portent un chemin précis.
Documentation. Le Schema est le contrat. Changez un champ et le diff montre la portée. Il génère aussi des types et des formulaires, donc une définition alimente plusieurs consommateurs.
Ce qu'il ne peut pas faire
Dépendances inter-champs. « La fin doit être après le début » peut s'exprimer avec if/then/else, mais le résultat est plus long et plus difficile à lire que trois lignes de code.
Invariants métier. « Le stock ne peut pas devenir négatif » dépend de l'état externe. Schema ne voit qu'un document.
Sémantique. price: -100 satisfait parfaitement {"type": "number"}. La légalité du prix est hors de la connaissance du Schema.
Une répartition viable
| Couche | Responsable |
|---|---|
| Syntaxe : est-ce du JSON valide | Parseur |
| Structure : champs, types, plages, formats | JSON Schema |
| Sémantique : inter-champs, règles métier, état externe | Code applicatif |
| Sécurité : taille, profondeur, débit | Passerelle / middleware |
Réduisez tout cela en un seul endroit et le Schema grandit à des centaines de lignes avec cinq niveaux de if/then. À ce stade, les gens le contournent.
Quand cela vaut le coup
- API publiques avec des consommateurs inconnus
- Plusieurs services lisant la même charge utile
- Systèmes pilotés par configuration où les fautes de frappe doivent échouer vite
- Génération de types ou de formulaires depuis le contrat
Pour un petit service interne à cinq champs et un seul frontend, des vérifications écrites à la main se maintiennent plus vite. Y introduire Schema est un travail négatif.
FAQ
Comment décider d'adopter JSON Schema ?
Pesez les consommateurs publics, les plusieurs services lisant la même charge utile, et le besoin de générer des types ou des formulaires. Pour un petit service interne à cinq champs et un seul frontend, des vérifications écrites à la main se maintiennent plus vite.
Pourquoi les règles inter-champs doivent-elles rester dans le code ?
« La fin doit être après le début » peut être glissé dans if/then/else, mais le résultat est plus long et plus difficile à lire que quelques lignes de code. Schema ne voit pas non plus l'état externe.
Schema doit-il valider la taille et la profondeur d'imbrication des charges utiles ?
Non. Schema décrit la structure, pas la taille ou la profondeur ; ces limites appartiennent à une passerelle ou à une couche middleware.