Come generare uno schema JSON da un esempio

A cosa serve partire da un esempio JSON

Questo generatore ricava una rappresentazione JSON Schema da un esempio JSON inserito come testo. È utile per ottenere una prima descrizione della forma dei dati prima di documentare un formato o confrontare diversi payload.

La rappresentazione dipende dai valori presenti nell’esempio: vengono dedotti i tipi, i nomi delle proprietà, la struttura degli array e alcuni formati riconoscibili per le stringhe. Un campione più ricco può rendere visibili più varianti, ma non aggiunge regole che nei dati non compaiono.

Considera quindi il risultato come una base da esaminare e completare secondo le esigenze del tuo formato. La descrizione ottenuta riflette ciò che è osservabile nel testo fornito, non ogni possibile contenuto futuro dello stesso tipo di dato. Il titolo può aiutarti a distinguere risultati destinati a documenti diversi, senza modificare i dati analizzati.

La procedura è adatta sia a un oggetto sia a un array, ma funziona anche con un valore JSON primitivo. Prima di avviarla, prepara un esempio che rappresenti davvero la struttura che vuoi descrivere.

Come ottenere la rappresentazione passo dopo passo

1. Prepara un documento JSON valido, come un oggetto con le proprietà da descrivere, un array o un valore primitivo. Inseriscilo nel campo dedicato ai dati di esempio, che accetta una stringa e parte vuoto per impostazione predefinita.
2. Controlla la sintassi prima di procedere: usa virgolette doppie per le stringhe e verifica parentesi, virgole, valori e annidamenti. Un testo malformato viene rifiutato invece di essere trasformato automaticamente.
3. Seleziona il campo del titolo solo quando vuoi personalizzare l’intestazione del risultato. Il titolo è facoltativo; se non viene compilato o resta vuoto, viene usato “Generated Schema”.
4. Avvia la generazione dopo aver verificato che esista un dato utilizzabile. Se il campo principale è vuoto, può essere impiegato il primo valore adatto disponibile negli ingressi alternativi json, data, text, input, value o sample; se non c’è alcun valore utilizzabile, l’operazione fallisce.
5. Verifica anche la dimensione del testo scelto: quando la codifica UTF-8 supera 1.000.000 di byte, l’input viene rifiutato. Dopo l’elaborazione, confronta la rappresentazione ottenuta con l’esempio che hai inserito, prestando attenzione a proprietà, tipi ed elementi degli array.
6. Se il risultato non corrisponde alla struttura desiderata, modifica il campione e avvia una nuova generazione. Non correggere manualmente una sintassi non valida aspettandoti che venga interpretata, perché il testo deve poter essere analizzato come JSON.

Come interpretare ciò che viene prodotto

Per i valori primitivi, null viene riconosciuto come tipo null, un valore vero o falso come boolean, un numero intero come integer e un numero decimale come number. Una stringa resta di tipo string; quando corrisponde a un modello riconosciuto, può ricevere il formato email, uuid, uri, ipv4, date-time, date oppure time.

Quando l’esempio è un oggetto, ogni nome osservato diventa una proprietà e i nomi presenti risultano obbligatori nella rappresentazione ottenuta. Le proprietà non presenti nella descrizione dedotta non sono consentite. Questo riflette i membri rilevati nel dato fornito e non una previsione di campi che potrebbero apparire in altri oggetti.

Un array vuoto ha una descrizione degli elementi senza vincoli specifici. Se gli elementi mostrano strutture differenti, le descrizioni distinte vengono riunite con anyOf dopo la rimozione dei duplicati. Perciò è importante controllare se la varietà osservata nell’array corrisponde davvero ai casi che vuoi ammettere.

Nel risultato compare l’identificatore di JSON Schema draft-07. L’informazione indica il riferimento dichiarato dalla rappresentazione, mentre i dettagli restano legati all’esempio: campi facoltativi, limiti numerici, dipendenze tra proprietà e altri requisiti non visibili nei dati devono essere valutati e aggiunti separatamente.

Esempio pratico

Devi descrivere la struttura di una risposta JSON che contiene dati di un cliente e una lista di articoli, usando un singolo esempio rappresentativo.

Inserisci un oggetto con un identificativo numerico, un indirizzo email e una lista di articoli, lascia il titolo vuoto oppure impostane uno, quindi avvia la generazione e controlla proprietà e tipi rilevati nel risultato. Il valore email può ricevere il formato email quando corrisponde al modello riconosciuto.

La forma attesa è una rappresentazione JSON Schema per un oggetto con proprietà osservate e relativi tipi; il risultato include l’identificatore JSON Schema draft-07 e può usare “Generated Schema” come titolo predefinito.

Limiti

• Il risultato copre ciò che l’esempio rende osservabile e non esprime automaticamente vincoli o casi assenti dal campione.

Errori comuni

• Causa: il testo contiene JSON malformato, per esempio una virgola o una parentesi fuori posto. Correzione: ricontrolla virgolette, parentesi, virgole e valori, quindi riprova con il documento corretto.

Domande frequenti

Posso generare una rappresentazione da un oggetto JSON?

Quando il documento è valido, un oggetto viene rappresentato con le proprietà osservate e con quei nomi indicati come obbligatori. Le proprietà non presenti nel dato analizzato non risultano consentite nella descrizione dedotta.

Cosa succede se lascio vuoto l’esempio?

Se il campo principale è vuoto, può essere scelto il primo valore adatto tra gli ingressi alternativi; senza dati utilizzabili, l’operazione fallisce. Inserire un testo vuoto non produce quindi una rappresentazione.

Come vengono descritti gli array?

Un array vuoto non impone un vincolo specifico agli elementi. Quando gli elementi hanno strutture differenti, le descrizioni diverse possono essere combinate tramite anyOf, eliminando prima le copie duplicate.