Come Convertire JSON in CSV (Senza Perdere Dati)

Convertire JSON in CSV significa trasformare un array di oggetti in una tabella: ogni oggetto diventa una riga, ogni chiave diventa una colonna. Il punto che genera più errori non è la trasformazione in sé, ma l’escaping: cosa succede quando un valore contiene una virgola, delle virgolette o va a capo. Se non sai come funziona quella regola, un file che sembra corretto può finire per mescolare colonne o perdere dati senza che tu te ne accorga subito.

Perché il CSV conta ancora

Il JSON è il formato naturale per API e configurazioni, ma per chi lavora con fogli di calcolo resta un file illeggibile fatto di parentesi graffe annidate. Il CSV, al contrario, si apre direttamente in Excel, Google Sheets o Numbers e si legge a colpo d’occhio. Per questo capita spesso di dover passare da un formato all’altro: un’API restituisce dati in JSON, ma un collega del reparto commerciale li vuole in un foglio, oppure una pipeline di importazione accetta solo CSV. La conversione stessa è semplice; le insidie stanno nei dettagli di come i valori vengono trasformati in testo.

Un esempio verificato, riga per riga

Prendi questo array JSON, tipico di un piccolo catalogo prodotti:

[
  { "sku": "A100", "product": "Wireless Mouse, Black", "price": 19.99, "in_stock": true },
  { "sku": "A101", "product": "17\" Laptop Stand", "price": 42.5, "in_stock": false },
  { "sku": "A102", "product": "USB-C Cable", "price": 8.99, "in_stock": true }
]

L’intestazione delle colonne è l’unione di tutte le chiavi viste in tutti gli oggetti, nell’ordine in cui compaiono la prima volta: sku, product, price, in_stock. Il risultato è questo:

sku,product,price,in_stock
A100,"Wireless Mouse, Black",19.99,true
A101,"17"" Laptop Stand",42.5,false
A102,USB-C Cable,8.99,true

Guarda cosa succede riga per riga. Nella prima riga, Wireless Mouse, Black contiene una virgola: se restasse così com’è, un parser CSV la leggerebbe come separatore tra due colonne inesistenti, quindi il valore viene racchiuso tra virgolette doppie e diventa "Wireless Mouse, Black". Nella seconda riga il prodotto è 17" Laptop Stand, con un carattere di virgolette doppie letterale dentro il nome. La regola RFC 4180 (lo standard che definisce il formato CSV) impone due cose insieme: raddoppiare ogni virgoletta interna (" diventa "") e racchiudere l’intero valore tra un’altra coppia di virgolette esterne. Il risultato è "17"" Laptop Stand", che a prima vista sembra strano ma è l’unico modo per cui un parser CSV possa distinguere le virgolette che fanno parte del dato da quelle che delimitano il campo. Nella terza riga, USB-C Cable non contiene né virgole, né virgolette, né interruzioni di riga, quindi passa senza modifiche, senza bisogno di alcun escaping.

La stessa regola vale per qualunque valore che contenga un a capo: viene racchiuso tra virgolette esattamente come una virgola o una virgoletta interna, perché altrimenti spezzerebbe la riga CSV in due.

Cosa succede quando un oggetto ha chiavi in più

L’intestazione non si limita alle chiavi del primo oggetto dell’array: è l’unione di tutte le chiavi trovate in qualsiasi oggetto, mantenendo l’ordine di prima comparsa. Se un oggetto successivo introduce una chiave nuova, quella chiave diventa comunque una colonna, anche se i record precedenti non la avevano. Prendi questo caso:

[
  { "id": 1, "name": "Tastiera" },
  { "id": 2, "name": "Mouse", "color": "black" },
  { "id": 3, "name": "Monitor", "color": "silver", "warranty_months": 24 }
]

Le colonne finali sono id, name, color, warranty_months, nell’ordine in cui ciascuna chiave è comparsa per la prima volta (la prima riga la introduce, la seconda o la terza). Il CSV risultante è:

id,name,color,warranty_months
1,Tastiera,,
2,Mouse,black,
3,Monitor,silver,24

Le celle mancanti restano semplicemente vuote, non generano un errore né saltano la riga. Un convertitore ingenuo che guarda solo le chiavi del primo oggetto perderebbe silenziosamente le colonne color e warranty_months: è un bug comune in script scritti al volo, e vale la pena verificarlo prima di fidarsi di un dataset con oggetti di forma variabile.

Prova la conversione

Incolla il tuo array JSON qui sotto per vedere il CSV generato all’istante, con lo stesso comportamento descritto sopra: unione delle chiavi, escaping RFC 4180, celle vuote per i campi mancanti. Tutto avviene nel browser, nessun dato lascia il tuo computer.

Errori comuni

Oggetti annidati diventano [object Object]. Se una chiave contiene un altro oggetto invece di un valore semplice, la conversione lo trasforma nella stringa letterale [object Object], perdendo tutti i dati che conteneva. Per esempio, questo record:

{ "id": 1, "name": "Mario Rossi", "address": { "city": "Torino", "zip": "10121" } }

produrrebbe una colonna address piena di [object Object], inutilizzabile. La correzione è appiattire l’oggetto prima di convertirlo, portando le sue chiavi al livello superiore con un prefisso:

{ "id": 1, "name": "Mario Rossi", "address_city": "Torino", "address_zip": "10121" }

Così ottieni due colonne separate, address_city e address_zip, con i valori reali al loro interno.

Gli array diventano una singola cella, non colonne separate. Un valore come ["red", "blue"] non viene esploso in più colonne: viene unito in una stringa con le virgole come separatore e senza parentesi, cioè red,blue. Siccome quella stringa contiene a sua volta una virgola, la regola di escaping vista sopra la racchiude tra virgolette per non confonderla con un separatore di colonna, ottenendo "red,blue" nel file finale. Il risultato è corretto dal punto di vista del formato CSV, ma se ti aspettavi una colonna per ogni elemento dell’array resterai deluso: dovrai separare quei valori a mano dopo l’importazione, oppure ristrutturare il JSON di partenza prima di convertirlo.

Il CSV si apre tutto in una colonna in Excel (in italiano). Il file generato usa la virgola come delimitatore, che è lo standard CSV internazionale. Excel in lingua italiana, però, usa la virgola come separatore decimale dei numeri, quindi per impostazione predefinita si aspetta il punto e virgola come separatore di elenco negli import CSV. Il sintomo tipico è aprire il file e vedere tutte le colonne incollate insieme nella cella A, come se non ci fosse stata alcuna conversione. La soluzione più rapida è usare “Dati > Testo in colonne” in Excel e scegliere esplicitamente la virgola come delimitatore; in alternativa si può cambiare il separatore di elenco nelle impostazioni internazionali del sistema operativo.

Dimenticare le parentesi quadre attorno a un singolo oggetto. Il convertitore accetta solo un array di oggetti, anche quando c’è un solo record da convertire. Incollare { "id": 1, "name": "Mario" } da solo, senza racchiuderlo tra [ e ], non produce un array valido e il tool mostra un errore invece di generare il CSV. Basta racchiudere l’oggetto tra parentesi quadre, [{ "id": 1, "name": "Mario" }], anche se contiene una sola riga.

Domande frequenti

Come vengono determinate le colonne del CSV? Sono l’unione di tutte le chiavi trovate in ogni oggetto dell’array, non solo le chiavi del primo oggetto, nell’ordine in cui ciascuna chiave compare per la prima volta. Se un oggetto non ha una certa chiave, la cella corrispondente resta vuota invece di generare un errore.

Perché nel CSV alcuni valori sono racchiusi tra virgolette e altri no? Perché lo standard RFC 4180 racchiude tra virgolette solo i valori che contengono una virgola, una virgoletta doppia o un a capo, cioè i caratteri che altrimenti verrebbero interpretati male da un parser CSV. Un valore semplice come USB-C Cable non ha bisogno di virgolette e resta invariato.

Perché un oggetto annidato diventa [object Object] nel CSV? Perché la conversione trasforma ogni valore in testo con una semplice chiamata di stringificazione, e per un oggetto JavaScript quel processo produce letteralmente il testo [object Object], senza includere le sue chiavi interne. La correzione è appiattire l’oggetto annidato in chiavi separate al primo livello prima di convertire, per esempio address_city e address_zip invece di un unico campo address.

Posso convertire un array che contiene un campo con valori multipli, come una lista di tag? Sì, ma il risultato sarà una singola cella con i valori uniti da virgole (per esempio ["rosso","blu"] diventa la stringa rosso,blu, correttamente racchiusa tra virgolette perché contiene una virgola), non colonne separate per ogni elemento. Se ti serve una colonna per valore, devi ristrutturare i dati prima della conversione.

Il file CSV generato è compatibile con Excel in italiano? È un CSV standard con la virgola come delimitatore, quindi si apre correttamente con “Apri con” o trascinandolo in un foglio già vuoto. Il problema riguarda solo l’importazione guidata di Excel in lingua italiana, che per default cerca il punto e virgola: in quel caso basta scegliere manualmente la virgola come delimitatore nel passaggio “Testo in colonne”.