DevToolBoxGRATIS
Blogg

JSON Schema Komplett Guide: Validering, Typer och Bästa Praxis

15 minby DevToolBox

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 :

DraftAnneeAjouts clesIdeal pour
Draft-042013Vocabulaire de base, $refSystemes anciens
Draft-072018if/then/elseLa plupart des projets
2020-122020$dynamicRef, prefixItemsNouveaux projets

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 :

  1. Identifier le type racine
  2. Definir les proprietes
  3. Definir les champs requis
  4. Ajouter des contraintes
  5. Gerer les objets imbriques
  6. Gerer les tableaux
  7. Ajouter les metadonnees
// 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 :

CategorieMots-clesUsage
Typetype, enum, constTypes et valeurs permises
Objetproperties, requiredForme de l'objet
CompositionallOf, anyOf, oneOfCombiner des schemas

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

𝕏 Twitterin LinkedIn
Var detta hjälpsamt?

Håll dig uppdaterad

Få veckovisa dev-tips och nya verktyg.

Ingen spam. Avsluta när som helst.

Try These Related Tools

{ }JSON Formatter✓JSON Validator✨JSON Beautifier

Related Articles

JSON Schema Validering: Typer, verktyg och bästa praxis

Allt om JSON Schema-validering: från grundläggande typer till avancerade mönster, valideringsbibliotek och integration med TypeScript och API:er.

JSON Formatter & Validator: Formatera och Validera JSON Online

Gratis online JSON-formaterare och validator. Formatera JSON, hitta syntaxfel med kodexempel i JavaScript och Python.

JSON vs YAML vs TOML: Vilket konfigformat ska du använda?

Jämför konfigurationsformaten JSON, YAML och TOML.