Validazione JSON Schema: Guida Completa per Definire e Validare i Dati JSON
Scopri come JSON Schema funziona come un contratto per i tuoi dati -- dai tipi base ai campi obbligatori, dalla validazione dei formati alle versioni draft e ai casi d'uso reali per API e file di configurazione.
Cos'e JSON Schema?
JSON Schema e un linguaggio dichiarativo che permette di descrivere la struttura, il contenuto e i vincoli di un documento JSON. Pensalo come un contratto tra un produttore e un consumatore di dati. Il produttore dice "inviero sempre un oggetto con una stringa name e un intero age", e il consumatore puo verificare che ogni payload in arrivo rispetti effettivamente questa promessa.
Questo e importante perche JSON stesso non ha schema. Qualsiasi valore JSON valido e perfettamente legale. Questa liberta e meravigliosa per la prototipazione rapida, ma diventa un problema quando due sistemi devono concordare su come devono apparire i dati.
Perche JSON Schema e importante per le API
Le API REST comunicano tramite payload JSON, e ogni endpoint ha una forma implicita. JSON Schema rende quella forma esplicita e leggibile dalle macchine. Con uno schema puoi:
- Validare le richieste sul server prima che raggiungano la logica di business.
- Validare le risposte nei test di integrazione per intercettare modifiche incompatibili.
- Generare documentazione automaticamente -- strumenti come Swagger/OpenAPI usano JSON Schema come colonna portante.
- Generare codice -- strumenti schema-to-TypeScript, schema-to-Go-struct eliminano le definizioni di tipo manuali.
Fondamenti di JSON Schema
Ogni JSON Schema e di per se un oggetto JSON. Lo schema piu semplice possibile e un oggetto vuoto {}, che accetta qualsiasi JSON valido.
Tipi primitivi
La parola chiave type e il fondamento. JSON Schema riconosce sei tipi primitivi:
| Tipo | Esempio JSON | Note |
|---|---|---|
| string | "ciao" | Valori di testo. Vincolabile con minLength, maxLength, pattern. |
| number | 3.14 | Qualsiasi valore numerico. Usa minimum, maximum, multipleOf. |
| integer | 42 | Solo numeri interi. Stessi vincoli di number. |
| boolean | true | Solo true o false. |
| object | {"chiave": "valore"} | Coppie chiave-valore. Definito con properties, required, additionalProperties. |
| array | [1, 2, 3] | Liste ordinate. Usa items, minItems, maxItems, uniqueItems. |
| null | null | L'assenza di un valore. Spesso combinato con un altro tipo. |
Proprieta e campi obbligatori
La parola chiave properties definisce quali chiavi sono attese. La parola chiave required elenca quali devono essere presenti.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1 },
"email": { "type": "string", "format": "email" },
"age": { "type": "integer", "minimum": 0 }
},
"required": ["name", "email"]
}Controllare le proprieta aggiuntive
"additionalProperties": false rende lo schema rigido -- solo le chiavi elencate sono permesse.
additionalProperties: false insieme a parole chiave di composizione come allOf, le proprieta definite in altri sotto-schemi possono essere rifiutate.
Validazione del formato
La parola chiave format fornisce validazione semantica oltre i tipi base.
Formati integrati
| Formato | Valore d'esempio | Caso d'uso |
|---|---|---|
| date-time | 2026-03-27T10:30:00Z | Timestamp ISO 8601 per eventi e log |
| date | 2026-03-27 | Date di calendario senza orario |
[email protected] | Moduli di contatto, registrazione utenti | |
| uri | https://example.com/api | URL webhook, link risorse |
| uuid | 550e8400-e29b-41d4-a716-446655440000 | Identificatori unici, chiavi primarie |
| ipv4 | 192.168.1.1 | Configurazione di rete, indirizzi server |
Formato come annotazione vs. asserzione
Per default, format e un'annotazione, non un'asserzione. In Draft 2020-12, devi abilitare esplicitamente l'asserzione di formato.
format con un regex pattern se la validazione rigorosa e critica.
Versioni draft: Draft-07 vs 2020-12
Le due versioni che incontrerai piu spesso sono Draft-07 e Draft 2020-12.
Differenze chiave
| Caratteristica | Draft-07 | Draft 2020-12 |
|---|---|---|
| prefixItems | Non disponibile | Sostituisce la validazione di tuple |
| $dynamicRef | Non disponibile | Nuovo -- riferimenti schema dinamici |
| unevaluatedProperties | Non disponibile | Risolve il problema additionalProperties + allOf |
| Supporto librerie | Eccellente | Buono e in crescita |
Quale versione scegliere?
Scegli Draft-07 se il tuo ecosistema lo usa gia o se hai bisogno della massima compatibilita.
Scegli Draft 2020-12 se stai iniziando un nuovo progetto senza vincoli legacy.
Conclusione
Per la maggior parte dei nuovi progetti nel 2026, Draft 2020-12 e la scelta predefinita migliore.
Come usare il nostro generatore JSON Schema
Il nostro Generatore JSON Schema gratuito prende qualsiasi payload JSON e produce automaticamente uno schema valido. Tutto funziona nel tuo browser.
Guida passo passo
- Apri lo strumento Generatore JSON Schema.
- Incolla il tuo JSON nell'area di input.
- Clicca su Genera e lo strumento analizera ogni campo, inferira i tipi e rilevera i formati.
- Esamina l'output -- lo schema generato appare nel pannello di output.
- Passa alla scheda Valida per testare il tuo schema contro nuovi payload.
- Copia lo schema con un clic e integralo nel tuo progetto.
Nota sulla privacy
Il nostro Generatore JSON Schema funziona al 100% nel tuo browser. I tuoi dati JSON, gli schemi generati e i risultati di validazione non lasciano mai il tuo dispositivo.
Genera il tuo JSON Schema istantaneamente
Incolla qualsiasi payload JSON e ottieni uno schema pronto all'uso con inferenza dei tipi, campi obbligatori e rilevamento del formato -- 100% nel tuo browser.