Cosa risolve davvero JSON Schema
In sintesi: Schema governa struttura e tipi, non il significato di business. Ferma campi mancanti, tipi errati ed enum fuori intervallo, mentre regole come importo maggiore di zero restano nel codice.
In sintesi: lascia che JSON Schema imponga struttura, tipi, intervalli e formati, mentre regole tra campi, invarianti di business e stato esterno restano nel codice; adottalo per API pubbliche e payload condivisi, non per un servizio interno con cinque campi.
Risponde a "questi dati hanno la forma corretta", non a "questi dati hanno senso".
Cosa fa bene
Completezza strutturale. Quali campi devono esistere, se sono ammessi extra (required, additionalProperties).
Tipi. port come numero o stringa, tags come array o scalare. Solo questo elimina molto codice difensivo nei sistemi multi-linguaggio.
Intervalli. enum, minimum/maximum, lunghezza di stringhe e array.
Formati. format per date, email, URI e UUID, con validatori che li impongono.
Annidamento. Ogni livello di oggetti e array ha i propri vincoli, e gli errori portano un percorso preciso.
Documentazione. Lo Schema è il contratto. Cambia un campo e il diff mostra il raggio d'impatto. Genera anche tipi e form, quindi una definizione alimenta diversi consumatori.
Cosa non può fare
Dipendenze tra campi. "La fine deve essere successiva all'inizio" può essere espresso con if/then/else, ma il risultato è più lungo e meno leggibile di tre righe di codice.
Invarianti di business. "Lo stock non può andare in negativo" dipende da stato esterno. Schema vede un solo documento.
Semantica. price: -100 soddisfa perfettamente {"type": "number"}. Se sia un prezzo legale è fuori dalla conoscenza dello Schema.
Una divisione praticabile
| Strato | Responsabile |
|---|---|
| Sintassi: è JSON valido | Parser |
| Struttura: campi, tipi, intervalli, formati | JSON Schema |
| Semantica: tra campi, regole di business, stato esterno | Codice dell'applicazione |
| Sicurezza: dimensione, profondità, frequenza | Gateway / middleware |
Concentra tutto in un unico punto e lo Schema cresce fino a centinaia di righe con cinque livelli di if/then. A quel punto le persone lo aggirano.
Quando vale la pena
- API pubbliche con consumatori sconosciuti
- Diversi servizi che leggono lo stesso payload
- Sistemi guidati da configurazione dove gli errori di battitura devono fallire subito
- Generazione di tipi o form dal contratto
Per un piccolo servizio interno con cinque campi e un frontend, i controlli scritti a mano sono più veloci da mantenere. Introdurre Schema lì è lavoro negativo.
FAQ
Come decido se adottare JSON Schema?
Valuta consumatori pubblici, più servizi che leggono lo stesso payload e la necessità di generare tipi o form. Per un piccolo servizio interno con cinque campi e un frontend, i controlli scritti a mano sono più veloci da mantenere.
Perché le regole tra campi dovrebbero restare nel codice?
"La fine deve essere successiva all'inizio" può essere compresso in if/then/else, ma il risultato è più lungo e meno leggibile di poche righe di codice. Schema non può nemmeno vedere lo stato esterno.
Schema deve validare dimensione del payload e profondità di annidamento?
No. Schema descrive la struttura, non dimensione o profondità; quei limiti appartengono a un gateway o a uno strato middleware.