Convertire CSV in JSON

Questa conversione serve a chi deve dare in pasto dei dati a qualcosa che parla JSON: un endpoint da provare, uno script Node, un file di seed, un import in MongoDB, un mock per il frontend mentre l’API vera non esiste ancora. Il CSV è arrivato da un foglio di calcolo o da un’esportazione gestionale, e la destinazione vuole oggetti.

È una richiesta diversa da quella di chi converte un CSV in XLSX. Lì il problema è che Excel indovina i tipi male; qui il problema è che JSON i tipi li pretende, e qualcuno deve deciderli. Il resto di questa pagina è essenzialmente su chi prende quella decisione e su quali basi.

Il file che ottenete è un array di oggetti: una riga del CSV diventa un oggetto, e le intestazioni della prima riga diventano le chiavi. È la forma che quasi ogni consumatore si aspetta — `JSON.parse` seguito da un `map`, oppure un `POST` diretto verso qualcosa che accetta una collezione.

Non è l’unica forma possibile. Esiste anche l’array di array, che conserva l’ordine delle colonne e pesa meno, ed esiste il JSON Lines, un oggetto per riga senza parentesi attorno, che è ciò che vogliono gli strumenti che leggono in streaming. Chi ha bisogno di quelle forme di solito lo sa già e ha uno script; chi arriva da un foglio di calcolo vuole l’array di oggetti, ed è quello che viene prodotto.

Un CSV non ha tipi. Ogni cella è testo, sempre, anche quando contiene 42. JSON invece distingue: `42` e `"42"` sono due cose diverse, e un consumatore che si aspetta un numero e riceve una stringa fallisce alla riga dopo. Quindi la conversione deve decidere, per ogni singolo valore, se toglierlo dalle virgolette o no.

La regola applicata qui è cauta: diventa numero soltanto ciò che è inequivocabilmente un numero e che sopravvive al giro di andata e ritorno senza cambiare. `42` diventa `42`. `3.14` diventa `3.14`. `007` resta `"007"`, perché trasformarlo in `7` distruggerebbe informazione che qualcuno ha messo lì apposta. Un codice fiscale, un CAP e un numero di conto restano stringhe per la stessa ragione, ed è esattamente il contrario di quello che farebbe un foglio di calcolo con gli stessi dati.

Una cella vuota in un CSV è ambigua in modo irriducibile. Può significare «questo valore non esiste», può significare «stringa vuota», e nel file non c’è nulla che distingua i due casi: entrambi si scrivono come niente fra due separatori.

Qui una cella vuota diventa `null`, non una stringa vuota: una riga `1,,3` sotto le intestazioni `a,b,c` esce come `{"a":1,"b":null,"c":3}`. È la conseguenza voluta della stessa rilevazione dei tipi che trasforma `1` in un numero anziché in `"1"`, e conviene saperlo prima, perché il passaggio non è reversibile: dal `null` non si torna indietro a distinguere quali colonne intendevano davvero una stringa vuota. Se la vostra destinazione vuole `""` — uno schema JSON che pretende una stringa rifiuta `null`, e una colonna dichiarata NOT NULL rifiuta la riga — la trasformazione è un `map` di una riga, e vale la pena scriverla voi, che sapete che cosa significano le vostre colonne.

Un CSV esportato da un sistema configurato in italiano usa quasi sempre il punto e virgola, non la virgola. Il motivo è la virgola decimale: `1,5` è un numero e mezzo, e non può contemporaneamente separare due campi. Lo stesso vale per il tedesco, il francese e lo spagnolo, il che significa che una buona parte dei CSV in circolazione non contiene una sola virgola di separazione.

Il delimitatore viene rilevato dal file. Se il rilevamento sbaglia — succede con file a una sola colonna, dove non c’è nulla da rilevare — potete impostarlo a mano fra le opzioni sotto il risultato e riconvertire. Il segnale che è andata storta è immediato: ottenete oggetti con una sola chiave, il cui nome è tutta la riga di intestazione.

Il delimitatore è metà della questione italiana; l’altra metà è che dentro le celle i numeri sono scritti `1.234,56`. JSON non ammette quella forma: un numero JSON usa il punto come separatore decimale e non ammette separatori di migliaia, punto.

Un valore così resta quindi una stringa, perché convertirlo richiederebbe di indovinare la convenzione e indovinare male su un prezzo è peggio che lasciarlo com’è. Se vi servono numeri veri, la strada pulita è riesportare il CSV con il punto decimale — quasi ogni gestionale ha l’opzione — invece di riparare a valle. Sistemare `1.234,56` con una sostituzione di stringhe funziona finché non incontrate un file dove il punto era davvero il decimale, e a quel punto avete moltiplicato per mille senza accorgervene.

La prima riga del CSV fornisce i nomi delle proprietà, così come sono scritti. Niente viene messo in camelCase, ripulito o abbreviato: una colonna chiamata `Data ordine` diventa una chiave `"Data ordine"`, con lo spazio e la maiuscola.

È deliberato, perché rinominare significherebbe inventare una convenzione e imporla a un file che finirà in un codice che non conosciamo. Vale però la pena guardare le intestazioni prima di convertire: una chiave con uno spazio dentro si legge in JavaScript solo con la notazione a parentesi quadre, e se il CSV lo controllate voi, cambiare l’intestazione nel foglio è più pulito che convivere con `riga["Data ordine"]` per sempre.

Un campo CSV può contenere il delimitatore, le virgolette e perfino un ritorno a capo, purché sia racchiuso fra virgolette doppie e le virgolette interne siano raddoppiate. Un indirizzo su due righe dentro una cella è legale e frequente nelle esportazioni di anagrafiche.

Il parser usato qui segue quella regola, quindi un campo multiriga sopravvive e diventa una stringa JSON con dentro un `\n`. Il caso che invece non si salva è il file scritto da qualcuno che ha concatenato dei valori a mano dimenticando di raddoppiare le virgolette: lì il conteggio dei campi salta a metà file, e nessun parser può indovinare dove volevate che finisse una cella. Se il risultato ha righe con un numero di chiavi diverso dalle altre, è quasi sempre questo.

I CSV che finiscono convertiti in JSON sono quasi sempre dati reali: clienti, ordini, utenti, indirizzi, a volte un’esportazione completa da un gestionale. È la categoria di file che non si carica su un servizio trovato in una pagina di risultati, e la maggior parte dei convertitori online fa esattamente questo.

Qui la conversione avviene nella vostra scheda del browser. Il parser è JavaScript che la pagina ha già scaricato, il file viene letto dal vostro disco in locale e il JSON viene scritto in memoria. Non parte nessuna richiesta con dentro i vostri dati, e questa è una cosa che si verifica invece di crederla: aprite gli strumenti di sviluppo, guardate la scheda di rete e convertite qualcosa.

JSON è un formato di testo e non è compatto. Un CSV di cinquanta megabyte diventa facilmente il doppio o il triplo, perché ogni riga ripete tutti i nomi delle colonne. Su qualche milione di righe questo smette di essere un dettaglio: il file diventa scomodo da spostare e, se qualcuno prova a caricarlo tutto con `JSON.parse`, da leggere.

Se i vostri dati hanno quelle dimensioni, il JSON Lines o il Parquet sono la risposta giusta e questa pagina non lo è. Vale la pena dirlo prima che dopo: un convertitore che accetta qualsiasi cosa senza commentare vi lascia scoprire il problema quando il file è già nella pipeline di qualcun altro.