Validador de TOML

TOML: Tom's Obvious Minimal Language e a ascensão da configuração explícita

TOML significa Tom's Obvious, Minimal Language, criada por Tom Preston-Werner (co-fundador do GitHub e autor do Jekyll) em 2013 como reação à ambiguidade do YAML e à verbosidade do JSON. A especificação estável atual é a TOML 1.0.0, publicada em janeiro de 2021 após sete anos de iteração.

O objetivo de design é cristalino: um arquivo de configuração deve ser óbvio de ler para humanos e sem ambiguidade para máquinas, com mapeamento 1:1 para uma hash table. Sem whitespace significativo, sem anchors, sem tags — todo documento TOML pode ser mentalmente transformado em um objeto JSON equivalente sem surpresas.

A sintaxe em um minuto

Um arquivo TOML é uma sequência de atribuições chave = valor, opcionalmente agrupadas em [tabelas] (objetos aninhados) e [[arrays de tabelas]] (listas de objetos). Comentários começam com #. Tipos suportados: string (variantes basic, literal e multi-line), inteiro, float (incluindo inf e nan), booleano, datetime RFC 3339, array e tabela inline.

title = "Exemplo TOML"

[server]
host = "localhost"
port = 8080

[database]
enabled = true
ports = [8001, 8001, 8002]
connection_max = 5000

[[clients]]
name = "Alice"
[[clients]]
name = "Bob"

Strings podem ser basic ("..." com sequências de escape), literal ('...' sem escape) ou multi-line ("""...""" e '''...''') — perfeitas para parágrafos de texto de ajuda em arquivos de configuração.

Onde a TOML aparece de verdade

• Cargo.toml do Rust: o manifest canônico de todo crate Rust. Inclui dependências, features, perfis de build e configurações de workspace.
• pyproject.toml do Python: padronizado pela PEP 518 (2016) para requisitos de build, PEP 517 para backends de build e PEP 621 para metadados de projeto. Ferramentas como Poetry, Hatch, PDM, Ruff, Black, mypy e pytest leem configuração dali.
• Sites estáticos Hugo e Zola: config.toml dirige todo o build.
• gopls do Go, Helm, Vagrant, cloud-init e dezenas de outras CLIs aceitam TOML.

TOML vs YAML vs JSON vs INI

• vs YAML: TOML é mais explícita, sem whitespace significativo, evitando o famoso problema da Noruega (no como booleano). YAML é mais densa para estruturas profundamente aninhadas.
• vs JSON: TOML aceita comentários, vírgulas no final, strings multi-line e tipos datetime explícitos. JSON é universal mas espartano.
• vs INI: TOML formaliza tipos e suporta tabelas aninhadas e arrays de tabelas. INI é especificada informalmente e varia entre implementações.
• vs XML: TOML é drasticamente menos verbosa; XML ainda leva vantagem em documentos com conteúdo misto.

Parsers e validadores por linguagem

• Node.js: @iarna/toml (referência), smol-toml (rápido).
• Python: tomllib na biblioteca padrão desde o Python 3.11; tomli para versões anteriores; tomli-w para escrita.
• Rust: crate toml (mantida pelo próprio time da linguagem); taplo para formatação e linting.
• Go: BurntSushi/toml, a referência de fato.
• CLI: taplo serve simultaneamente como formatter, validador e language server — roda localmente e dentro de muitos editores.

Boas práticas para arquivos TOML

• Ordem estável de chaves: mantenha as chaves agrupadas dentro de cada tabela; reordenar gera diffs barulhentos no git.
• Prefira strings literais para caminhos Windows e regex: sem dor de cabeça com escape.
• Documente com comentários: TOML permite, mas a cultura YAML/JSON às vezes esquece que existem.
• Evite abusar de heredoc: se você está enfiando blobs enormes num arquivo de config, provavelmente quer um asset separado.
• Rode taplo fmt no CI para normalizar formatação e expor erros de sintaxe antes do merge.

FAQ

Como a TOML se compara ao YAML?

A TOML é mais explícita: sem whitespace significativo, sem coerção implícita de tipos (sem o problema da Noruega), sem anchors. O YAML é mais denso e mais popular no geral, especialmente no ecossistema Kubernetes, mas a TOML lê como um INI bem feito, com tipos de verdade.

TOML é obrigatória em projetos Python?

A tendência é forte. A PEP 621 (2020) padronizou metadados de projeto no pyproject.toml, e ferramentas modernas (Poetry, Hatch, Ruff, Black, mypy, pytest) leem configuração dali. O setup.py ainda funciona, mas projetos novos raramente começam por ele.

A TOML é realmente legível?

Sim — Preston-Werner explicitamente mirou a mesma legibilidade que o Markdown alcançou para prosa. Cabeçalhos de seção [assim.aninhados] mapeiam naturalmente para "pastas" mentais, e chave = valor é universalmente familiar.

A TOML suporta estruturas aninhadas?

Sim, via nomes de tabela com pontos ([servers.alpha]) e arrays de tabelas ([[clients]]). Para estruturas ad-hoc profundamente aninhadas, no entanto, JSON ou YAML podem parecer mais naturais.

Qual versão da TOML devo mirar?

TOML 1.0.0 (janeiro de 2021). Rascunhos 0.x anteriores tinham diferenças sutis no parsing de datetime e na semântica de tabelas inline. Qualquer parser de produção a partir de 2022 fala 1.0 nativamente.