Capire JSON Schema: Valida i tuoi dati come un professionista

Hai mai avuto un bug in cui la tua API restituiva "42" (una stringa) invece di 42 (un numero) e tutto a valle si rompeva? O qualcuno ha inviato una richiesta senza un campo obbligatorio e la tua app è crashata invece di restituire un errore utile? JSON Schema esiste proprio per prevenire questo tipo di problemi.

Pensalo come un progetto per i tuoi dati JSON — descrive quale forma devono avere i dati e cattura tutto ciò che non corrisponde.

Come si presenta JSON Schema

JSON Schema è scritto in JSON (meta, vero?). Ecco uno schema semplice per un oggetto utente:

Questo dice: "Mi aspetto un oggetto con un name obbligatorio (stringa non vuota) e un'email (formato email valido), più un age opzionale (intero tra 0 e 150)." Se qualcuno invia {"name": "", "email": "not-an-email"}, il validatore individuerà entrambi i problemi.

Costruire schema passo dopo passo

Inizia con il tipo. Ogni schema inizia con "type": object, array, string, number, integer, boolean o null.

Aggiungi vincoli. Per stringhe: minLength, maxLength, pattern (regex). Per numeri: minimum, maximum, multipleOf. Per array: minItems, maxItems, uniqueItems. La guida ufficiale JSON Schema ha la lista completa.

Segna i campi obbligatori. Usa l'array "required" a livello di oggetto. Elenca solo i campi che devono essere presenti — non rendere tutto obbligatorio a meno che non sia intenzionale.

Definisci oggetti annidati. Basta annidare le definizioni di schema dentro "properties". Ecco un utente con un indirizzo:

Quel pattern sul codice postale? Assicura che vengano accettati solo codici postali statunitensi a 5 cifre. La validazione pratica come questa impedisce ai dati spazzatura di insinuarsi nel tuo database.

Perché dovresti davvero usarlo

Validazione API: Valida i body delle richieste in entrata ai margini della tua API. I dati errati vengono rifiutati con messaggi di errore chiari prima di toccare la tua logica di business. La maggior parte dei framework lo supporta — Ajv per JavaScript è velocissimo.

Validazione della configurazione: Valida i file di config all'avvio dell'app. Fallisci rapidamente con un chiaro "alla tua configurazione manca il campo database.host" invece di un'eccezione criptica di puntatore nullo 5 minuti dopo.

Documentazione: JSON Schema funge da documentazione vivente. Strumenti come Swagger UI generano documentazione API direttamente dagli schema.

Generazione di codice: Genera interfacce TypeScript, struct Go o dataclass Python dal tuo schema. Scrivilo una volta, usalo ovunque.

Testing: Valida le risposte API nella tua suite di test per individuare le regressioni automaticamente.

Iniziare in 30 secondi

Il modo più veloce per iniziare? Genera uno schema da dati JSON esistenti. Incolla una risposta JSON di esempio nel nostro JSON Schema Generator — analizzerà i dati e produrrà uno schema che puoi perfezionare. Poi usa il nostro JSON Schema Validator per testarlo con dati reali.

Puoi anche validare in modo programmatico. Ecco un rapido esempio Node.js con Ajv:

Per Python, dai un'occhiata alla libreria jsonschema. Per Java, c'è everit-json-schema. Praticamente ogni linguaggio ha un supporto solido — consulta la lista completa delle implementazioni.

Funzionalità avanzate dello Schema da conoscere

Una volta padroneggiati i fondamentali, JSON Schema offre funzionalità potenti che rendono possibile la validazione complessa.

oneOf, anyOf, allOf — Combinare Schema:

A volte un campo può essere uno di diversi tipi. Ad esempio, un'API potrebbe accettare sia un ID stringa che un ID numerico:

Questo schema accetta sia {"id": "PRD-1234"} che {"id": 42} ma rifiuta {"id": -1} o {"id": "invalid"}.

$ref — Definizioni di Schema riutilizzabili:

Man mano che i tuoi schema crescono, vorrai evitare di ripetere le stesse definizioni. La parola chiave $ref ti permette di fare riferimento a definizioni condivise:

Ora sia billing_address che shipping_address utilizzano esattamente le stesse regole di validazione. Modifica la definizione di address una volta, e entrambi i campi si aggiornano. Questo è essenziale per mantenere gestibili gli schema di grandi dimensioni.

additionalProperties — Blocca i tuoi oggetti:

Per impostazione predefinita, JSON Schema consente proprietà aggiuntive non elencate in properties. Questo spesso NON è ciò che vuoi — campi inaspettati potrebbero indicare un bug del client o un'incompatibilità di versione. Imposta "additionalProperties": false per rifiutare i campi sconosciuti:

Con questo schema, {"name": "Alice", "email": "[email protected]", "admin": true} verrebbe rifiutato perché admin non è una proprietà definita.

Errori comuni di JSON Schema

Anche sviluppatori esperti commettono questi errori quando scrivono schema:

1. Dimenticare che required è a livello di oggetto, non a livello di proprietà. Questo è sbagliato:

Il modo corretto è:

2. Usare "type": "number" quando intendi "type": "integer". Il tipo number accetta decimali come 3.14, mentre integer accetta solo numeri interi. Se il tuo campo è un contatore o un ID, usa integer.

3. Non specificare format per pattern comuni. JSON Schema ha validatori di formato integrati per email, uri, date-time, ipv4, ipv6, uuid e altro. Usali invece di scrivere pattern regex complessi.

4. Rendere tutto obbligatorio. Segna i campi come obbligatori solo se devono davvero essere presenti. Vincolare troppo il tuo schema rende più difficile l'evoluzione dell'API — aggiungere un nuovo campo opzionale è una modifica non distruttiva, ma perdi quella flessibilità se tutto è obbligatorio.

Esempio pratico: Schema prodotto E-Commerce

Vediamo uno schema pratico che potresti usare per un'API di prodotti:

Questo schema impone che ogni prodotto abbia un nome (1-200 caratteri), un prezzo positivo e una categoria da una lista fissa. I tag sono opzionali ma devono essere stringhe uniche con un massimo di 10. La parola chiave enum è incredibilmente utile per i campi che devono accettare solo valori specifici.

Versioni di JSON Schema: Quale Draft usare

JSON Schema è passato attraverso diversi draft — ciascuno pubblicato come Internet-Draft IETF — e questo può confondere i principianti. Ecco una panoramica rapida:

Per nuovi progetti, usa 2020-12 (l'ultimo). Se stai lavorando con una codebase esistente, verifica quale draft supporta il tuo validatore. La maggior parte dei validatori moderni come Ajv supporta il Draft 7 e successivi.

Integrare JSON Schema nel tuo workflow

Ecco un approccio pratico per aggiungere la validazione JSON Schema a un'API Express.js:

Questo pattern ti offre la validazione automatica delle richieste con messaggi di errore chiari. L'opzione allErrors: true garantisce che tutti gli errori di validazione vengano segnalati in una volta, non solo il primo.

Provalo tu stesso

Pronto ad aggiungere la validazione dello schema al tuo progetto? Inizia con questi strumenti:

• JSON Schema Generator — Incolla qualsiasi dato JSON e ottieni uno schema generato automaticamente. Perfetto per creare schema da risposte API di esempio.
• JSON Schema Validator — Testa il tuo schema con dati reali per assicurarti che catturi ciò che dovrebbe e permetta ciò che dovrebbe.
• JSON Validator — Verifica rapidamente che il tuo JSON sia sintatticamente valido prima di preoccuparti della validazione dello schema.

JSON Schema può sembrare lavoro extra all'inizio, ma si ripaga molte volte individuando i bug ai confini del tuo sistema invece che nel profondo della tua logica di business.