JSON Toolkit

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.

Principiante~6 min di letturaPubblicato il 2026-11-20Aggiornato il 2026-11-20
Copertina introduttiva alle strutture di array e oggetti JSON

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:

  1. 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.
  2. Separa le coppie con virgole e non lasciare mai la virgola dopo l'ultima. {"a": 1, "b": 2,} fallisce con Unexpected token } alla graffa di chiusura.
  3. 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.
  4. 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.