Tutoriel JSON

Qu'est-ce que JSON Schema ? Usage, exemples et tutoriel complet (2026)

Lecture d'environ 12 min

Lorsque vous traitez des réponses API ou des fichiers de configuration, un JSON syntaxiquement valide ne signifie pas que les données sont « légales » — champs manquants, types incorrects ou valeurs hors limites n'apparaissent souvent qu'à l'exécution. JSON Schema est la spécification conçue pour résoudre exactement ce problème. En partant de la définition et des cas d'usage, cet article couvre la syntaxe de base, les mots-clés courants, un flux de validation pratique et le choix des outils pour vous aider à mettre en place une stratégie de contraintes JSON viable.

Aperçu rapide

Élément Description
Problème central JSON syntaxiquement valide, mais structure ou valeurs non conformes aux règles métier
Approche Déclarer types de champs, champs requis et contraintes dans Schema, puis valider automatiquement
Version recommandée Draft 2020-12 (écosystème le plus mature)
Cet article couvre Définition → syntaxe → mots-clés → pratique → choix → FAQ

Qu'est-ce que JSON Schema ?

JSON Schema est une spécification basée sur JSON qui décrit les conditions qu'une donnée JSON doit satisfaire. Considérez-le comme une déclaration de type plus des règles de contrainte : quels champs sont requis, le type de chaque champ, la longueur des chaînes ou les bornes numériques, la structure des éléments de tableau — tout cela peut être écrit dans un Schema.

C'est lui-même un document JSON valide, mais avec une sémantique différente — le Schema ne porte pas les données métier, il décrit la forme des données métier. OpenAPI 3.x utilise JSON Schema pour les corps de requête/réponse ; de nombreux outils CLI valident les fichiers de config avec Schema ; les bibliothèques de formulaires frontend s'appuient souvent sur Schema pour la validation. Une fois maîtrisé, vous pouvez réutiliser la même définition de contraintes côté frontend, backend et CI, en réduisant le travail dupliqué où « chaque couche écrit sa propre validation ».

Pourquoi utiliser JSON Schema ?

Au quotidien, JSON.parse() ne vous indique que si les accolades correspondent et si les guillemets sont corrects. La validation syntaxique est impuissante dans des cas comme :

  • L'API exige un champ email, mais la réponse l'a omis
  • age devrait être un entier, mais le client a envoyé la chaîne "25"
  • Le champ enum status a reçu une valeur inattendue "unknown"
  • L'objet imbriqué address.zip ne respecte pas le format de code postal

La valeur de JSON Schema est de transformer ces « accords implicites » en déclarations exécutables, partageables et versionnées. Les équipes peuvent vérifier les changements d'API par rapport au Schema en code review, au lieu de découvrir des champs incohérents seulement en intégration ou après mise en production.

Bases et exemples de JSON Schema

Un Schema minimal déclare $schema (la version de spec utilisée) et un type racine. Ci-dessous, un objet utilisateur : name est une chaîne requise ; age est un entier non négatif optionnel.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/user.json",
  "title": "User",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Nom complet de l'utilisateur"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name"],
  "additionalProperties": false
}

Une instance de données valide :

{ "name": "Jean Dupont", "age": 28, "email": "jean@example.com" }

Si vous passez { "age": 28 } (champ requis name manquant), ou { "name": "Jane Doe", "extra": true } (additionalProperties: false interdit les champs supplémentaires), le validateur renvoie un chemin d'erreur et une raison explicites.

Aide-mémoire des mots-clés courants

En Draft 2020-12, les mots-clés les plus utilisés par les développeurs sont :

Mot-clé Rôle Exemple
type Déclarer le type de données "string" / "integer" / "object"
properties Définitions des propriétés d'objet { "id": { "type": "integer" } }
required Liste des champs requis ["id", "name"]
enum Restreindre aux valeurs enum ["draft", "published"]
format Formats de chaîne courants "email" / "date-time"
$ref Référencer d'autres fragments Schema "#/$defs/Address"

Pour des Schemas complexes, utilisez $defs pour découper des fragments réutilisables (p. ex. Address, Pagination), puis référencez-les avec $ref afin d'éviter un fichier unique trop volumineux.

JSON Schema vs validation syntaxique JSON

Ils résolvent des problèmes à des niveaux différents ; en pratique, on combine généralement les deux :

  • Validation syntaxique : crochets, guillemets, virgules → possibilité de JSON.parse
  • Validation Schema : champs, types, contraintes conformes à l'accord → respect des règles métier

Flux recommandé : collez d'abord le texte brut dans JSONSort pour le formatage et la vérification syntaxique, puis confiez-le à ajv, fastjsonschema ou similaire pour la validation Schema. Les outils locaux gèrent la syntaxe ; Schema gère la sémantique — responsabilités bien séparées.

Pratique : flux de validation de contrat API

Pour un projet REST typique, le flux complet se décompose en quatre étapes :

  1. Définir le Schema : maintenir schemas/user.json dans le dépôt, versionné avec OpenAPI ou la doc API.
  2. Rédiger des exemples : fournir un échantillon valide et un invalide comme fixtures de tests unitaires.
  3. Intégration CI : dans les pipelines PR, valider les réponses mock par rapport au Schema pour éviter suppression ou renommage accidentel de champs.
  4. Filet de sécurité runtime : valider les corps de requête côté serveur avec Schema ; renvoyer 400 avec erreurs structurées au lieu d'écrire des données incorrectes en base.

Le bénéfice central est la visibilité des changements : les modifications de champs API sont détectées en CI, au lieu de compter sur la mémoire ou une découverte accidentelle en intégration.

JSON Schema vs autres approches

Approche Avantages Limites
JSON Schema Indépendant du langage, support OpenAPI natif, écosystème mature Expressivité limitée pour règles complexes ; courbe d'apprentissage
Types TypeScript Excellente expérience IDE, vérifications à la compilation Écosystème TS uniquement ; conversion supplémentaire à l'exécution
Validation if/else écrite à la main Flexible, sans dépendance supplémentaire Difficile à maintenir et réutiliser, cas limites facilement oubliés
Protobuf / Avro Typage fort, sérialisation haute performance Nécessite une étape de compilation ; peu adapté aux scénarios API JSON purs

Si votre API est déjà JSON + OpenAPI, JSON Schema est généralement le choix le moins frictionnel ; si vous êtes full-stack TypeScript sans besoin de contrat multi-langage, privilégiez TS et utilisez Schema en complément.

JSON Schema vaut-il l'investissement ?

Scénarios où l'investissement vaut le coup :

  • API publiques nécessitant un contrat lisible par machine partagé avec les consommateurs
  • Structures de configuration complexes où les erreurs de format doivent être interceptées avant déploiement
  • Plusieurs clients (Web / mobile / backend) partageant les mêmes contraintes de données
  • Détection automatisée en CI des breaking changes d'API

Scénarios où vous pouvez attendre :

  • Formater ou consulter du JSON occasionnellement → JSONSort suffit
  • Structures de données très simples et stables → validation manuelle peut coûter moins cher
  • Pas de flux OpenAPI / tests de contrat → établir d'abord des habitudes de documentation avant d'introduire Schema

FAQ

Qu'est-ce que JSON Schema ?

JSON Schema est un ensemble de règles pour décrire la structure et les contraintes JSON. C'est un document JSON qui déclare types de champs, champs requis, plages de valeurs, etc., afin que les validateurs jugent automatiquement si les données sont valides.

Quelle est la différence entre JSON Schema et JSON ?

JSON porte les données métier ; JSON Schema décrit à quoi ces données doivent ressembler. Analogie : JSON est « l'instance », Schema est « le moule ».

Quelle version choisir ?

Les nouveaux projets devraient privilégier Draft 2020-12. Les projets existants en Draft-07 / 2019-09 n'ont pas besoin de migrer sauf si vous dépendez de mots-clés plus récents.

Comment valider en local ?

Syntaxe : JSONSort pour le formatage et la vérification ; Schema : ajv (Node.js), jsonschema (Python) ou l'extension JSON Schema de VS Code.

Quel est le lien entre OpenAPI et JSON Schema ?

Les définitions de corps de requête/réponse OpenAPI 3.x reposent sur un sous-ensemble JSON Schema avec extensions. Rédiger une doc OpenAPI, c'est essentiellement écrire du Schema.

Conclusion

JSON Schema ne répond pas à « le JSON peut-il être parsé ? », mais à « les données respectent-elles les accords de l'équipe ? ». De la définition à l'intégration CI, sa valeur est de transformer des règles implicites en contrats explicites et exécutables. Commencez par une petite API ou un fichier de config, écrivez votre premier Schema et branchez la validation, puis étendez au projet entier.

Pour aller plus loin

Journal des modifications : publication initiale