Cos'è JSON? Una guida in parole semplici (e come correggere gli errori comuni)

JSON è ovunque nel software moderno — file di configurazione, risposte delle API, database e impostazioni ci si affidano. Eppure una singola virgola smarrita può rompere un intero file e lasciarti a fissare un criptico errore «Unexpected token». Questa guida spiega cos'è JSON in parole semplici, come funziona davvero la sua sintassi e come diagnosticare e correggere gli errori che incontrerai più spesso.

Cos'è JSON

JSON sta per JavaScript Object Notation. È un formato leggero, basato su testo, per memorizzare e scambiare dati strutturati. Nonostante il nome, non è legato a JavaScript — praticamente ogni linguaggio di programmazione può leggerlo e scriverlo, ed è proprio per questo che è diventato la lingua predefinita delle API web.

Tutto il senso di JSON è essere leggibile sia dagli umani sia dalle macchine. Rappresenta i dati come combinazione di pochi semplici mattoni:

• Oggetti — raccolte di coppie chiave/valore racchiuse tra parentesi graffe { }.
• Array — elenchi ordinati racchiusi tra parentesi quadre [ ].
• Valori — una stringa, un numero, true, false, null, un oggetto o un array.

Ecco un esempio piccolo ma completo:

{
  "name": "Ada Lovelace",
  "active": true,
  "age": 36,
  "skills": ["math", "logic"],
  "address": {
    "city": "London",
    "postcode": null
  }
}

Le regole che fanno inciampare

JSON somiglia molto a un oggetto JavaScript, e proprio questa somiglianza è la fonte della maggior parte degli errori — JSON è più rigido. Tieni a mente queste regole ed eviterai la stragrande maggioranza degli errori:

1. Chiavi e stringhe richiedono le doppie virgolette

Ogni chiave dev'essere una stringa tra doppie virgolette, e anche ogni valore testuale deve usare le doppie virgolette. Gli apici singoli non sono JSON valido, anche se in JavaScript vanno bene.

// Non valido
{ 'name': 'Ada' }

// Valido
{ "name": "Ada" }

2. Niente virgole finali

Non puoi lasciare una virgola dopo l'ultimo elemento di un oggetto o array. È di gran lunga l'errore JSON più comune, perché molti editor e linguaggi la consentono volentieri altrove.

// Non valido — virgola dopo l'ultimo valore
{ "a": 1, "b": 2, }

// Valido
{ "a": 1, "b": 2 }

3. Niente commenti

Il JSON standard non ha sintassi per i commenti. Le righe che iniziano con // o i blocchi tra /* */ causano un errore di analisi. Se ti servono commenti, formati come JSON5 o YAML li consentono — dai un'occhiata al nostro formattatore YAML se fa più al caso tuo.

4. I numeri sono semplici

I numeri si scrivono senza virgolette e senza zeri iniziali o punti decimali finali. 01, 1. e .5 sono tutti non validi; scrivi 1, 1.0 e 0.5.

Errori comuni e come correggerli

Quando un parser rifiuta il tuo JSON, di solito segnala una riga e una colonna. Quel punto indica dove il parser ha rinunciato, che spesso è appena dopo l'errore reale. Ecco i messaggi che vedrai di più e cosa significano davvero:

• "Unexpected token } in JSON" — quasi sempre una virgola finale prima della graffa o quadra di chiusura. Togli la virgola in più.
• "Unexpected string" / "Expected comma" — manca una virgola tra due valori, o hai usato un a capo dove doveva esserci una virgola.
• "Unexpected token ' in JSON" — apici singoli. Sostituiscili con le doppie virgolette.
• "Unexpected end of JSON input" — una parentesi non è mai stata chiusa. Conta le tue { e }; ogni apertura ha bisogno di una chiusura corrispondente.
• "Unexpected token o in JSON" — segno classico che hai provato ad analizzare qualcosa che era già un oggetto, non una stringa JSON. Chiama un parser solo su testo.

Il modo più rapido per individuare il punto esatto è passare il testo in un formattatore che valida strada facendo. Il nostro formattatore e validatore JSON evidenzia la riga e la colonna precise del primo errore e, una volta che il JSON è valido, lo stampa formattato così che i problemi strutturali (una parentesi fuori posto, un valore annidato un livello di troppo) risultino evidenti a colpo d'occhio. Tutto gira nel tuo browser, quindi puoi controllare dati privati o sensibili in sicurezza.

Formattare vs. minificare

Due operazioni ricorrono di continuo lavorando con JSON. Formattare (detto anche abbellire o pretty-print) aggiunge indentazione e a capo per rendere leggibile un blocco denso — ideale mentre fai debug. Minificare rimuove ogni spazio e a capo superfluo per produrre l'output più piccolo possibile — ideale per l'invio in rete o l'incorporamento nel codice, quando la dimensione conta. I dati sono identici in entrambi i casi; cambia solo lo spazio bianco.

Checklist rapida

Prima di consegnare il JSON a un programma, verifica:

• Tutte le chiavi e i valori stringa usano le doppie virgolette.
• Non ci sono virgole finali.
• Non ci sono commenti.
• Ogni parentesi quadra e graffa è bilanciata.
• Supera un validatore senza errori.

Azzecca questi cinque punti e JSON diventa ciò per cui è stato progettato: un formato noioso, prevedibile, che semplicemente funziona. Quando qualcosa sfugge comunque, incollalo nel formattatore JSON e lascia che ti porti dritto al problema.