In questo articolo
Cos'è TOML?
TOML (Tom's Obvious, Minimal Language) è un formato di file di configurazione progettato per essere facile da leggere e scrivere. Creato da Tom Preston-Werner (cofondatore di GitHub), TOML si mappa chiaramente su una tabella hash ed è pensato per essere non ambiguo — ogni documento TOML ha esattamente un'interpretazione valida.
TOML è il formato di configurazione preferito per Rust (Cargo.toml), Python (pyproject.toml) e molti generatori di siti statici. Supporta commenti, letterali data-ora e tabelle annidate pur rimanendo più semplice di YAML e più leggibile di JSON.
Regole di sintassi TOML
La sintassi TOML è progettata per essere minima e non ambigua. Ecco gli elementi fondamentali del linguaggio.
- Coppie chiave/valore — il blocco di costruzione di base, scritto come chiave = valore su ogni riga. Le chiavi possono essere nude (senza virgolette), tra virgolette o con punti per l'accesso annidato.
- Tabelle — sezioni definite con intestazioni [nome_tabella] che raggruppano coppie chiave/valore correlate. Le tabelle possono essere annidate usando chiavi puntate o la sintassi [[array_di_tabelle]].
- Array — liste ordinate definite con parentesi quadre [1, 2, 3]. Tutti gli elementi devono essere dello stesso tipo. Gli array multiriga sono consentiti con virgole finali.
- Letterali data-ora — TOML supporta nativamente le date RFC 3339 come 2026-03-15T14:30:00Z, le date locali (2026-03-15), le ore locali (14:30:00) e gli offset data-ora.
- Stringhe multiriga — le stringhe tra triple virgolette ("""testo""") preservano le interruzioni di riga e consentono contenuti lunghi senza sequenze di escape. Le stringhe letterali usano virgolette singole ('no\escape').
Pattern TOML comuni
TOML è ampiamente utilizzato nei file di configurazione dei progetti in diversi ecosistemi.
- Cargo.toml — il gestore dei pacchetti di Rust usa TOML per i metadati del progetto, le dipendenze, i profili di build e la configurazione del workspace
- pyproject.toml — la configurazione del moderno sistema di build di Python, definita da PEP 517/518, sostituisce setup.py e setup.cfg con un file TOML standardizzato
- Configurazione Hugo — il generatore di siti statici Hugo usa TOML (o YAML/JSON) per la configurazione del sito inclusi temi, menu, tassonomie e impostazioni di build
- Configurazione Netlify — netlify.toml configura i comandi di build, le regole di reindirizzamento, le variabili d'ambiente e i contesti di deploy per i siti Netlify
Prova gratuitamente — nessuna registrazione richiesta
Valida TOML online →Errori di validazione comuni
TOML è rigoroso per design — molti errori che YAML accetterebbe silenziosamente falliranno in TOML. Ecco i problemi di validazione più comuni.
- Chiavi duplicate — TOML vieta di definire la stessa chiave due volte nella stessa tabella. Questo include le chiavi impostate tramite notazione puntata e le intestazioni di tabella regolari.
- Formato data non valido — TOML richiede date RFC 3339. Gli errori comuni includono l'assenza del separatore T (2026-03-15 14:30:00 invece di 2026-03-15T14:30:00) o l'uso di barre oblique invece di trattini.
- Tipi di array misti — tutti gli elementi in un array TOML devono essere dello stesso tipo. [1, "due", 3] non è valido perché mescola interi e stringhe.
- Stringhe non chiuse — dimenticare di chiudere una stringa tra virgolette o usare il tipo di virgolette errato causa errori di analisi. Fai attenzione alle triple virgolette non corrispondenti nelle stringhe multiriga.
TOML vs YAML vs JSON
Ogni formato ha punti di forza che lo rendono più adatto per determinati casi d'uso.
- Leggibilità — TOML e YAML sono entrambi molto leggibili per gli esseri umani. TOML usa una sintassi esplicita (parentesi, segni di uguale) mentre YAML si basa sull'indentazione. JSON è meno leggibile per la configurazione a causa delle virgolette obbligatorie e dell'assenza di commenti.
- Rigore — TOML è il più rigoroso dei tre. Rifiuta le costruzioni ambigue e non ha coercizione implicita del tipo. La flessibilità di YAML (yes/no come booleani, stringhe nude) spesso causa comportamenti imprevisti.
- Commenti — sia TOML che YAML supportano i commenti (TOML usa #, YAML usa #). JSON non ha alcun supporto per i commenti, il che lo rende meno adatto ai file di configurazione che necessitano di documentazione.
Domande frequenti
Come funzionano le tabelle annidate in TOML?
TOML supporta le tabelle annidate attraverso due meccanismi: chiavi puntate (a.b.c = valore) e intestazioni di tabella ([genitore.figlio]). Entrambi creano la stessa struttura annidata. Per gli array di tabelle (come le dipendenze di più pacchetti), usa le doppie parentesi ([[nome_array]]). Ogni blocco [[nome_array]] aggiunge un nuovo elemento all'array.
Quali sono le differenze tra TOML v1.0 e le versioni precedenti?
TOML v1.0 (rilasciato a gennaio 2021) è la prima versione stabile. Le modifiche principali rispetto alle bozze pre-1.0 includono la gestione chiarificata di datetime, la semantica formalizzata delle tabelle inline e il comportamento affinato degli array di tabelle. La maggior parte degli strumenti moderni usa TOML v1.0 — se stai scrivendo nuovi file di configurazione, punta alla v1.0.
Come si converte YAML in TOML?
YAML e TOML hanno modelli di dati diversi, quindi la conversione non è sempre biunivoca. Le strutture chiave-valore semplici e gli oggetti annidati si convertono direttamente. Le funzionalità YAML come gli anchor, gli alias e le chiavi complesse non hanno equivalenti TOML. Per la maggior parte dei file di configurazione, la conversione è semplice — mappa i dizionari YAML nelle tabelle TOML e le liste YAML negli array TOML.