Convertire JSON in TOML

JSON non ha commenti. È scritto nella specifica invece di essere una svista, ed è l’unica ragione per cui la maggior parte della configurazione scritta in JSON è sgradevole da mantenere: la ragione per cui un timeout è 45 secondi non può vivere accanto al 45. TOML, che ha impiegato otto anni di release 0.x per raggiungere la 1.0 nel gennaio 2021 ed è ora il formato di configurazione per Cargo, pyproject.toml e Hugo, ha i commenti, e di solito è questa l’intera motivazione di questa conversione.

La seconda ragione è la piattezza. Una configurazione JSON a tre livelli è tre livelli di graffe e molta indentazione; la stessa cosa in TOML è una riga di intestazione che legge [server.tls.client] e un breve elenco di chiavi sotto. Niente dei dati è cambiato, ma la diff che un revisore vede quando un valore si sposta è una riga invece di un blocco ri-indentato, ed è la differenza tra una pull request facile e una dolorosa.

Un documento TOML è una tabella. Non può cominciare con un array come può fare un documento JSON, quindi un file il cui carattere più esterno è una parentesi quadra non ha nulla su cui mappare. La conversione gestisce questo invece di fallire: un valore che non è un oggetto è racchiuso sotto una chiave chiamata items, e l’output inizia con [[items]].

Questo mantiene il file valido, ed è un segnaposto invece di una risposta. Nessun convertitore può sapere se lo strumento che legge il file si aspetta che quell’elenco si chiami dependencies, servers o plugins. Rinominare la chiave nella prima riga e il resto del file è già corretto, è un edit di una parola, ed è deliberatamente ovvio invece che nascosto, ed è il tipo di cortesia che fa risparmiare debug dopo.

Questo è il guasto da controllare ogni volta. TOML non ha un letterale null, e chi scrive non ne inventa uno: una chiave il cui valore JSON era null non è scritta e basta. Convertire {"a": null} e l’output è un file vuoto. Convertire una tabella con una chiave vera e una chiave null e solo la chiave vera compare.

Se questo conta dipende interamente dallo strumento che legge il risultato. Molti parser di configurazione trattano una chiave assente e una chiave null allo stesso modo, entrambi ricadono su un default, e per quelli nulla è andato perso. Altri li distinguono, e lì la conversione ha silenziosamente cambiato la configurazione. La difesa è cercare null nel JSON prima di convertire invece di confrontare i due file dopo, perché una riga assente è molto più difficile da notare di una modificata, ed è il tipo di errore che si propaga per mesi prima di essere trovato.

Questa è la parte che di solito sorprende chi si aspetta che TOML sia un formato più debole di JSON. Un elenco di record è espresso come la stessa intestazione di tabella ripetuta: [[servers]] tre volte dà tre server, ognuno con le proprie chiavi sotto. È più verboso di un array JSON e considerevolmente più facile da editare, perché aggiungere un quarto server significa copiare cinque righe invece di bilanciare parentesi.

I membri non devono combaciare. Un array in cui il primo oggetto ha un id e un nome e il secondo aggiunge una regione converte senza reclami, e il TOML resta valido, ogni blocco porta le chiavi che ha. È un vantaggio reale rispetto alle destinazioni tabulari di questo sito, dove un array eterogeneo deve essere riconciliato in un unico insieme di colonne prima che qualcosa possa essere scritto, ed è la differenza che si vede quando si ha a che fare con configurazioni che crescono nel tempo.

Un’intestazione di tabella TOML possiede tutto ciò che sta sotto di essa fino all’intestazione successiva. Ciò significa che una chiave semplice messa dopo [server] appartiene a server, qualunque cosa l’autore intendesse. Quindi chi scrive innalza ogni scalare al livello superiore sopra la prima intestazione di tabella: {"server": {"host": "localhost"}, "debug": true} esce come debug = true, una riga vuota, poi [server] e host.

L’output quindi non è nell’ordine in cui era il JSON, e non può esserlo. Questo è l’unico riordino che preserva il significato, e qualsiasi altro cambierebbe la tabella a cui appartiene una chiave. Se il raggruppamento originale contava per la leggibilità, ripristinarlo spostando interi blocchi di tabella in giro, che è sicuro, invece di spostare chiavi singole sopra o sotto un’intestazione, ed è una regola che vale la pena tenere a mente per le revisioni.

Quattro livelli di annidamento JSON diventano una singola riga di intestazione: {"a":{"b":{"c":{"d":1}}}} converte in [a.b.c] con d = 1 sotto. TOML esprime la profondità nell’intestazione invece che nell’indentazione, che è il motivo per cui una configurazione profondamente strutturata è spesso più corta e piatta in TOML che nel JSON da cui proviene.

Ha anche un limite che è questione di gusto invece che di validità. Un’intestazione come [build.targets.linux.arm64.flags] è legale e nessuno gode a leggerla. Se il file convertito ha intestazioni oltre i tre o quattro segmenti, di solito è un segnale che la configurazione vuole essere divisa in file separati o strumenti separati, e la conversione ha appena reso visibile un problema esistente, che è la cosa migliore che uno strumento possa fare.

L’output non ha commenti, perché l’input non aveva dove tenerne. JSON non li porta, quindi non c’è nulla da tradurre, non è una mancanza del convertitore ma il motivo per cui il JSON valeva la pena di essere lasciato dov’era in primo luogo.

Il che rende i primi cinque minuti dopo la conversione la parte più preziosa dell’esercizio. Il file TOML è la versione di questa configurazione che può contenere la conoscenza istituzionale su di essa: quali valori è sicuro cambiare, quale deve corrispondere a un valore in un altro repository, perché un limite è impostato dove è impostato. Quella conoscenza esiste nella testa di qualcuno o in un messaggio di commit oggi, e questo è il momento in cui scriverla nel file non costa nulla, ed è il tipo di finestra che si chiude presto se non la si coglie.

TOML ha quattro tipi di data e ora, incluso un offset date-time che è un valore di prima classe invece di una stringa. JSON non ne ha: RFC 8259 dà stringhe, numeri, booleani, null, array e oggetti, e ogni timestamp in ogni file JSON sulla terra è uno dei primi due per convenzione.

Quindi un valore JSON di «2024-01-01T00:00:00Z» è scritto come una stringa TOML quotata, il che è corretto e non è ciò che il formato potrebbe esprimere. Se lo strumento che legge il file vuole un date-time reale, togliere le virgolette a mano su quelle righe. Viene analizzato come una data dopo, e nient’altro nel file deve cambiare, ed è il tipo di pulizia che vale la pena fare prima del commit.

Il controllo più economico è un viaggio di ritorno: convertire il TOML di nuovo in JSON e confrontarlo con quello da cui si è partiti. Le chiavi che contenevano null mancheranno e nient’altro dovrebbe differire, il che trasforma una preoccupazione vaga in una diff che si può leggere in pochi secondi.

Il secondo controllo è lo strumento stesso. Cargo, Hugo e la maggior parte degli strumenti di packaging Python diranno immediatamente se il documento viene analizzato e se le chiavi sono dove se le aspettano, e questo cattura la cosa che un viaggio di ritorno non può: un file convertito correttamente la cui chiave al livello superiore si chiama ancora items perché nessuno l’ha rinominata, ed è un dettaglio che si vede solo aprendo il file nello strumento reale.

In questa scheda del browser, sul proprio processore. Entrambe le metà sono JavaScript, il parser JSON è quello integrato nel browser, e lo scrittore TOML è una piccola libreria caricata su richiesta, quindi nessuna richiesta porta il file da qualche parte, e non c’è account, coda o tetto giornaliero. Il piano gratuito accetta file fino a 100 MB, che per la configurazione non è un limite che qualcuno raggiunge.

Questo conta di più per la configurazione che per la maggior parte dei dati. Un file di configurazione JSON è esattamente il tipo di cosa che contiene hostname interni, nomi di bucket, account di servizio e occasionalmente una credenziale che qualcuno intendeva rimuovere, e caricarlo su un convertitore web sarebbe la parte che sarebbe effettivamente contro policy. Qui non c’è nulla da caricare, ed è il tipo di distinzione che la conformità riconosce prima che il caricamento avvenga.