JSON Schema è un modo per descrivere quale dovrebbe essere la struttura di un documento JSON, usando un altro documento JSON. Invece di validare i dati a mano con condizioni nel codice, si possono descrivere in modo dichiarativo i tipi attesi, i campi obbligatori e i vincoli sui valori, e poi verificare i dati automaticamente.
Parole chiave principali di draft-07
type— il tipo di valore atteso (object, string, number, array, ecc.).required— l'elenco dei campi dell'oggetto che devono essere obbligatoriamente presenti.properties— la descrizione dello schema per ciascun campo dell'oggetto individualmente.enum— limita un valore a un insieme specifico di opzioni.pattern— valida una stringa con un'espressione regolare, ad esempio per il formato della Partita IVA.
Esempio: pattern per la Partita IVA italiana
La Partita IVA italiana è composta da esattamente 11 cifre. Uno schema per un campo di fatturazione in un'API B2B può descriverla così: "partitaIva": {"type": "string", "pattern": "^\\d{11}$"}. Questo non verifica il carattere di controllo calcolato con l'algoritmo ufficiale — per quello serve una logica dedicata — ma respinge subito gli errori più comuni: un numero con spazi, confuso con il Codice Fiscale (16 caratteri alfanumerici, tutt'altro formato), o con una lunghezza sbagliata copiata da una fattura scansionata.
In cosa differisce dalla validazione della sintassi
La normale validazione JSON verifica solo che il testo sia sintatticamente corretto — parentesi, virgolette, virgole al posto giusto. JSON Schema verifica molto di più: se un oggetto ha un campo obbligatorio email, se il valore di age è un numero e non una stringa, se status rientra nell'elenco di valori consentiti.
A cosa serve
- Verificare che la risposta di un'API di terze parti rispetti il contratto documentato.
- Validare i file di configurazione prima del deploy per individuare un errore in anticipo.
- Documentare la struttura dati attesa in un formato verificabile automaticamente da subito.
additionalProperties: si possono aggiungere campi extra?
Per impostazione predefinita, JSON Schema consente nell'oggetto qualsiasi campo oltre a quelli descritti in properties — required e properties stabiliscono solo un minimo, non un elenco esaustivo. Se serve vietare campi sconosciuti, bisogna aggiungere esplicitamente "additionalProperties": false — senza questo flag lo schema rimane "aperto".