What Does Flattening a JSON Mean? Cosa significa davvero il termine (Guida 2026)

La parola stessa: cosa significa "piatto" nei dati

Dimentica il JSON per un momento e immagina la parola. Una superficie piatta non ha dossi, strati o profondità nascoste: tutto sta allo stesso livello, visibile in una volta. Chi lavora con i dati ha preso in prestito quell'immagine. Dati piatti sono dati senza annidamento: ogni valore sta al livello principale, un valore per slot, niente infilato dentro qualcos'altro.

Una riga di foglio di calcolo è l'esempio più puro di dati piatti. Una riga, un insieme di colonne, un valore per cella. Il valore nella cella C4 non contiene un altro foglio di calcolo. Contiene testo, o un numero, o niente. Questo è piatto.

Il JSON, al contrario, non è quasi mai piatto. Si annida: gli oggetti contengono oggetti, gli array contengono oggetti, gli oggetti contengono array. Un record cliente può contenere un oggetto indirizzo, che contiene coordinate, che contengono una coppia di numeri. Quell'annidamento è l'intero scopo del JSON, ed è anche il motivo per cui esiste la parola "appiattimento". Non puoi versare un albero in una tabella senza fare qualcosa ai rami. Appiattire è il nome di quel qualcosa.

Quindi quando qualcuno dice "appiattisci il JSON", intende: riscrivi questa struttura annidata così che ogni valore viva al livello principale, con nomi che registrano da dove proviene. Il valore stesso non cambia. Cambia il suo indirizzo, da un percorso attraverso oggetti annidati a un singolo nome piatto.

Perché la parola esiste: il JSON si annida, il CSV no

Ecco la tensione in un'immagine sola. Il JSON è un albero: rami, sotto-rami, foglie. Il CSV è una tabella: righe e colonne, e niente di più profondo. Una cella CSV non può contenere un oggetto. Può contenere solo testo. Quindi ogni conversione da JSON a CSV deve rispondere alla stessa domanda: cosa facciamo con l'annidamento?

Le risposte possibili sono poche, e "appiattimento" è la più comune. Prendi questo record reale, del tipo che un'API potrebbe restituire:

Nested: the address object lives inside the customer record

{
  "id": "A-101",
  "customer": { "name": "Amelia", "city": "Austin" },
  "tags": ["new", "vip"]
}

L'oggetto customer è un livello più in basso. La lista tags è un livello più in basso. Un CSV non ha il concetto di "un livello più in basso", quindi la versione appiattita tira tutto in superficie. Output verificato dal convertitore di questa pagina:

Cosa fa davvero l'appiattimento, passo per passo

L'appiattimento non è un unico trucco, sono quattro piccole regole applicate ovunque. Passa il record qui sopra nel convertitore di questa pagina con l'appiattimento attivo, ed ecco esattamente cosa esce, verificato sulla macchina di build:

Flattened: depth 1, one value per slot (verified converter output)

{
  "id": "A-101",
  "customer.name": "Amelia",
  "customer.city": "Austin",
  "tags": "new; vip"
}

Regola uno: gli oggetti annidati diventano colonne in notazione a punti. Il percorso verso il valore diventa il nome: customer.name, customer.city. I punti sono solo briciole di pane. Niente del nome di Amelia è cambiato, è cambiata solo la sua etichetta di indirizzo.

Regola due: le liste brevi di valori semplici vengono unite in una sola cella. "new" e "vip" sono diventati il singolo testo "new; vip". I due valori ci sono ancora, ma ora sono una stringa con un separatore, e il fatto che fossero due non è più leggibile da una macchina.

Regola tre: le liste di oggetti non si possono unire sensatamente, quindi collassano in testo JSON dentro una singola cella. Una lista di articoli come [{"sku":"B1","qty":2}] diventa un'unica lunga cella tra virgolette. I dati sopravvivono, ma come testo che dovresti analizzare di nuovo, non come struttura.

Regola quattro: null e i valori vuoti diventano celle vuote. Non c'è modo di scrivere "esplicitamente niente" in una tabella piatta, quindi null svanisce semplicemente in uno spazio vuoto. Ricorda questa: dopo l'appiattimento non puoi distinguere "era null" da "era una lista vuota" o "mancava del tutto".

Confronta con l'appiattimento disattivato sugli stessi dati, e la differenza è l'intero significato della parola. Con l'interruttore spento, l'oggetto customer resta come un'unica cella di testo JSON: {"name":"Amelia","city":"Austin"}. I dati non sono persi, ma non sono nemmeno piatti: c'è ancora annidamento dentro la cella, e un foglio di calcolo ti mostrerà un blob illeggibile. Piatto significa piatto fino in fondo, un valore per cella, senza eccezioni.

La confusione da chiarire: appiattire non è minificare

Chiedi a cinque principianti cosa significa "appiattire un JSON" e uno di loro farà questo: cancellare tutti gli a capo e gli spazi, producendo un'unica riga gigante. Questa è minificazione, non appiattimento, e la distinzione conta perché le parole suonano correlate ma descrivono cose completamente diverse.

La minificazione cambia gli spazi bianchi. L'appiattimento cambia la struttura. Un file JSON minificato è ancora annidato, solo che è annidato su una riga. Verificato sulla macchina di build: analizzare le versioni minificata e formattata dello stesso record produce strutture identiche byte per byte, e l'oggetto customer è comunque un oggetto in entrambi i casi. L'albero non si è mosso. È cambiata solo la vernice.

Minified is still nested (depth 2); flattened is depth 1

# minified: no whitespace, STILL nested -> customer is an object
{"id":"A-101","customer":{"name":"Amelia","city":"Austin"},"tags":["new","vip"]}

# flattened: depth 1, nothing nested at any width
{"id":"A-101","customer.name":"Amelia","customer.city":"Austin","tags":"new; vip"}

Perché nasce la confusione? Perché nel linguaggio comune "piatto" a volte significa "su una riga", come in "mettilo tutto in una riga". Nel lavoro sui dati, "piatto" significa "senza annidamento". Se un tutorial ti dice di appiattire il JSON prima di importarlo in un foglio di calcolo, intende il tipo strutturale: colonne in notazione a punti, liste unite, un valore per cella. Cancellare gli spazi bianchi non aiuterà la tua importazione di una virgola.

La stessa idea veste nomi diversi

Una volta che sai cosa significa appiattire, inizi a vederlo ovunque, vestito in modo diverso. Nella libreria pandas di Python, la funzione si chiama json_normalize, e "normalize" fa esattamente il lavoro dell'appiattimento: gli oggetti annidati diventano colonne in notazione a punti. Verificato nei nostri test precedenti: appiattisce customer.address in customer.city allo stesso modo del convertitore di questa pagina.

In Power Query di Excel, il pulsante dice "Espandi": fai clic sulla piccola doppia freccia su una colonna di record annidati e li espande in nuove colonne. Stessa idea, verbo più amichevole. In SQL, UNNEST trasforma un array annidato in righe. Stessa famiglia.

Un avviso onesto: in jq, lo strumento da riga di comando per JSON, "flatten" significa qualcosa di più ristretto. Il flatten di jq collassa array annidati in un unico array, non trasforma gli oggetti in percorsi in notazione a punti. Se un tutorial di jq dice "flatten", controlla quale significato intende prima di dare per scontato. Il mondo dei dati riusa le parole con leggerezza, e questo è l'unico punto in cui il termine si divide davvero.

L'appiattimento ha anche due cugini stretti che vale la pena nominare, perché la gente mescola tutti e tre. L'appiattimento mantiene una riga per record e allarga le colonne. L'esplosione mantiene le colonne e moltiplica le righe: una riga per elemento della lista. L'unione piega una lista in una singola cella, ed è ciò che la regola due qui sopra fa alle liste brevi. La nostra guida "how to flatten the JSON data: esplodere, unire o lasciare annidato (Guida 2026)" illustra la decisione tra esplodere e unire con esempi reali, e "Come appiattire JSON in CSV: cosa fa davvero l'interruttore di appiattimento (Guida 2026)" mostra cosa fa l'interruttore di appiattimento del convertitore cella per cella.

Cosa ti costa l'appiattimento

L'appiattimento è un lavoro onesto, ma è un lavoro con perdita, e vale la pena nominare le perdite prima di fare clic. Primo, la forma è andata per sempre. Dopo l'appiattimento, niente registra che city e state fossero fratelli dentro un unico oggetto address. Sono solo due colonne che per caso condividono un prefisso.

Secondo, la notazione a punti ha un'ambiguità di cui nessuno ti avverte. Se il tuo JSON contiene letteralmente una chiave chiamata "a.b" al livello principale E un oggetto annidato a con chiave b, entrambe si appiattiscono nello stesso nome di colonna, e un valore sovrascrive l'altro in silenzio. Raro in pratica, brutale quando capita.

Terzo, le liste unite perdono il conteggio come dato. "new; vip" sembra una stringa. Un programma che legge il CSV non può sapere che erano due tag senza dividere sul separatore, e se un tag contiene mai un punto e virgola, anche quello si rompe.

Quarto, i tipi collassano. 101 diventa i caratteri "101". true diventa i caratteri "true". Chiunque apra il CSV decide cosa significano, ed Excel in particolare ama reinterpretare i tuoi dati: gli zeri iniziali svaniscono, gli ID lunghi diventano notazione scientifica. I valori sono sopravvissuti all'appiattimento; potrebbero non sopravvivere al foglio di calcolo.

Niente di tutto questo significa che appiattire sia sbagliato. Significa che l'appiattimento è un viaggio di sola andata, e dovresti conservare il JSON originale come fonte di verità. Appiattisci una copia, lavora sulla copia, e non buttare mai via l'albero da cui l'hai appiattita.

Dovresti appiattire? Una decisione in 60 secondi

La destinazione decide, non i dati. Se la destinazione è un foglio di calcolo, un'importazione CSV o un umano che scorre le righe, appiattisci: è ciò che quegli strumenti sono costruiti per consumare, e un file appiattito si apre in modo pulito ovunque.

Se la destinazione è un altro programma, un'API o un viaggio di ritorno al JSON più tardi, non appiattire. Conserva l'annidamento, perché ogni perdita dell'appiattimento elencata qui sopra diventa un bug che devi sbrogliare sulla via del ritorno.

Se non sei sicuro, appiattisci una copia e guardala. Apri il CSV, controlla che le colonne in notazione a punti abbiano senso, che le liste unite sembrino giuste, che niente di importante sia diventato un blob illeggibile. Sessanta secondi di sguardo battono un'ora di debug di un'importazione sbagliata.

Foglio di calcolo, importazione CSV, revisione umana: appiattisci, è ciò che quegli strumenti si aspettano.
API, database, viaggio di ritorno al JSON: conserva l'annidamento, le perdite dell'appiattimento diventano bug.
Non sei sicuro: appiattisci una copia, aprila e controlla le colonne prima di impegnarti.

Provalo in questa pagina

Il convertitore in cima a questa pagina appiattisce per impostazione predefinita. Incolla qualsiasi JSON annidato e guarda l'anteprima: gli oggetti annidati diventano colonne in notazione a punti, le liste si uniscono con "; " e ogni cella contiene esattamente un valore. Disattiva l'appiattimento e incolla lo stesso JSON per vedere la differenza che fa la parola: blob annidati nelle celle contro una tabella piatta e pulita. Quel confronto fianco a fianco, sui tuoi dati, è il modo più veloce per far sedimentare il termine.

Se il tuo JSON ha liste di oggetti che vorresti davvero come righe, l'appiattimento da solo non basta: si chiama esplosione, un'operazione diversa, e la nostra guida "how to flatten the JSON data: esplodere, unire o lasciare annidato (Guida 2026)" spiega esattamente quando esplodere invece.

Guide correlate

Domande frequenti

Cosa significa appiattire un JSON, in parole semplici?

Significa riscrivere JSON annidato così che niente sia più annidato. Gli oggetti dentro gli oggetti diventano nomi in notazione a punti come customer.city, le liste brevi diventano un'unica cella unita, e ogni valore sta al livello principale, uno per cella. Il risultato è una tabella piatta, che è ciò di cui hanno bisogno i file CSV e i fogli di calcolo.

Appiattire il JSON è la stessa cosa che minificarlo?

No, ed è la confusione più comune. La minificazione rimuove gli spazi bianchi, producendo un'unica riga lunga che resta completamente annidata. L'appiattimento cambia la struttura stessa, tirando i valori annidati al livello principale. Un file minificato si analizza nello stesso identico albero; un file appiattito è una forma diversa, più superficiale.

Appiattire un file JSON cambia i miei dati?

Cambia la forma, non i valori. Ogni valore foglia sopravvive, ma l'annidamento diventa colonne in notazione a punti, le liste diventano testo unito, i tipi collassano in testo e null diventa una cella vuota. Conserva il JSON originale come fonte di verità e tratta il file appiattito come una copia di lavoro.

Qual è la differenza tra appiattire ed esplodere il JSON?

L'appiattimento mantiene una riga per record e allarga le colonne: i percorsi annidati diventano nuove colonne. L'esplosione mantiene le colonne e moltiplica le righe: ogni elemento di una lista ottiene la sua riga, con il resto del record ripetuto. Appiattisci un cliente con tre tag e ottieni una riga con una cella "tag1; tag2; tag3"; esplodilo e ottieni tre righe. La nostra guida "how to flatten the JSON data: esplodere, unire o lasciare annidato (Guida 2026)" spiega quando scegliere l'una o l'altra.

Perché i file CSV hanno bisogno di dati piatti?

Perché un CSV ha solo righe, colonne e testo. Non c'è un posto dove mettere l'annidamento: una cella non può contenere un oggetto, solo caratteri. Quindi le strutture annidate vanno appiattite (o impacchettate come testo JSON in una cella) prima di poter vivere in un CSV.

Posso de-appiattire un CSV tornando al JSON annidato?

Solo approssimativamente. Colonne in notazione a punti come customer.city possono essere raggruppate in oggetti annidati da uno script, e alcuni strumenti lo fanno, ma l'informazione distrutta dall'appiattimento è andata: le liste unite non si possono dividere di nuovo in array in modo affidabile, i tipi sono congetture, e null contro mancante è inconoscibile. Se ti serve l'annidamento indietro, conserva il JSON originale.

Il convertitore da JSON a CSV di questa pagina appiattisce automaticamente?

Sì, l'appiattimento è attivo per impostazione predefinita: incolla JSON annidato e l'anteprima mostra subito colonne in notazione a punti. Puoi disattivarlo, nel qual caso oggetti annidati e array restano come testo JSON dentro singole celle. Per lavorare nei fogli di calcolo, lascialo attivo.

Guarda l'appiattimento dal vivo

Incolla JSON annidato nel convertitore e vedi l'appiattimento trasformarlo in colonne in notazione puntata. Gratis, senza registrazione, gira interamente nel tuo browser.

Apri il convertitore JSON in CSV

Tutte le guide