JSON Schema : valider des données en ligne (Draft 2020-12)

JSON Schema : valider des données en ligne (Draft 2020-12)

Testez payloads API et fichiers config contre un JSON Schema Draft 2020-12 — erreurs par chemin JSON Pointer, dans le navigateur.

12.08.2026
7 min de lecture
Partager cet article:
json-schemavalidationAPIopenapiTutoriel

Valider des données JSON contre un schéma

Un JSON valide n'est pas forcément valide pour votre API. Un payload peut être analysé correctement. Il peut pourtant manquer un champ requis, envoyer un mauvais type ou violer une contrainte format. Ces bugs n'apparaissent souvent qu'en tests d'intégration ou dans les journaux de production. JSON Schema répond à une autre question que la vérification de la syntaxe : cette instance respecte-t-elle le contrat ? Le validateur JSON Schema en ligne de FastMinify exécute la validation Draft-07 et 2020-12 dans deux éditeurs Monaco (schéma et instance), entièrement dans votre navigateur. Si la syntaxe est douteuse, commencez par le validateur JSON. Si le contrat vit dans OpenAPI, utilisez validate-openapi. Le hub outils API regroupe les outils de conversion de schémas et de lint OpenAPI.

Schéma et syntaxe : détecter les champs requis manquants et les types incorrects une fois le JSON analysé
Draft-07 et 2020-12 via Ajv, avec des erreurs instancePath et keyword pour chaque violation
Deux éditeurs avec validation en direct après un court debounce (~300 ms), sans installation ni compte
Mode Strict facultatif pour la relecture de schémas (Ajv strict: true à la compilation)
100 % local : le schéma et les payloads ne quittent jamais le navigateur

Limites honnêtes et schémas maintenables

Ce que le validateur navigateur ne fait pas

Un résultat vert signifie que l'instance respecte le schéma collé, pas que toute la plateforme d'API est conforme.

Aucune requête réseau : les $ref externes, y compris en https://, ne sont jamais résolues
Pas de lot de plusieurs fichiers : collez un JSON de schéma autonome à chaque exécution
Pas de lint des opérations OpenAPI : utilisez lint-openapi pour operationId et les tags
Aucune interrogation d'endpoint en direct : l'instance doit être collée explicitement
Les schémas Draft-04, Draft-06 et 2019-09 sont refusés : migrez ou convertissez d'abord les drafts
Conseils de conception de schéma

Les schémas qui passent proprement dans le navigateur résistent mieux à la CI et à la génération de SDK.

Définissez toujours $schema dans les fichiers partagés pour éviter les hypothèses implicites sur 2020-12
Préférez additionalProperties: false seulement pour des objets fermés délibérément
Utilisez examples dans OpenAPI et collez-les comme instances pendant les relectures
Maintenez l'alignement des enums avec le code et documentez, dans description, les valeurs dépréciées
Versionnez les changements cassants du schéma : les consommateurs valident contre le tag de schéma qu'ils visent
Quand passer aux outils de CI

Les contrôles dans le navigateur économisent des minutes de pipeline, et la politique de l'organisation reste en CI.

Ajv ou jsonschema dans GitHub Actions / GitLab CI sur chaque PR
Détecteurs de changements cassants entre versions de schéma
Pact ou tests de contrat sur des environnements réels
Registres de schémas (Apicurio, Buf) pour la gouvernance de plusieurs équipes
Combiner avec notre guide CI/CD

Syntaxe JSON vs validation JSON Schema

Deux validateurs, deux questions

Ne changez pas d'outil en plein débogage : chacun cible un type d'échec distinct.

Validateur JSON (json-validator) : syntaxe seule, comme les virgules finales, les guillemets simples ou un collage tronqué
Validateur JSON Schema (json-schema-validator) : le contrat sémantique, c'est-à-dire types, champs requis, enums et formats
Une syntaxe verte avec un schéma rouge indique une violation du contrat, pas une erreur d'analyse
Réparez d'abord le JSON cassé avec json-repair ou les liens voisins du validateur
Valider un document OpenAPI est une troisième intention : utilisez validate-openapi pour l'enveloppe de la spécification
Drafts pris en charge (et ce qui est refusé)

FastMinify détecte le draft d'après $schema quand il est présent ; sans $schema, c'est 2020-12 par défaut.

Draft 2020-12 : https://json-schema.org/draft/2020-12/schema
Draft-07 : http://json-schema.org/draft-07/schema#
Draft-04, Draft-06 et 2019-09 renvoient une erreur unsupported-draft explicite, sans conversion silencieuse
Déclarez le draft explicitement dans les schémas partagés pour éviter les dérives d'équipe
OpenAPI 3.1 s'aligne sur 2020-12 ; OpenAPI 3.0 utilise souvent Draft-07 dans components.schemas
instancePath et mots-clés en erreur

En cas d'échec, Ajv indique où l'instance a enfreint le schéma, ce qui est précieux sur les gros payloads d'API.

instancePath pointe vers la valeur en échec (style JSON Pointer)
Le mot-clé indique la règle en échec (required, type, format, …)
Plusieurs violations sont listées séparément : corrigez-les dans l'ordre ou en commençant par le champ le plus important
Instance vide avec schéma required → chemin / ou propriétés manquantes
Utilisez le visualiseur JSON sur les payloads profonds

Valider du JSON contre un schéma, pas à pas

Utiliser le validateur JSON Schema

Le validateur JSON Schema propose deux éditeurs : Schéma et Instance. Collez du JSON dans chaque champ. Le YAML n'est pas accepté dans l'éditeur de schéma, qui lit uniquement du JSON. La limite est de 512 KiB par champ.

Validation en direct après un court debounce (~300 ms), dès que les deux côtés sont analysables
Panneau de résultats : valide ou invalide, nombre de violations, draft détecté
Pour chaque erreur : instancePath, keyword et message
Actions Copier et Agrandir (⌘⇧E) sur chaque panneau d'éditeur
L'option Strict est désactivée par défaut ; activez-la pour un lint de schéma comme en CI
Quand activer le mode Strict

Le mode Strict active strict: true d'Ajv à la compilation du schéma : les mots-clés inconnus et les autres motifs non stricts échouent avant la validation de l'instance.

Désactivé (par défaut) : débogage pragmatique de schémas réels avec des clés supplémentaires
Activé : relecture d'un schéma avant publication dans un registre ou dans components.schemas d'OpenAPI
Les erreurs de compilation Strict s'affichent dans le panneau de résultats : corrigez le schéma, puis testez de nouveau l'instance
Combinez Strict avec format-openapi pour les schémas intégrés à de grandes spécifications
Ne remplace pas la gouvernance Spectral à l'échelle de l'organisation ni les vocabulaires personnalisés
Une réponse d'API échoue en préproduction

Le client mobile plante sur une nouvelle forme de champ. La réponse est du JSON valide, mais elle casse le schéma publié.

1

Confirmez la syntaxe JSON

Collez la réponse dans json-validator. Si la syntaxe échoue, réparez-la avant la validation du schéma.

2

Collez le schéma et l'instance

Ouvrez json-schema-validator. Collez le schéma de référence (export OpenAPI ou registre de schémas) et la réponse de préproduction.

3

Lisez les erreurs instancePath

Corrigez l'API ou mettez le schéma à jour avec un plan de dépréciation. Validez de nouveau après le déploiement. Vous pouvez aussi comparer les payloads de préproduction et de production avec diff.

Un fichier de configuration avant kubectl apply

L'équipe partage une configuration JSON validée en CI avec JSON Schema, et vous voulez un contrôle local rapide sans cloner le pipeline.

1

Chargez le schéma depuis le dépôt

Copiez le JSON du schéma. Il doit être autonome, car les $ref externes ne sont pas résolus dans le navigateur.

2

Validez votre modification

Collez la configuration modifiée comme instance. Activez Strict si le schéma est écrit pour une relecture stricte.

3

Enchaînez avec les outils YAML si besoin

Les configurations sont souvent en YAML. Convertissez-les avec yaml-to-json, vérifiez la syntaxe, puis validez l'instance JSON contre le schéma.

OpenAPI, components.schemas et conversion

Où vivent les schémas dans les contrats API

Les équipes REST publient souvent leurs formes dans components.schemas d'OpenAPI, tandis que les registres de schémas stockent des fichiers autonomes. Le validateur accepte l'un comme l'autre une fois extrait en JSON. Le déroulé : validate-openapi pour l'enveloppe de la spécification, extraction du schéma, puis json-schema-validator pour vérifier le payload contre ce schéma. Voir notre guide validation OpenAPI et le guide lint & format pour le côté spécification du contrat.

Convertir entre OpenAPI et JSON Schema

Quand la source du schéma est le fichier OpenAPI, changez de format sur le hub sans CLI locale. Utilisez openapi-to-json-schema pour extraire un schéma des components OpenAPI. Utilisez json-schema-to-openapi pour envelopper un schéma autonome dans une coque OpenAPI à importer dans un portail.

L'état d'esprit du test de contrat

La validation dans le navigateur accélère le retour d'information, la CI garde les suites de régression. Collez des instances représentatives : cas nominal, valeurs nulles limites et bornes des enums. Documentez le draft dans $schema, à côté de chaque fichier de schéma partagé dans le dépôt git.

Échecs de validation fréquents

Erreurs d'instance courantes

Ces cas reviennent sans cesse dans les tickets de support et les jobs de CI instables.

Propriété required manquante : instancePath désigne le parent ou la racine /
Mauvais type, par exemple une chaîne là où un entier est attendu (fréquent après la sérialisation d'un formulaire)
additionalProperties: false attrape les champs en trop venus d'une erreur de versionnage de l'API
Violations de format comme date-time, email ou uuid (via ajv-formats)
Écart par rapport à enum : codes de statut ou de région non documentés dans le payload
Erreurs de compilation de schéma

Le mode Strict et les drafts non pris en charge apparaissent ici avant la validation de l'instance.

URL $schema non prise en charge : passez à Draft-07 ou 2020-12
Une $ref externe est une erreur bloquante : intégrez ou regroupez d'abord les références en local
YAML collé dans l'éditeur de schéma : convertissez-le en JSON ou collez uniquement du JSON
Un schéma de plus de 512 KiB : scindez-le ou utilisez des outils de regroupement en CI
Mots-clés inconnus sous Strict : retirez-les ou déplacez-les vers description ou des extensions propriétaires, selon la politique de l'organisation

Conclusion

La validation JSON Schema comble l'écart entre un JSON analysable et des données d'API fiables. Commencez par la syntaxe si besoin, puis validez les instances contre des schémas Draft-07 ou 2020-12, avec des erreurs instancePath claires, en local avant la CI. Extrayez les schémas depuis OpenAPI quand le contrat vit dans la spécification, et gardez des limites honnêtes sur les références, les drafts et la taille.

Validez votre instance JSON contre un schéma maintenant

La syntaxe d'abord avec json-validator, la validation du schéma ensuite
Déclarez $schema explicitement dans chaque fichier schéma partagé
Activez Strict pour relire un schéma avant la fusion, pas pour déboguer un payload permissif
Regroupez en local les $ref externes : l'outil du navigateur ne récupère jamais d'URL
Chaînez avec openapi-to-json-schema quand la source est un fichier OpenAPI
Partager cet article
Partager cet article: