Neste artigo
O que é TOML?
TOML (Tom's Obvious, Minimal Language) é um formato de arquivo de configuração projetado para ser fácil de ler e escrever. Criado por Tom Preston-Werner (cofundador do GitHub), o TOML mapeia claramente para uma tabela hash e é projetado para ser inequívoco — cada documento TOML tem exatamente uma interpretação válida.
TOML é o formato de configuração preferido para Rust (Cargo.toml), Python (pyproject.toml) e muitos geradores de sites estáticos. Ele suporta comentários, literais de data e hora e tabelas aninhadas, permanecendo mais simples que YAML e mais amigável para humanos que JSON.
Regras de sintaxe TOML
A sintaxe TOML é projetada para ser mínima e inequívoca. Aqui estão os elementos fundamentais da linguagem.
- Pares chave/valor — o bloco de construção básico, escrito como chave = valor em cada linha. As chaves podem ser simples (sem aspas), entre aspas ou com pontos para acesso aninhado.
- Tabelas — seções definidas com cabeçalhos [nome_tabela] que agrupam pares chave/valor relacionados. As tabelas podem ser aninhadas usando chaves com pontos ou a sintaxe [[array_de_tabelas]].
- Arrays — listas ordenadas definidas com colchetes [1, 2, 3]. Todos os elementos devem ser do mesmo tipo. Arrays de múltiplas linhas são permitidos com vírgulas finais.
- Literais de data e hora — o TOML suporta nativamente datas RFC 3339 como 2026-03-15T14:30:00Z, datas locais (2026-03-15), horários locais (14:30:00) e deslocamentos de data e hora.
- Strings multilinha — strings entre aspas triplas ("""texto""") preservam quebras de linha e permitem conteúdo longo sem sequências de escape. Strings literais usam aspas simples ('no\escape').
Padrões TOML comuns
O TOML é amplamente usado em arquivos de configuração de projetos em diferentes ecossistemas.
- Cargo.toml — o gerenciador de pacotes do Rust usa TOML para metadados do projeto, dependências, perfis de build e configuração do workspace
- pyproject.toml — a configuração do sistema de build moderno do Python, definida pelo PEP 517/518, substitui setup.py e setup.cfg por um arquivo TOML padronizado
- Configuração Hugo — o gerador de sites estáticos Hugo usa TOML (ou YAML/JSON) para configuração do site, incluindo temas, menus, taxonomias e configurações de build
- Configuração Netlify — netlify.toml configura comandos de build, regras de redirecionamento, variáveis de ambiente e contextos de implantação para sites Netlify
Experimente gratuitamente — sem cadastro
Validar TOML online →Erros de validação comuns
O TOML é rígido por design — muitos erros que o YAML aceitaria silenciosamente falharão no TOML. Aqui estão os problemas de validação mais comuns.
- Chaves duplicadas — o TOML proíbe definir a mesma chave duas vezes na mesma tabela. Isso inclui chaves definidas via notação com pontos e cabeçalhos de tabela normais.
- Formato de data inválido — o TOML requer datas no formato RFC 3339. Erros comuns incluem a ausência do separador T (2026-03-15 14:30:00 em vez de 2026-03-15T14:30:00) ou o uso de barras em vez de hífens.
- Tipos de array mistos — todos os elementos em um array TOML devem ser do mesmo tipo. [1, "dois", 3] é inválido porque mistura inteiros e strings.
- Strings não fechadas — esquecer de fechar uma string entre aspas ou usar o tipo de aspas errado causa erros de análise. Fique atento a aspas triplas sem correspondência em strings multilinha.
TOML vs YAML vs JSON
Cada formato tem pontos fortes que o tornam mais adequado para determinados casos de uso.
- Legibilidade — TOML e YAML são altamente legíveis para humanos. O TOML usa sintaxe explícita (colchetes, sinais de igual) enquanto o YAML depende de indentação. O JSON é menos legível para configuração devido às aspas obrigatórias e à ausência de comentários.
- Rigor — o TOML é o mais rígido dos três. Ele rejeita construções ambíguas e não tem coerção de tipo implícita. A flexibilidade do YAML (yes/no como booleanos, strings simples) frequentemente causa comportamento inesperado.
- Comentários — tanto TOML quanto YAML suportam comentários (TOML usa #, YAML usa #). JSON não tem suporte a comentários, o que o torna menos adequado para arquivos de configuração que precisam de documentação.
Perguntas frequentes
Como funcionam as tabelas aninhadas no TOML?
O TOML suporta tabelas aninhadas por meio de dois mecanismos: chaves com pontos (a.b.c = valor) e cabeçalhos de tabela ([pai.filho]). Ambos criam a mesma estrutura aninhada. Para arrays de tabelas (como múltiplas dependências de pacotes), use colchetes duplos ([[nome_array]]). Cada bloco [[nome_array]] adiciona um novo elemento ao array.
Quais são as diferenças entre o TOML v1.0 e versões anteriores?
O TOML v1.0 (lançado em janeiro de 2021) é a primeira versão estável. As principais mudanças em relação aos rascunhos pré-1.0 incluem o tratamento clarificado de data e hora, semântica formalizada de tabelas inline e comportamento refinado de arrays de tabelas. A maioria das ferramentas modernas usa TOML v1.0 — se você estiver escrevendo novos arquivos de configuração, use a v1.0.
Como converter YAML para TOML?
YAML e TOML têm modelos de dados diferentes, então a conversão nem sempre é um para um. Estruturas simples de chave-valor e objetos aninhados convertem diretamente. Recursos do YAML como âncoras, aliases e chaves complexas não têm equivalente em TOML. Para a maioria dos arquivos de configuração, a conversão é direta — mapeie dicionários YAML para tabelas TOML e listas YAML para arrays TOML.