Validation de schéma JSON Capture des violations du contrat d'API avant leur livraison

Si votre API retourne un champ qui n'existe pas selon votre schéma, ou accepte un corps de requête avec une propriété requise manquante, vous avez un violation de contrat. Ces bugs sont subtils, souvent silencieux, et remarquablement coûteux à détecter en production. La validation de schéma JSON est la couche qui les capte plus tôt — plus proche de leur origine.

Ce guide explique comment fonctionne le schéma JSON, quels validateurs utiliser dans Node.js, Python et AWS, et comment maintenir votre schéma proche de la réalité.

Qu'est-ce que le schéma JSON ?

Le schéma JSON est un vocabulaire pour décrire la structure d'un document JSON. Ce n'est pas du code — c'est du métadonnées. Vous écrivez un schéma qui déclare comment un objet JSON valide se présente, puis vous le validez.

Le schéma lui-même est un document JSON. Exemple minimal :

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0 }
  },
  "required": ["email"]
}

C'est tout. Fournissez ce document à un validateur avec n'importe quel payload JSON, et vous obtiendrez un résultat de passage ou une liste structurée des échecs.

Les mots-clés fondamentaux

Un petit nombre de mots-clés couvre la majorité des besoins de validation dans le monde réel :

additionalProperties: false mérite une mention particulière. C'est le mot-clé qui rend votre schéma strict — toute propriété non déclarée dans properties déclenche une erreur de validation. Il est désactivé par défaut, ce qui signifie que la plupart des schémas acceptent silencieusement des champs incorrects, sauf si vous les activez explicitement.

Schéma complet : demande de création d'utilisateur

Voici un schéma JSON complet pour le corps de requête d'une requête de création d'utilisateur. C'est le type de schéma que vous écririez une seule fois et que vous valideriez à chaque couche touchant l'endpoint.

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "title": "UserRegistration",
  "type": "object",
  "required": ["email", "password", "username"],
  "additionalProperties": false,
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "minLength": 8
    },
    "username": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_]{3,32}$"
    },
    "role": {
      "type": "string",
      "enum": ["user", "admin"],
      "default": "user"
    },
    "birthDate": {
      "type": "string",
      "format": "date"
    }
  }
}

Vous pouvez tester cela interactivement contre n'importe quel payload en utilisant le IO Tools JSON Schema Validator avant de l'intégrer dans votre codebase.

Validation des corps de requête d'API

Express + AJV

AJV est le validateur le plus rapide de schéma JSON pour Node.js. Voici un middleware Express qui valide le corps de la requête avant qu'elle ne parvienne à votre gestionnaire :

import Ajv from "ajv";
import addFormats from "ajv-formats";

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);

function validateBody(schema) {
  const validate = ajv.compile(schema);
  return (req, res, next) => {
    if (validate(req.body)) {
      return next();
    }
    res.status(400).json({
      error: "Validation failed",
      details: validate.errors,
    });
  };
}

// Usage
app.post("/register", validateBody(registrationSchema), registerHandler);

allErrors: true instructe AJV de collecter tous les erreurs dans le document au lieu d'arrêter à la première — utile lorsque vous souhaitez retourner toutes les erreurs de validation au client en même temps.

FastAPI (Python)

En Python, FastAPI utilise Pydantic sous-jacent et génère automatiquement un schéma JSON à partir de vos annotations de type. Si vous travaillez avec un schéma JSON brut provenant d'une source externe plutôt qu'avec des modèles Pydantic, jsonschema est la bibliothèque standard :

from jsonschema import validate, ValidationError

schema = { ... }  # your schema dict

try:
    validate(instance=request_body, schema=schema)
except ValidationError as e:
    return {"error": e.message}, 400

AWS API Gateway

API Gateway prend en charge la validation du corps de requête nativement. Vous définissez un modèle (qui est un document de schéma JSON) et l'attache à votre méthode comme un REQUEST_BODY validateur. Les requêtes qui échouent à la validation sont rejetées au niveau du gateway — avant que votre fonction Lambda n'ait même été exécutée. Cela élimine une catégorie entière d'erreurs de gestionnaire et réduit les appels lors de froid-start pour des trafics invalides.

Schémas réutilisables avec $ref et $defs

Quand plusieurs schémas partagent une structure commune — comme une adresse, un montant monétaire ou un objet de pagination — définissez-la une seule fois dans $defs et référez-la avec $ref:

{
  "$defs": {
    "Address": {
      "type": "object",
      "required": ["street", "city", "country"],
      "properties": {
        "street": { "type": "string" },
        "city":   { "type": "string" },
        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billingAddress":  { "$ref": "#/$defs/Address" },
    "shippingAddress": { "$ref": "#/$defs/Address" }
  }
}

Dans les grands projets, les schémas sont stockés dans des fichiers séparés et $ref pointe vers une URI. Les validateurs qui supportent le mot-clé $id et la résolution de URI peuvent charger les schémas de manière lazy ou à partir d'un registre — AJV gère cela grâce à addSchema().

Drift de schéma

Le drift de schéma survient quand le schéma et l'API réelle divergent. C'est plus fréquent qu'on ne le pense : le schéma est écrit une seule fois, l'API évolue, et personne ne met à jour le schéma.

Les symptômes sont subtils. Un champ est renommé dans le code mais pas dans le schéma — la validation passe toujours parce que additionalProperties n'est pas définie à faux. Un champ requis devient facultatif dans la pratique parce que le code ne le vérifie plus — le schéma le considère toujours comme requis, mais personne ne le remarque jusqu'à ce qu'un client envoie une requête sans lui.

Capter le drift exige de traiter la validation du schéma comme un test, et non comme un contrôle en temps réel. Certains équipes l'automatisent avec des tests de snapshot contre des fixtures de réponses réelles. D'autres exécutent le validateur de schéma dans CI contre un ensemble de requêtes capturées. Le point est que le schéma doit être mis à l'épreuve régulièrement, et non seulement déployé une seule fois.

JSON Schema et OpenAPI

OpenAPI (anciennement Swagger) utilise le schéma JSON pour décrire les corps de requête et de réponse, mais avec quelques modifications. Les versions antérieures (OpenAPI 2.0, 3.0) utilisaient un sous-ensemble de schéma JSON avec des extensions. OpenAPI 3.1 s'aligne davantage sur le schéma JSON draft 2020-12, donc les schémas sont presque interchangeables.

La différence pratique : OpenAPI enveloppe les schémas dans un document plus large qui décrit également les chemins, les opérations, l'authentification et les serveurs. Le schéma JSON seul est simplement un contrat de validation. Si vous construisez une API basée sur le schéma, vous pouvez écrire le schéma JSON pour chaque endpoint, le valider, puis transférer directement ces schémas dans un document OpenAPI.

Génération de schémas à partir de données existantes

Écrire des schémas à la main fonctionne bien pour de nouvelles APIs. Pour des APIs existantes avec un comportement non documenté, il est souvent plus rapide de générer un schéma à partir de payloads réels, puis de le raffiner.

Des outils comme genson (Python) et generate-schema (Node.js) prennent des objets JSON d'exemple et produisent un brouillon de schéma. Le schéma généré est presque toujours trop permissif — tout devient facultatif, aucun additionalProperties: false — mais il vous fournit un point de départ. Vous ajoutez ensuite required, affinage type les définitions, et ajoutez enum des contraintes où les valeurs sont bornées.

Cette approche est également utile lors de l'intégration d'une API tierce sans documentation de schéma. Exécutez plusieurs réponses par un générateur de schémas, fusionnez les sorties, et vous obtenez un contrat fonctionnel à valider.

La validation de schéma JSON doit être placée à chaque couche qui accepte des données structurées — middleware HTTP, consommateurs de files de messages, chemins d'écriture dans la base de données. Plus tôt une violation de contrat est détectée, plus elle est coûteuse à corriger. Un validateur de schéma JSON en ligne vous permet de prototyper des schémas contre des payloads réels avant de vous engager dans une intégration avec une bibliothèque, ce qui en fait la première étape idéale pour tout travail de validation.

Vous aimerez peut-être aussi

Génération d'un palette de couleurs : Création d'une palette complète à partir d'un seul hexadécimal

En savoir plus "

Publié le 12 mai 2026

Vérification de la signature PDF : Ce que les développeurs doivent savoir

En savoir plus "

Publié le 10 mai 2026

Markdown vs HTML : Quand utiliser chacun pour les documents, les README et les API

En savoir plus "

Publié le 9 mai 2026

Paramètres UTM : Comment suivre les campagnes de marketing sans deviner

En savoir plus "

Publié le 8 mai 2026