Convertitore da TOML a JSON

Il TOML nasce per essere leggibile dalle persone: i file di configurazione come Cargo.toml o pyproject.toml usano una sintassi pulita, basata su sezioni e coppie chiave-valore. Il JSON, invece, è il formato che quasi ogni linguaggio e API legge in modo nativo. Convertire da TOML a JSON serve proprio quando devi elaborare quei dati in modo programmatico oppure passarli a uno strumento che parla solo JSON.

Le differenze strutturali principali riguardano il modo in cui i due formati rappresentano gli stessi concetti. Una tabella TOML, scritta tra parentesi quadre, diventa un oggetto annidato in JSON. Un array di tabelle si traduce in un array di oggetti. Le tabelle inline corrispondono a oggetti compatti, mentre i valori datetime, che il TOML supporta in modo nativo, vengono resi come stringhe nel JSON.

Il risultato è una rappresentazione equivalente sul piano dei dati, ma più adatta al consumo automatico. Per il percorso opposto puoi usare il convertitore da JSON a TOML.

Il convertitore lavora in tre fasi. Prima analizza il testo TOML in ingresso, riconoscendo sezioni, chiavi, tipi di dato e commenti. Poi costruisce una struttura intermedia che rispetta la gerarchia delle tabelle. Infine serializza tutto in JSON, con un'indentazione leggibile.

Vediamo una mappatura tipica:

Gli interi e i numeri con virgola mobile restano numeri, i booleani restano true o false, mentre le date vengono convertite in stringhe perché il JSON non ha un tipo datetime dedicato.

Alcuni casi limite meritano attenzione. Le stringhe multilinea conservano gli a capo, le chiavi con punti generano oggetti annidati e i commenti, che il JSON non prevede, vengono rimossi dall'output. Se il TOML contiene errori di sintassi, lo strumento segnala la riga problematica invece di restituire un risultato parziale.

La conversione da TOML a JSON torna utile in molti flussi di lavoro reali. Ecco gli scenari più comuni:

1. Pipeline di integrazione continua: leggere un pyproject.toml o un Cargo.toml e passare i valori a script che si aspettano JSON.
2. Migrazione di configurazioni: spostare un progetto da TOML a un sistema che accetta solo JSON senza riscrivere tutto a mano.
3. Debug di file TOML: visualizzare la struttura JSON aiuta a capire come viene interpretata davvero la gerarchia delle tabelle.
4. Scambio di dati tra sistemi: produrre un payload JSON a partire da una configurazione leggibile dall'utente.

In pratica, mantieni il TOML come fonte comoda da scrivere e usi il JSON come formato di trasporto. Una volta ottenuto il JSON, puoi ripulirlo con il formattatore JSON o continuare a lavorare con altri formati. Se parti invece da YAML, esiste anche il convertitore da YAML a JSON per uniformare tutto allo stesso output.

TOML e JSON condividono lo stesso modello di dati di base, fatto di oggetti, array, stringhe, numeri e booleani. Le differenze emergono nell'uso quotidiano.

Il TOML privilegia la scrittura umana: i commenti con #, le sezioni esplicite e le date native lo rendono comodo per la configurazione. Il JSON privilegia invece l'elaborazione automatica: niente commenti, sintassi rigida e supporto universale nelle librerie.

Un altro punto riguarda i numeri. Il TOML distingue interi, decimali, valori esadecimali e ottali, ma in JSON tutto confluisce in un unico tipo numerico. Le date TOML, prive di equivalente in JSON, diventano stringhe in formato ISO.

Proprio per questo la conversione non è sempre simmetrica. Passando da TOML a JSON perdi i commenti e l'informazione sul tipo esatto di numero. Tornando indietro non recuperi quei dettagli in automatico. Conviene quindi trattare il TOML come sorgente principale e generare il JSON ogni volta che serve, anziché modificarlo in entrambe le direzioni.

Qualche accortezza riduce gli intoppi più frequenti durante la conversione.

• Controlla le virgolette: in TOML le stringhe vanno racchiuse tra virgolette doppie o singole. Una chiave senza valore o una stringa aperta provoca un errore di analisi.
• Attenzione alle chiavi duplicate: definire due volte la stessa tabella o la stessa chiave non è consentito e blocca la conversione.
• Verifica gli array di tabelle: ricorda la doppia parentesi [[nome]], che è ciò che distingue un array di oggetti da una singola tabella.
• Date in formato corretto: usa il formato ISO 8601, ad esempio 2026-06-21, così la conversione produce una stringa coerente.

Dopo aver incollato il TOML, dai un'occhiata all'anteprima JSON: se la gerarchia non corrisponde a quella attesa, di solito il problema è una sezione scritta nel punto sbagliato. Lo strumento elabora i dati nel browser, quindi anche con file di configurazione corposi la conversione resta immediata e i tuoi dati non lasciano il dispositivo.