Convertire JSON in TSV

La virgola è il carattere più comune in prosa dopo lo spazio, e un file delimitato che la usa come separatore deve fare l’escape di ogni valore che ne contiene una. Il meccanismo funziona, ed è anche la fonte di quasi ogni importazione storpiata che si è vista: una virgoletta sbilanciata e il resto della riga atterra nelle colonne sbagliate.

Le tabulazioni compaiono nei dati reali quasi mai. Nessuno digita una tabulazione in un campo indirizzo, in una descrizione di prodotto o in una casella di commento, perché nella maggior parte delle interfacce il tasto sposta il focus invece. Questa è l’intera argomentazione, e per un lavoro singolo è forte: il separatore che non appare nei dati non ha bisogno di escaping.

Excel e Google Sheets leggono testo separato da tabulazioni dalla clipboard in modo nativo. Copiare l’output convertito, cliccare una cella, incollare, e i dati atterrano nelle colonne senza dialogo, senza domanda sul delimitatore e senza procedura guidata di importazione. Un CSV incollato allo stesso modo arriva come una colonna di testo per riga, che è il motivo per cui la gente finisce su questa pagina.

Questo lo rende la via più rapida da un’esportazione JSON a qualcosa che si può ordinare e filtrare, e vale la pena essere onesti su quando è la via sbagliata. Se il file sarà conservato, spedito a qualcuno o importato ripetutamente, salvare un CSV o una cartella di lavoro invece, perché la clipboard è una comodità, non un meccanismo di consegna, e i dati incollati non portano alcun registro di dove siano venuti.

Ogni record nell’array diventa una riga, e le colonne vengono dalle chiavi. I record non devono essere d’accordo: la conversione raccoglie l’unione di ogni chiave attraverso l’intero file e lascia una cella vuota dove un record non ha nulla, quindi un’esportazione in cui alcune voci portano un campo facoltativo converte senza che nessuna venga scartata.

Questa riconciliazione spiega una sorpresa comune. Convertire i primi dieci record per un test può produrre meno colonne che convertendo l’intera esportazione, perché il campione non conteneva i campi più rari. Se manca una colonna che ci si aspettava, la ragione è quasi sempre che nessun record nel file ce l’aveva, il che è di per sé un’informazione, ed è un dettaglio che fa risparmiare un’ora di «ma dov’è finita».

Le risposte API raramente restituiscono un array nudo. Restituiscono un oggetto con una chiave, results, data, items, il cui valore è l’array che si vuole. La conversione riconosce quella forma: un oggetto con esattamente una chiave che contiene un array è spacchettato, e i record dentro diventano le righe.

Un oggetto con due chiavi non è spacchettato, perché non c’è modo di sapere quale di esse sia il dato e quale il cursore di paginazione. In quel caso l’intero oggetto diventa una singola riga con nomi di colonna con punti, il che sembra sbagliato ed è il segnale per cancellare la busta in un editor di testo e convertire di nuovo, ed è una distinzione che si vede al primo tentativo.

JSON è un albero e una tabella è una griglia, quindi l’annidamento deve andare da qualche parte. Va nei nomi delle colonne: un record con un oggetto cliente che contiene una città produce una colonna intestata cliente.città. Un livello di annidamento produce una tabella che chiunque può leggere, e due è di solito ancora accettabile.

Oltre degrada rapidamente. I nomi delle colonne crescono lunghi, la tabella diventa molto larga, e la maggior parte delle celle sono vuote perché record diversi annidano in modo diverso. Sessanta colonne da quello che sembrava un’esportazione semplice è la forma dei dati che traspare invece di un difetto, ed è un momento ragionevole per decidere che il JSON dovrebbe restare JSON, ed è una decisione che si fa meglio prima di incollare ventimila righe.

Un record con tre tag diventa tre colonne chiamate tag.0, tag.1 e tag.2. È onesto, preserva ogni valore, ed è una tabella scadente: il record successivo con cinque tag aggiunge altre due colonne, e ordinare per «il secondo tag» è privo di significato.

Dove l’array porta il significato, un ordine con le voci, un post con i commenti, la risposta utile sono due tabelle collegate da un identificativo, come le terrebbe un database. Dove è incidentale, unire i valori in una stringa nel JSON prima di convertire produce un foglio di calcolo molto più usabile di una corsa di colonne numerate, ed è una pulizia che paga al primo tentativo di PivotTable.

L’affermazione che le tabulazioni non compaiono mai nei dati è vera quasi sempre e non del tutto sempre. Testo copiato da un PDF, un frammento di codice in un campo di commento e qualunque cosa incollata da un altro foglio di calcolo possono portarne uno. Un a-capo dentro un valore è ancora più comune.

Quando succede, il valore è racchiuso tra virgolette doppie, che è l’escape standard ed è letto correttamente da ogni strumento che importa un file. La clipboard è dove è meno affidabile, perché la gestione dell’incolla varia fra applicazioni e versioni. Se si sa che i dati contengono testo libero con a-capo dentro, scaricare il file e usare il percorso di importazione invece di incollare, ed è una distinzione che fa risparmiare una sessione di debug su Excel.

I numeri sono scritti come numeri, i booleani come true e false in minuscolo, e un null come cella vuota. Nulla è quotato che non abbia bisogno di esserlo, quindi il file si legge esattamente come appare.

Ciò che succede dopo è fuori dalle mani del file. Excel e Sheets inferiscono entrambi un tipo per colonna in fase di incolla, il che toglie gli zero iniziale dai CAP e dai codici prodotto e trasforma qualunque cosa assomigli a una data in una data. La difesa è la stessa di sempre: formattare le colonne di destinazione come testo prima di incollare, o usare un percorso di importazione in cui i tipi di colonna possono essere impostati. Non è qualcosa che la conversione possa prevenire, perché l’informazione è già corretta quando arriva, ed è un dettaglio che si vede solo quando un CAP diventa un numero.

La clipboard è un destinatario per il TSV; l’altro è software che si aspetta tabulazioni per impostazione predefinita. Il comando COPY di Postgres usa la tabulazione come delimitatore predefinito, R read.delim si aspetta tabulazioni, e una lunga coda di strumenti di bioinformatica e di elaborazione di log accettano input separato da tabulazioni e nient’altro.

Per quelli l’output è pronto così com’è, con un caveat che vale la pena controllare: le righe finiscono con un semplice a-capo invece di un ritorno carrello e a-capo, che è ciò che gli strumenti Unix si aspettano e che ad alcuni importatori solo-Windows non piace. Se un caricatore si lamenta del terminatore di riga, convertirlo è un passaggio attraverso un editor di testo, ed è il tipo di dettaglio che emerge solo la prima volta.

L’analisi e la scrittura sono entrambe JavaScript in questa scheda. Niente viene caricato, non c’è registrazione né tetto giornaliero, e il piano gratuito accetta fino a 100 MB, con il tetto pratico che è la memoria propria, perché l’intero array deve essere letto prima che qualcosa possa essere scritto.

Questo vale più di quanto sembri per questa coppia. Un’esportazione JSON è quasi sempre output grezzo di un’API, record di clienti, storie di ordini, submission di moduli, e di solito contiene campi a cui nessuno ha pensato perché nessuno si aspettava di doverli leggere. Portarlo in un foglio di calcolo senza che passi attraverso il server di qualcuno è la versione semplice del non doverci pensare affatto, ed è una distinzione che diventa ovvia quando il file è il registro di un cliente.