Convertire TOML in JSON

Il TOML è lo standard per il packaging Python e Rust da anni, e gli strumenti attorno a un repository spesso non si sono aggiornati. Un passo CI con jq disponibile e nient’altro, uno script Node che deve leggere la versione da un Cargo.toml, una dashboard che conta le dipendenze su duecento repository — tutti possono leggere JSON e nessuno può leggere TOML senza una nuova dipendenza.

È il caso a cui serve questa conversione, e funziona in modo pulito perché i due modelli di dati si sovrappongono quasi interamente. Il TOML è una tabella di coppie chiave-valore con annidamento e array, cioè un oggetto JSON con annidamento e array. Le parti interessanti sono i quattro punti dove il TOML sa qualcosa che il JSON non sa.

Un’intestazione tra parentesi diventa un oggetto annidato, e un’intestazione puntata diventa annidamento su più livelli — un’intestazione scritta per uno strumento e poi un linter sotto produce un oggetto dentro un oggetto, così il percorso JSON corrisponde esattamente all’intestazione. Niente della struttura richiede interpretazione.

Un’intestazione a doppia parentesi è l’array di tabelle, e diventa un array JSON di oggetti con una voce per occorrenza. È ciò che contiene gli autori di un pacchetto Python, i binari di un crate Rust e i target di una build, ed è il costrutto per cui le persone si preoccupano di più e devono preoccuparsi di meno. L’ordine viene preservato.

Il TOML è l’unico formato in questa famiglia con veri tipi temporali: date-ora con offset, date-ora locali, date locali e ore locali sono nella specifica, e un parser le restituisce come date. Il JSON non ha alcun tipo data, quindi ognuna diventa una stringa.

I valori sopravvivono con una piega. Una data-ora con offset mantiene il proprio offset piuttosto che essere normalizzata a UTC, un comportamento migliore di diverse altre conversioni su questo sito. Un’ora locale acquisisce una componente in millisecondi che non aveva — un’ora scritta come otto del mattino arriva con una parte frazionaria attaccata.

Il TOML 1.0 richiede a un’implementazione di gestire interi con segno a 64 bit. I numeri JSON sono double IEEE ed sono esatti solo fino a circa nove quadrilioni. Un file TOML che contiene un intero oltre quell’intervallo è del tutto legale, e il parser qui si ferma con un errore che dice che l’intero non può essere rappresentato senza perdita.

Rifiutare è la scelta giusta e vale la pena capirla piuttosto che aggirarla alla cieca. Un identificativo arrotondato silenziosamente è un bug che emerge settimane dopo in un join che non corrisponde a nulla. Se il vostro TOML contiene un valore di quella dimensione, mettetelo tra virgolette come stringa nella sorgente.

I float TOML includono inf e nan come valori letterali. Il JSON non ha nessuno dei due, e il serializzatore scrive null per entrambi. È il comportamento JavaScript standard ed è con perdita in un modo che niente segnala — un limite superiore configurato a infinito e un limite superiore non impostato diventano la stessa cosa nel JSON.

La perdita più sottile è la tipizzazione. Il TOML distingue un intero da un float, quindi 1 e 1.0 sono valori diversi con tipi diversi, e uno schema o un’applicazione può contarci. Il JSON ha un solo tipo numero, e 1.0 viene serializzato come 1.

Tabelle e chiavi escono nell’ordine dichiarato dal TOML, il che mantiene un file convertito leggibile e mantiene significativo un diff fra due conversioni. L’uscita è indentata di due spazi e termina con un ritorno a capo.

L’eccezione sono le chiavi numeriche. Una chiave TOML tra virgolette che è un numero — che appare in configurazioni che indicizzano per anno o porta — viene riordinata davanti a ogni altra chiave nel suo oggetto e ordinata in modo crescente, perché è così che JavaScript ordina le chiavi simili a interi.

L’uscita è JSON ordinario, quindi jq lo legge senza flag: estrarre una versione di progetto, elencare nomi di dipendenze o controllare se esiste una sezione strumento sono tutte espressioni di una riga. Di solito è l’intera ragione del viaggio, e trasforma uno script shell che stava per fare grep su un file TOML in uno che lo interroga correttamente.

Apre anche la validazione. JSON Schema è maturo e ampiamente implementato, e il TOML non ha un linguaggio di schema nella sua specifica, quindi convertire e poi validare è un modo genuino per far rispettare regole aziendali su molti repository — ogni pacchetto deve dichiarare una licenza, ogni crate deve fissare la sua edizione.

Il TOML supporta i commenti e li usa pesantemente: la ragione per cui una dipendenza è fissata, il numero di ticket accanto a una soluzione temporanea, il blocco che spiega a quale ambiente si applica un’impostazione. Il JSON non ha sintassi per commenti sotto RFC 8259, quindi niente di tutto ciò arriva.

Questo stabilisce la direzione della relazione. Il TOML è il file che le persone modificano e revisionano, e il JSON viene generato da esso ogni volta che qualcosa deve leggerlo. Depositare il JSON nel repository accanto al TOML crea due versioni della verità che divergeranno; generarlo nel passo di build no.

Se la lettura avviene dentro un’applicazione piuttosto che in un passo di build, usate un parser. Ogni linguaggio principale ne ha uno — Python ha tomllib nella libreria standard da diverse versioni, e Rust, Go e JavaScript hanno tutti opzioni ben mantenute. Leggere il file direttamente mantiene i tipi temporali e la distinzione intero-float che questa conversione appiattisce.

Il convertitore si guadagna il posto al confine: un’ispezione occasionale, un passo CI dove aggiungere una dipendenza è più fastidio di quanto valga, o una pipeline il cui stadio successivo parla solo JSON. Tutto gira nel vostro browser, quindi una configurazione privata con credenziali è sicura da trascinare qui.