Validazione JSON Schema: guida completa a draft e regole

Cos'è JSON Schema?

JSON Schema è un vocabolario per annotare e validare documenti JSON. Definisce la struttura, i tipi e i vincoli che un documento JSON deve soddisfare. Pensalo come un contratto — lo schema descrive come appaiono i dati validi, e i validatori verificano se un documento è conforme a quel contratto.

JSON Schema è scritta in JSON stesso, rendendola leggibile dalle macchine e indipendente dal linguaggio. È supportata da validatori in tutti i principali linguaggi di programmazione (JavaScript/Ajv, Python/jsonschema, Java/everit, Go/gojsonschema) ed è usata per la validazione API, i file di configurazione e la generazione di form.

Basi di JSON Schema

Le parole chiave principali definiscono la forma dei documenti JSON validi.

• type — specifica il tipo JSON consentito: string, number, integer, boolean, object, array o null. Il vincolo più fondamentale.
• properties e required — per gli oggetti, 'properties' definisce lo schema di ciascun campo e 'required' elenca quali campi devono essere presenti. I campi non in 'required' sono facoltativi per impostazione predefinita.
• enum e const — 'enum' limita un valore a un insieme fisso di scelte, mentre 'const' lo limita a un singolo valore esatto. Utile per campi di stato, categorie e opzioni di configurazione.
• pattern e format — 'pattern' valida le stringhe rispetto a un'espressione regolare. 'format' fornisce la validazione semantica come 'email', 'uri', 'date-time' e 'ipv4' senza regex.

Queste parole chiave di base coprono la maggior parte delle esigenze di validazione. Uno schema semplice potrebbe definire un tipo oggetto con la proprietà obbligatoria 'name' (stringa) e facoltativa 'age' (intero, minimo 0).

Funzionalità avanzate degli schema

Per requisiti di validazione complessi, JSON Schema offre composizione, riferimenti e logica condizionale.

• $ref riferimenti — riusa le definizioni dello schema referenziandole con $ref. Punta a definizioni all'interno dello stesso documento ($ref: #/$defs/Address) o file esterni. Elimina la duplicazione nei grandi schemi.
• allOf / anyOf / oneOf — parole chiave di composizione che combinano più schemi. 'allOf' richiede che tutti i sotto-schemi corrispondano, 'anyOf' richiede almeno uno e 'oneOf' richiede esattamente uno. Utile per tipi polimorfici.
• if / then / else — schemi condizionali che applicano diverse regole di validazione in base ai valori dei dati. Ad esempio, se il paese è 'US' allora il codice postale deve corrispondere a un pattern a 5 cifre, altrimenti consentire qualsiasi formato.
• additionalProperties — controlla se un oggetto può contenere proprietà non elencate in 'properties'. Imposta a false per la validazione rigorosa o a uno schema per vincolare le proprietà extra.

Versioni bozza degli schema

JSON Schema si è evoluta attraverso diverse versioni bozza, ognuna aggiungendo nuove funzionalità e perfezionando il comportamento esistente.

• Draft-04 — la prima versione ampiamente adottata. Ha introdotto $ref, required come array e parole chiave di validazione di base. Ancora usato in molti sistemi legacy e OpenAPI 3.0.
• Draft-06 — ha aggiunto la parola chiave const, propertyNames, contains per gli array e schemi booleani (true/false come schemi validi). Aggiunte minori ma utili.
• Draft-07 — ha aggiunto la logica condizionale if/then/else, le annotazioni readOnly/writeOnly e le parole chiave per la codifica del contenuto. La versione bozza più popolare oggi.
• 2019-09 (Draft 2019-09) — ristrutturazione importante. Ha introdotto $defs (in sostituzione di definitions), $anchor, unevaluatedProperties e il sistema di vocabolari. Migliore per la progettazione di schemi su larga scala.
• 2020-12 (Draft 2020-12) — l'ultima bozza stabile. Ha perfezionato i riferimenti dinamici, aggiunto prefixItems per la validazione di tuple (in sostituzione di items come array) e migliorato i formati di output. Raccomandato per i nuovi progetti.

Casi d'uso comuni

JSON Schema è usato ovunque i dati JSON debbano essere validati o documentati.

• Validazione API — valida i corpi delle richieste e i parametri di query rispetto agli schemi nei middleware Express/Fastify. Le specifiche OpenAPI/Swagger incorporano JSON Schema per la definizione del contratto API.
• Validazione della configurazione — valida i file di configurazione dell'applicazione (JSON, YAML convertito in JSON) all'avvio. Individua errori di battitura e campi mancanti prima che causino errori di runtime.
• Generazione di form — strumenti come react-jsonschema-form e vue-jsonschema-form generano automaticamente form HTML dalle definizioni JSON Schema, incluse regole di validazione e widget UI.
• Generazione di codice — genera interfacce TypeScript, struct Go o dataclass Python dalle definizioni JSON Schema. Mantiene i tipi sincronizzati con i contratti API.

Errori di validazione comuni

Quando si valida JSON rispetto a uno schema, questi sono gli errori più frequenti che si incontreranno.

• Mancata corrispondenza del tipo — il tipo del valore non corrisponde al vincolo 'type' dello schema. Esempi comuni: stringa dove si aspetta un numero, null per un campo non nullable, o un oggetto dove è richiesto un array.
• Campi obbligatori mancanti — l'oggetto JSON è privo di una proprietà elencata nell'array 'required'. I validatori segnalano quale campo specifico manca.
• Errore di pattern — un valore stringa non corrisponde alla regex 'pattern'. Questo rileva spesso formati email non validi, numeri di telefono o identificatori personalizzati che non seguono il pattern previsto.
• Errore di risoluzione $ref — lo schema fa riferimento a un altro schema tramite $ref che non può essere trovato. Ciò accade quando una voce $defs è mancante, il percorso è errato o i file schema esterni non sono accessibili.

Domande frequenti

Quale bozza di JSON Schema devo usare per nuovi progetti?

Usa Draft 2020-12 per nuovi progetti a meno che tu non abbia vincoli. Ha le funzionalità più avanzate (prefixItems per le tuple, unevaluatedProperties, riferimenti dinamici) e la migliore qualità delle specifiche. Se hai bisogno di compatibilità con OpenAPI 3.0, usa Draft-04. Se hai bisogno del supporto librerie più ampio, Draft-07 è la scelta più sicura — quasi tutti i validatori lo supportano.

Come posso riutilizzare gli schemi in più file?

Usa $ref per fare riferimento agli schemi tramite URI. Per le definizioni locali, inserisci gli schemi riutilizzabili sotto $defs nello stesso file e fai riferimento ad essi con $ref: '#/$defs/SchemaName'. Per i riferimenti tra file, usa URI relativi ($ref: './address.json') o URI assoluti. La maggior parte dei validatori supporta la risoluzione $ref sia locale che remota.

JSON Schema può validare oggetti annidati?

Sì. Definisci gli schemi annidati nelle 'properties' dell'oggetto padre. Ogni proprietà annidata può avere il proprio tipo, campi obbligatori e regole di validazione. Per le strutture profondamente annidate, usa $ref per mantenere lo schema leggibile. Non c'è limite alla profondità di annidamento — il validatore valida ricorsivamente ogni livello.