Panduan Lengkap JSON Schema: Validasi, Tipe, dan Praktik Terbaik

JSON Schema est le standard pour decrire la structure, les contraintes et les regles de validation des donnees JSON. Ce guide couvre les bases, les drafts, les mots-cles, $ref, et la validation en Python et JavaScript.

Essayez notre generateur gratuit JSON vers JSON Schema.

Qu'est-ce que JSON Schema ?

JSON Schema est un vocabulaire base sur JSON pour annoter et valider des documents JSON. Il definit les types de donnees, les proprietes requises et les contraintes.

JSON Schema est utilise pour la validation d'API (OpenAPI), la validation de fichiers de configuration, la generation de formulaires et la validation de bases de donnees de documents.

La specification a evolue a travers plusieurs drafts. Draft-07 est le plus largement supporte, Draft 2020-12 est la derniere version.

Versions des Drafts JSON Schema

JSON Schema a ete developpe a travers plusieurs versions :

Draft-07 offre le meilleur equilibre entre fonctionnalites et support.

Comment creer un JSON Schema a partir de JSON

Creer un JSON Schema implique l'analyse d'un document JSON et la production d'un schema decrivant sa structure :

// Example: Sample JSON input
{
  "id": 1,
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "age": 28,
  "is_active": true,
  "roles": ["admin", "editor"],
  "address": {
    "street": "123 Main St",
    "city": "Springfield",
    "zip": "62704"
  }
}

// Generated JSON Schema (Draft-07)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0 },
    "is_active": { "type": "boolean" },
    "roles": {
      "type": "array",
      "items": { "type": "string" }
    },
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "zip": { "type": "string", "pattern": "^[0-9]{5}$" }
      },
      "required": ["street", "city", "zip"]
    }
  },
  "required": ["id", "name", "email", "is_active"]
}

Mots-cles essentiels de JSON Schema

JSON Schema utilise un ensemble riche de mots-cles :

Exemples de code : Validation JSON

Python : bibliotheque jsonschema

La bibliotheque jsonschema est le validateur le plus populaire pour Python :

import json
from jsonschema import validate, ValidationError, Draft7Validator

# Define the schema
schema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"},
        "age": {"type": "integer", "minimum": 0, "maximum": 150},
        "roles": {
            "type": "array",
            "items": {"type": "string", "enum": ["admin", "editor", "viewer"]},
            "minItems": 1,
            "uniqueItems": True
        }
    },
    "required": ["name", "email"],
    "additionalProperties": False
}

# Valid data
valid_data = {
    "name": "Alice",
    "email": "alice@example.com",
    "age": 28,
    "roles": ["admin", "editor"]
}

# Validate
try:
    validate(instance=valid_data, schema=schema)
    print("Validation passed!")
except ValidationError as e:
    print(f"Validation failed: {e.message}")

# Collect all errors at once
invalid_data = {"name": "", "email": "not-an-email", "age": -5}
validator = Draft7Validator(schema)
errors = list(validator.iter_errors(invalid_data))
for error in errors:
    print(f"Error at {list(error.path)}: {error.message}")

JavaScript/Node.js : Ajv

Ajv est le validateur JSON Schema le plus rapide en JavaScript :

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

const ajv = new Ajv({ allErrors: true });
addFormats(ajv); // Adds "email", "uri", "date-time", etc.

const schema = {
  type: "object",
  properties: {
    name: { type: "string", minLength: 1 },
    email: { type: "string", format: "email" },
    age: { type: "integer", minimum: 0 },
    tags: {
      type: "array",
      items: { type: "string" },
      uniqueItems: true
    },
    address: {
      type: "object",
      properties: {
        street: { type: "string" },
        city: { type: "string" },
        country: { type: "string", default: "US" }
      },
      required: ["street", "city"]
    }
  },
  required: ["name", "email"],
  additionalProperties: false,
};

// Compile schema once, validate many times (fast!)
const validate = ajv.compile(schema);

const data = {
  name: "Bob",
  email: "bob@example.com",
  age: 35,
  tags: ["developer", "writer"],
  address: { street: "456 Oak Ave", city: "Portland" }
};

if (validate(data)) {
  console.log("Valid!");
} else {
  console.log("Errors:", validate.errors);
  // Each error: { keyword, dataPath, message, params }
}

Utiliser $ref pour des composants reutilisables

$ref permet de referencer des schemas definis ailleurs pour garder vos schemas DRY.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "billing_address": { "$ref": "#/definitions/Address" },
    "shipping_address": { "$ref": "#/definitions/Address" },
    "user": { "$ref": "#/definitions/User" }
  },
  "definitions": {
    "Address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "state": { "type": "string", "minLength": 2, "maxLength": 2 },
        "zip": { "type": "string", "pattern": "^[0-9]{5}(-[0-9]{4})?$" }
      },
      "required": ["street", "city", "state", "zip"]
    },
    "User": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" }
      },
      "required": ["name", "email"]
    }
  }
}

$ref utilise la syntaxe JSON Pointer. Dans Draft-07, les definitions sont sous "definitions". Dans 2020-12, sous "$defs".

L'utilisation extensive de $ref transforme votre schema en architecture modulaire.

Champs requis et valeurs par defaut

"required" est un tableau de noms de proprietes obligatoires.

"default" specifie une valeur par defaut. Le comportement varie selon le validateur.

Patterns de validation courants

Patterns pratiques pour le developpement d'API :

Validation email : "format": "email".

Validation date/heure : "format": "date-time".

Valeurs enum : "enum": [...].

Schemas conditionnels : if/then/else.

// Conditional schema: if/then/else (Draft-07+)
{
  "type": "object",
  "properties": {
    "account_type": { "enum": ["personal", "business"] },
    "name": { "type": "string" }
  },
  "required": ["account_type", "name"],
  "if": {
    "properties": { "account_type": { "const": "business" } }
  },
  "then": {
    "properties": {
      "company_name": { "type": "string", "minLength": 1 },
      "tax_id": { "type": "string", "pattern": "^[0-9]{2}-[0-9]{7}$" }
    },
    "required": ["company_name", "tax_id"]
  },
  "else": {
    "properties": {
      "date_of_birth": { "type": "string", "format": "date" }
    }
  }
}

Bonnes pratiques JSON Schema

Commencez avec Draft-07 pour le meilleur support.

Utilisez additionalProperties: false avec prudence.

Organisez avec $ref pour la reutilisabilite.

Ajoutez title et description pour la documentation.

Utilisez les mots-cles format pour les types semantiques.

Testez avec plusieurs validateurs.

Versionnez vos schemas avec $id.

Outils connexes : JSON Formatter, JSON Validator, JSON to TypeScript.

JSON to JSON SchemaJSON FormatterJSON ValidatorJSON to TypeScript

Questions frequemment posees

Comment generer un JSON Schema a partir d'un fichier JSON ?

Utilisez notre outil gratuit en ligne pour generer instantanement un schema Draft-07 avec types inferes et champs requis.

Quelle difference entre Draft-07 et Draft 2020-12 ?

Draft 2020-12 ajoute $dynamicRef, prefixItems, et traite format comme annotation par defaut. Draft-07 a un meilleur support.

JSON Schema peut-il valider des objets imbriques ?

Oui, avec properties pour les objets et items pour les tableaux, avec une profondeur arbitraire.

Comment rendre un champ optionnel ?

Omettez le nom du champ du tableau required. Les proprietes definies mais non requises sont optionnelles.

Quels sont les meilleurs validateurs JSON Schema ?

Python : jsonschema. JavaScript : Ajv. Les deux sont maintenus activement.

JSON Schema est essentiel pour valider et documenter les donnees JSON. Utilisez notre outil gratuit pour generer des schemas.

Generez un JSON Schema instantanement avec notre outil gratuit.

Related Developer Tools and Guides

• JSON to JSON Schema Generator - Generate JSON Schema from any JSON data
• JSON Formatter - Format and beautify JSON data
• JSON Validator - Validate JSON syntax and structure
• JSON to TypeScript Converter - Generate TypeScript interfaces from JSON
• JSON to Go Converter - Create Go structs from JSON
• JSON to Java Converter - Generate Java classes from JSON
• JSON to Kotlin Converter - Create Kotlin data classes from JSON
• JSON to Python Converter - Generate Python dataclasses from JSON
• JSON to YAML Converter - Convert between JSON and YAML formats
• JSON vs YAML vs TOML - Comparison of configuration formats