Generatore schema JSON

A cosa serve JSON Schema

JSON Schema è un modo dichiarativo per descrivere come dovrebbe essere un documento JSON: quali proprietà ha, quali tipi contengono quelle proprietà, cosa è obbligatorio rispetto a cosa è opzionale, e quali valori sono validi. È l'equivalente nel mondo JSON di XSD per XML o di una definizione di tabella di database. Il progetto ufficiale vive su json-schema.org.

Dove lo incontrerai nel mondo reale:

• Contratti API. OpenAPI 3.1 (rilascio di febbraio 2021) incorpora direttamente JSON Schema: ogni corpo di richiesta e di risposta in una specifica API moderna è descritto con un frammento di JSON Schema.
• Autocompletamento e validazione nell'IDE. settings.json di VS Code, il package.json e tsconfig.json del tuo progetto, i file workflow.yml di GitHub Actions: tutti si completano e vengono controllati rispetto agli JSON Schema pubblicati.
• Validazione lato server. Express / Fastify / Spring / Flask / FastAPI / Echo si integrano tutti con validatori JSON Schema (AJV, jsonschema, fastjsonschema) per rifiutare corpi di richiesta malformati prima che arrivino alla logica di business.
• Generazione di codice. Strumenti come quicktype, json-schema-to-typescript e datamodel-code-generator trasformano uno schema in struct Go, tipi TypeScript, dataclass Python, POJO Java, ecc., fornendo tipi agnostici rispetto al linguaggio da una singola sorgente.
• Documentazione. Uno schema funge anche da documentazione leggibile dalle macchine per qualunque dato a forma di JSON che pubblichi.

I draft che incontrerai nel mondo reale

La specifica di JSON Schema è stata pubblicata come una serie di draft. Il draft stabile attuale è 2020-12 (dalla pagina ufficiale della specifica: "The current version is 2020-12"). I draft che potresti incontrare:

• Draft 4, vecchio ma ancora in uso; OpenAPI 3.0 usava un sottoinsieme esteso della JSON Schema Specification Wright Draft 00 (a volte informalmente chiamata Draft 5), vicina ma non identica al Draft 4.
• Draft 6, Draft 7, il Draft 7 (2018) è stato il draft di produzione dominante per anni ed è ancora molto comune negli strumenti legacy.
• Draft 2019-09, primo draft a usare la convenzione di identificatore anno-mese; ha introdotto $defs accanto al vecchio keyword definitions.
• Draft 2020-12, il draft stabile attuale e ciò che questo generatore emette. Allineato con OpenAPI 3.1.

Nel dubbio, scegli il draft che corrisponde al tuo validatore. AJV (il validatore JavaScript più popolare) supporta i Draft 04, 06, 07, 2019-09 e 2020-12 con opt-in esplicito. jsonschema in Python fa lo stesso. Se non sai cosa vuole il tuo consumatore a valle, 2020-12 è un default sicuro per nuovi lavori.

I tipi integrati

JSON Schema descrive sette tipi base che corrispondono ai tipi di valore di JSON:

Le parole chiave di composizione ti permettono di mescolare e abbinare: oneOf (esattamente uno), anyOf (almeno uno), allOf (ognuno), not (l'inverso). Più enum per una lista finita di valori ammessi e const per un singolo valore fisso.

Cosa uno schema generato automaticamente può e non può dirti

Inferire uno schema da un singolo esempio JSON è potente ma limitato. Il generatore può rilevare:

• Il tipo di ogni valore foglia (stringa, numero, booleano, array, oggetto).
• La struttura di oggetti e array annidati.
• Le chiavi che compaiono nell'esempio (e marcarle come required se attivi l'opzione).

Non può rilevare:

• Campi opzionali. Una chiave nel tuo esempio potrebbe essere opzionale nella specifica reale, ma un singolo esempio non può dirtelo. Per impostazione predefinita tutto appare obbligatorio.
• Suggerimenti di formato. La stringa "2024-04-12" sembra una data, ma potrebbe anche essere un'etichetta libera che si presenta a forma di data. Aggiungi format: date a mano se il campo è davvero tale.
• Vincoli di validazione. Lunghezza massima, valori enum ammessi, pattern regex: tutto richiede input umano.
• Stringhe di documentazione. title, description ed examples su ciascun campo migliorano l'esperienza dello sviluppatore ma richiedono cura manuale.
• Varianti. Se un campo può essere stringa o numero a seconda del contesto, un singolo esempio sceglierà uno e tralascerà l'altro. Combina più esempi o usa oneOf manualmente.

Tratta l'output come un punto di partenza fatto al 70%. Le aggiunte di valore (quali campi sono davvero obbligatori, quali formati di stringa si applicano, quali intervalli di valori sono ammessi, cosa significa ogni campo) sono il passo di rifinitura umana.

Due trappole sottili che vale la pena conoscere

• format è informativo per impostazione predefinita nel 2020-12. Il vocabolario format-annotation marca format: email come un suggerimento, non una regola di validazione rigida, a meno che il tuo validatore non attivi esplicitamente format-assertion. Quindi una stringa che non corrisponde alla regex dell'email per impostazione predefinita passa comunque. La modalità strict di AJV e il pacchetto ajv-formats aggiungono la validazione completa del formato; controlla i default del tuo validatore prima di affidarti ai controlli di formato per input critici per la sicurezza.
• additionalProperties: false non collabora bene con allOf. Se componi schemi con allOf per una validazione in stile ereditarietà, additionalProperties: false su un ramo non vede le proprietà definite in rami fratelli, quindi campi legittimi falliscono la validazione. La soluzione nel Draft 2019-09+ è unevaluatedProperties: false, che è consapevole della composizione.

JSON Schema contro Zod / Joi / Yup contro i tipi TypeScript

Diverse tecnologie si sovrappongono al ruolo di JSON Schema; ognuna ha il suo punto di forza:

• JSON Schema. JSON dichiarativo, convalida a runtime, agnostico rispetto al linguaggio. Vince quando i contratti API attraversano i confini tra linguaggi (per esempio un server Go, una pipeline di dati Python e un frontend TypeScript che consumano tutti la stessa API).
• Tipi TypeScript. Solo a tempo di compilazione. Bellissimi per la sicurezza dei tipi in-process dentro un codebase TS, ma scompaiono a runtime e non offrono alcuna convalida del JSON in ingresso. Strumenti come json-schema-to-typescript generano tipi da uno schema per ottenere il meglio dei due mondi.
• Zod, Joi, Yup. Convalida a runtime code-first in JavaScript o TypeScript, con inferenza TypeScript integrata. Singolo linguaggio, ma eccellente esperienza per lo sviluppatore dentro quel linguaggio. Gli schemi sono oggetti JS, non JSON portabile.
• Pydantic e Marshmallow. Gli equivalenti Python: convalida a runtime basata su classi con i type hint Python.

Se il tuo schema deve essere consumato da più linguaggi o da strumenti (IDE, tooling OpenAPI, generatori di codice), JSON Schema è il posto giusto. Se resti all'interno di un singolo linguaggio, l'opzione nativa del linguaggio è di solito più piacevole da scrivere.

Casi d'uso comuni

• Bootstrap di una specifica OpenAPI. Incolla una risposta API reale, genera lo schema, mettilo nei tuoi components.schemas.
• Generare tipi TypeScript / Go / Python tramite quicktype o simili, fornendo tipi agnostici rispetto al linguaggio da una singola sorgente.
• Validare input non fidati su un endpoint server con AJV / jsonschema / Pydantic.
• Scrivere autocompletamento IDE per un formato di configurazione personalizzato. VS Code, gli IDE di JetBrains e altri leggono gli JSON Schema per alimentare l'autocompletamento dei file JSON.
• Documentare la forma di un file di configurazione per i consumatori a valle.
• Migrazione tra formati di dati. Uno JSON Schema generato da una sorgente può guidare validazione, trasformazione o documentazione a valle.

Errori comuni

1. Trattare lo schema generato automaticamente come la specifica finale. È un punto di partenza. Aggiungi suggerimenti di formato, marca i campi davvero opzionali, aggiungi documentazione, imposta intervalli di valori.
2. Dimenticare la dichiarazione $schema. I validatori la usano per sapere quale draft applicare. Includila sempre in cima allo schema.
3. Trattare required come un attributo per proprietà. A differenza di XSD o degli schemi Mongoose, required in JSON Schema è un array al livello dell'oggetto genitore che elenca i nomi delle proprietà obbligatorie.
4. Dimenticare additionalProperties: false quando vuoi una validazione stretta. Il valore predefinito è true, ovvero le chiavi sconosciute sono ammesse silenziosamente.
5. Confondere enum con examples. enum = la lista dei valori ammessi (validazione). examples = valori di esempio solo a scopo documentale (nessun effetto di validazione).
6. Assumere che format sia imposto. Per impostazione predefinita nel Draft 2020-12 è un'annotazione, non un'asserzione; la tua regex per email non verrà eseguita se non attivi l'opzione.
7. Inferire l'opzionalità da un singolo esempio. Ogni chiave del tuo esempio diventa obbligatoria per impostazione predefinita. Le specifiche reali hanno quasi sempre campi opzionali; rimuovili dall'array required come parte della rifinitura.

Altre domande frequenti

Lo schema funzionerà con OpenAPI 3.1?

Sì. OpenAPI 3.1 (rilasciato a febbraio 2021) ha allineato il suo linguaggio di schemi pienamente con JSON Schema Draft 2020-12, che è ciò che questo generatore emette. Inserisci lo schema in components.schemas nel tuo documento OpenAPI e richiamalo via $ref. OpenAPI 3.0 più vecchio usava un sottoinsieme precedente; potresti dover fare delle modifiche se punti al 3.0.

Posso generare tipi nel mio linguaggio da questo schema?

Sì. quicktype genera TypeScript, Go, Python, Java, C#, Swift, Kotlin, Rust, Elm e altri da uno JSON Schema. json-schema-to-typescript è un'alternativa specifica per JS. La maggior parte dei linguaggi moderni ha almeno uno strumento da schema a tipi; lo schema generato funziona come input per tutti loro.

Qual è la differenza tra $defs e definitions?

Entrambi sono luoghi dove inserire sotto-schemi riutilizzabili che puoi richiamare con $ref altrove nel documento. definitions è il nome legacy, usato nei Draft 04, 06 e 07. $defs è il nome attuale, introdotto nel Draft 2019-09 e mantenuto nel 2020-12. Funzionalmente equivalenti, ma usa $defs per i lavori nuovi.

Il mio JSON viene inviato da qualche parte?

No. La generazione dello schema gira interamente nel tuo browser. Il JSON incollato viene analizzato localmente, percorso ed emesso come schema nella textarea di output. Nulla viene caricato su un server, nulla viene registrato, nulla viene conservato dopo la chiusura della scheda. Conta perché gli esempi JSON contengono spesso dati reali (record dei clienti, risposte API interne, informazioni sui dipendenti) che non vuoi facoltativamente far passare per una terza parte.

Perché lo schema del mio array descrive solo il primo elemento?

L'inferenza da un singolo esempio tratta gli array come omogenei: guarda il primo elemento e assume che il resto corrisponda. Se il tuo array reale può contenere forme diverse, dovrai scrivere a mano items come { "oneOf": [...] }. Oppure esegui il generatore su ogni variante separatamente e combina gli schemi.

Devo proprio usare un generatore, o scrivere lo schema a mano?

Per uno schema piccolo che controlli da capo a piedi, scriverlo a mano ti insegna la specifica più in fretta. Per una risposta API grande con dozzine di oggetti annidati, generare ti porta a una bozza in pochi secondi e dedichi il tempo risparmiato a curare vincoli, descrizioni e array required. La maggior parte degli sviluppatori che lavorano fa entrambe le cose: genera, poi rifinisce.