Per convertire un JSON annidato in CSV, usa un convertitore online da JSON a CSV che ti permetta di scegliere quale array JSON trasformare nelle righe del CSV. Questa scelta è più importante di quanto si possa pensare. Le esportazioni JSON reali spesso iniziano con metadati, informazioni sulla paginazione o oggetti wrapper, mentre i record che ti servono si trovano in un percorso come results, data.items o payload.records.
Di solito considero la conversione da JSON a CSV come un insieme di tre decisioni:
- Quale array deve diventare un insieme di righe?
- Quali campi degli oggetti annidati devono diventare colonne?
- Quali array devono essere uniti, mantenuti in formato JSON o espansi in righe separate?
Una volta chiariti questi punti, il resto segue il normale flusso di lavoro di un CSV. Controlli l'anteprima, verifichi le colonne e scarichi un file CSV utilizzabile in un foglio di calcolo, un CRM, uno strumento di BI o un processo di data cleaning.
📌 In breve
Inizia stabilendo che cosa deve rappresentare ogni riga del CSV. In questo esempio voglio una società per riga, quindi il row node è
$.results. A quel punto posso appiattire le metriche aziendali e decidere come gestire array comecontactsetags.
In questa guida userò un'esportazione JSON annidata con 20.000 record aziendali all'interno di results. Lo stesso procedimento funziona con risposte API, risultati di scraping, log di webhook, esportazioni CRM e dati di marketplace in cui i record utili non si trovano alla radice del JSON.
Link rapidi:
- Esempio di file JSON annidato
- Convertire JSON annidato in CSV con Datablist
- Scegliere il row node corretto
- Appiattire gli oggetti JSON annidati
- Gestire gli array nelle righe JSON
- Controllare e scaricare il CSV
Esempio di file JSON annidato
Per questo esempio, immaginiamo una grande esportazione JSON proveniente da un'API o da uno strumento di scraping. Il file pesa circa 8,8 MB e contiene 20.000 record in un array di primo livello chiamato results.
L'oggetto radice ha questo aspetto:
{
"meta": {
"generatedAt": "2026-07-04T10:00:00Z",
"source": "stress_test"
},
"results": [
{
"id": 0,
"name": "NbDXeG4Gyg",
"website": "https://example-0.com",
"contacts": [
{
"name": "Ava Martin",
"emails": [
"ava@example-0.com"
],
"phones": [
"+1 555 0100"
]
},
{
"name": "Noah Lee",
"emails": [
"noah@example-0.com"
],
"phones": []
}
],
"tags": "enterprise",
"metrics": {
"employees": 124,
"revenue": {
"amount": 476171,
"currency": "USD"
}
},
"createdAt": "2026-06-25T09:12:00Z"
},
{
"id": 1,
"name": "DwwGmkzmBi",
"website": "https://example-1.com",
"contacts": [
{
"name": "Mia Chen",
"emails": [
"mia@example-1.com"
],
"phones": [
"+1 555 0101"
]
}
],
"tags": [
"saas",
"mid-market"
],
"metrics": {
"employees": 47,
"revenue": null
},
"createdAt": "2026-06-26T14:33:00Z"
}
]
}È il tipo di file che mette in difficoltà i convertitori più semplici. I record non coincidono con l'oggetto radice, ma si trovano dentro results. Inoltre contengono oggetti e array annidati, valori che possono essere sia stringhe sia array, valori null e date.
🔍 Perché questo file è un buon test
Un array JSON piatto verifica soltanto il caso più semplice. Questo file mette alla prova le scelte che contano nelle esportazioni reali: metadati wrapper, un array di record annidato, campi oggetto, campi array, valori misti e null.
Ecco la struttura delle prime righe:
| Riga | Formato di Website | Numero di contatti | Formato di Tags | Fatturato |
|---|---|---|---|---|
| 0 | Stringa | 2 | Stringa | Importo e valuta |
| 1 | Stringa | 2 | Array | Null |
| 2 | Array | 1 | Array | Null |
Il CSV finale deve contenere una società per riga. Voglio colonne utili come id, name, website, employees, amount, currency e createdAt. Per campi come contacts e tags, devo invece decidere quanta parte della struttura conservare.
Convertire JSON annidato in CSV con Datablist
Apri il convertitore JSON di Datablist. Puoi incollare il JSON nell'editor oppure caricare un file .json.
Per una piccola risposta API, incollare il contenuto va benissimo. Per un'esportazione più grande preferisco caricare il file, così evito che un copia e incolla incompleto tronchi accidentalmente i dati. Il contenuto viene letto nel browser e la conversione avviene in locale, senza inviare il file ai server di Datablist.
Dopo il caricamento, Datablist analizza la struttura e cerca gli array di oggetti. Accetta JSON la cui radice sia un array o un oggetto, quindi esamina percorsi annidati come $.results, $.data.items o array ancora più profondi.
Se il file è difficile da interpretare, a volte apro prima il JSON in JSONCrack. La sua visualizzazione ad albero aiuta a individuare l'array da trasformare in righe. È un passaggio facoltativo, ma torna utile quando il file contiene diversi array potenzialmente validi.
In questo esempio, il row node corretto è:
$.results
Scelgo $.results perché voglio una società per riga. Ogni elemento dell'array diventa una riga del CSV.
Datablist può suggerire un row node, ma consiglio comunque di verificarlo manualmente. È qui che avviene la maggior parte degli errori di conversione. Un file JSON può contenere un array principale di società, un array secondario di contatti e un altro array secondario di tag o eventi. Sono tutti array, ma solo uno corrisponde al CSV che vuoi ottenere.
⚠️ Cambiare il row node cambia il dataset
$.resultse$.results[].contactssono entrambi row node validi, ma non producono lo stesso CSV. Scegli l'array principale se vuoi righe relative agli account. Scegli quello secondario se sono gli elementi annidati a costituire il dataset.
Per questo articolo mantengo il row node principale:
$.resultssignifica una società o un account per riga.$.results[].contactssignificherebbe un contatto per riga.
Anche la seconda opzione può essere corretta, ma cambia il risultato. Un CSV a livello di contatto è utile quando vuoi ottenere un elenco di persone. Un CSV a livello aziendale è più adatto per pulire gli account, arricchire i dati delle società, importare record in un CRM o analizzare le metriche.
Scegliere il row node corretto
Il row node è l'array JSON i cui elementi diventano le righe del CSV.
Gli esempi più comuni sono questi:
| Percorso JSON | Quando usarlo |
|---|---|
$.results | I record sono archiviati sotto una chiave results |
$.data.items | Un'API racchiude i record in un oggetto data |
$.payload.records | Un webhook o un'esportazione interna racchiude i record sotto payload |
$.results[].contacts | Vuoi un contatto annidato per riga |
Prima di scegliere, mi pongo sempre una domanda: che cosa deve rappresentare una singola riga?
Se deve rappresentare una società, un account, un ordine, un prodotto, un annuncio o un evento, scegli l'array principale. Se invece deve rappresentare un contatto, un'email, una voce d'ordine, un prezzo, un commento o un evento secondario, scegli l'array figlio.
Sembra semplice, ma questa scelta cambia l'intero CSV.
Con $.results, il CSV mantiene il contesto aziendale. Il campo contacts resta nella riga della società come valore annidato, a meno che tu non decida di elaborare i contatti separatamente. Con $.results[].contacts, il CSV diventa una lista di contatti, ma i campi della società principale non vengono inclusi automaticamente, salvo che il convertitore non introduca questa funzione in una versione futura.
Di norma parto dall'array principale. È una prima esportazione più sicura, perché posso sempre esaminare in seguito gli array annidati. Passo a un array figlio solo quando sono davvero gli elementi annidati a costituire il dataset.
Appiattire gli oggetti JSON annidati
È nella gestione degli oggetti annidati che un convertitore CSV deve offrire qualcosa in più di una semplice trasformazione di file.
Nel file di esempio, metrics è un oggetto:
{
"metrics": {
"employees": 124,
"revenue": {
"amount": 476171,
"currency": "USD"
}
}
}In un foglio di calcolo non voglio una singola cella metrics contenente un oggetto JSON. Voglio colonne che possa filtrare e ordinare:
employeesamountcurrency
Datablist rileva i percorsi degli oggetti annidati e ti permette di scegliere quali appiattire. Mantengo appiattiti i campi scalari utili, perché sono più facili da gestire negli strumenti CSV.
In questo esempio, appiattisco:
metrics.employeesinemployeesmetrics.revenue.amountinamountmetrics.revenue.currencyincurrency
Il CSV previsto a livello aziendale avrà questa struttura:
| Colonna CSV | Valore di origine |
|---|---|
id | Identificativo della riga |
name | Nome della società o dell'account |
website | Valore del sito web, array unito o stringa JSON in base alle impostazioni |
contacts | Dati annidati dei contatti quando si esporta una società per riga |
tags | Etichette unite o testo originale |
employees | Valore di metrics.employees |
amount | Valore di metrics.revenue.amount |
currency | Valore di metrics.revenue.currency |
createdAt | Data originale o formattata |
Per la prima esportazione preferisco nomi di colonna leggibili. Se il file contiene nomi ripetuti in oggetti diversi, controlla l'anteprima prima del download. Per esempio, billing.amount e revenue.amount non dovrebbero diventare entrambi una colonna ambigua chiamata amount senza una verifica.
💡 La mia regola per l'appiattimento
Appiattisci i campi scalari che vuoi filtrare, ordinare o importare come colonne. Mantieni gli oggetti strutturati o gli array in formato JSON quando l'appiattimento rischia di nasconderne il significato o di creare celle illeggibili.
Gestire gli array nelle righe JSON
Gli array richiedono una decisione specifica: le celle CSV contengono testo, mentre gli array JSON possono rappresentare informazioni molto diverse.
Un elenco di tag non equivale a una lista di contatti. Un elenco di email non è come un insieme di voci d'ordine. Per questo evito di applicare un'unica regola globale ad array con significati diversi.
Per il file di esempio userei queste impostazioni:
| Campo | Gestione consigliata | Motivo |
|---|---|---|
tags | Unire i valori | I tag sono etichette semplici e funzionano bene in una sola cella |
website | Unire i valori o mantenere il JSON | Uniscili per una maggiore leggibilità; mantieni il JSON se è importante conservare i diversi formati |
contacts | Mantenere come JSON nelle righe aziendali | Gli oggetti contatto contengono a loro volta campi annidati |
contacts | Usare $.results[].contacts come row node per le righe dei contatti | È la scelta migliore quando l'elenco dei contatti è il vero risultato desiderato |
Datablist offre opzioni per unire i valori degli array, mantenerli come stringhe JSON, prendere soltanto il primo elemento e applicare impostazioni diverse caso per caso.
La mia regola di base è semplice:
- Unire gli array semplici, come i tag.
- Mantenere gli array strutturati come stringhe JSON quando devo conservarne la struttura.
- Prendere il primo elemento solo quando ha un significato preciso, per esempio un'email principale.
- Cambiare il row node quando ogni elemento dell'array merita una riga separata.
Nell'esportazione aziendale mantengo contacts come valore strutturato, perché ogni contatto ha un nome, email e numeri di telefono. Appiattire tutto in una sola cella renderebbe il CSV disordinato, mentre conservare soltanto il primo contatto causerebbe una perdita di dati.
Per un'esportazione dei contatti sceglierei invece $.results[].contacts. Il CSV conterrebbe quindi colonne a livello di contatto come queste:
| Colonna CSV | Valore di origine |
|---|---|
name | Nome del contatto |
emails | Elenco di email unito o stringa JSON |
phones | Elenco di telefoni unito o stringa JSON |
Il compromesso riguarda il contesto. Un'esportazione aziendale mantiene intatta la riga della società. Un'esportazione dei contatti si concentra sulle persone, ma i campi della società principale non vengono copiati automaticamente in ogni riga, salvo che lo strumento non introduca questa funzione in seguito.
Configurare le impostazioni di output
Dopo aver impostato correttamente il row node, l'appiattimento e la gestione degli array, configura l'output CSV.
Di solito parto da queste impostazioni:
- Separatore: virgola per un CSV standard.
- Riga di intestazione: attiva.
- Formato della data: mantieni quello originale, a meno che il foglio di calcolo di destinazione non richieda un formato più leggibile.
Usa il punto e virgola se il tuo foglio di calcolo o le impostazioni locali prevedono file con questo separatore. È un aspetto particolarmente importante nelle configurazioni europee, dove la virgola viene spesso utilizzata come separatore decimale.
Per le date preferisco mantenere il formato di origine nella prima esportazione. I timestamp ISO sono facili da elaborare in seguito e conservano i dettagli sul fuso orario. Se il CSV è destinato a un collega non tecnico, formattare le date può però renderlo più leggibile.
Prima del download, controlla entrambe le anteprime:
- L'anteprima tabellare serve a verificare righe e colonne.
- L'anteprima del CSV grezzo serve a controllare separatori, virgolette e interruzioni di riga.
🔑 Controlla l'anteprima prima di esportare
È nell'anteprima che puoi individuare un row node errato, colonne mancanti, array disordinati e problemi con il separatore. Meglio dedicare 30 secondi a questo controllo che dover correggere in seguito un'importazione non riuscita nel CRM o nel foglio di calcolo.
Controllo sempre l'anteprima del CSV grezzo quando sono presenti array o testi su più righe. Bastano pochi secondi e permette di intercettare molti più problemi di importazione di quanto si possa immaginare.
Controllare e scaricare il CSV
Prima di scaricare il file, seguo questa checklist:
- Il numero di righe corrisponde al row node selezionato?
- Le righe rappresentano l'entità che volevo ottenere?
employees,amountecurrencysono suddivisi in colonne utili?- Gli array sono leggibili oppure sono conservati come JSON quando la struttura è importante?
- I valori null del fatturato sono vuoti o abbastanza chiari per il passaggio successivo?
- Le date sono adatte al foglio di calcolo o allo strumento di importazione?
- L'anteprima del CSV grezzo usa il separatore previsto?
A questo punto scarica il CSV. Quando carichi un file, il nome del documento scaricato può essere basato su quello originale, rendendo più semplice risalire alla provenienza del CSV.
Dopo l'esportazione, apri il file nell'editor CSV di Datablist, in Excel, Google Sheets o nello strumento che userai per il passaggio successivo. In Datablist puoi proseguire con pulizia, filtri, deduplicazione, enrichment o traduzione. Se crei più esportazioni, puoi confrontare due file CSV. Se il file è troppo grande per un altro strumento, puoi dividere il CSV in file più piccoli.
Risultato CSV previsto
Selezionando $.results, il risultato principale contiene una società o un account per riga.
| Colonna CSV | Percorso JSON nella riga | Valore previsto |
|---|---|---|
id | $.id | Identificativo della riga |
name | $.name | Nome della società o dell'account |
website | $.website | Stringa del sito web, array unito o stringa JSON |
contacts | $.contacts | Array dei contatti unito o in formato JSON quando si mantiene una società per riga |
tags | $.tags | Etichette unite o stringa originale |
employees | $.metrics.employees | Numero di dipendenti |
amount | $.metrics.revenue.amount | Importo del fatturato, se presente |
currency | $.metrics.revenue.currency | Valuta del fatturato, se presente |
createdAt | $.createdAt | Data originale o formattata |
Selezionando $.results[].contacts, il risultato cambia e contiene un contatto per riga.
| Colonna CSV | Percorso JSON nel contatto | Valore previsto |
|---|---|---|
name | $.name | Nome del contatto |
emails | $.emails | Elenco di email unito o stringa JSON |
phones | $.phones | Elenco di telefoni unito o stringa JSON |
Entrambe le esportazioni sono valide, ma rispondono a esigenze diverse.
Usa l'esportazione a livello aziendale per pulire gli account, analizzare i dati firmografici, arricchire i record delle società o preparare le importazioni nel CRM. Usa quella a livello di contatto quando sono le persone a costituire il dataset di destinazione.
Quando usare questo procedimento
Questo procedimento è utile ogni volta che il formato di origine è JSON, ma quello di lavoro è CSV.
Alcuni esempi:
- Risposte API con metadati, paginazione e un array
resultsannidato. - Risultati di scraping tramite API contenenti annunci, prodotti, contatti o eventi.
- Esportazioni CRM e RevOps in cui le società contengono contatti, tag, metriche e campi personalizzati.
- Esportazioni da marketplace o cataloghi di prodotti con varianti, prezzi, categorie e fornitori.
- Log di webhook in cui gli eventi sono annidati sotto un payload.
- Flussi di localizzazione in cui vuoi tradurre il CSV ottenuto.
Lo schema è sempre lo stesso: individua l'array che rappresenta le righe, appiattisci i campi oggetto necessari, decidi come trattare gli array e controlla l'anteprima prima dell'esportazione.
Risolvere i problemi nella conversione da JSON annidato a CSV
Se il JSON non è valido, controlla innanzitutto il file di origine. Virgole mancanti, log della console copiati nel file, testo aggiunto in coda, download parziali e virgolette senza escape possono impedire il parsing. Di solito valido il file prima di modificare le impostazioni di conversione, perché un JSON non valido deve essere corretto alla fonte.
Se non viene trovato alcun row node, il file potrebbe non contenere un array di oggetti. Un singolo oggetto composto soltanto da campi scalari non è sufficiente per questo procedimento. Radici primitive, stringhe, numeri e valori singoli non generano righe CSV utili.
Un numero di righe corretto non garantisce che ogni campo sia diventato una colonna. Datablist individua le colonne usando i primi 50 record del row node selezionato; l'anteprima tabellare mostra fino a 100 righe. Per esempio, se solo il record 51 contiene il campo optional_note, il CSV può includere tutte e 51 le righe ma omettere completamente quel campo.
Controlla nel file di origine i campi che compaiono solo nei record successivi e confrontali con le intestazioni del risultato. Nell'esempio precedente, sposta in una copia del JSON il record contenente optional_note tra i primi 50, mantenendone invariati ID e valori. Ripeti la conversione e verifica che l'intestazione compaia e che la nota del record 51 sia presente nel CSV scaricato. Il riordinamento modifica l'ordine delle righe: usa quindi gli ID per confrontare i risultati e conserva il JSON originale. Se lo schema è più variabile, assicurati che i primi 50 record includano tutti i campi necessari prima di esportare.
Se nell'anteprima compaiono le righe sbagliate, cambia il row node selezionato. In genere significa che il convertitore ha trovato un array, ma non quello che avevi in mente. Cerca il percorso che contiene i record, per esempio $.results, $.data.items o $.payload.records.
Se contatti, tag, voci d'ordine o eventi risultano difficili da leggere, modifica la gestione degli array. Unisci gli elenchi semplici. Mantieni gli array strutturati in formato JSON quando vuoi conservarne i dettagli. Passa a un row node figlio quando ogni elemento annidato deve diventare una riga.
Se un file di grandi dimensioni risulta lento, ricorda che le prestazioni del browser e del dispositivo contano comunque. Datablist esegue il parsing e la conversione in un web worker, quindi il processo non occupa il thread principale dell'interfaccia, ma la memoria e la CPU locali continuano a determinare i limiti pratici.
Se il CSV non viene importato correttamente in un altro strumento, prova un separatore diverso, mantieni attiva la riga di intestazione e controlla l'anteprima del CSV grezzo. Virgolette e interruzioni di riga possono essere rilevanti quando i valori JSON contengono testo, array o oggetti annidati.
Cosa avviene nel browser
Datablist analizza e converte il JSON in un worker del browser. Il worker esamina i possibili row node, salva in cache l'oggetto analizzato, converte il nodo selezionato in CSV e restituisce all'interfaccia l'anteprima e il risultato.
Questo è importante per due motivi.
Innanzitutto, la conversione non viene eseguita nel thread principale dell'interfaccia. La pagina rimane quindi utilizzabile mentre il file viene analizzato.
Inoltre, l'elaborazione avviene localmente nel browser: il file non viene inviato ai server di Datablist per la conversione. È utile quando gestisci esportazioni API, risultati di scraping o file di dati interni e non vuoi caricarli su un convertitore server-side.
Resta comunque opportuno rispettare le consuete regole di gestione dei dati. L'elaborazione locale nel browser è utile, ma non sostituisce le policy aziendali in materia di privacy e compliance.
Conclusione
La conversione di un JSON annidato in CSV dipende soprattutto dalla scelta del row node corretto. Una volta individuato l'array da trasformare in righe, tutto il resto diventa più semplice.
Nel file di esempio, $.results genera una società per riga. Appiattendo metrics.employees, metrics.revenue.amount e metrics.revenue.currency si ottengono colonne utili per un foglio di calcolo. Le impostazioni degli array determinano invece se campi come tags, website e contacts diventano testo leggibile, JSON strutturato o un'esportazione separata a livello di contatto.
Apri il convertitore da JSON a CSV, carica un'esportazione JSON annidata, seleziona il row node, controlla l'anteprima e scarica il CSV. Se poi devi pulire, filtrare, deduplicare, arricchire o tradurre i dati, apri il file esportato nell'editor CSV di Datablist.






