YAML vs JSON vs TOML: forças, casos de uso e as armadilhas de tipagem implícita do YAML
O domínio de cada formato
Cada formato de serialização de dados domina em seu próprio terreno. JSON (JavaScript Object Notation, padronizado como ECMA-404 e RFC 8259) é a linguagem universal das APIs HTTP: praticamente todos os endpoints REST o utilizam, cada linguagem possui um analisador JSON sem dependências, e sua gramática cabe em uma única página. YAML (YAML Ain't Markup Language) domina os arquivos de configuração nas ferramentas DevOps — manifestos do Kubernetes, workflows do GitHub Actions, playbooks do Ansible e arquivos Docker Compose são todos YAML. Suas strings multilinhas e suporte a comentários o tornam muito mais confortável que JSON para arquivos que humanos editam diariamente. TOML (Tom's Obvious, Minimal Language) é a escolha canônica para configuração em nível de projeto: Cargo.toml para pacotes Rust, pyproject.toml para metadados de build Python e configurações de sites Hugo usam TOML.
Essas diferenças de domínio não são acidentais — refletem as prioridades de design de cada formato. JSON prioriza interoperabilidade e determinismo; YAML prioriza legibilidade humana e expressividade; TOML prioriza segurança de tipos e análise previsível. Compreender essas prioridades facilita a escolha da ferramenta correta.
A tipagem implícita do YAML: o problema da Noruega
A armadilha mais infame do YAML é sua agressiva coerção de tipo implícita. No YAML 1.1 (a versão usada pela maioria dos analisadores até recentemente, incluindo PyYAML < 6.0 e Psych do Ruby antes de 4.0), um escalar sem aspas é testado contra uma sequência de expressões regulares para determinar seu tipo. Os testes booleanos correspondem a yes, no, on, off, true, false — todos sem distinção de maiúsculas. Isso causou um bug real de integridade de dados em software usando códigos de país ISO 3166-1 alpha-2: o código da Noruega é NO, que o YAML 1.1 converte silenciosamente para o booleano false. Um mapeamento como norway: NO torna-se {norway: false} em tempo de execução — sem erro, sem aviso.
YAML 1.2 (publicado em 2009, adotado por ruamel.yaml e analisadores mais recentes) restringiu o conjunto booleano para apenas true e false (sensível a maiúsculas), eliminando as variantes yes/no/on/off. No entanto, milhões de arquivos de produção ainda rodam contra analisadores YAML 1.1. A regra segura: sempre coloque aspas em valores de string que possam ser interpretados errado — códigos de país, palavras tipo bandeira, strings de aparência numérica.
Outras armadilhas do YAML: tabulações, âncoras e o separador de documentos
A indentação é a sintaxe do YAML — e tabulações nunca são indentação YAML válida. A especificação proíbe explicitamente caracteres de tabulação em posições de indentação. No entanto, as tabulações são invisíveis na maioria dos editores por padrão, e uma tabulação acidental produz um erro de scanner que aponta para o número de linha errado em alguns analisadores. A solução é habilitar 'mostrar espaços em branco' no editor e configurá-lo para expandir tabulações em espaços em arquivos .yaml.
As âncoras YAML (&) e os aliases (*) permitem reutilizar um nó em todo o documento, o que é genuinamente útil para longos manifestos do Kubernetes com specs de contêiner repetidas. Mas também permitem ataques de expansão tipo 'billion laughs' em analisadores que não limitam a profundidade de alias. A maioria dos analisadores de produção (PyYAML 5.1+, snakeyaml com SafeLoader) limita a profundidade de alias; use sempre as APIs de carregamento seguro. O separador de documentos --- permite múltiplos documentos YAML em um arquivo — kubectl apply -f depende disso — mas alguns analisadores retornam apenas o primeiro documento a menos que se itere explicitamente.
Os tipos explícitos do TOML e a vantagem com datas
O TOML atribui um tipo a cada valor no nível da sintaxe, sem coerção implícita. Inteiros são escritos sem aspas (port = 8080), floats requerem um ponto decimal (timeout = 1.5), booleanos são true ou false em minúsculas, e strings sempre precisam de aspas. Um erro de digitação que produz uma palavra sem aspas é um erro de análise, não uma mudança de tipo silenciosa. TOML 1.0 (lançado em 2021) também especifica quatro tipos de data-hora como literais de primeira classe: offset_date_time (1979-05-27T07:32:00Z), local_date_time, local_date e local_time.
A sintaxe [table] e [[array of tables]] mapeia claramente para objetos aninhados e arrays de objetos. Um bloco [[servers]] seguido de outro bloco [[servers]] anexa um segundo elemento ao array servers — explícito, legível e impossível de quebrar com um espaço extra. A contrapartida: TOML não suporta âncoras nem arquivos multi-documento.
A rigidez do JSON como funcionalidade
A gramática do JSON não tem funcionalidades opcionais, sem coerção de tipo e sem diretivas no nível do documento. Um analisador compatível lendo {"active": true} em qualquer plataforma produzirá um booleano — não a string "true", não o inteiro 1. Este determinismo explica por que JSON tornou-se o formato de fio padrão para APIs. O RFC 8259 reforça a especificação: um texto JSON é um valor serializado. Chaves duplicadas em um objeto são explicitamente 'não deveria', e a codificação deve ser UTF-8 sem BOM.
A falta de comentários é a reclamação mais citada sobre JSON. Existem soluções: JSON5 (um superconjunto com comentários e vírgulas finais), JSONC (usado no settings.json do VS Code), e simplesmente remover linhas // antes de analisar. A solução idiomática para configuração que precisa de comentários é usar TOML ou YAML para autoria e JSON apenas como formato de troca de máquinas, gerado por uma etapa de build.
Escolhendo o formato certo
A regra de decisão prática é simples: JSON para qualquer dado que cruze uma fronteira de serviço (APIs HTTP, filas de mensagens, configuração gerada por código); YAML para arquivos de configuração que operadores editam à mão e que precisam de comentários ou strings multilinhas — especialmente em ecossistemas que o exigem (Kubernetes, GitHub Actions); TOML para configuração no nível do projeto onde tipagem forte é mais importante que a expressividade do YAML. Em caso de dúvida, favoreça o formato que seu ecossistema já usa.
Se você herdar um grande arquivo de configuração YAML e suspeitar de bugs de tipagem implícita, uma auditoria rápida é executá-lo por um linter YAML 1.2 (yamllint, spectral) e procurar valores sem aspas que correspondam a padrões booleanos ou numéricos. Para novos projetos, considere adicionar um schema (JSON Schema funciona para os três formatos via ferramentas). O conversor YAML / JSON / TOML do TeaFun permite alternar entre os três no navegador sem instalação.