Ho spedito abbastanza API per conoscere il momento esatto in cui un progetto ha bisogno di uno schema JSON Non è mai all'inizio Sono passate tre settimane, quando un secondo team inizia a consumare il tuo endpoint, qualcuno invia un corpo di richiesta non valido e un null scivola in un campo che tutti presumevano fosse sempre una stringa All'improvviso hai bisogno di un contratto - un documento che dice, in una forma che una macchina può far rispettare, & quot; ecco come appare un payload valido.& quot; Quel documento è uno schema JSON e scriverne uno a mano da un endpoint che restituisce già dati reali è uno dei lavori più noiosi nel lavoro di backend.
tl; dr: Incolla un campione JSON nel Generatore di schemi JSON, scegli Draft-07 o 2020-12 e deduce uno schema: tipi,
requiredcampi, elementi di array uniti e formati di stringa comedate-timeeuuid. Funziona interamente nel tuo browser, quindi i payload che trasportano token e dati personali non lasciano mai la pagina Tratta l'output come una prima bozza forte, quindi stringilo con i vincoli che solo tu conosci.
Ho costruito questo strumento per Toolz.dev perché continuavo a fare la stessa cosa a mano: aprire un corpo di risposta, strizzare gli occhi su di esso e trascrivere la sua forma in uno schema clausola per clausola È ripetitivo e la trascrizione ripetitiva è dove si nascondono gli errori Questa guida spiega cosa fa il generatore, dove l'inferenza è affidabile, dove ha bisogno del tuo giudizio e come uno schema generato si inserisce in un flusso di lavoro di convalida reale.
Cos'è uno schema JSON e perché generarne uno dai dati?
JSON Schema è un vocabolario per descrivere la struttura di JSON, mantenuto come una specifica a sé stante piuttosto che come convenzione Uno schema è esso stesso un documento JSON che dichiara il tipo previsto di ogni campo, quali campi sono richiesti, quale forma assumono gli oggetti e gli array nidificati e - con parole chiave come pattern, enum, minimum, e format - quali valori sono effettivamente consentiti I validatori in quasi tutte le lingue leggono uno schema e ti dicono se un dato documento è conforme È la cosa più vicina che il mondo JSON ha a un sistema di tipi che viaggia oltre i confini del servizio.
Il motivo per generare uno schema da un campione, piuttosto che scriverlo da zero, è che la maggior parte di uno schema è meccanico Camminare su un payload e registrare & quot; questa è una stringa, questo è un numero intero, questo oggetto ha queste chiavi" è esattamente il tipo di lavoro che una macchina dovrebbe fare Che cos'è no meccanico è lo strato semantico: sapere che status può essere solo una delle quattro corde, quella age non può essere negativo, quello email deve corrispondere a un modello di indirizzo reale Generation gestisce l'impalcatura meccanica in modo da poter spendere la tua attenzione sui vincoli che contano Si parte da un documento che già corrisponde alla realtà e si aggiungono regole, invece di partire da un file vuoto e sperare di ricordare ogni campo.
C'è anche una dimensione di fiducia Quando digiti uno schema a mano, codifichi ciò che ti credere ritorna l'endpoint Le credenze vanno alla deriva dalla realtà - un campo viene aggiunto, un numero intero diventa nullable, un endpoint che ha restituito un singolo oggetto inizia a restituire un array Uno schema generato da una risposta effettiva è ancorato a ciò che il servizio inviato genuinamente il giorno in cui l'hai catturato Quell'ancora vale molto quando stai debuggando perché la convalida passa nella messa in scena e fallisce nella produzione.
Come il generatore deduce uno schema
Il motore analizza il tuo JSON e cammina il valore in modo ricorsivo, emettendo un nodo schema per ogni parte della struttura Le regole sono volutamente conservative, perché uno schema troppo loose è inutile e uno schema troppo rigido rifiuta i dati validi.
Per gli scalari, distingue integer a number - 42 diventa integer, 4.2 diventa number - perché questa distinzione è significativa per i validatori e per chiunque legga lo schema. Booleani e null mappa ai propri tipi Strings diventano type: string, e se il rilevamento del formato è attivo, il motore controlla il valore rispetto a un insieme di modelli ben noti e lo tagga: date-time, date, time, email, uri, uuid, e ipv4.
Per gli oggetti, registra ogni chiave, deduce uno schema per ogni valore e - se required l'inferenza è abilitata - segna una chiave richiesta quando è presente in ogni oggetto in quella posizione Per un singolo oggetto che significa tutte le chiavi; il caso interessante sono gli array.
Per gli array di oggetti, il generatore fa qualcosa di più utile di una camminata ingenua Invece di emettere uno schema separato per ogni elemento o uno sprawling anyOf di forme quasi identiche, unisce tutti gli oggetti dell'array in uno solo items schema che descrive un singolo elemento È richiesta una chiave presente in ogni elemento; una chiave presente solo in alcuni elementi è lasciata facoltativa Questo rispecchia il comportamento delle raccolte API reali: un elenco impaginato in cui la maggior parte dei record trasporta un avatarUrl ma alcuni no. Lo schema unito cattura & quot;questi campi appaiono sempre, questi a volte appaiono& quot; in una definizione leggibile Puoi vederlo nel campione integrato, dove il members array ha due oggetti: uno con un active campo e uno senza - e i segni dello schema degli elementi generati id e role richiesto ma lascia active facoltativo.
Per array di scalari misti, il motore comprime i tipi di elementi in un unico type array - ["integer", "string", "boolean"] - piuttosto che un'unione prolissa Quando le forme oggetto e non oggetto si mescolano genuinamente in un array, ricade su anyOf, che è il costrutto corretto dello schema JSON per & quot; una di queste alternative."
Come utilizzare il JSON Schema Generator
Passaggio 1: incollare un campione rappresentativo
Rilascia una risposta API, un dispositivo, un file di configurazione o un corpo webhook La singola cosa più importante che puoi fare per la precisione è incollare un rappresentante campione Se si dispone di diversi record da una risposta reale, includerli tutti all'interno di un array - il generatore li unirà e dedurrà l'opzionalità correttamente Un campione di un record dice al motore che ogni campo che vede è sempre presente, il che è spesso sbagliato Carica prima il campione incorporato per vedere come vengono gestiti gli oggetti nidificati, gli array di oggetti e le stringhe formattate prima di incollare il tuo.
Passo 2: Scegli il dialetto
Scegli Draft-07 per la più ampia compatibilità tra le librerie di convalida o 2020-12 per la specifica corrente Lo strumento scrive il corretto $schema identificatore sulla radice in modo che il tuo validatore applichi le regole giuste Per le forme di oggetti e array prodotte da questo generatore, l'output strutturale è lo stesso in entrambi i dialetti; la differenza visibile è l'identificatore Se non sei sicuro di quale sia il tuo strumento di supporto, Draft-07 è il default sicuro: ha il supporto della libreria più ampio di qualsiasi versione.
Passaggio 3: imposta le opzioni
Aggiungi un title se si desidera che lo schema si auto-documenti Decidi se emettere required - la maggior parte delle volte lo si desidera, ma durante l'esplorazione iniziale si può preferire uno schema più flessibile Mantenere il rilevamento del formato attivo a meno che non si vedano falsi positivi E attivare la modalità rigorosa (additionalProperties: false) quando lo schema protegge qualcosa che controlli completamente, come un file di configurazione o un corpo di richiesta, e desideri che le chiavi impreviste vengano rifiutate anziché ignorate.
Passaggio 4: generare, rivedere ed esportare
Premere Genera, quindi leggere l'output in modo critico Controlla che required corrisponde al tuo intento, che il numero intero contro il numero è uscito correttamente e che tutti i formati rilevati sono corretti anziché casuali Quando sembra giusto, copia lo schema o scaricalo come a .json file pronto per essere inserito nel validatore o nel repository.
Un esempio lavorato
Considera questa risposta da un ipotetico /projects punto finale:
{
"id": "5b2a1f6e-8c3d-4a1b-9f7e-2c1d3e4f5a6b",
"name": "Toolz",
"createdAt": "2026-01-14T09:30:00Z",
"score": 4.8,
"members": [
{ "id": 1, "role": "owner", "active": true },
{ "id": 2, "role": "editor" }
]
}
Il generatore produce uno schema in cui id è una stringa con format: "uuid", createdAt è una stringa con format: "date-time", score è un number (non un numero intero, a causa del decimale), e members è un array il cui items schema richiede id e role ma non active. Quest'ultimo dettaglio è il profitto: da due membri di esempio lo ha dedotto correttamente active è facoltativo Fare quel ragionamento a mano su un grande carico utile è esattamente il tipo di lavoro attento e noioso che un generatore rimuove.
Dove finisce l'inferenza e inizia il tuo giudizio
Voglio essere diretto sui limiti, perché uno schema generato consegnato direttamente alla produzione è un errore L'inferenza vede tipi e struttura; non può vedere l'intento.
Non può sapere che role è un enum di owner, editor, e viewer - dal campione che conosce solo role è una stringa Non può sapere che score varia da 0 a 5, quello name ha una lunghezza massima, o che un codice che sembra un UUID è in realtà un identificatore opaco che dovrebbe rimanere una stringa semplice. Ne deduce required dalla presenza, quindi un campo opzionale che appare nel tuo campione verrà contrassegnato come richiesto finché non lo correggi. E funziona dai dati che gli dai: se il tuo campione non include mai a null per un campo nullable, lo schema non saprà che il campo può essere null.
Il giusto modello mentale è lo scaffolding Il generatore costruisce il frame in modo accurato - ogni campo, il suo tipo, il nesting, le forme degli array, l'elenco richiesto basato sulla presenza Si aggiungono quindi i vincoli semantici: enumerazioni, pattern, limiti numerici e qualsiasi formato che il motore non potrebbe vedere da un valore Questo è più veloce e meno incline agli errori che partire dal nulla, perché la noiosa trascrizione strutturale è già fatta e corretta.
Draft-07 contro 2020-12: quale scegliere?
| considerazione | Bozza-07 | 2020-12 |
|---|---|---|
| Supporto biblioteca | Più ampio; sostenuto un po' ovunque | Crescere; controllare il proprio validatore |
| stato | Ampiamente distribuito, stabile | Specificazione attuale |
$schema valore |
http://json-schema.org/draft-07/schema# |
https://json-schema.org/draft/2020-12/schema |
| Array parole chiave dell'elemento | items per schemi a voce singola |
items / prefixItems spaccato per tuple |
| Migliore quando | La massima compatibilità conta | Vuoi le funzionalità specifiche più recenti |
Per gli schemi generati da questo strumento - oggetti, elenchi richiesti, array di una forma di singolo elemento - entrambi i dialetti esprimono la stessa struttura La decisione pratica si riduce a ciò che supporta la libreria di convalida Se stai cablando lo schema in uno stack stabilito, abbina la versione dei tuoi documenti validatori Se stai iniziando da nuovo e non hai vincoli, Draft-07 rimane la scelta pragmatica per il suo supporto ecosistemico senza pari.
Casi d'uso comuni
Documentazione di un'API esistente. Quando erediti un endpoint senza schema, generandone uno da una risposta reale ti viene fornito un documento di partenza accurato in pochi secondi, quindi lo perfeziona in un contratto pubblicato Questo si abbina naturalmente ai tipi di generazione per il tuo codice client - lo stesso campione può alimentare il JSON a dattiloscritto strumento in modo che il contratto del server e i tipi di client provengano dalla stessa fonte di verità.
Convalida degli organi di richiesta. Per un corpo di richiesta che controlli, genera uno schema da un esempio valido, attiva la modalità rigorosa per rifiutare le chiavi impreviste e aggiungi gli enumeraggi e i limiti applicati dall'endpoint. Ora le richieste non valide falliscono sul bordo con un chiaro errore di convalida invece di causare errori confusi nel profondo del tuo gestore.
Config-file validazione. Le applicazioni che leggono la configurazione JSON traggono enormi benefici da uno schema Genera uno da una configurazione di buon livello, stringilo e convalida all'avvio in modo che un errore di battitura in una chiave di configurazione fallisca ad alta voce invece di disabilitare silenziosamente una funzionalità.
Prove e infissi. Uno schema funge anche da risorsa di prova Convalida i tuoi dispositivi in CI in modo che un dispositivo che va alla deriva fuori forma venga catturato prima di produrre un test verde fuorviante.
Test contrattuali tra servizi. Quando due servizi concordano su un payload, uno schema condiviso è il contratto. Generarlo da un messaggio reale e perfezionarlo fornisce a entrambi i team un documento contro cui possono convalidare in modo indipendente.
Privacy: perché viene eseguito nel tuo browser
I campioni API sono alcuni dei testi più sensibili gestiti da uno sviluppatore Contengono abitualmente token di accesso, identificatori di sessione, indirizzi e-mail, ID di record interni e occasionalmente dati personali che non dovrebbero mai essere incollati in un modulo Web casuale È proprio per questo che il JSON Schema Generator fa tutto il suo lavoro lato client L'analisi, l'inferenza e la serializzazione avvengono in JavaScript nel tuo browser Nulla viene caricato, registrato o archiviato su un server Puoi verificarlo aprendo la scheda di rete mentre generi, o disconnettendoti da internet - lo strumento funziona ancora Mi interessa questo perché non userei uno strumento che spediva i miei payload a qualcun altro' server, e non ti chiederei di farlo neanche Lo stesso principio attraversa tutto Toolz.dev, che è l'argomento che faccio a lungo nel Privacy dei dati negli strumenti online scrittura.
Come si adatta al più ampio toolkit JSON
Uno schema è un artefatto in un flusso di lavoro JSON più grande Prima di generare uno schema, aiuta ad avere un input pulito e valido: il Formattatore JSON formatterà e convaliderà un payload in modo da non inserire testo non valido nel generatore Dopo aver avuto uno schema, spesso desideri tipi per il codice della tua applicazione, che è dove JSON a dattiloscritto entra. E se la tua pipeline si sposta tra i formati, il JSON a Yaml convertitore gestisce la conversione molti sistemi di config e CI si aspettano Ho scritto su come questi pezzi si collegano nel Guida definitiva agli strumenti JSON, e sull'assemblaggio di un kit più ampio nel Toolkit per sviluppatori web panoramica Il punto di un toolkit connesso è che un singolo campione può fluire attraverso diversi strumenti - schema, tipi, conversione di formato - senza mai lasciare il browser.
FAQ
Come faccio a generare uno schema JSON da JSON?
Incolla il tuo JSON nell'editor, scegli Draft-07 o 2020-12 e premi Genera Lo strumento deduce il tipo di ogni campo, estrae i tasti richiesti e restituisce uno schema che puoi copiare direttamente in un validatore. Non viene caricato nulla: l'inferenza viene eseguita interamente nel tuo browser.
Qual è la differenza tra il draft-07 e il 2020-12?
Sono due versioni della specifica JSON Schema Draft-07 ha il più ampio supporto tra le librerie ed è un default sicuro 2020-12 è la release corrente e cambia il modo in cui vengono espressi array e sotto-schemi, tra le altre cose Per le forme di oggetti e array questo strumento produce la struttura è la stessa; la principale differenza visibile è la $schema identificatore.
Come fa lo strumento a decidere quali campi sono richiesti?
Una chiave è contrassegnata quando appare in ogni oggetto che vede il generatore. Per un singolo oggetto che significa ogni chiave; per una matrice di oggetti significa chiavi presenti in tutti gli elementi. Le chiavi che appaiono solo in alcuni record vengono escluse dal necessario, il che riproduce il modo in cui le API omettono i campi facoltativi. È possibile disattivare completamente il rilevamento del campo richiesto.
Cosa succede con una matrice di oggetti?
Gli oggetti vengono fusi in uno solo items schema che descrive un singolo elemento, e la proprietà è digitata come un array di esso Le chiavi presenti in ogni elemento diventano richieste; le chiavi presenti solo in alcuni rimangono opzionali Questo mantiene lo schema leggibile invece di produrre un grande anyOf di forme quasi identiche.
Quali formati di stringa rileva?
Riconosce date-time, date, time, email, uri, uuid, e ipv4 stringhe e aggiunge la corrispondenza format parola chiave Il rilevamento è il miglior sforzo da un singolo campione, quindi esamina i risultati: un codice che sembra un UUID verrà contrassegnato come uno. Puoi disabilitare il rilevamento del formato se preferisci i tipi di stringa semplici.
Posso generare uno schema da un singolo campione?
Sì, ma un campione mostra solo una forma possibile Un campo che è un numero nel tuo campione potrebbe essere nullo o una stringa altrove, e un campo opzionale che capita di essere presente sarà contrassegnato richiesto Più rappresentativo è il campione - idealmente diversi record reali - più accurati sono i tipi dedotti e l'elenco richiesto.
Uno schema generato è pronto per la convalida della produzione?
Trattalo come un punto di partenza forte piuttosto che come un documento finito L'inferenza cattura tipi, struttura e campi richiesti in modo accurato, ma i vincoli semantici - enumerazioni, schemi di stringa, minimi e massimi numerici, formati che non può vedere da un valore - devono ancora essere aggiunti a mano Generare rimuove l'impalcatura noiosa in modo da potersi concentrare su quelle regole.
Il mio JSON è stato caricato su un server?
No. L'intero motore di inferenza funziona come JavaScript nel browser Non viene trasmesso, registrato o memorizzato nulla Puoi confermarlo guardando la scheda di rete mentre generi o disconnettendoti da Internet: lo strumento funziona ancora.
