Validazione JSON Schema: La Guida Definitiva

JSON Schema è un vocabolario per annotare e validare documenti JSON. Fornisce un contratto per i tuoi dati — definendo quale forma dovrebbero avere, quali tipi sono accettabili e quali campi sono obbligatori. Se lavori con API, file di configurazione o qualsiasi dato strutturato, JSON Schema è uno strumento essenziale nel tuo arsenale.

Perché Usare JSON Schema?

Senza validazione, i dati JSON sono un'incognita. Potresti ricevere un campo età come stringa, un'email mancante o una data nel formato sbagliato. JSON Schema intercetta questi problemi al confine, prima che i dati errati si propaghino nel tuo sistema.

Vantaggi principali:

• Applicazione del contratto API: Valida automaticamente i body di request e response
• Documentazione: Lo schema serve come documentazione vivente delle tue strutture dati
• Generazione di codice: Gli strumenti possono generare tipi, form e schemi database da JSON Schema
• Testing: Valida fixture di test e dati mock rispetto allo schema

Struttura Base dello Schema

Ogni JSON Schema inizia con alcune proprietà 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"]
}

Usa il nostro JSON Formatter per formattare i tuoi schema e renderli più leggibili prima di condividerli con il team.

Vincoli di Tipo

JSON Schema supporta sei tipi primitivi:

Vincoli per le Stringhe

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

I formati integrati includono: email, uri, date, date-time, ipv4, ipv6, uuid e hostname.

Vincoli per i Numeri

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

Validazione degli Array

Gli array possono essere validati per i loro elementi, lunghezza e unicità:

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

Per la validazione di tuple (array a lunghezza fissa con tipi specifici per posizione):

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

Validazione degli Oggetti

Gli oggetti supportano la validazione delle proprietà, campi obbligatori e controllo delle proprietà aggiuntive:

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

Impostare additionalProperties a false è una modalità strict che rifiuta qualsiasi proprietà non definita nello schema. Questo è particolarmente utile per le API dove vuoi intercettare errori di battitura nei nomi dei campi.

Parole Chiave di Composizione

JSON Schema supporta la combinazione di schema usando operatori logici:

allOf (AND)

I dati devono essere validi rispetto a tutti i sotto-schema:

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

oneOf (XOR)

I dati devono essere validi rispetto a esattamente uno dei sotto-schema:

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

anyOf (OR)

I dati devono essere validi rispetto ad almeno uno dei sotto-schema.

Validazione Condizionale

Le parole chiave if/then/else abilitano la validazione condizionale:

{
  "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 -]+$" } }
  }
}

Riferimenti e Riuso

Usa $ref per fare riferimento a definizioni riutilizzabili:

{
  "$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" }
  }
}

Validazione nella Pratica

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}")

Per una validazione rapida senza configurare un ambiente di sviluppo, incolla il tuo JSON e lo schema nel nostro JSON Validator.

Esempio Reale: Schema di Risposta 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

Qual è la differenza tra JSON Schema draft-07 e 2020-12?

Il Draft 2020-12 ha introdotto diversi miglioramenti: prefixItems ha sostituito la forma tuple di items, $dynamicRef abilita riferimenti più flessibili, e il supporto ai vocabolari consente estensioni personalizzate. Per i nuovi progetti, usa 2020-12. Per la compatibilità con strumenti più vecchi, draft-07 è ancora ampiamente supportato.

JSON Schema può validare JSON annidato all'interno di un campo stringa?

No, direttamente. JSON Schema valida la struttura del JSON già parsato. Se un campo contiene una stringa JSON, dovresti prima analizzarla e validarla separatamente. Alcuni validatori offrono validatori di formato personalizzati che possono gestire questo caso, ma non fa parte dello standard.

Risorse Correlate

• JSON Formatter — Formatta e abbellisci i tuoi JSON schema
• Come Validare JSON — Errori comuni di validazione JSON e correzioni
• Pattern di Design per API JSON — Costruire API REST migliori con JSON