TOML vs YAML (e JSON): a mesma config de três jeitos | We.Inc
Compare TOML, YAML e JSON nos mesmos arquivos de configuração, lado a lado. Veja onde cada formato é exigido, de pyproject.toml e Cargo.toml a compose.yaml.
TOML é um formato parecido com INI feito para arquivos de configuração: cabeçalhos [table] explícitos, strings entre aspas, tipos de data de verdade e indentação sem significado. YAML depende da indentação, deduz tipos a partir de valores sem aspas e acrescenta anchors e múltiplos documentos. Para configurações rasas, TOML é mais difícil de quebrar; para aninhamento profundo, YAML se lê melhor.
TOML, YAML e JSON num relance
TOML 1.0
YAML 1.2
JSON
Aninhamento
Cabeçalhos [table] e [a.b]
Indentação
Chaves
Comentários
Nenhum
Strings
Sempre entre aspas
Aspas opcionais
Sempre entre aspas duplas
Datas e horas
Tipos nativos
Fora do core schema 1.2
Só como strings
Diferencia maiúsculas
Sim
Sim
Sim
Media type
application/toml
application/yaml
application/json
Na maioria das vezes você não escolhe: o empacotamento do Python lê pyproject.toml, o Rust lê Cargo.toml, e o GitHub Actions e o Docker Compose leem YAML. Quando você escolhe, ver uma mesma config nos três formatos deixa as vantagens e desvantagens óbvias. Escolha um exemplo abaixo e compare.
Escolha um dos exemplos de config: configurações de aplicação, um manifesto de pacote ou uma lista de servidores.
Leia os mesmos dados em TOML, YAML e JSON lado a lado.
Repare onde o TOML precisa de cabeçalhos ([[servers]]) e onde o YAML exige indentação cuidadosa.
Copie a versão que a sua ferramenta espera.
Listas longas de registros parecidos são onde o TOML fica prolixo: cada entrada precisa do próprio cabeçalho [[name]].
O TOML proíbe definir a mesma chave ou tabela duas vezes, o que pega erros de copiar e colar que o YAML pode deixar passar, dependendo do parser.
Coloque números de versão entre aspas no YAML. O TOML não tem essa armadilha, porque texto sem aspas nunca é uma string válida nele.
Mantenha um formato por repositório quando puder. Misturar formatos só faz sentido quando cada ferramenta exige o seu.
Perguntas frequentes
TOML é melhor que YAML?
Nenhum vence em tudo. Os cabeçalhos explícitos e as aspas obrigatórias do TOML tornam arquivos de config pequenos e médios difíceis de interpretar errado. O YAML lida com aninhamento profundo e listas longas com menos ruído, ao preço de uma sintaxe sensível a espaços e de tipagem implícita.
Por que o Python usa pyproject.toml?
Os guias de empacotamento do Python definem o pyproject.toml com três tabelas: [build-system] para o backend de build, [project] para metadados como nome, versão e dependências, e [tool] para configurações de ferramentas específicas, como linters.
O TOML consegue representar tudo o que o YAML representa?
Nem tudo. O TOML não tem anchors nem aliases, não aceita vários documentos por arquivo e não tem null, já que toda chave precisa receber um valor. Para configuração isso raramente importa, mas dados YAML que dependem desses recursos não se convertem de forma direta.
Quais formatos o Docker Compose e o GitHub Actions aceitam?
Os dois usam YAML. Os workflows do GitHub Actions ficam em .github/workflows com extensão .yml ou .yaml, e o Compose procura compose.yaml por padrão, ainda aceitando docker-compose.yaml em projetos mais antigos.
O TOML aceita strings de várias linhas?
Sim. Três aspas duplas iniciam uma string básica de várias linhas que aceita escapes, e três aspas simples iniciam uma string literal de várias linhas que mantém o conteúdo exatamente como foi escrito.
Onde cada formato é exigido
Projetos Python se descrevem em pyproject.toml e crates Rust em Cargo.toml, então o TOML é a norma nesses ecossistemas. O Hugo também aceita front matter em TOML entre linhas +++.
Pipelines de CI, setups de containers e manifestos de deploy se apoiam no YAML: workflows do GitHub Actions e arquivos do Docker Compose são YAML, e a extensão que você escolhe é mais uma questão de consistência.
Do que o TOML abre mão pela segurança
O objetivo do TOML, na própria spec, é mapear sem ambiguidade para uma tabela hash. Isso significa nada de adivinhação: texto precisa de aspas, booleanos são só true e false, e toda tabela é nomeada em um cabeçalho.
O preço é a repetição em dados aninhados. Com três níveis de profundidade, um arquivo TOML repete o caminho da tabela em cada cabeçalho, enquanto o YAML apenas indenta.
Quais arquivos usam qual formato
Arquivos de config comuns e o formato que exigem
Arquivo
Formato
Lido por
TOML
Ferramentas de build e empacotamento do Python
Cargo.toml
TOML
Cargo, o gerenciador de pacotes do Rust
.github/workflows/*.yml
YAML
GitHub Actions
YAML
Docker Compose
JSON
npm e outros gerenciadores de pacotes do Node
Front matter em Markdown
YAML (TOML com +++ no Hugo)
Geradores de sites estáticos
Sintaxe do TOML que vale conhecer
Dotted keys, inline tables e datas
Dotted keys e inline tables evitam cabeçalhos extras para grupos pequenos, e datas são valores tipados, não strings.
Uma config em TOML, YAML e JSON
Escolha um exemplo. As três versões guardam exatamente os mesmos dados, para você comparar como cada formato os escreve.
Exemplo de config
TOML
YAML
JSON
No exemplo de configurações de aplicação, o TOML guarda opens como uma hora local de verdade, enquanto as versões YAML e JSON a mantêm como string.