Che cos’è un file TOML?

TOML è un formato di testo semplice che si apre in qualsiasi editor. Si usa per la modifica.

L’estensione è .toml e il nome per esteso è Tom's Obvious Minimal Language. Contano entrambi meno di ciò che il file può contenere, ed è di questo che parla il resto della pagina.

Risale al 2013. La specifica è TOML 1.0.

L’età serve saperla per un motivo pratico: più un formato è vecchio, più programmi hanno avuto tempo di impararlo.

È pubblicata per intero, quindi la si può implementare partendo dal documento invece che per osservazione: è per questo che il formato compare in così tanti programmi, ed è per questo che file scritti vent’anni fa si aprono ancora. Una specifica pubblicata però non è la stessa cosa di una esente da royalty: dove un formato incapsula un codec, le licenze sui brevetti restano una questione a parte che lo standard non risolve.

TOML conserva il suo contenuto esattamente. Risalvarlo non cambia nulla, quindi puoi aprirlo, modificarlo e risalvarlo quante volte vuoi senza accumulare danni: è questo che ne fa un formato di lavoro e non di consegna.

TOML ha una sintassi per i commenti, ed è la differenza fra un file che cura una persona e uno che scrive un programma. I commenti sono la prima cosa che si perde convertendo in un formato che non li ha, e nessuno ti avvisa.

Visual Studio Code lo legge, e lo stesso vale per quasi tutti i programmi dello stesso tipo.

Quando un file non si apre, il formato è raramente il problema: più spesso è il programma a essere più vecchio di lui. Convertire in qualcosa di più vecchio è la via d’uscita affidabile, ed è a questo che serve il resto di questo sito.

Nessun browser lo legge.

È di gran lunga il motivo più comune per convertirlo: non che il formato sia scadente, ma che il posto in cui vuoi mostrare il file non sappia leggerlo.

TOML è pensato per essere aperto e modificato. Tieni il file in questo formato per tutto il tempo in cui il lavoro va avanti, ed esporta da lì ogni volta che serve una copia finita.

Il TOML assomiglia a un INI e si comporta come un formato di dati. Un valore scritto 30 è un intero, 30.0 è un decimale, true è un booleano, "30" è una stringa e 2026-08-05 è una data — il formato definisce tutti questi, quindi qualsiasi analizzatore concorda e nessun programma deve indovinare cosa intendesse chi ha scritto il file.

Questa sola proprietà spiega gran parte della sua esistenza. Gli errori di configurazione si concentrano proprio in quell’ambiguità: un interruttore letto come la stringa "false" che risulta essere vero, un numero di versione trasformato in decimale senza avviso, una porta che arriva come testo. Un formato con tipi elimina l’intera classe di problemi.

Lo YAML è più capace e molto più facile da rovinare, e il TOML è stato scritto come risposta diretta a questo. In YAML la struttura si esprime con l’indentazione, quindi uno spazio messo male cambia il significato del documento senza produrre un errore: il file continua a essere analizzato, ma come qualcos’altro.

E poi c’è l’inferenza dei tipi. Le vecchie versioni leggono no come un booleano, quindi un codice paese, un campo lingua o una colonna di risposte finisce per valere falso. Un numero di versione come 1.20 diventa 1.2. Una stringa dall’aspetto di un’ora si trasforma in un numero in base sessanta. Ognuno di questi casi ha causato incidenti reali. Il TOML non ne ha nessuno: la struttura è esplicita e un valore è ciò che dice la sua sintassi.

Rust lo ha diffuso ovunque per primo: ogni progetto con Cargo ha il suo Cargo.toml. Python ha seguito in modo decisivo, e pyproject.toml è oggi il posto standard della configurazione di build, con un lettore di TOML incluso nella libreria standard del linguaggio.

Oltre a questi due: Hugo e diversi generatori di siti statici, Netlify, Poetry, Ruff e un flusso costante di nuovi strumenti che volevano una configurazione modificabile a mano senza il rischio dell’indentazione. È diventato la scelta predefinita per la configurazione letta da chi programma, più o meno come lo YAML lo è per l’infrastruttura.

Un’intestazione fra parentesi quadre è una tabella, come il TOML chiama una sezione. L’annidamento si scrive con un punto: [tool.ruff.lint] dichiara una tabella dentro una tabella dentro un’altra, e i punti sono struttura e non parte di un nome. È esattamente dove l’INI si ferma e il TOML continua.

Vale la pena ricordare che tutto ciò che sta sotto un’intestazione appartiene a quella tabella fino alla successiva. Una chiave scritta sopra la prima intestazione finisce nel livello radice e, molto spesso, nessuno la legge: lo strumento la cerca dentro la propria sezione e lì non c’è.

Scrivere [[bin]] tre volte non ridefinisce tre volte la stessa tabella: dichiara un array di tabelle, cioè tre voci di un elenco. È il modo di esprimere «più cose dello stesso tipo» — tre eseguibili, quattro dipendenze, un elenco di autori.

Ed è la causa abituale di un sintomo molto riconoscibile: blocchi di configurazione ripetuti che sembrano sovrapporsi invece di sommarsi. Quando sopravvive solo l’ultimo, quasi sempre ci sono parentesi singole dove dovevano essercene di doppie.

Il TOML capisce date e orari direttamente: una data isolata, un’ora isolata e una marca temporale con o senza fuso orario. Sono valori come un intero, non stringhe che qualcosa deve interpretare dopo.

È una funzione piccola che toglie un fastidio persistente. Una configurazione con una data di pubblicazione, una scadenza, un taglio o un calendario smette di aver bisogno di un formato di stringa concordato in un commento e reimplementato in ogni programma che lo legge. Lo specifica il formato, e l’analizzatore restituisce una data.

I dati molto annidati. Il TOML è pensato per essere piatto e leggibile, e non appena la struttura scende di tre o quattro livelli i nomi delle intestazioni si allungano e il file si segue peggio del JSON che intendeva sostituire. Se la vostra configurazione ha forma di albero documentale, probabilmente vuole essere un albero documentale.

L’altro caso sono i dati generati da macchine. Il TOML è per file che una persona modifica; il JSON è per file che i programmi si scambiano, ed è più piccolo, più veloce da analizzare e compatibile con tutto. Usare il TOML come formato di scambio si può, e non si guadagna nulla: la leggibilità che ottimizza vale solo quando c’è qualcuno che legge.

Una cosa sparisce sempre e vale la pena dirlo prima: i commenti. Né TOML, né YAML, né INI, né XML li conservano passando di qui, perché il file viene analizzato fino a diventare valori e in quella rappresentazione non c’è alcun posto dove salvare una riga che inizia con un cancelletto. In un file di configurazione ciò è spesso proprio ciò che spiegava perché un valore fosse quello e non un altro, quindi copiate i commenti a parte se vi interessano. L’ordine delle chiavi, invece, viene mantenuto: nulla nel convertitore ordina alcunché.

Per il resto, decide la destinazione. Verso JSON, YAML o XML l’albero arriva intero. Verso INI no, e la conversione viene contrassegnata come approssimativa proprio per questo: l’INI non ha annidamento né tipi, quindi una tabella dentro un’altra viene appiattita e un booleano diventa testo che qualche programma deciderà di interpretare in seguito. Tutto questo avviene dentro il vostro browser, senza caricare il file da nessuna parte e senza quote, con un tetto di 100 MB per file e 100 file per gruppo.