A forma mais rápida de converter TOML para YAML é yq -oy '.' file.toml. Para conversão manual, mapeie os cabeçalhos de tabela [table] do TOML para blocos indentados em YAML, os arrays do TOML para listas com prefixo de traço e sempre coloque aspas em strings ambíguas para evitar o “Problema da Noruega.”
Conversão Rápida: Usando o CLI yq
O TOML (Tom’s Obvious, Minimal Language) alcançou sua versão v1.1.0 em dezembro de 2025, mas o YAML continua sendo o padrão para pipelines de CI/CD e manifestos do Kubernetes. A ferramenta yq realiza a conversão em um único comando.
Instalar o yq
| Plataforma | Comando |
|---|---|
| macOS/Linux | brew install yq |
| Windows | choco install yq |
| Python (pip) | pip install yq |
A versão baseada em Go de Mike Farah é preferida pela velocidade. Conforme notedo na documentação do yq de Mike Farah, a ferramenta decodifica a estrutura TOML e a recodifica como YAML limpo.
Executar a Conversão
Exibir no terminal:
yq -oy '.' your-config.toml
Salvar em arquivo:
yq -oy '.' your-config.toml > your-config.yaml
O flag -oy define o formato de saída como YAML. Isso gerencia pares chave-valor, tabelas aninhadas e arrays.
Mapa de Tradução de Sintaxe: Estrutura TOML para YAML
O desenvolvedor Drew DeVault observou que, embora o TOML seja popular, o YAML gerencia aninhamento profundo de forma mais limpa. Aqui está o mapeamento exato:
Tabelas para Chaves Indentadas
O TOML usa cabeçalhos entre colchetes; o YAML usa indentação.
| TOML | YAML |
|---|---|
[server] |
server: |
host = "127.0.0.1" |
host: 127.0.0.1 |
port = 8080 |
port: 8080 |
Diferença crítica: No TOML, a indentação é cosmética. No YAML, a indentação é estrutural — um espaço errado quebra toda a configuração.
Arrays para Listas com Prefixo de Traço
TOML: ports = [ 8000, 8001 ]
YAML:
ports:
- 8000
- 8001
Como o Knightli.com explica, o “estilo de bloco” do YAML torna as listas legíveis, desde que o alinhamento vertical seja consistente.
Tabelas Inline e Chaves com Ponto
| Construto TOML | Equivalente YAML |
|---|---|
[a.b.c] (cabeçalho com ponto) |
a: → b: → c: (indentação aninhada) |
point = { x = 1, y = 2 } (tabela inline) |
point: → x: 1 → y: 2 |
Casos de Uso no Mundo Real
Configuração de Site Estático Hugo
O Hugo aceita hugo.toml, hugo.yaml ou hugo.json. A maioria dos projetos começa com TOML (o padrão), depois migra para YAML quando a configuração precisa se alinhar com plataformas de deploy como Netlify ou GitHub Actions. O Hammer Europe observa que o comando hugo lê esses arquivos para determinar como o Markdown converte em um site ativo.
Empacotamento Python: pyproject.toml para YAML de CI/CD
A comunidade Python padronizou o pyproject.toml via PEP 518. Essas configurações frequentemente precisam de tradução para YAML nos workflows de CI/CD do GitHub Actions. Para workflows de agentes de IA, o CocoIndex relata que configurações YAML otimizadas podem reduzir o uso de tokens em até 70%.
O Problema da Noruega e Outras Armadilhas de Conversão
O Bug do Código de País NO
No YAML 1.1, strings sem aspas como NO, OFF e YES são automaticamente convertidas para o booleano false ou true. O TOML evita isso exigindo aspas em todas as strings. Ao converter, sempre coloque aspas nos valores ambíguos no YAML:
| Valor | Interpretação YAML 1.1 | Correção |
|---|---|---|
NO |
false |
"NO" |
OFF |
false |
"OFF" |
YES |
true |
"YES" |
On |
true |
"On" |
O YAML 1.2 (a especificação atual) corrige a maioria dessas coerções, mas muitos analisadores ainda usam o comportamento 1.1 por padrão.
Erros de Indentação
Analisadores YAML rejeitam arquivos com indentação inconsistente. Erros comuns:
- Misturar tabs e espaços (YAML proíbe tabs)
- Usar 3 espaços em um bloco e 2 em outro
- Itens de lista desalinhados
Geração Assistida por IA
Ferramentas como o AgentBuilder permitem descrever a configuração em linguagem natural e gerar YAML validado. Esse ciclo “descrever → gerar → validar” ajuda a evitar tanto erros de indentação quanto o Problema da Noruega.
Conclusão
Use yq -oy '.' file.toml para conversão automatizada. Para trabalho manual, mapeie tabelas TOML para indentação YAML, arrays para listas com prefixo de traço e sempre coloque aspas em strings que possam ser confundidas com booleanos. Após qualquer conversão, valide a saída YAML antes de implantar — um único espaço desalinhado ou um NO sem aspas pode quebrar todo o seu pipeline.
Perguntas Frequentes
O YAML suporta comentários como o TOML?
Sim. Ambos usam # para comentários de uma linha. Comentários YAML podem interferir na análise de strings multilinha, então coloque-os em linhas separadas quando houver dúvida.
O que é o ‘Problema da Noruega’ no YAML?
No YAML 1.1, strings sem aspas como NO (código do país Noruega) são automaticamente convertidas para o booleano false. O TOML evita isso exigindo aspas em todos os valores de string. Ao converter TOML para YAML, envolva qualquer string potencialmente ambígua em aspas.
Qual formato gerencia melhor o aninhamento profundo?
YAML. O TOML exige repetir cabeçalhos longos como [table.subtable.subsubtable] para cada nível, o que se torna verboso. O YAML representa a mesma hierarquia com indentação — mais compacto e legível em profundidade.
Deixe um comentário