Sur cette page
La syntaxe indique si un texte peut être lu comme du JSON ; JSON Schema vérifie des exigences explicites sur ses valeurs. Une API peut donc rejeter un document qui passe la validation syntaxique. Vérifiez d’abord la syntaxe, puis validez le document avec son schéma. Un résultat conforme ne couvre que les règles présentes dans ce schéma et prises en charge par le validateur.
| Vérification | Question posée | Que revoir en cas d’échec ? |
|---|---|---|
| Syntaxe | Les deux textes peuvent-ils être analysés comme du JSON ? | L’entrée signalée : document ou schéma. |
| Schéma pris en charge | Le validateur comprend-il le schéma et ses règles ? | Le draft, les mots-clés et leur déclaration. |
| Conformité | Les valeurs respectent-elles ce schéma ? | Le champ et la règle indiqués dans le diagnostic. |
| Règles métier externes | La commande existe-t-elle et est-elle autorisée ? | La source des données et les contrôles de l’application. Le schéma de cet exemple ne répond pas à ces questions. |
Une commande lisible qui ne respecte pas le contrat
Cette commande fictive est un document JSON syntaxiquement correct :
{
"id": "00123",
"quantity": "2",
"active": true
}Supposons que le contrat exige une quantité entière d’au moins une unité. Voici le schéma complet pour la vérifier :
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": { "type": "string", "minLength": 1 },
"quantity": { "type": "integer", "minimum": 1 },
"active": { "type": "boolean" }
},
"required": ["id", "quantity"],
"additionalProperties": false
}La racine doit être un objet. properties décrit les champs : id est une chaîne non vide, quantity est un entier supérieur ou égal à 1 et active, s’il est présent, est un booléen. required impose la présence de id et de quantity ; déclarer active dans properties ne le rend pas obligatoire. additionalProperties: false interdit les champs absents de cette liste.
La distinction entre les types et le minimum inclusif suivent JSON Schema draft-07, sections 6.1.1 et 6.2.4. Ici, "2" est du texte. La présence d’un chiffre n’en fait pas un entier.
Repérer l’erreur et choisir la correction
- Ouvrez le validateur JSON Schema. Collez le schéma complet dans Schéma JSON et la commande initiale dans Document JSON.
- Choisissez Valider. Si une entrée ne peut pas être analysée, corrigez d’abord ses erreurs de syntaxe JSON.
- Avec ces entrées, le résultat attendu est une incompatibilité de
typeà/quantity, avec la règle située à/properties/quantity/type. - Vérifiez dans le contrat et la source que la valeur représente bien une quantité. Si c’est le cas, remplacez
"2"par2, puis choisissez à nouveau Valider.
Les emplacements du diagnostic sont des JSON Pointers, pas des requêtes JSONPath. /quantity désigne la donnée ; /properties/quantity/type, la règle du schéma. Le libellé du message peut varier selon la langue, mais ces emplacements et le mot-clé permettent de comprendre l’erreur.
Le document corrigé est le suivant :
{
"id": "00123",
"quantity": 2,
"active": true
}Le résultat attendu est conforme à ce schéma. id reste une chaîne et conserve ses zéros initiaux. Ne retirez pas les guillemets de toutes les valeurs qui ressemblent à des nombres : un identifiant n’est pas forcément une quantité. Le validateur ne convertit pas "2" en 2 ; c’est à vous de décider si cette modification est justifiée.
Cas indépendants : type, minimum et champ supplémentaire
Repartez du document corrigé pour chaque ligne, en gardant le même schéma. Annulez la modification précédente avant de passer au cas suivant.
| Modification unique | Résultat attendu | Suite à donner |
|---|---|---|
Remplacer "quantity": 2 par "quantity": "2" |
type à /quantity. |
Le texte ne satisfait pas le type entier. Confirmez le contrat avant de modifier la donnée. |
Remplacer "quantity": 2 par "quantity": 0 |
minimum à /quantity. |
Le type est correct, mais le minimum est 1. Vérifiez la quantité à la source ; n’en inventez pas une pour réussir la validation. |
Ajouter "currency": "MXN" |
additionalProperties, propriété currency, instance racine. |
Le contrat n’autorise pas ce champ. Vérifiez s’il est superflu ou si le schéma doit évoluer ; ne le supprimez pas sans examen. |
| Conserver le document corrigé | Conforme au schéma. | Les règles déclarées sont respectées, sans vérification de l’existence ni de l’autorisation de la commande. |
La racine est représentée par le JSON Pointer vide (""). Ce sont des cas séparés, pas une sortie regroupant plusieurs erreurs : l’outil ne signale que la première incompatibilité. Après correction et nouvelle validation, une autre peut apparaître.
Quand le problème vient du schéma
Un schéma peut avoir une syntaxe JSON correcte tout en utilisant un mot-clé que cet outil ne prend pas en charge. Pour observer la différence, gardez la commande corrigée et remplacez le schéma par cet exemple volontairement non pris en charge :
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"format": "email"
}Le résultat attendu est schéma non pris en charge, à cause de format, avant l’évaluation des données. Cela ne signifie pas que la commande est non conforme ni que son identifiant doit être une adresse e-mail. Rétablissez le schéma de la commande pour continuer.
Cet outil implémente un sous-ensemble de draft-07. Il exige un objet à la racine du schéma et l’URI exact de $schema indiqué plus haut. Il rejette les mots-clés inconnus ou non pris en charge, dont $ref, format, les combinateurs et les conditions. Il ne propose pas de prise en charge complète de draft-07, ni des versions 2019-09 ou 2020-12.
Ce que prouve un résultat conforme
La commande corrigée respecte ce contrat. Cela ne prouve pas que "00123" existe, que le stock est suffisant ou que l’expéditeur est autorisé à passer commande. Cela ne confirme pas non plus que la quantité copiée correspond à la source. Ces vérifications relèvent toujours de l’application et du contrôle des données d’origine.
La validation ne répare pas la syntaxe, ne supprime pas de propriétés et ne modifie pas l’entrée. Une annulation ou une limite atteinte laisse la vérification inachevée : ce n’est ni un résultat conforme ni la preuve d’un non-respect du contrat. La page du validateur JSON Schema détaille les limites de taille, de profondeur et d’exécution, ainsi que le rejet des nombres que l’outil ne peut pas représenter de façon sûre.