TOML vs YAML (e JSON): la stessa config in tre modi | We.Inc
Confronta TOML, YAML e JSON sugli stessi file di configurazione, affiancati. Scopri dove è richiesto ciascun formato, da pyproject.toml e Cargo.toml fino a compose.yaml.
TOML è un formato simile a INI pensato per i file di configurazione: intestazioni [table] esplicite, stringhe tra virgolette, veri tipi data e nessuna indentazione significativa. YAML si basa sull'indentazione, deduce i tipi dai valori senza virgolette e aggiunge anchor e documenti multipli. Per impostazioni poco annidate TOML è più difficile da rompere; per annidamenti profondi YAML si legge meglio.
TOML, YAML e JSON in sintesi
TOML 1.0
YAML 1.2
JSON
Annidamento
Intestazioni [table] e [a.b]
Indentazione
Parentesi graffe
Commenti
Nessuno
Stringhe
Sempre tra virgolette
Virgolette facoltative
Sempre tra virgolette doppie
Date e orari
Tipi integrati
Non presenti nel core schema 1.2
Solo stringhe
Distingue maiuscole e minuscole
Sì
Sì
Sì
Media type
application/toml
application/yaml
application/json
Il più delle volte non sei tu a scegliere: il packaging Python legge pyproject.toml, Rust legge Cargo.toml, e GitHub Actions e Docker Compose leggono YAML. Quando invece puoi scegliere, vedere una stessa config in tutti e tre i formati rende evidenti i compromessi. Scegli un esempio qui sotto e confronta.
Scegli una delle config di esempio: impostazioni di un'app, un manifest di pacchetto o un elenco di server.
Leggi gli stessi dati in TOML, YAML e JSON uno accanto all'altro.
Nota dove TOML richiede intestazioni ([[servers]]) e dove YAML richiede un'indentazione attenta.
Copia la versione che il tuo strumento si aspetta.
Gli elenchi lunghi di record simili sono il punto in cui TOML diventa prolisso: ogni voce ha bisogno della propria intestazione [[name]].
TOML vieta di definire due volte la stessa chiave o tabella, e questo intercetta errori di copia e incolla che YAML potrebbe lasciar passare a seconda del parser.
In YAML metti tra virgolette i numeri di versione. TOML non ha questa trappola perché lì il testo senza virgolette non è mai una stringa valida.
Quando puoi, usa un solo formato per repository. Formati misti vanno bene solo quando ogni strumento richiede il proprio.
Domande frequenti
TOML è meglio di YAML?
Nessuno dei due vince ovunque. Le intestazioni esplicite e le virgolette obbligatorie di TOML rendono difficile fraintendere file di configurazione piccoli e medi. YAML gestisce annidamenti profondi ed elenchi lunghi con meno rumore, al prezzo di una sintassi sensibile agli spazi e di una tipizzazione implicita.
Perché Python usa pyproject.toml?
Le guide al packaging di Python definiscono pyproject.toml con tre tabelle: [build-system] per il backend di build, [project] per i metadati come nome, versione e dipendenze, e [tool] per le impostazioni dei singoli strumenti come i linter.
TOML può rappresentare tutto ciò che rappresenta YAML?
Non tutto. TOML non ha anchor né alias, né documenti multipli per file, né null, dato che ogni chiave deve avere un valore. Per la configurazione conta raramente, ma i dati YAML che si basano su queste funzionalità non si convertono uno a uno.
Quali formati accettano Docker Compose e GitHub Actions?
Entrambi usano YAML. I workflow di GitHub Actions stanno in .github/workflows con estensione .yml o .yaml, e Compose cerca compose.yaml per default, accettando ancora docker-compose.yaml per i progetti più vecchi.
TOML supporta le stringhe su più righe?
Sì. Tre virgolette doppie aprono una stringa base su più righe che ammette i caratteri di escape, e tre virgolette singole aprono una stringa letterale su più righe che mantiene il contenuto esattamente come è scritto.
Dove è richiesto ciascun formato
I progetti Python si descrivono in pyproject.toml e i crate Rust in Cargo.toml, quindi TOML è la norma in questi ecosistemi. Anche Hugo accetta il front matter in TOML tra righe +++.
Pipeline CI, configurazioni di container e manifest di deploy si appoggiano a YAML: i workflow di GitHub Actions e i file Docker Compose sono entrambi YAML, e l'estensione che scegli è soprattutto una questione di coerenza.
A cosa rinuncia TOML in cambio della sicurezza
L'obiettivo di TOML, secondo la sua stessa specifica, è corrispondere senza ambiguità a una hash table. Questo significa niente supposizioni: il testo richiede le virgolette, i booleani sono solo true e false, e ogni tabella ha un nome in un'intestazione.
Il prezzo è la ripetizione nei dati annidati. A tre livelli di profondità, un file TOML ripete il percorso della tabella in ogni intestazione, mentre YAML si limita a indentare.
Quali file usano quale formato
File di configurazione comuni e il formato che richiedono
File
Formato
Letto da
TOML
Strumenti di build e packaging Python
Cargo.toml
TOML
Cargo, il package manager di Rust
.github/workflows/*.yml
YAML
GitHub Actions
YAML
Docker Compose
JSON
npm e altri package manager di Node
Front matter Markdown
YAML (TOML con +++ in Hugo)
Generatori di siti statici
Sintassi TOML da conoscere
Chiavi puntate, tabelle inline e date
Chiavi puntate e tabelle inline evitano intestazioni extra per piccoli gruppi, e le date sono valori tipizzati, non stringhe.
Una config in TOML, YAML e JSON
Scegli un esempio. Tutte e tre le versioni contengono esattamente gli stessi dati, così puoi confrontare come li scrive ciascun formato.
Config di esempio
TOML
YAML
JSON
Nell'esempio delle impostazioni dell'app, TOML salva opens come un vero orario locale, mentre le versioni YAML e JSON lo mantengono come stringa.