Validation JSON Schema : Le guide définitif

JSON Schema est un vocabulaire pour annoter et valider les documents JSON. Il fournit un contrat pour vos données — définissant quelle forme elles doivent avoir, quels types sont acceptables et quels champs sont requis. Si vous travaillez avec des API, des fichiers de configuration ou des données structurées, JSON Schema est un outil essentiel dans votre arsenal.

Pourquoi utiliser JSON Schema ?

Sans validation, les données JSON sont une inconnue. Vous pourriez recevoir un champ âge sous forme de chaîne, un email manquant ou une date dans un mauvais format. JSON Schema détecte ces problèmes à la frontière, avant que les mauvaises données ne se propagent dans votre système.

Avantages clés :

• Application des contrats d'API : Validez automatiquement les corps de requête et de réponse
• Documentation : Le schéma sert de documentation vivante pour vos structures de données
• Génération de code : Les outils peuvent générer des types, des formulaires et des schémas de base de données à partir de JSON Schema
• Tests : Validez les fixtures de test et les données fictives par rapport au schéma

Structure de base d'un schéma

Chaque JSON Schema commence par quelques propriétés standard :

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/user.schema.json",
  "title": "User",
  "description": "A registered user in the system",
  "type": "object",
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "name": { "type": "string", "minLength": 1, "maxLength": 100 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "name", "email"]
}

Utilisez notre Formateur JSON pour embellir vos schémas afin d'en améliorer la lisibilité avant de les partager avec votre équipe.

Contraintes de type

JSON Schema prend en charge six types primitifs :

Contraintes de chaîne

{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[A-Za-z0-9]+$",
  "format": "email"
}

Les formats intégrés incluent : email, uri, date, date-time, ipv4, ipv6, uuid et hostname.

Contraintes numériques

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "exclusiveMinimum": 0,
  "multipleOf": 0.01
}

Validation de tableau

Les tableaux peuvent être validés pour leurs éléments, leur longueur et leur unicité :

{
  "type": "array",
  "items": { "type": "string", "format": "email" },
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

Pour la validation de tuple (tableaux de longueur fixe avec des types spécifiques par position) :

{
  "type": "array",
  "prefixItems": [
    { "type": "number" },
    { "type": "string" },
    { "type": "boolean" }
  ],
  "items": false
}

Validation d'objet

Les objets supportent la validation de propriétés, les champs requis et le contrôle des propriétés additionnelles :

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "role": { "enum": ["admin", "editor", "viewer"] }
  },
  "required": ["name", "role"],
  "additionalProperties": false
}

Définir additionalProperties à false est un mode strict qui rejette toute propriété non définie dans le schéma. C'est particulièrement utile pour les API où vous voulez détecter les fautes de frappe dans les noms de champs.

Mots-clés de composition

JSON Schema prend en charge la combinaison de schémas à l'aide d'opérateurs logiques :

allOf (ET)

Les données doivent être valides par rapport à tous les sous-schémas :

{
  "allOf": [
    { "$ref": "#/$defs/baseUser" },
    { "properties": { "role": { "const": "admin" } } }
  ]
}

oneOf (OU exclusif)

Les données doivent être valides par rapport à exactement un des sous-schémas :

{
  "oneOf": [
    { "properties": { "type": { "const": "email" }, "email": { "type": "string" } } },
    { "properties": { "type": { "const": "phone" }, "phone": { "type": "string" } } }
  ]
}

anyOf (OU)

Les données doivent être valides par rapport à au moins un des sous-schémas.

Validation conditionnelle

Les mots-clés if/then/else permettent la validation conditionnelle :

{
  "type": "object",
  "properties": {
    "country": { "type": "string" },
    "postalCode": { "type": "string" }
  },
  "if": {
    "properties": { "country": { "const": "US" } }
  },
  "then": {
    "properties": { "postalCode": { "pattern": "^[0-9]{5}(-[0-9]{4})?$" } }
  },
  "else": {
    "properties": { "postalCode": { "pattern": "^[A-Z0-9 -]+$" } }
  }
}

Références et réutilisation

Utilisez $ref pour référencer des définitions réutilisables :

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "country": { "type": "string" }
      },
      "required": ["street", "city", "country"]
    }
  },
  "type": "object",
  "properties": {
    "billingAddress": { "$ref": "#/$defs/address" },
    "shippingAddress": { "$ref": "#/$defs/address" }
  }
}

Validation en pratique

JavaScript (Ajv)

const Ajv = require('ajv');
const ajv = new Ajv();

const validate = ajv.compile(schema);
const valid = validate(data);
if (!valid) console.log(validate.errors);

Python (jsonschema)

from jsonschema import validate, ValidationError

try:
    validate(instance=data, schema=schema)
except ValidationError as e:
    print(f"Validation error: {e.message}")

Pour une validation rapide sans configurer un environnement de développement, collez votre JSON et votre schéma dans notre Validateur JSON.

Exemple concret : Schéma de réponse API

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "enum": ["success", "error"] },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "required": ["id", "name"]
      }
    },
    "pagination": {
      "type": "object",
      "properties": {
        "page": { "type": "integer", "minimum": 1 },
        "perPage": { "type": "integer", "minimum": 1, "maximum": 100 },
        "total": { "type": "integer", "minimum": 0 }
      }
    }
  },
  "required": ["status", "data"]
}

FAQ

Quelle est la différence entre JSON Schema draft-07 et 2020-12 ?

Le draft 2020-12 a introduit plusieurs améliorations : prefixItems a remplacé la forme tuple de items, $dynamicRef permet des références plus flexibles, et le support des vocabulaires autorise les extensions personnalisées. Pour les nouveaux projets, utilisez 2020-12. Pour la compatibilité avec les outils plus anciens, draft-07 est encore largement supporté.

JSON Schema peut-il valider du JSON imbriqué dans un champ de type chaîne ?

Non, pas directement. JSON Schema valide la structure du JSON analysé. Si un champ contient une chaîne JSON, vous devez d'abord l'analyser et la valider séparément. Certains validateurs offrent des validateurs de format personnalisés qui peuvent gérer cela, mais ce n'est pas une fonctionnalité standard.

Ressources connexes

• Formateur JSON — Formatez et embellissez vos schémas JSON
• Comment valider du JSON — Erreurs courantes de validation JSON et corrections
• Patterns de conception d'API JSON — Construire de meilleures API REST avec JSON