Come generare un JSON Schema
- Incolla un esempio JSON rappresentativo. Gli array con più elementi danno i risultati migliori, perché i loro elementi vengono uniti in un unico schema.
- Scegli la versione dello schema (draft 2020-12 o draft-07) e decidi se le proprietà devono essere obbligatorie, se rilevare i formati e se vietare le proprietà aggiuntive.
- Copia o scarica lo schema, poi perfezionalo a mano – ad esempio aggiungendo descrizioni, enum o valori minimi e massimi.
Cosa deduce il generatore
| Esempio JSON | Schema |
|---|---|
"ada@example.com" | {"type": "string", "format": "email"} |
"2026-05-01T10:00:00Z" | formato date-time (anche date, time, uri, uuid, ipv4) |
42 / 4.5 | "integer" / "number" |
| una chiave presente in ogni oggetto | elencata in required |
| una chiave assente in alcuni elementi dell'array | facoltativa (non in required) |
[1, "a", null] | "items": {"type": ["string", "integer", "null"]} |
| oggetti mescolati a valori semplici | anyOf con uno schema per ciascun tipo |
Cos'è JSON Schema?
JSON Schema è un vocabolario per descrivere e validare la struttura dei dati JSON: quali proprietà esistono, che tipo ha ciascuna, quali sono obbligatorie e quali valori sono ammessi. Si usa per i contratti delle API in OpenAPI, per i file di configurazione, per generare moduli e per validare l'output strutturato dei modelli di intelligenza artificiale. La versione attuale è la 2020-12; la draft-07 è ancora supportata da molti strumenti meno recenti. La specifica è pubblicata su json-schema.org.
Perfezionare lo schema generato
- Aggiungi
titleedescriptionper documentare il significato di ogni campo. - Limita i valori con
enum,minimum,maximum,maxLengthopattern. - Spunta Non consentire proprietà aggiuntive (
additionalProperties: false) per rifiutare le chiavi sconosciute. - Valida i dati con Ajv in JavaScript o con il pacchetto
jsonschemain Python.
Domande frequenti
Quale versione di JSON Schema conviene usare?
Usa la draft 2020-12 per i nuovi progetti: è la versione attuale e la base di OpenAPI 3.1. Scegli la draft-07 se il tuo validatore o i tuoi strumenti non supportano ancora la 2020-12.
Perché tutte le mie proprietà sono obbligatorie?
Con un solo oggetto di esempio ogni proprietà è presente, quindi vengono tutte contrassegnate come obbligatorie. Usa un array con più esempi diversi tra loro oppure disattiva Segna le proprietà come obbligatorie.
Il generatore può rilevare enum o intervalli di valori?
No. Un solo esempio non può indicare quali valori sono ammessi in generale, quindi enum, valori minimi e massimi e pattern vanno aggiunti a mano.
Come si valida un JSON rispetto allo schema?
Usa una libreria di validazione come Ajv per JavaScript o jsonschema per Python. Molti editor di codice validano anche un file JSON rispetto allo schema indicato nella sua proprietà $schema.