JSON Schema

Ce que c'est

JSON Schema est un langage qui décrit la forme attendue de données
JSON et qui s'écrit lui-même en JSON. Une description dans ce
langage, appelée schéma, pose les règles : cette valeur est un
objet, il doit posséder ces propriétés, celle-ci est un entier d'au
moins un, celle-là une chaîne d'au plus 200 caractères. Un programme
appelé validateur reçoit un schéma et une instance, les données à
vérifier, puis indique si l'instance est conforme et, sinon, où et
pourquoi. Le projet écrit son nom avec un S majuscule, JSON Schema,
tandis qu'un document écrit dans ce langage est simplement un
schéma, en minuscule.

La spécification est maintenue par le projet JSON Schema sur
json-schema.org. La version actuelle est 2020-12 et la précédente
2019-09 ; les plus anciennes étaient des brouillons numérotés, comme
draft-04 et draft-07, et les anciens outils et articles les
désignent encore par ces noms. Le texte comprend deux parties. Le
document central définit le traitement d'un schéma, les références
entre schémas et le type de média `application/schema+json` ; un
second document, sur la validation, définit les mots-clés qui
vérifient les valeurs. Les deux documents actuels de 2020-12 sont
datés du 16 juin 2022.

Chaque mot-clé ajoute une contrainte. `type` nomme l'un des six
types de base, string (chaîne), number (nombre), boolean (booléen),
array (tableau), object (objet) ou null (nul), ou bien `integer`,
qui n'accepte que les nombres dont la partie fractionnaire est
nulle. Les nombres prennent `minimum`, `maximum` et `multipleOf` ;
les chaînes, `minLength`, `maxLength` et `pattern`, une expression
régulière ; les tableaux, `minItems`, `maxItems` et `uniqueItems` ;
les objets, `properties`, `required` et `additionalProperties`. Des
mots-clés comme `allOf`, `anyOf`, `oneOf` et `not` combinent les
schémas, et `$ref` pointe vers un schéma défini ailleurs, souvent
sous `$defs` dans le même document, pour réutiliser en plusieurs
endroits une forme écrite une seule fois. Tout ce qu'un schéma ne
mentionne pas est autorisé. Le schéma vide, `{}`, accepte toutes les
instances possibles.

Un schéma peut aussi indiquer la version du langage dans laquelle il
est écrit. Le mot-clé `$schema` contient l'adresse d'un métaschéma,
un schéma qui décrit les schémas valides pour cette version ; la
page de spécification précise que le métaschéma se valide lui-même.
Pour 2020-12, cette adresse est
`https://json-schema.org/draft/2020-12/schema`.

Pourquoi c'est important

JSON ne dit rien du sens. Tout document bien formé peut être
analysé, que le programme qui le lit puisse ou non en faire quelque
chose. Sans description écrite, chaque programme qui lit un document
garde sa propre idée de ce qui est valide, éparpillée dans les
conditions de son code ; ces idées divergent jusqu'à ce qu'une
requête échoue en production. Un schéma rassemble les règles dans
une forme lisible par les personnes comme par les programmes. Il
peut être stocké, versionné, revu et publié comme n'importe quel
fichier.

La spécification énonce un objectif large : JSON Schema est destiné
à la validation et à la documentation des données JSON, à la
navigation par hyperliens et au contrôle des interactions ; le
vocabulaire de validation vise aussi à fournir des indications aux
interfaces qui affichent les données. En pratique, une même
description peut rejeter les entrées incorrectes à la frontière d'un
service, documenter une API, piloter un formulaire et vérifier que
le JSON renvoyé par un modèle de langage possède les champs attendus
à l'étape suivante.

Il est aussi devenu le socle commun d'autres spécifications. OpenAPI
3.1 définit son Schema Object comme un surensemble de JSON Schema
2020-12 : les corps de requête et de réponse d'une description d'API
sont donc du JSON Schema avec quelques ajouts. MCP, le protocole par
lequel les agents d'IA découvrent et appellent des outils, décrit
les paramètres de chaque outil par un `inputSchema` qui est un JSON
Schema. MCP peut aussi décrire le résultat de l'outil par un
`outputSchema` auquel les clients devraient confronter les résultats
structurés pour les valider. Une même description peut donc servir à
un validateur, à un document d'API et à un agent.

À quoi cela ressemble en pratique

Le schéma ci-dessous décrit l'entrée d'un outil qui réserve un
créneau de livraison. Il nomme la version dans laquelle il est
écrit, énumère quatre propriétés avec leurs règles, indique les
trois qui doivent être présentes et refuse toute propriété non
répertoriée :

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/tools/book-slot.json",
  "title": "Book a delivery slot",
  "type": "object",
  "properties": {
    "order": { "type": "string", "pattern": "^[0-9]{4,8}$" },
    "date": { "type": "string", "format": "date" },
    "pallets": { "type": "integer", "minimum": 1, "maximum": 30 },
    "note": { "type": ["string", "null"], "maxLength": 200 }
  },
  "required": ["order", "date", "pallets"],
  "additionalProperties": false
}
```

Une instance qui enfreint les règles :

```json
{ "order": "4471", "date": "27/10/2026", "pallets": 0, "pallet": 2 }
```

L'instance échoue sur deux points. `pallets` est inférieur au
minimum de 1, et `pallet`, une faute de frappe pour `pallets`, est
une propriété absente de la liste du schéma. L'absence de `note`
n'est pas une erreur, car `note` ne figure pas dans `required` ; si
elle avait été envoyée avec la valeur `null`, elle serait aussi
acceptée, puisque son type autorise null. La date est le cas
instructif. Le format `date` exige l'année en premier et
`27/10/2026` place le jour en premier, mais un validateur avec ses
réglages initiaux l'accepte : la spécification fait de `format` une
annotation qui n'est vérifiée que si cette vérification est activée.
Activez-la dans un validateur qui vérifie les dates, et la même
instance échouera sur trois points.

C'est d'un outil ainsi décrit que traite la page de ce site sur la
transformation de logiciels existants en outils pour agents d'IA.
Elle présente chaque opération dont un agent devrait disposer, comme
réserver un créneau ou libérer une commande, sous la forme d'un
outil aux entrées typées, aux erreurs auxquelles un agent peut
réagir utilement et aux appels idempotents, afin qu'une nouvelle
tentative ne réserve jamais deux fois. La description est un
document OpenAPI généré depuis le code, et un serveur MCP propose
les mêmes opérations. La page souligne qu'un agent fait confiance à
la description d'un outil même lorsqu'elle est périmée, et qu’une
description écrite à la main peut diverger de l’implémentation. Les
descriptions sont donc générées depuis le code vers l'extérieur, en
passant par la base de données, l'API, la description et le client,
avec à chaque étape une vérification qui fait échouer le processus
de construction lorsque deux éléments divergent.

Où les problèmes surviennent

Une propriété répertoriée qui n'est jamais obligatoire. `properties`
ne vérifie que les propriétés présentes : un objet qui les omet
toutes est donc accepté. La présence relève d'un autre mot-clé, et
omettre `required` signifie que rien n'est obligatoire. Écrivez
toujours `required` à côté de `properties` et conservez un cas de
test par propriété obligatoire, où cette propriété a été retirée.

Des fautes de frappe acceptées comme propriétés supplémentaires.
Sans `additionalProperties`, toute propriété non répertoriée par le
schéma est autorisée : `pallet` passe et la véritable propriété
`pallets` manque silencieusement. Régler ce mot-clé sur `false`
ferme l'objet, mais ce mot-clé ne voit que les `properties` et
`patternProperties` de son propre objet de schéma. Un schéma qui en
prolonge un autre par `allOf` ou `$ref` puis se ferme ainsi rejette
précisément les propriétés héritées. La version 2020-12 propose
`unevaluatedProperties` pour ce cas, car ce mot-clé compte aussi les
propriétés vérifiées par `allOf`, `$ref` et les autres mots-clés qui
appliquent des schémas au même emplacement de l'instance. Utilisez
`additionalProperties: false` pour un schéma autonome et
`unevaluatedProperties: false` pour un schéma composé.

Un `format` qui ne vérifie rien. Sans activation explicite de sa
vérification, `format` est une annotation et non une assertion : la
spécification exige qu'un validateur capable de vérifier les formats
garde cette vérification désactivée sauf demande explicite. Même
lorsque cette vérification est activée, un validateur peut laisser
passer n'importe quel format sans le vérifier. OpenAPI 3.1 suit la
même règle et ajoute que la qualité de la vérification varie selon
l'implémentation. Activez la vérification des formats dans votre
validateur, prouvez-la avec un cas de test qui doit échouer et,
lorsqu'un format compte mais ne peut être vérifié, ajoutez un
`pattern` ou une vérification dans le code.

Des motifs qui correspondent à une partie d'une valeur. Un `pattern`
n'est pas ancré : `[0-9]{4}` accepte donc `order 4471b`, car quatre
chiffres s'y trouvent quelque part ; l'exemple de la spécification
est que `es` correspond à `expression`. Commencez le motif par `^`
et terminez-le par `$` lorsque la valeur entière doit correspondre.
Les motifs suivent le dialecte ECMA-262, et la spécification
recommande un petit ensemble de constructions pour qu'ils se
comportent partout de la même manière : tenez-vous-en aux classes,
quantificateurs et ancrages simples.

Confondre absence, null et vide. Une propriété absente, une
propriété ayant la valeur `null` et une chaîne vide sont trois
instances différentes. `"type": "string"` rejette `null`, et une
propriété absente de `required` peut être omise. Un client qui
envoie `null` pour signifier l'absence de valeur face à un schéma
prévu pour l'absence de propriété échoue à chaque requête de ce
type. Décidez pour chaque propriété du sens de ces trois cas et
écrivez-le : `["string", "null"]` lorsque null a un sens, l'absence
de la propriété dans `required` lorsqu'elle est facultative, et
`minLength: 1` lorsqu'une chaîne vide n'est pas une valeur.

Pas de `$schema`, ou deux versions mélangées. Lorsque la racine d'un
schéma n'a pas de `$schema`, la spécification laisse le comportement
à l'implémentation et chaque validateur applique sa version
prédéfinie. Les versions diffèrent sur des points importants. En
2019-09, un tableau fourni à `items` décrivait un tuple ; en
2020-12, ce rôle appartient à `prefixItems`, et `items` a repris
celui d'`additionalItems`. Placez `$schema` dans chaque racine,
suivez les notes de version lors d'une migration et validez chaque
schéma avec son métaschéma en intégration continue.

Pour aller plus loin

  * Spécification de JSON Schema — l'index du projet pour la version
actuelle, ses métaschémas et les notes de version de chaque ancien
brouillon.

  * JSON Schema : un type de média pour décrire des documents JSON —
Core 2020-12 : traitement des schémas, `$schema`, `$ref` et `$defs`,
et mots-clés qui combinent les schémas.

  * Validation de JSON Schema : vocabulaire de validation
structurelle de JSON — mots-clés de chaque type de valeur,
`required` et règles de `format`.

  * Notes de version de JSON Schema 2020-12 — changements depuis
2019-09, avec `prefixItems` et `$dynamicRef` mis en regard de ce
qu'ils ont remplacé.

  * Spécification OpenAPI v3.1.1 — Schema Object comme surensemble
de JSON Schema 2020-12 et `format` comme annotation sans activation
explicite de sa vérification.

  * Model Context Protocol : outils — déclaration des paramètres et
de la sortie structurée d'un outil en JSON Schema.

hCette page sur le Web	URL:https://engineer.company/fr/glossary/json-schema/	engineer.company	70
