Generatore JSON in JSON Schema

Cos'è JSON Schema?

JSON Schema è un vocabolario per descrivere il JSON. Dice "questo oggetto deve avere queste chiavi, di questi tipi, con valori che corrispondono a questi pattern" — e poi i validatori (Ajv, jsonschema, opis/json-schema, ogni strumento OpenAPI) fanno rispettare quel contratto. Lo standard attuale è Draft 2020-12, che è quello che usa OpenAPI 3.1; Draft 7 è la versione precedente ed è ancora comune nelle toolchain più vecchie. I due hanno differenze sintattiche minori — questo generatore emette entrambi.

Come usarlo

Incolla un esempio JSON. Il pannello di output emette uno schema corrispondente con ogni foglia tipizzata come string, integer, number, boolean, null, più object / array per i contenitori. Con Rileva i formati abilitato, le stringhe che corrispondono a pattern comuni ricevono un suggerimento format — email, uri, date, date-time, uuid, ipv4. Con Contrassegna obbligatori abilitato, ogni chiave presente nell'esempio viene aggiunta a required — incolla un array di più oggetti per ottenere un elenco onesto dei campi obbligatori (sopravvivono solo le chiavi presenti in tutti gli oggetti). I campi opzionali Title e $id vengono aggiunti in cima allo schema.

Formati rilevati

email — qualsiasi cosa corrisponda al semplice pattern local@host.tld.
uri — stringhe che iniziano con http:// o https://.
date — YYYY-MM-DD (RFC 3339 full-date).
date-time — YYYY-MM-DDTHH:MM:SS[.fff][Z|+HH:MM] (RFC 3339).
time — HH:MM:SS[.fff][Z|+HH:MM].
uuid — UUID v1–v5 RFC 4122.
ipv4 — indirizzi IPv4 in notazione decimale puntata.

Altri formati delle specifiche (uri-reference, idn-email, regex, json-pointer) non vengono rilevati automaticamente; aggiungili a mano se ti servono.

Domande frequenti

Posso fidarmi di uno schema inferito in produzione?

Trattalo come un punto di partenza. L'inferenza può vedere solo ciò che è nel tuo esempio — se un campo è un intero positivo in ogni esempio ma è documentato per consentire zero o negativi, lo schema inferito è troppo stretto. Allo stesso modo, i campi che appaiono nel 100% dei tuoi esempi potrebbero essere opzionali nella realtà. Rivedi sempre lo schema rispetto al contratto documentato della tua API prima di metterlo in produzione.

Come sceglie i campi obbligatori?

Per un singolo oggetto, ogni chiave viene contrassegnata come obbligatoria (perché ogni chiave è presente). Per un array di oggetti, solo le chiavi presenti in ogni oggetto vengono contrassegnate come obbligatorie — le chiavi che appaiono in alcuni ma non in tutti diventano opzionali. Ciò corrisponde a come i validatori leggono lo schema: "questo campo deve essere sempre presente".

Qual è la differenza tra Draft 2020-12 e Draft 7?

Per il 95% degli schemi, niente — il vocabolario di base è identico. Le differenze appaiono nelle funzionalità avanzate: $dynamicRef sostituisce $recursiveRef, items sostituisce additionalItems per la validazione delle tuple, e alcune parole chiave si sono spostate tra i vocabolari. Se stai integrando con OpenAPI 3.1 o Ajv 8+, scegli 2020-12; per Ajv più vecchio (v6), Stoplight più vecchio o qualsiasi cosa generata prima del 2019, scegli Draft 7.

Perché la mia data viene rilevata come date-time e non date?

L'ordine di rilevamento è date-time prima di date, quindi 2024-01-15T00:00:00Z corrisponde prima a date-time. 2024-01-15 da solo corrisponde a date. Se vuoi un campo solo data che casualmente include un orario, modifica a mano lo schema o rimuovi il componente orario dall'esempio prima.

Lo schema preserva i campi simili a enum?

No — inferire "questo deve essere uno di [active, paused, archived]" richiede più esempi di quelli che un tipico incolla contiene, e i falsi positivi sono pericolosi (un singolo tenant che passa a un nuovo stato rompereb la validazione in produzione). Aggiungi enum: [...] a mano una volta esaminato il tuo dominio.

Posso usare l'output con OpenAPI?

Sì — inserisci il corpo dello schema (tutto tranne $schema e $id) in una voce components.schemas.MyType. OpenAPI 3.1 supporta l'intero vocabolario Draft 2020-12; OpenAPI 3.0 supporta un sottoinsieme vicino a Draft 7 ma con alcune particolarità (nessuna parola chiave nullable in Draft 7 — OpenAPI 3.0 ha aggiunto la sua).

Generatore JSON in JSON Schema