Validare la sintassi di un JSON

A cosa serve un validatore JSON?

Un validatore JSON ha un ruolo più modesto, ma più preciso, di un formattatore: non riscrive nulla. Prende una stringa e risponde a una domanda binaria: questo testo è JSON conforme alla RFC 8259? Se sì, lo strumento restituisce il controllo. Altrimenti, indica esattamente la riga, la colonna e un estratto del JSON intorno al problema, per aiutare lo sviluppatore a correggere immediatamente.

In pratica, è lo strumento che si usa appena un parser da qualche parte restituisce un messaggio di errore criptico del tipo SyntaxError: Unexpected token } in JSON at position 217. Piuttosto che contare i caratteri a mano in un editor, si incolla la stringa completa, si legge la posizione e si vede l'estratto difettoso.

Validazione, formattazione: due operazioni distinte

Si confondono spesso. Il nostro formattatore JSON prende JSON valido e lo riscrive con un'indentazione leggibile. Il validatore, invece, si accontenta di un verdetto sintattico. Non effettua validazione semantica: non sa se il valore di un campo email assomigli a un'email, né se la struttura corrisponda a uno schema JSON Schema. Per questo, si usano strumenti dedicati (ajv in Node, justinrainbow/json-schema in PHP).

La sequenza classica in debug è: validare prima (lo strumento indica l'errore di sintassi), formattare dopo (il payload ormai valido diventa leggibile), confrontare infine con un altro payload di riferimento tramite il nostro comparatore JSON.

Gli errori JSON più frequenti

• Virgola finale (trailing comma): {"a": 1, "b": 2,}. Tollerata da JavaScript, ECMAScript e JSON5; rifiutata da JSON puro. È l'errore n°1 quando si copia-incolla da un editor di codice.
• Apostrofi invece di virgolette doppie: {'a': 1} è invalido. JSON accetta solo virgolette doppie, intorno alle chiavi come ai valori stringa.
• Chiavi non quotate: {a: 1}, sintassi JavaScript valida ma JSON invalida.
• Caratteri di controllo non escapati in una stringa: un a capo grezzo, una tabulazione. JSON richiede \n, \t, \r.
• Commenti: // commento o /* */. Accettati in JSONC (config VS Code) o JSON5, rifiutati in JSON puro.
• Encoding scorretto: un BOM UTF-8 all'inizio del file, contenuto in latin-1 mal convertito. Il validatore restituisce spesso un messaggio generico per questi casi.
• Struttura non terminata: una { o [ senza chiusura, frequente quando si tronca un payload al copia-incolla.

Come il validatore localizza l'errore

Lo strumento usa json_decode() di PHP con il flag JSON_THROW_ON_ERROR. PHP restituisce un messaggio che contiene una posizione in byte (posizione 217), che convertiamo in coppia riga/colonna contando i ritorni a capo prima dell'offset. Un estratto di circa 80 caratteri viene poi ritagliato intorno alla posizione per dare contesto. È generalmente sufficiente per individuare l'errore: una virgoletta mal posizionata, una virgola in più, una parentesi quadra mancante.

Attenzione: la posizione riportata da PHP non è sempre esattamente il carattere difettoso. È spesso dopo l'errore, nel momento in cui il parser ha rinunciato. Se l'estratto mostra "name": "Alice", }, l'errore reale è la virgola, non la graffa.

Casi d'uso tipici

• Configurazione corrotta: composer.json, package.json, tsconfig.json che impediscono l'avvio di una build. Si incolla, si vede la riga, si corregge.
• Risposta API troncata: un proxy ha tagliato il payload. La struttura non è terminata, il validatore lo segnala.
• Payload di webhook: un servizio terzo invia JSON mal formato. Il validatore permette di constatare il problema lato emettitore senza tuffarsi nel codice applicativo.
• JSON costruito per concatenazione: pratica da evitare ma comune, soprattutto in bash o in SQL. Il validatore rivela le virgolette doppie non escapate.

Limiti dello strumento

Il validatore non effettua validazione contro uno schema. Non dice che manca il campo email, che il valore non è un intero o che l'array atteso non ha la lunghezza giusta. Per queste verifiche strutturali, si usa JSON Schema. Il validatore non corregge nemmeno il JSON: non tenta di aggiungere una graffa mancante, né di rimuovere una virgola in più. È una scelta: la correzione automatica maschera troppo spesso errori reali.

Domande frequenti

Esempio di richiesta

curl -X POST https://cdrn.fr/api/v1/tools/json-validator/execute \
  -H "Content-Type: application/json" \
  -d '{"input":"..."}'

Schema di input

Endpoint

• GET https://cdrn.fr/api/v1/tools - elenca tutti gli strumenti disponibili
• GET https://cdrn.fr/api/v1/tools/json-validator - recupera lo schema di questo strumento
• POST https://cdrn.fr/api/v1/tools/json-validator/execute - esegue questo strumento con un payload JSON