Cos'è il JSON? Guida alla Sintassi e agli Errori Comuni
Il JSON (JavaScript Object Notation) è un formato di testo per rappresentare dati strutturati: numeri, stringhe, booleani, liste e oggetti annidati, tutti scritti con una sintassi minima e leggibile sia da un umano sia da una macchina. È lo standard con cui quasi ogni API web scambia dati oggi, ed è il formato che file di configurazione, database documentali e strumenti da riga di comando usano per salvare le informazioni.
Cos’è davvero il JSON
Il JSON conosce solo sei tipi di valore. Una stringa, sempre racchiusa tra virgolette doppie, mai singole. Un numero, senza distinzione tra interi e decimali. Un booleano, true o false. Il valore null. Un oggetto, delimitato da {}, che raccoglie coppie chiave-valore. E un array, delimitato da [], che raccoglie una lista ordinata di valori. Ogni struttura dati in JSON, per quanto complessa, nasce dalla combinazione di questi sei elementi.
Attorno a questi tipi esistono regole di sintassi rigide, e sono proprio queste regole a rompere il parsing quando qualcosa non torna. Le chiavi di un oggetto devono essere stringhe racchiuse tra virgolette doppie: niente virgolette singole, niente chiavi lasciate senza virgolette. Non è ammessa una virgola dopo l’ultimo elemento di un array o l’ultima proprietà di un oggetto. Non sono ammessi commenti di nessun tipo, né // né /* */. E tre valori che in JavaScript useresti tranquillamente, NaN, Infinity e undefined, semplicemente non esistono in JSON: non sono valori validi. Le funzioni, allo stesso modo, non possono essere rappresentate: il JSON descrive solo dati, mai comportamento.
JSON contro un oggetto letterale JavaScript
Chi scrive JavaScript ogni giorno tende a dare per scontato che un oggetto letterale e un documento JSON siano intercambiabili, ed è proprio qui che nascono la maggior parte degli errori di sintassi. Sono linguaggi diversi con regole diverse, anche se si somigliano a colpo d’occhio.
| Caratteristica | JSON | Oggetto letterale JavaScript |
|---|---|---|
| Chiavi tra virgolette obbligatorie | Sì, solo virgolette doppie | No, le virgolette sono opzionali |
| Virgola finale ammessa | No | Sì |
| Commenti ammessi | No | Sì |
| Stringhe con virgolette singole | No | Sì |
| Funzioni come valori | No | Sì |
undefined come valore | No | Sì |
La confusione ha una spiegazione semplice: il JSON è nato come sottoinsieme della sintassi degli oggetti JavaScript, quindi un oggetto letterale valido sembra quasi sempre JSON valido a un primo sguardo. Ma la somiglianza si ferma all’aspetto. Un file .json o una risposta API che arriva a un parser rigoroso viene validata contro le regole della tabella sopra, non contro quelle, molto più permissive, di JavaScript.
Esempio pratico: minificare e formattare una vera risposta API
Prendiamo un oggetto realistico, il tipo di dato che un’API potrebbe restituire per un utente. Ecco la sua versione minificata, senza un solo spazio superfluo, lunga esattamente 107 caratteri:
{"id":1,"name":"Ada Lovelace","email":"[email protected]","roles":["admin","user"],"active":true,"meta":null}Ed ecco lo stesso oggetto formattato con un’indentazione di 2 spazi, lungo 145 caratteri:
{
"id": 1,
"name": "Ada Lovelace",
"email": "[email protected]",
"roles": [
"admin",
"user"
],
"active": true,
"meta": null
}La differenza tra le due versioni, circa il 35% in più di caratteri nella versione formattata, viene interamente da spazi e a capo aggiunti: nessun dato in più, solo leggibilità in più. Questo spiega perché un’API restituisce quasi sempre JSON minificato: ogni byte risparmiato conta quando la risposta viaggia in rete, magari migliaia di volte al secondo. Ma quello stesso JSON, appena arriva sullo schermo di uno sviluppatore che deve debuggare una richiesta, diventa illeggibile su una riga sola. Formattarlo con un’indentazione coerente è il primo passo per capire cosa contiene davvero.
Formatta il tuo JSON
Incolla qui sotto il tuo JSON per formattarlo, minificarlo o scoprire subito dove si trova un errore di sintassi.
Errori comuni e casi limite
La virgola finale. È probabilmente l’errore di sintassi JSON più frequente in assoluto, perché in JavaScript è del tutto legale. Prova a fare il parsing di {"id":1,"name":"Ada",} e otterrai Expected double-quoted property name in JSON at position 21 (line 1 column 22). Il motore si aspettava una nuova proprietà tra virgolette doppie dopo la virgola e ha trovato invece la parentesi di chiusura.
Chiave senza virgolette. Scrivere {id:1} invece di {"id":1} produce Expected property name or '}' in JSON at position 1 (line 1 column 2): il parser, appena dopo la parentesi graffa di apertura, si aspetta una stringa tra virgolette doppie o la chiusura immediata dell’oggetto, non un identificatore nudo.
Chiave tra virgolette singole. {'a':1} genera esattamente lo stesso errore della chiave senza virgolette, Expected property name or '}' in JSON at position 1 (line 1 column 2), perché per il parser JSON una virgoletta singola non è una virgoletta valida: è un carattere qualunque, quindi la chiave risulta comunque assente.
NaN come valore. In JavaScript NaN è un valore legittimo (il risultato, per esempio, di una divisione 0/0), ma in JSON non esiste. {"a":NaN} fallisce con Unexpected token 'N', "{"a":NaN}" is not valid JSON.
undefined come valore. Stesso discorso: {"a":undefined} produce Unexpected token 'u', "{"a":undefined}" is not valid JSON. Se stai serializzando un oggetto JavaScript che contiene proprietà undefined, JSON.stringify le rimuove silenziosamente durante la conversione, ma se undefined compare già come testo letterale in un file o in una risposta, il parsing si interrompe.
Questi messaggi arrivano da V8, il motore JavaScript di Chrome, ed è anche il motore che esegue JSON.parse nel browser della maggior parte dei visitatori quando usano uno strumento online come questo. La formulazione esatta può cambiare leggermente da browser a browser (SpiderMonkey, il motore di Firefox, scrive gli errori in modo un po’ diverso), ma il risultato è sempre lo stesso: il parsing fallisce e si ferma al primo carattere che non rispetta la sintassi.
Chiavi duplicate: l’errore silenzioso. A differenza di tutti i casi sopra, questo non genera nessun errore. {"a":1,"a":2} è sintatticamente JSON perfettamente valido, e il parsing va a buon fine producendo {"a":2}: la maggior parte dei parser, incluso quello di JavaScript, tiene silenziosamente solo l’ultima occorrenza della chiave e scarta la precedente. È un problema molto più insidioso dei precedenti proprio perché non lancia nessun errore: capita, per esempio, in un file di configurazione modificato a mano o generato da uno strumento di build che accidentalmente scrive la stessa chiave due volte, e nessuno se ne accorge finché il valore sbagliato non salta fuori a runtime.
Domande frequenti
Cos’è il JSON?
È un formato di testo per rappresentare dati strutturati (stringhe, numeri, booleani, null, oggetti e array) con una sintassi minima, pensata per essere letta facilmente sia da un programma sia da una persona. È lo standard più usato per lo scambio di dati tra API web e applicazioni.
Il JSON è la stessa cosa di un oggetto JavaScript?
No. Il JSON è un sottoinsieme più rigido: richiede chiavi tra virgolette doppie, non ammette virgole finali, commenti, virgolette singole o valori come undefined e funzioni, tutte cose che invece un oggetto letterale JavaScript accetta senza problemi. Un oggetto JavaScript valido non è automaticamente JSON valido.
Perché una virgola in più rompe il mio JSON? Perché la specifica JSON non ammette virgole dopo l’ultimo elemento di un array o l’ultima proprietà di un oggetto. Il parser, dopo la virgola, si aspetta un altro elemento; se trova invece la parentesi di chiusura, il parsing fallisce con un errore che segnala esattamente quella posizione.
Il JSON supporta i commenti?
No, in nessuna forma. Né // né /* */ sono sintassi valida in un documento JSON. Se hai bisogno di annotare un file di configurazione, alcuni strumenti offrono varianti come JSON5 o JSONC che aggiungono i commenti, ma non sono JSON puro.
Qual è la differenza tra formattare e minificare? Formattare aggiunge indentazione e a capo per rendere la struttura leggibile a occhio umano, a costo di più byte. Minificare rimuove ogni spazio superfluo per ottenere il file più piccolo possibile, pensato per essere trasmesso in rete o salvato in modo compatto, non per essere letto direttamente.
I miei dati vengono inviati a un server quando uso un formattatore JSON online?
Con lo strumento di pluri.tools, no. Il formattatore JSON esegue JSON.parse e JSON.stringify interamente nel browser, con normale JavaScript lato client: non viene fatta nessuna chiamata di rete. Il JSON che incolli non lascia mai il tuo dispositivo.