YAML vs TOML

Duas filosofias: inferido versus declarado

A diferença mais profunda de todas é onde a estrutura mora. No YAML, a estrutura é espaço em branco: níveis de indentação definem o aninhamento, e tabulações são terminantemente proibidas. No TOML, a estrutura é pontuação: uma linha como [database.pool] declara uma tabela, e a indentação é puramente cosmética. Todo o resto desta página — segurança ao colar, verbosidade em profundidade, mensagens de erro — decorre dessa única decisão.

Sintaxe: indentação versus cabeçalhos de tabela

Configuração rasa favorece os dois formatos; aninhamento profundo os separa. O YAML fica cada vez mais silencioso conforme a estrutura cresce — dois espaços e um traço — enquanto o TOML escreve um cabeçalho por nível: [database.pool.limits], e depois [database.pool.limits.read]. Com três níveis, o TOML é apenas verboso; com oito, o YAML é a única opção sensata para escrita manual. Arrays de tabelas invertem o veredito: os blocos [[products]] do TOML são nítidos e fáceis de localizar com grep, enquanto listas longas de mapas em YAML são exatamente onde as colunas se desalinham.

A segurança ao colar decorre direto disso. Soltar um bloco no YAML uma coluna mais à esquerda ou à direita quebra o parsing ou — pior — muda silenciosamente o que ele significa; o arquivo continua válido e nada avisa. No TOML, um bloco colado carrega o próprio [header], então ele cai onde o cabeçalho diz, independentemente do espaço em branco ao redor.

Tipos e o problema da Noruega

O YAML infere tipos de escalares, e a inferência tem dentes: yes, no, on e off viram booleanos sob as regras do YAML 1.1 que muitos parsers ainda trazem, NO vira false, e uma versão escrita como 1.20 pode chegar como o número 1.2. O YAML 1.2 aparou as regras, mas não unificou os parsers, então o mesmo arquivo pode receber tipos diferentes em ferramentas diferentes. A defesa é colocar aspas em tudo o que precisa continuar sendo string.

O TOML não tem uma etapa de inferência para errar: aspas fazem uma string, dígitos sem aspas fazem um inteiro (underscores são permitidos por legibilidade) e timestamps RFC 3339 são um tipo de primeira classe — uma vantagem real sobre JSON e YAML para configuração que carrega datas. Strings multilinha existem nos dois: os blocos entre aspas triplas """ do TOML e os escalares | e > do YAML.

Ecossistemas e quando escolher cada um

Os ecossistemas já dividiram o território. O YAML domina o cloud-native e o CI: manifests do Kubernetes, GitHub Actions e GitLab CI, Ansible, docker-compose, descrições OpenAPI. O TOML domina metadados de empacotamento e ferramentas: o Cargo do Rust, o pyproject.toml do Python e uma longa lista de ferramentas CLI que querem configuração inequívoca e amigável a comentários. Escolher contra um ecossistema significa brigar com as ferramentas dele para sempre, então raramente essa é uma escolha livre.

Onde a escolha é sua: opte pelo YAML para documentos profundamente aninhados e revisados por humanos, e pelo TOML quando os valores precisam ser inequívocos, os diffs exatos e os arquivos editados tanto por humanos quanto por geradores. A recomendação se inverte com frequência — a maioria dos repositórios tem os dois — e os conversores linkados aqui fazem a ponte nos dois sentidos, localmente.