Array e oggetti JSON: struttura e annidamento per principianti
In sintesi: JSON ha solo due contenitori: l'oggetto per i campi nominati, l'array per le liste ordinate. Impara a combinarli, a scegliere quello giusto e a correggere i tre errori più frequenti: falsi array con chiavi numeriche, virgola finale e apostrofi.

JSON ti dà solo due contenitori: l'oggetto porta campi nominati, l'array porta liste ordinate — e quasi ogni payload malformato si spiega con virgolette, virgole, o una lista scritta come un falso oggetto.
Uno: JSON ha solo due contenitori
Per quanto complessa sia una risposta API, tutto si riduce a due contenitori e sei tipi di valore. Un oggetto è una collezione di coppie chiave/valore racchiusa tra graffe {}; un array è una lista ordinata di valori racchiusa tra parentesi quadre []. Un valore può essere una stringa, un numero, true, false, null — oppure di nuovo un oggetto o un array. Oggetti dentro array, array dentro oggetti: questa ricorsione è tutta la potenza espressiva di JSON.
{
"user": { "name": "Ada", "active": true },
"roles": ["admin", "editor"],
"lastLogin": null,
"loginCount": 42
}
Da qui una conseguenza pratica: davanti a un payload confuso, non leggerlo carattere per carattere. Verifica prima se il carattere più esterno è { o [. Se è un oggetto, leggilo come campi nominati; se è un array, leggilo come lista e poi scendi livello per livello. Il diagramma grammaticale di json.org sta in una sola pagina proprio perché due strutture più la ricorsione coprono tutto.
Due: scrivere oggetti, quattro regole ferree
Gli oggetti sono dove i principianti sbagliano di più, ma le regole si riducono a quattro:
- Le chiavi devono essere stringhe tra virgolette doppie.
{name: "Ada"}e{'name': 'Ada'}sono entrambi invalidi; bisogna scrivere{"name": "Ada"}. I letterali oggetto di JavaScript consentono chiavi nude e apostrofi, JSON no — è la confusione più comune tra i due. - Separa le coppie con virgole e non lasciare mai la virgola dopo l'ultima.
{"a": 1, "b": 2,}fallisce conUnexpected token }alla graffa di chiusura. - Le chiavi dovrebbero essere uniche. RFC 8259 lo formula come SHOULD, non MUST: le chiavi duplicate non causano errore, ma conservare il primo o l'ultimo valore dipende dall'implementazione, e i linguaggi divergono. Non ci fare mai affidamento.
- L'ordine delle chiavi non ha significato.
{"a":1,"b":2}e{"b":2,"a":1}sono lo stesso oggetto; i tool di diff e le funzioni di confronto ignorano l'ordine delle chiavi. Se l'ordine conta, i dati appartengono a un array.
Tre: scrivere array, l'ordine è un dato
Gli array conservano i valori per posizione e l'indicizzazione parte da 0: in ["admin", "editor"] la stringa "editor" è [1]. Questo ordine è significativo — è la differenza essenziale tra array e oggetti. Risultati di ricerca ordinati per rilevanza, voci di log ordinate per data: questa informazione vive solo nella sequenza, e convertirla in oggetto la distrugge.
Due raccomandazioni pratiche. Primo, mantieni gli elementi omogenei: [{"id":1},{"id":2}] è molto più facile da consumare di [1, "text", true], che è legale ma obbliga ogni consumatore a testare i tipi a ogni passo. Secondo, un array vuoto [] è un valore perfettamente valido — quando un campo lista non ha ancora contenuto, emetti [] invece di null, così il consumatore non deve verificare prima l'esistenza e poi il vuoto.
[
{ "city": "Tokyo", "population": 13960000 },
{ "city": "Delhi", "population": 16780000 }
]
Quattro: l'annidamento, le quattro forme dei payload reali
I dati reali sono solo questi due contenitori annidati l'uno nell'altro, e i pattern si riducono a quattro forme:
| Forma | Come appare | Uso tipico |
|---|---|---|
| Oggetto contenente un array | {"tags": ["a","b"]} |
Campo lista di un'entità |
| Array di oggetti | [{"id":1},{"id":2}] |
Liste di record, risultati paginati |
| Oggetto contenente un oggetto | {"db": {"host": "..."}} |
Configurazione raggruppata, blocchi indirizzo |
| Array di array | [[1,2],[3,4]] |
Matrici, righe di tabella |
Una tipica risposta API usa un oggetto come involucro e un array come contenuto:
{
"code": 0,
"data": {
"items": [
{ "id": 1, "title": "first" },
{ "id": 2, "title": "second" }
],
"page": 1,
"total": 2
}
}
Non annidare per annidare. Oltre i tre o quattro livelli i percorsi di accesso diventano illeggibili e il codice consumatore si gonfia in parallelo. I campi che viaggiano sempre insieme appartengono a un sotto-oggetto: sostituisci addrCity e addrZip con address: {city, zip}.
Cinque: oggetto o array, una tabella decisionale
| Domanda | Risposta | Perché |
|---|---|---|
| Ogni valore ha un nome? | Oggetto | Accesso per chiave; aggiungere o togliere campi non rompe nulla |
| È una lista di record simili? | Array | L'ordine conta; si può mappare e filtrare |
| Serve una ricerca veloce per chiave? | Oggetto indicizzato per identificatore | Accesso O(1) invece di una scansione |
| Più attributi di una stessa entità? | Oggetto | Gli attributi non hanno un ordine proprio |
| Collezione crescente di elementi simili? | Array | La lunghezza si estende liberamente |
Un anti-pattern merita una menzione speciale: imitare un array con un oggetto le cui chiavi sono "0", "1", "2". Si parsa senza errori, ma perdi la semantica della lunghezza e gli strumenti di iterazione di un vero array, e i consumatori devono ordinare Object.keys prima di leggere qualsiasi cosa. Se le chiavi sono numeri sequenziali, scrivi un vero array. Vale anche l'inverso: una lista di coppie chiave/valore come [{"key":"theme","value":"dark"}] è inferiore all'oggetto {"theme": "dark"} — salvo che le chiavi siano davvero dinamiche e non dichiarabili in anticipo.
Sei: tre errori frequenti e i loro messaggi
| Forma errata | Errore tipico | Correzione |
|---|---|---|
Virgola finale {"a":1,} |
Unexpected token } |
Togliere l'ultima virgola |
Apostrofi / chiavi nude {name:'Ada'} |
Unexpected token ' / Expected property name |
Virgolette doppie per chiavi e stringhe, sempre |
Letterali Python True / None |
Unexpected token T |
Sostituire con true / null |
| Falso array con chiavi numeriche | Nessun errore, semantica sbagliata | Riscrivere come vero array |
Due abitudini di debug: i parser segnalano di solito una posizione dopo il carattere colpevole, quindi quando vedi position 42, guarda uno o due caratteri indietro; e un JSON enorme su una sola riga va formattato prima — i numeri di riga e colonna battono gli offset di caratteri ogni volta. Il catalogo completo degli errori è in la tabella di lookup degli errori JSON, e il flusso di triage passo-passo in come correggere gli errori di parse JSON.
Sette: dopo aver scritto, verifica la struttura
Un JSON scritto a mano deve sempre passare da un parser prima della consegna. La verifica più leggera sta in una riga di comando:
python3 -m json.tool config.json > /dev/null && echo OK
jq empty config.json && echo OK
Online incolla il contenuto nella pagina formattatore e validatore JSON — gli errori di sintassi tornano con riga e colonna. Passa alla vista ad albero per vedere il tipo di ogni livello a colpo d'occhio: se un numero è stato interpretato come stringa, se le lunghezze degli array coincidono. E quando il pubblico non è tecnico, un payload array-di-oggetti può essere disteso in righe e colonne nella pagina JSON in tabella, il che verifica anche che i tuoi dati formino davvero una lista regolare di record.
Le domande sul campo che doveva essere un array, o sul rifacimento di un annidamento diventato troppo profondo, appartengono alla modellazione dei tipi — la prossima lettura è sei tipi, precisione numerica e trappole di encoding.
Array e oggetti JSON possono essere convertiti l'uno nell'altro?
Sì, ma non senza perdite. Convertire un oggetto in array significa di solito trasformare le chiavi in valori e perdere l'accesso per chiave; convertire un array in oggetto richiede di inventare una chiave per ogni elemento, e l'origine di quelle chiavi è un nuovo problema di design. Decidi in base a come il consumatore legge i dati, non alla comodità sintattica.
Le chiavi di un oggetto possono essere duplicate?
Sintatticamente sì — RFC 8259 dice solo che le chiavi DOVREBBERO essere uniche. Ma JavaScript conserva l'ultimo valore mentre alcune librerie della famiglia C conservano il primo: il comportamento diverge tra i parser. In firme, diff o hash, le chiavi duplicate causano disaccordi diretti. Evitali lato produttore e tratta i duplicati da una fonte sconosciuta come un rischio lato consumatore.
Un array può contenere valori di tipi diversi?
Sintatticamente sì: [1, "a", true] è un JSON valido. Ma gli array eterogenei costringono a verifiche di tipo a ogni posizione nel codice consumatore, e sono difficili da esprimere in uno schema. Salvo matrici e tuple, dove la posizione è la semantica, mantieni gli array omogenei.
Perché {name:'json'} fallisce la validazione?
Perché JSON esige virgolette doppie attorno a ogni chiave e a ogni valore stringa. {name:'json'} è un letterale oggetto JavaScript, non JSON. Sostituiscilo con {"name": "json"} e la validazione passa. Apostrofi, chiavi nude e commenti appartengono a dialetti come JSON5/JSONC, che richiedono parser propri invece del JSON.parse standard.