JSON Schema

JSON Schema est une manière standard de décrire à quoi ressemble un document JSON valide : quelles propriétés existent, leurs types, lesquelles sont obligatoires, les valeurs et formats autorisés. Un validateur compare ensuite les données réelles au schéma et signale chaque violation. Pour les testeurs d’API, cela transforme « la réponse a l’air correcte » en une vérification unique et reproductible de toute la structure de la réponse. La version actuelle de la spécification est le draft 2020-12 ; le draft-07 reste très largement utilisé.

Exemple

Un schéma pour un utilisateur renvoyé par GET /users/{id} :

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email", "role", "createdAt"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "role": { "enum": ["admin", "member", "viewer"] },
    "createdAt": { "type": "string", "format": "date-time" },
    "nickname": { "type": ["string", "null"] }
  },
  "additionalProperties": false
}

Validation en Node avec Ajv (ajv/dist/2020 prend en charge le draft 2020-12, et ajv-formats ajoute email et date-time) :

import Ajv2020 from 'ajv/dist/2020';
import addFormats from 'ajv-formats';

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(userSchema);

if (!validate(responseBody)) {
  console.log(validate.errors);
}

En Java, le module json-schema-validator de REST Assured fournit matchesJsonSchemaInClasspath("schemas/user.json"), à utiliser dans .body(...). Vérifiez quel draft votre validateur prend en charge avant d’utiliser des mots-clés récents.

Pourquoi c’est important

• Une seule assertion couvre toute la structure. Champs manquants, mauvais types et null inattendus sont détectés sans écrire une vérification par champ.
• Il détecte les fuites. "additionalProperties": false échoue si la réponse contient soudain quelque chose comme passwordHash.
• Il documente le contrat. Les spécifications OpenAPI utilisent JSON Schema pour décrire les corps de requête et de réponse.

Erreurs courantes

• Des schémas qui acceptent n’importe quoi. Un schéma sans required valide {}. Listez toujours les champs obligatoires.
• Supposer que format est appliqué. Beaucoup de validateurs traitent format comme une simple annotation, sauf si la validation des formats est activée.
• Ne valider que le schéma. Une réponse peut respecter le schéma et contenir malgré tout le mauvais utilisateur. Gardez des assertions sur les valeurs des données qui comptent.