Cos'è JSON? Sintassi, errori comuni e come validarlo

JSON (JavaScript Object Notation) è un formato testuale leggero per memorizzare e scambiare dati strutturati, costruito con oggetti di coppie chiave/valore, array ordinati e una manciata di tipi di valore: stringhe, numeri, true, false e null. È il formato predefinito delle API web e di molti file di configurazione perché è facile da leggere per le persone e semplice da analizzare per qualsiasi linguaggio di programmazione. JSON è rigoroso: chiavi e stringhe richiedono le virgolette doppie, mentre virgole finali e commenti non sono ammessi.

Che aspetto ha JSON

JSON nasce dalla sintassi che JavaScript usa per i letterali oggetto, ma è indipendente dal linguaggio. È definito nella RFC 8259 e nello standard ECMA-404, e il riassunto di una pagina su json.org descrive l'intera grammatica. Un documento tipico ha questo aspetto:

{
  "id": 1042,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "active": true,
  "score": 98.5,
  "manager": null,
  "roles": ["admin", "editor"],
  "address": {
    "city": "London",
    "postcode": "N1 9GU"
  }
}

Gli spazi tra gli elementi (spazi, tabulazioni e a capo) vengono ignorati, quindi gli stessi dati possono stare su una sola riga o essere distribuiti con l'indentazione. Il livello più alto di un documento JSON può essere qualsiasi valore, anche se le API usano quasi sempre un oggetto o un array.

Tipi di dati JSON

Non esiste un tipo data. Le date si scrivono di solito come stringhe in formato ISO 8601, ad esempio "2026-10-13T09:30:00Z", oppure come timestamp Unix numerici; il nostro convertitore timestamp Unix passa da un formato all'altro.

Numeri e precisione

Lo standard JSON non limita la dimensione o la precisione dei numeri, ma i programmi che lo leggono sì. JavaScript memorizza i numeri come valori in virgola mobile a 64 bit, quindi gli interi maggiori di 9.007.199.254.740.991 (2⁵³ − 1) possono perdere precisione senza alcun avviso. Per gli ID molto grandi, molte API li inviano come stringhe, ad esempio "id": "1234567890123456789".

Le regole che fanno inciampare

JSON assomiglia a JavaScript, ai dizionari Python e a YAML, ed è proprio per questo che si scrive JSON non valido per distrazione. Queste regole non hanno eccezioni nel JSON standard:

• Le chiavi devono essere stringhe tra virgolette doppie. {name: "Ada"} è JavaScript valido ma JSON non valido; scrivi {"name": "Ada"}.
• Solo virgolette doppie. 'Ada' non è una stringa JSON.
• Niente virgole finali. [1, 2, 3,] e {"a": 1,} non sono validi.
• Niente commenti. Né // ... né /* ... */ sono ammessi.
• I valori letterali sono in minuscolo. True, FALSE e None (la grafia di Python) non sono validi; usa true, false e null.
• Niente undefined, funzioni o numeri speciali. Esistono in JavaScript ma non hanno un equivalente in JSON.
• Le chiavi dovrebbero essere univoche. Lo standard dice che i nomi all'interno di un oggetto dovrebbero essere univoci; con i duplicati i parser si comportano in modo diverso e molti tengono in silenzio solo l'ultimo.

Alcuni strumenti accettano varianti più permissive. File come settings.json di VS Code e tsconfig.json di TypeScript vengono letti con parser che ammettono i commenti (spesso chiamati JSONC), e JSON5 ammette commenti, virgolette singole e virgole finali. Sono formati distinti: un parser JSON standard, compreso quello usato dal tuo client API o dal tuo server, li rifiuterà.

Errori JSON comuni e come correggerli

La formulazione degli errori cambia da un parser all'altro. La tabella mostra il tipo di messaggio che vedrai dal modulo json di Python o da JSON.parse del browser, che cosa significa di solito e la correzione. La posizione indicata spesso punta subito dopo l'errore vero, quindi guarda anche il carattere che la precede.

L'ultima riga è una delle più frequenti nella pratica: il codice chiama JSON.parse o response.json() su una pagina di errore che inizia con <!DOCTYPE html>, e il < viene segnalato come token inatteso.

JSON vs YAML vs XML

YAML 1.2 è stato progettato in modo che i documenti JSON siano, salvo rari casi limite, anche YAML validi, il che rende semplice la conversione tra i due. Il nostro convertitore JSON ↔ YAML gestisce entrambe le direzioni, il formattatore YAML e il formattatore XML validano gli altri due formati, e il convertitore CSV ↔ JSON trasforma le esportazioni dei fogli di calcolo in array di oggetti.

Formattazione leggibile e minificazione

Poiché gli spazi non sono significativi, lo stesso JSON può essere formattato per le persone o per le macchine:

• Il JSON formattato in modo leggibile (pretty-printed) aggiunge a capo e indentazione, di solito due o quattro spazi, così l'annidamento si vede. Usalo per file di configurazione, documentazione e debug.
• Il JSON minificato rimuove tutti gli spazi facoltativi per ridurre il payload. Usalo per i dati inviati in rete o archiviati in massa; anche la compressione HTTP riduce le dimensioni, quindi il risparmio è spesso modesto.

{"name":"Ada","roles":["admin","editor"],"active":true}

La maggior parte dei linguaggi sa fare entrambe le cose. In JavaScript, JSON.stringify(data, null, 2) formatta con indentazione di due spazi e JSON.stringify(data) minifica. In Python, json.dumps(data, indent=2) formatta e json.dumps(data, separators=(",", ":")) produce l'output più compatto.

Come validare JSON

Validare JSON ha due livelli: è, prima di tutto, JSON sintatticamente valido? E ha la struttura che la tua applicazione si aspetta?

1. Controlla la sintassi con un parser rigoroso. Incolla il testo nel nostro formattatore e validatore JSON, che indica riga e colonna del primo errore e gira nel tuo browser. Da riga di comando, python3 -m json.tool data.json o jq . data.json stampa il documento formattato oppure un errore.
2. Correggi gli errori uno alla volta. Un parser si ferma al primo problema, quindi rieseguilo dopo ogni correzione finché non riesce.
3. Controlla la struttura. Verifica che i campi obbligatori esistano e abbiano i tipi giusti, nel codice oppure con un validatore JSON Schema.
4. Controlla la codifica. Il JSON scambiato tra sistemi dovrebbe essere UTF-8. Un file salvato con un'altra codifica può produrre caratteri strani o errori su testi non inglesi.

JSON Schema in breve

JSON Schema è un vocabolario, scritto nello stesso JSON, per descrivere come deve essere un documento valido: quali proprietà sono obbligatorie, di che tipo deve essere ciascuna, valori ammessi, pattern per le stringhe, intervalli numerici e così via. Esistono validatori per la maggior parte dei linguaggi, e formati di descrizione delle API come OpenAPI usano JSON Schema per descrivere i corpi di richieste e risposte. La specifica è pubblicata su json-schema.org. Un piccolo esempio:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "roles": { "type": "array", "items": { "type": "string" } }
  }
}

Un documento senza email o con un id di tipo stringa sarebbe JSON valido ma non supererebbe questo schema. Tieni presente che molti validatori trattano format come un'annotazione e non lo applicano, a meno che non siano configurati in tal senso.

Domande frequenti

JSON può avere commenti?

No. Il JSON standard non ammette commenti di alcun tipo. Alcuni strumenti accettano JSONC o JSON5, che li ammettono, ma i file destinati a essere letti da altri programmi dovrebbero restare in JSON puro. Se ti serve una nota, aggiungi un campo come "_comment".

Perché JSON non ammette le virgole finali?

La grammatica è stata tenuta volutamente minima e semplicemente non le prevede. Molti motori JavaScript e altri linguaggi accettano le virgole finali nella propria sintassi, ed è per questo che compaiono spesso per errore nel JSON scritto a mano.

Qual è la differenza tra JSON e un oggetto JavaScript?

JSON è un formato testuale; un oggetto JavaScript è una struttura dati in memoria. La sintassi di JSON è un sottoinsieme più rigoroso della sintassi dei letterali JavaScript. Si passa dall'uno all'altro con JSON.parse e JSON.stringify.

Cosa significa "Unexpected token < in JSON at position 0"?

Il testo da analizzare inizia con <, il che quasi sempre significa che hai ricevuto HTML, come una pagina di errore o di login, invece di JSON. Controlla l'URL della richiesta, il codice di stato HTTP e il corpo grezzo della risposta.

L'ordine delle chiavi in un oggetto JSON viene mantenuto?

Lo standard considera gli oggetti non ordinati, quindi non dovresti fare affidamento sull'ordine delle chiavi. In pratica la maggior parte dei parser moderni mantiene l'ordine in cui legge, ma l'ordine degli array è l'unico che JSON garantisce.

Quale estensione di file e tipo MIME usa JSON?

I file usano l'estensione .json e il tipo di media è application/json, come registrato nella RFC 8259.