Perché questa pagina esiste
La conversione da JSON a CSV è un processo profondamente diverso da una semplice trasformazione tra formati. Mentre uno strumento per convertire CSV in Excel aggiunge struttura, questo strumento la rimuove. JSON è un formato gerarchico e tipizzato: supporta oggetti, array, numeri, booleani e null annidati in strutture arbitrarie. CSV è un formato piatto e privo di tipi: ogni cella è una stringa, non esiste nidificazione, non esistono fogli multipli, non esiste formattazione. La conversione – eseguita interamente nel browser, senza inviare alcun dato a un server – deve decidere come appiattire la gerarchia, come rappresentare array di oggetti e come gestire la perdita inevitabile delle informazioni di tipo.
Questa pagina esiste proprio per risolvere quel problema specifico: prendere un file JSON con struttura potenzialmente complessa e produrre un CSV che possa essere aperto in Excel, Google Sheets o importato in un database, tutto lato client, senza compromessi sulla privacy.
Il metodo di appiattimento: dot‑path notation
Il cuore della conversione è la scelta di come trasformare oggetti annidati in colonne piatte. Lo strumento adotta la dot‑path notation (notazione a percorsi separati da punto). Per esempio, dato il seguente JSON:
{
"nome": "Mario",
"indirizzo": {
"citta": "Roma",
"cap": "00100"
},
"telefoni": ["06-123456", "340-987654"]
}
Il CSV risultante avrà colonne come:
| nome | indirizzo.citta | indirizzo.cap | telefoni? Nota: array di valori primitivi |
|---|
(In realtà lo strumento gestisce gli array in modo specifico: array di oggetti diventano righe aggiuntive, mentre array di array o array di primitivi vengono tenuti come righe, con gli elementi trasformati in colonne. Il flattening di oggetti annidati produce colonne con nome oggetto.sottocampo.)
Questo approccio non è l'unico possibile, ma è il più comune e prevedibile. L'utente deve essere consapevole che la struttura gerarchica originale viene persa: i campi annidati vengono appiattiti in singole colonne, e non esiste modo di ricostruire l'oggetto originale dal CSV se non conoscendo la mappa di conversione. Se il JSON contiene array di oggetti (ad esempio "contatti": [{"nome":"Anna"}, {"nome":"Luca"}]), ogni oggetto nell'array produce una riga separata, con le altre colonne ripetute. Questo è il comportamento standard per "appiattire" array di oggetti in una tabella piatta.
Perdita del tipo e delle nidificazioni
Un CSV non ha tipi. I numeri diventano stringhe, i booleani diventano "true" o "false", i valori null diventano stringhe vuote o il testo "null" a seconda della codifica dello strumento. Lo zero iniziale (leading zero) viene perso – un codice postale 00100 diventerà 100 nella cella CSV a meno che non venga forzato l'uso del formato testo nel foglio elettronico di destinazione. Questo è un problema noto del CSV: non esiste un modo standard per preservare uno zero iniziale, perché il formato tratta tutto come numeri quando possibile.
Più grave è la perdita di struttura. Se il JSON include oggetti annidati a più livelli, il dot‑path li riduce a singole colonne. Un campo "dati": {"sensor": {"temperatura": 22.5}} diventa la colonna dati.sensor.temperatura. Non ci sono gerarchie di colonne, non ci sono fogli multipli, non ci sono tabelle correlate. Se il JSON originale conteneva più array indipendenti (ad esempio "clienti": [...] e "prodotti": [...]), non è possibile rappresentarli nello stesso CSV se non come due tabelle separate, ma lo strumento richiede che l'input sia table‑shaped – un singolo array di oggetti o un array di array. JSON multigrafo con più radici non è gestibile in un unico CSV.
Delimitatore: perché non solo virgola
L'utente può scegliere tra tre delimitatori: virgola (,), punto e virgola (;), tabulazione (\t). La scelta non è estetica: in molti paesi europei il separatore decimale è la virgola, quindi il separatore di campo nel CSV deve essere il punto e virgola per evitare conflitti (standard RFC 4180 adattato localmente). Lo strumento imposta un delimitatore predefinito (probabilmente virgola), ma l'utente può cambiarlo prima dell'esportazione.
Avvertenza pratica: se il CSV verrà aperto in Excel italiano, usa punto e virgola. Se verrà aperto in un sistema che si aspetta la virgola, usa virgola. Se il file contiene dati testuali con virgole, lo strumento le cita automaticamente (racchiude il valore tra virgolette doppie e raddoppia le virgolette interne). Ma se il delimitatore scelto è la virgola e i dati contengono virgole, il file sarà comunque valido secondo RFC 4180.
Regole concrete per un input “table‑shaped”
Lo strumento accetta solo JSON che sia table‑shaped. Questo significa che il file deve contenere:
- Un singolo array di oggetti (es.
[{"a":1}, {"a":2}]). Ogni oggetto diventa una riga, le chiavi diventano colonne (con dot‑path per oggetti annidati). - Un singolo array di array (es.
[["a","b"],]). Ogni array interno è una riga, gli elementi diventano colonne.
Se il JSON è un oggetto singolo, un array di primitivi, un oggetto con più campi non all'interno di un array, o un array di array con profondità variabile, lo strumento mostra l'errore: “This JSON is invalid or not table‑shaped.” (in italiano, probabilmente “Questo JSON non è valido o non ha una struttura tabellare.”). L'utente deve quindi preprocessare il file: se ha un oggetto singolo, lo deve avvolgere in un array; se ha più array, li deve combinare in un unico array di oggetti.
Esempio di errore frequente: un file con { "nome": "Mario", "eta": 30 } (senza array) sarà rifiutato, perché non è table‑shaped. Va trasformato in [{"nome": "Mario", "eta": 30}].
Limiti e messaggi di errore
Lo strumento impone limiti precisi, documentati dalla scheda informativa:
- Dimensione del file: se supera un valore massimo (
‹max›), compare “This file is too large. Use a file under ‹max›.”. - Numero di righe: se la tabella convertita ha più di
‹max›righe, errore “This table has more than ‹max› rows.”. - Numero di colonne: se la tabella ha più di
‹max›colonne, errore “This table has more than ‹max› columns.”. - Altri errori:
- “Choose one file first.” – se nessun file selezionato.
- “Choose a CSV, JSON or XLSX file.” – se il tipo di file non è accettato.
- “Choose a different output format.” – se l'utente prova a convertire in un formato non supportato.
- “Could not convert this file.” – errore generico.
- “Conversion cancelled.” – se l'utente interrompe.
- “This conversion is taking too long. Try a smaller file.” – timeout.
Tutti i limiti dipendono dalla configurazione locale della pagina; la scheda non fornisce i valori esatti, ma sono applicati dal codice client-side.
Chi ha bisogno di questo strumento
Caso tipico 1 – Un analista ha esportato dati da un'API REST in formato JSON e deve caricarli in un foglio di calcolo per reportistica. Il JSON contiene oggetti nidificati (es. utente.indirizzo.citta). Con questo strumento ottiene un CSV piatto con colonne utente.indirizzo.citta.
Caso tipico 2 – Un professionista che lavora con dati sensibili non può caricare file su server esterni. Lo strumento opera interamente nel browser: nessun dato lascia il computer.
Caso tipico 3 – Un utente in un paese dove il separatore decimale è la virgola deve generare un CSV con punto e virgola per Excel locale. Può selezionare il delimitatore prima della conversione.
Caso tipico 4 – Uno sviluppatore prototipa velocemente una pipeline di dati e ha bisogno di controllare la struttura di un JSON trasformandolo in CSV per ispezionarlo visivamente.
FAQ (domande frequenti)
1. Perché il mio JSON con un oggetto singolo non viene convertito?
Perché lo strumento richiede un array di oggetti (table‑shaped). Avvolgi l'oggetto in un array: {...} → [{...}].
2. Perché il codice postale "00100" viene convertito in "100"?
Il CSV non preserva i tipi; i numeri vengono scritti senza zeri iniziali. Per mantenerli, devi forzare il formato testo nel foglio di calcolo dopo l'apertura, oppure modificare il JSON originale trasformando il cap in stringa esplicita ("00100" rimane tale, ma se il JSON lo scrive come numero 00100 viene interpretato come 100). In pratica, se il dato proviene da un'API e arriva come numero intero, lo zero iniziale è già perso a monte.
3. Cosa succede se il mio JSON contiene una virgola all'interno di un valore?
Lo strumento cita automaticamente il valore tra virgolette doppie. Per esempio, "nome": "Rossi, Mario" diventerà "Rossi, Mario" nel CSV. Le virgolette doppie interne vengono raddoppiate (" → "").
4. Posso convertire un JSON con più di un array? No, lo strumento accetta un solo array di oggetti o un solo array di array. Se hai più array, devi unirli in un unico array di oggetti (aggiungendo una colonna per differenziarli) oppure convertire ogni array separatamente.
5. Il processamento è davvero lato client? Sì. Il file JSON viene letto dal browser e convertito interamente in memoria. Nessun dato viene trasmesso a server esterni. Puoi verificarlo disconnettendoti da Internet: la conversione funziona comunque.
6. Perché ottengo l'errore “This conversion is taking too long”? Probabilmente il file JSON è molto grande o ha una struttura molto complessa con molti livelli di nidificazione. Prova a ridurre il file prima di caricarlo, oppure azienda la conversione in più passaggi.