Come appiattire JSON in CSV: cosa fa davvero l'interruttore di appiattimento (Guida 2026)

Perché il JSON resiste alla piattezza: alberi contro griglie

Un CSV è una griglia: righe e colonne, ogni cella un singolo valore piatto. Il JSON è un albero: oggetti dentro oggetti, elenchi dentro oggetti, oggetti dentro elenchi. L'appiattimento è la traduzione tra queste due forme, ed è l'unica parte della conversione da JSON a CSV in cui il convertitore deve prendere decisioni al posto tuo — perché non esiste una sola risposta "corretta". Chi cerca come appiattire JSON in CSV di solito inciampa proprio qui: si aspetta che la conversione sia meccanica, e invece c'è un passaggio di interpretazione.

Prendi il record annidato più semplice: { "id": 1, "customer": { "name": "Ana", "city": "Madrid" } }. Una griglia non ha modo di contenere un "customer" che contiene due cose. Così il convertitore deve scegliere: dare a customer una colonna propria e infilarci dentro l'oggetto come testo, oppure esplodere l'oggetto nelle colonne customer.name e customer.city. Ogni convertitore fa questa scelta con la stessa manciata di regole — e una volta che le conosci, puoi prevedere il tuo CSV prima ancora di premere converti.

L'esempio concreto che appiattiremo

Tutto ciò che segue è dimostrato su un unico file — tre ordini con tre livelli di annidamento, un elenco di valori semplici, un elenco vuoto, un oggetto vuoto, un null e un elenco di oggetti. Abbiamo passato questo file esatto nel vero motore di conversione di questo sito (lo stesso JavaScript che gira quando premi Converti), e ogni output mostrato è ciò che il motore ha prodotto davvero:

orders-nested.json

[
  { "orderId": "A-101", "customer": { "name": "Ana Ruiz", "contact": { "email": "ana@example.com", "city": "Madrid" } }, "items": ["book", "pen"], "tags": [], "meta": {} },
  { "orderId": "A-102", "customer": { "name": "Ken Sato", "contact": { "email": "ken@example.com", "city": "Osaka" } }, "items": ["lamp"], "tracking": [{ "code": "TX-1", "status": "shipped" }, { "code": "TX-2", "status": "pending" }] },
  { "orderId": "A-103", "customer": { "name": "Lina Noor", "contact": { "email": null, "city": "Berlin" } }, "items": ["mug", null, "plate"] }
]

Regola 1: gli oggetti annidati diventano colonne con notazione a punti

La prima e più importante regola: ogni livello di annidamento di oggetti diventa un nome di colonna con i livelli uniti da punti. customer.contact.email non sono tre colonne — è una colonna sola il cui nome è il percorso completo lungo l'albero. Ecco l'output reale del motore con l'appiattimento attivo:

CSV output — flattening ON (verified against the real engine)

orderId,customer.name,customer.contact.email,customer.contact.city,items,tags,meta,tracking
A-101,Ana Ruiz,ana@example.com,Madrid,book; pen,,{},
A-102,Ken Sato,ken@example.com,Osaka,lamp,,,"[{""code"":""TX-1"",""status"":""shipped""},{""code"":""TX-2"",""status"":""pending""}]"
A-103,Lina Noor,,Berlin,mug; ; plate,,,

La profondità di annidamento non ha limiti pratici nella regola stessa — abbiamo testato anche un oggetto a quattro livelli ({ a: { b: { c: { d: "deep" } } } }) e il motore ha prodotto una singola colonna chiamata a.b.c.d con il valore deep. I nomi puntati si ordinano e si filtrano normalmente in un foglio di calcolo; se customer.contact.city ti sembra troppo lungo, puoi rinominare le intestazioni dopo in un colpo solo. Questa è la regola che rende possibile appiattire JSON in CSV senza perdere la struttura logica dei dati: il percorso resta leggibile nel nome della colonna.

Regola 2: gli elenchi di valori semplici si uniscono in un'unica cella

Quando un elenco contiene solo valori semplici — stringhe, numeri, booleani, null — l'intero elenco collassa in un'unica cella con i valori uniti da "; " (punto e virgola-spazio). Guarda la colonna items qui sopra: ["book", "pen"] è diventata l'unica cella book; pen, e ["mug", null, "plate"] è diventata mug; ; plate — il null si è trasformato in un segmento vuoto, non saltato.

Due conseguenze pratiche. Primo: se poi scegli il punto e virgola come delimitatore CSV, quella cella unita viene messa tra virgolette automaticamente ("book; pen") così il separatore dentro la cella non può dividerla — il motore applica le regole di quotatura CSV cella per cella, verificato nel test qui sopra. Secondo: l'unione perde l'informazione sui confini — dopo l'appiattimento, book; pen è testo, non un elenco. Se devi ridividere gli articoli in righe, vedi la Regola 3.

Regola 3: gli elenchi di oggetti collassano in un'unica cella di testo JSON

Questa è la regola che sorprende tutti. Quando un elenco contiene oggetti — come l'array tracking con le sue voci { code, status } — non può diventare colonne (gli oggetti hanno struttura, non solo valori) e non può unirsi come i valori semplici. Così il motore memorizza l'intero elenco come cella di testo JSON tra virgolette. Qui sopra, la colonna tracking per A-102 contiene l'intero array JSON come testo, con escape secondo le regole CSV.

È un limite? Onestamente: sì, per questa forma. In questo convertitore non esiste un interruttore di espansione righe — non crea mai una riga CSV per ogni elemento dell'elenco. Se ti serve davvero una riga per ogni evento di tracking, ristruttura prima di convertire: estrai l'array interno (converti [{ "code": "TX-1", "status": "shipped" }, ...] da solo) e ottieni righe pulite code/status. Una colonna di testo JSON è l'alternativa onesta all'inventare in silenzio righe che non hai chiesto.

Regola 4: valori vuoti e null seguono regole precise

I null e i vuoti sono la causa della maggior parte dei "perché il mio CSV è strano", quindi ecco i comportamenti verificati, senza tirare a indovinare:

Un valore null diventa una cella vuota. L'email: null di Lina Noor ha prodotto una cella vuota sotto customer.contact.email — niente testo "null", niente virgolette.
Un elenco vuoto diventa una cella vuota. Il tags: [] di A-101 ha lasciato la cella bianca. (Nota: questo è il comportamento con appiattimento attivo; con l'appiattimento disattivo lo stesso elenco appare come testo letterale [].)
Un oggetto vuoto diventa il testo {}. Il meta: {} di A-101 ha prodotto una cella contenente {} — il motore non ha nulla da espandere, quindi scrive la forma letterale dell'oggetto.
Un null dentro un elenco diventa un segmento unito vuoto — mug; ; plate qui sopra — invece di essere saltato o scritto come "null".

Sono decisioni di progettazione, non leggi universali, ma sono coerenti: null significa "niente qui", e il CSV non dice niente.

Appiattimento attivo contro disattivo, byte per byte

Stesso file, appiattimento disattivo. Ogni chiave di primo livello mantiene la sua colonna e le strutture annidate vengono memorizzate come testo JSON tra virgolette:

CSV output — flattening OFF (verified against the real engine)

orderId,customer,items,tags,meta,tracking
A-101,"{""name"":""Ana Ruiz"",""contact"":{""email"":""ana@example.com"",""city"":""Madrid""}}","[""book"",""pen""]",[],{},
A-102,"{""name"":""Ken Sato"",""contact"":{""email"":""ken@example.com"",""city"":""Osaka""}}","[""lamp""]",,,"[{""code"":""TX-1"",""status"":""shipped""},{""code"":""TX-2"",""status"":""pending""}]"
A-103,"{""name"":""Lina Noor"",""contact"":{""email"":null,""city"":""Berlin""}}","[""mug"",null,""plate""]",,,

Nota i dettagli della modalità disattiva: le colonne si riducono alle chiavi di primo livello (customer, items, tags, meta, tracking), ogni valore annidato è JSON grezzo convertito in stringa con raddoppio delle virgolette secondo CSV, e l'elenco vuoto e l'oggetto vuoto appaiono come testo letterale [] e {}. La modalità disattiva è la rappresentazione onesta-ma-brutta — corretta quando devi preservare l'esatta struttura annidata (per esempio, prima di rimandare le righe in un sistema che si aspetta campi in forma JSON). Per l'analisi — filtri, tabelle pivot, grafici — l'appiattimento attivo è la scelta giusta, ed è per questo che è l'impostazione predefinita quando vuoi appiattire JSON in CSV per lavorarci davvero.

Da dove vengono le righe: array, wrapper API e JSON Lines

L'appiattimento decide le colonne; qualcos'altro decide le righe. Il motore guarda il tuo valore di primo livello e segue tre casi:

Caso uno: il tuo primo livello è un array di oggetti — ogni oggetto diventa una riga. Questo è l'esempio degli ordini qui sopra: tre oggetti, tre righe. Caso due: il tuo primo livello è un singolo oggetto — ottieni una riga. Il caso tre è quello utile: il tuo primo livello è un oggetto che avvolge un array, come fanno le risposte API — { "data": [ ... ], "total": 2 }. Il motore rileva l'array interno (controlla chiavi wrapper comuni come data, results, users, items) e trasforma ogni elemento in una riga, scartando i campi del wrapper. L'abbiamo verificato: { "data": [{ "a": 1, "b": 2 }, { "a": 3, "b": 4 }], "total": 2 } ha prodotto esattamente le due righe di dati con colonne a e b — total sparito.

Un'altra forma di input da conoscere: il motore accetta anche JSON Lines (NDJSON) — un oggetto JSON per riga. Se la tua esportazione è di diecimila righe invece di un unico grande array, incollala così com'è; si converte allo stesso modo.

Dati irregolari: le chiavi mancanti lasciano solo celle vuote

Le esportazioni reali sono irregolari: l'ordine A-102 ha tracking ma non meta, A-101 ha meta ma non tracking, A-103 non ha né l'uno né l'altro. Il motore costruisce l'elenco delle colonne come unione di ogni chiave trovata in ogni riga, in ordine — così la riga di intestazione qui sopra ha tutte e otto le colonne — e ogni riga a cui manca una chiave riceve semplicemente una cella vuota sotto di essa.

Ecco perché le intestazioni escono in ordine di inserimento (prima orderId, poi le prime chiavi annidate incontrate) e non in ordine alfabetico: le colonne seguono la forma dei tuoi dati mentre il motore li attraversa. Se una riga successiva introduce un percorso annidato tutto nuovo, la colonna appare comunque — niente viene scartato in silenzio.

Tre casi limite che mordono

Primo: chiavi che contengono già punti. Se il tuo JSON ha sia una chiave letterale "user.name" sia un user: { name: ... } annidato, entrambi vogliono la stessa colonna. L'abbiamo testato: vince il valore annidato e il valore della chiave letterale si perde ([{ "user.name": "x", user: { name: "y" } }] ha prodotto un'unica colonna user.name contenente y). Rinomina le chiavi puntate prima di convertire se entrambi i valori contano.

Secondo: elenchi di tipo misto. Un elenco come [1, "a", { "b": 2 }] non è "tutto primitivi", quindi il motore lo tratta come un elenco di oggetti e converte l'intera cosa in un'unica cella di testo JSON — anche se la maggior parte era semplice. Tieni gli elenchi omogenei se vuoi il comportamento di unione con "; ".

Terzo: l'annidamento profondo va bene, ma occhio ai nomi delle colonne. Dieci livelli di annidamento ti danno un nome di colonna puntato in dieci parti, tecnicamente corretto e praticamente illeggibile. Appiattisci tutto, poi rinomina le tre colonne che ti interessano davvero.

La checklist di appiattimento da 30 secondi

Se non ricordi nient'altro: lascia l'appiattimento attivo per l'analisi, disattivalo solo per preservare la struttura; aspettati colonne con notazione a punti ed elenchi uniti con "; "; estrai gli elenchi di oggetti e convertili separatamente quando ti serve una riga per elemento; e tratta le celle vuote come la rappresentazione onesta dei null — non come errori. L'interruttore è un clic solo, ma ora sai esattamente cosa fa quel clic quando devi appiattire JSON in CSV senza sorprese.

Guide correlate

Domande frequenti

Cosa significa appiattire JSON in CSV?

L'appiattimento è il passaggio che trasforma il JSON annidato in una griglia piatta da foglio di calcolo: gli oggetti annidati diventano colonne con notazione a punti (customer.contact.city), gli elenchi di valori semplici si uniscono in un'unica cella con "; ", e gli elenchi di oggetti collassano in un'unica cella di testo JSON. Senza appiattimento, i valori annidati vengono memorizzati come testo JSON grezzo tra virgolette, uno per colonna.

Come appiattisco gli oggetti JSON annidati in colonne CSV?

Usa un convertitore con l'opzione di appiattimento e lasciala attiva — gli oggetti annidati vengono espansi in colonne con notazione a punti automaticamente, a qualsiasi profondità (customer.contact.email, o persino a.b.c.d). Nel convertitore di questo sito l'appiattimento è l'impostazione predefinita: incolla o carica il tuo JSON, converti, e ogni percorso annidato diventa una colonna ordinabile e filtrabile.

Cosa succede agli array quando appiattisco JSON in CSV?

Dipende da cosa contiene l'array. Gli elenchi di valori semplici (stringhe, numeri) si uniscono in un'unica cella con "; " — ["book", "pen"] diventa book; pen. Gli elenchi di oggetti vengono memorizzati come un'unica cella di testo JSON tra virgolette, perché gli oggetti non possono diventare valori piatti. Gli elenchi vuoti diventano celle vuote. Gli elenchi misti vengono convertiti in stringa per intero, quindi tienili omogenei per risultati prevedibili.

Perché il mio CSV appiattito ha così tante celle vuote?

Le celle vuote sono normali e oneste: un valore null diventa una cella vuota, un elenco vuoto diventa una cella vuota, e quando le righe hanno chiavi diverse (dati irregolari) le chiavi mancanti lasciano spazi bianchi. Controlla se i vuoti corrispondono ai null nel tuo JSON di origine — se sì, la conversione è corretta.

Devo attivare o disattivare l'appiattimento quando converto JSON in CSV?

Lascialo attivo per l'analisi — le colonne con notazione a punti sono ciò di cui hanno bisogno tabelle pivot, filtri e grafici. Disattivalo solo quando devi preservare l'esatta struttura annidata, per esempio prima di rimandare le righe in un sistema che si aspetta campi in forma JSON. La modalità disattiva memorizza ogni valore annidato come testo JSON grezzo tra virgolette: corretto ma inutilizzabile nei fogli di calcolo.

Posso ottenere una riga CSV per ogni elemento di un array annidato di oggetti?

Questo convertitore non espande gli elenchi di oggetti in righe — li memorizza come un'unica cella di testo JSON. La soluzione affidabile: estrai l'array interno e convertilo da solo (per esempio converti solo [{"code":"TX-1"},{"code":"TX-2"}]) per ottenere un output pulito con una riga per elemento. Fai l'estrazione prima di convertire, non dopo.

Esiste uno strumento gratuito che appiattisce JSON in CSV online?

Sì — il convertitore di questo sito è gratuito, non richiede registrazione e appiattisce il JSON annidato per impostazione predefinita (colonne con notazione a punti, elenchi uniti con "; ") interamente nel tuo browser, così i tuoi dati non lasciano mai il tuo dispositivo. Carica un file o incolla il JSON, lascia l'appiattimento attivo, scegli il delimitatore e scarica il CSV.