Convertire XLSX in JSON

Questa conversione esiste per uno schema che si ripete in ogni azienda: la versione autorevole di qualcosa — un listino prezzi, un catalogo prodotti, una tabella di traduzioni, un orario di apertura, una mappa fra codici e nomi — vive in un foglio di calcolo curato da qualcuno che non è uno sviluppatore, e deve arrivare a un programma che si aspetta dati.

È un accordo del tutto ragionevole. Un foglio di calcolo è una buona interfaccia di modifica, chi lavora in azienda lo conosce già, e costruire un piccolo strumento amministrativo per sostituirlo raramente vale lo sforzo. Ciò che serve è una conversione affidabile al confine, ed è tutto il compito di questa pagina.

La mappatura è quella ovvia. La prima riga viene trattata come intestazione e fornisce i nomi delle chiavi; ogni riga successiva diventa un oggetto; ogni cella diventa un valore su quell’oggetto. Il risultato è un array di record, la forma che quasi ogni programma consumatore si aspetta.

Vale la pena pensare deliberatamente alla riga di intestazione, perché quelle celle diventano nomi di chiave nel vostro codice. Brevi, minuscole, senza spazi e senza punteggiatura danno chiavi comode da usare; un’intestazione come «Prezzo unitario (€, IVA esclusa)» produce qualcosa che nessuno vuole digitare due volte.

Un foglio di calcolo non memorizza le date come date. Memorizza un numero che conta i giorni da un’origine, e la formattazione della cella è ciò che fa apparire 45678 come una data a schermo. La conversione restituisce ciò che è davvero nel file, cioè il numero.

Le due strade per aggirarlo sono entrambe deliberate. Formattare la colonna come testo nel foglio e scrivere date ISO al suo interno, il che rende il file autoesplicativo e sopravvive a ogni conversione. Oppure trasformare i valori dopo la conversione, applicando voi stessi l’aritmetica dei conteggi di giorni. Vanno bene entrambe; scoprire il problema dopo che i dati sono arrivati in produzione no.

Un CAP, un codice prodotto, un codice IBAN o un codice fiscale memorizzato in una cella formattata come numero ha già perso gli zeri iniziali — è successo in Excel quando il valore è stato digitato o importato, e il file contiene un numero.

Lo stesso vale per gli identificativi oltre i quindici numeri, che perdono le ultime cifre alla virgola mobile già dentro il foglio stesso. Nessun convertitore può ripristinare nessuno dei due, perché l’informazione non è nel file. La correzione va fatta a monte: quelle colonne devono essere formattate come testo nel foglio, e conviene dirlo a chi lo cura una volta sola invece di sistemare l’output ogni mese.

Le formule, di cui si ottiene il risultato — ciò che serve davvero, dato che un programma non saprebbe cosa farsene di una formula. La formattazione, i colori, le regole condizionali e la larghezza delle colonne, nessuno dei quali è dato. I grafici, i commenti e le celle unite, che non hanno equivalente.

Le celle unite sono quelle da tenere d’occhio. Un’intestazione unita su tre colonne è un espediente grafico, e produce un oggetto con una chiave valorizzata e due vuote — un record dall’aspetto strano che viene da un foglio dall’aspetto perfettamente sensato. Intestazioni piatte, una cella per colonna, sono ciò che rende questa conversione noiosa, e noioso è l’obiettivo.

L’assetto comune è tenere il foglio di calcolo come sorgente modificabile, convertire in JSON come passaggio e versionare il JSON insieme al codice. I dati diventano così revisionabili in una pull request, tracciati e disponibili in fase di build senza dipendenza a runtime da un file che qualcuno potrebbe spostare.

Due abitudini fanno funzionare la cosa nel tempo. Convertire sempre allo stesso modo, così un diff mostra cambiamenti reali invece di un riordino. E validare il risultato rispetto a uno schema prima di versionarlo, così una colonna rinominata da un collega ben intenzionato fallisce un controllo invece di produrre in silenzio oggetti con un campo mancante.

Se la destinazione è un import in un database, uno strumento di analisi o una pipeline dati, il CSV è di solito l’intermedio migliore: scorre in streaming, ogni sistema lo legge e non impone una struttura ad albero a dati che non ne hanno.

Il JSON si guadagna il posto quando i dati vanno in codice applicativo — un frontend, un file di configurazione, una fixture per un’API — dove un array di oggetti è ciò che il linguaggio vuole e il parsing è una riga. Scegliete in base a chi legge il file, non a quale formato sembra più moderno.

La conversione gira nella scheda del browser sul vostro stesso processore, quindi nulla viene caricato e nessun server ne tiene una copia. Non c’è account, non c’è coda e non c’è soglia giornaliera; il limite di dimensione è 100 MB per file, cento file per lotto.

Non è un dettaglio secondario qui. I fogli di calcolo che si convertono sono interni: prezzi, margini, elenchi clienti, dati del personale, cataloghi non ancora pubblicati. Non spedirli da nessuna parte è la forma più semplice di non doversi fidare di nessuno con quei dati.