In questo articolo
Cos'e JSON Schema?
JSON Schema e un vocabolario che permette di descrivere la struttura e le regole di validazione per i dati JSON. Scritto in JSON stesso, uno schema definisce quali proprieta puo avere un oggetto, quali tipi sono consentiti, quali campi sono obbligatori e quali vincoli si applicano -- trasformando contratti dati informali in specifiche leggibili dalle macchine.
La versione piu utilizzata e Draft-07, sebbene le versioni piu recenti (2019-09, 2020-12) aggiungano funzionalita come schemi condizionali e riferimenti dinamici. Un generatore di JSON Schema automatizza il tedioso processo di scrittura manuale degli schemi -- analizza dati JSON di esempio e deduce automaticamente tipi, struttura e campi obbligatori.
Come funziona la generazione di schemi
Un generatore di schemi esamina il JSON di esempio e produce uno schema che lo validerebbe. Il processo coinvolge inferenza dei tipi, analisi della struttura e rilevamento dei vincoli.
- Inferenza dei tipi -- ogni valore viene ispezionato per determinare il suo tipo JSON (string, number, integer, boolean, null, array, object) e lo schema assegna la parola chiave di tipo corrispondente
- Analisi della struttura annidata -- gli oggetti vengono analizzati ricorsivamente per generare sotto-schemi per ogni proprieta, e gli array vengono ispezionati per dedurre lo schema degli elementi dal loro contenuto
- Rilevamento dei campi obbligatori -- tutte le proprieta presenti nell'esempio vengono tipicamente contrassegnate come obbligatorie, poiche il generatore presume che l'esempio rappresenti un'istanza valida completa
Prova gratuitamente — nessuna registrazione richiesta
Genera un JSON Schema →Quando usare JSON Schema
JSON Schema e uno strumento fondamentale per qualsiasi progetto che invia o riceve dati JSON.
- Validazione delle richieste API -- validare i payload in entrata rispetto a uno schema prima dell'elaborazione, rifiutando le richieste mal formate in anticipo e fornendo messaggi di errore chiari ai consumatori dell'API
- Generazione di moduli -- librerie UI come react-jsonschema-form e vue-form-generator possono generare moduli automaticamente da un JSON Schema, mantenendo sincronizzate la validazione backend e l'interfaccia frontend
- Test dei contratti in CI/CD -- verificare che le risposte API corrispondano allo schema previsto nei test di integrazione, individuando modifiche incompatibili prima che raggiungano la produzione
Domande frequenti
Quale versione draft di JSON Schema dovrei usare?
Draft-07 e la scelta piu sicura per un'ampia compatibilita -- la maggior parte dei validatori, generatori di moduli e generatori di codice lo supporta pienamente. Usare 2020-12 se servono funzionalita avanzate come $dynamicRef, prefixItems o unevaluatedProperties. Verificare sempre che la propria libreria di validazione supporti il draft scelto.
Come combinare piu schemi?
JSON Schema fornisce parole chiave di composizione: allOf richiede che tutti i sotto-schemi corrispondano, anyOf richiede che almeno uno corrisponda, e oneOf richiede che esattamente uno corrisponda. Usare $ref per riferire definizioni di schema riutilizzabili. Ad esempio, uno schema User potrebbe usare allOf per combinare uno schema PersonSchema base con campi di autenticazione aggiuntivi.
Si possono generare tipi TypeScript da un JSON Schema?
Si. Strumenti come json-schema-to-typescript e quicktype convertono JSON Schemas in interfacce TypeScript, assicurando che i tipi frontend restino sincronizzati con i contratti backend. Questo e particolarmente utile nei monorepo dove lo schema funge da unica fonte di verita sia per la validazione API che per il controllo dei tipi lato client.