Como escolher um formato de configuração: JSON, YAML ou TOML

O que é

O JSON conforme a RFC 8259 prevê objetos, arrays, strings, números, true, false e null, e não tem comentários. A RFC diz que os nomes dentro de um objeto devem ser únicos (SHOULD) e que o comportamento do software receptor diante de nomes duplicados é imprevisível: alguns reportam apenas o último par, outros geram um erro. O YAML 1.2 foi projetado, segundo sua especificação, com o objetivo principal de ser um superconjunto estrito do JSON, e removeu muitas das recomendações problemáticas sobre tipagem implícita. No esquema central (Core Schema), porém, escalares sem aspas continuam tendo o tipo resolvido com base em padrões, de modo que true, True e TRUE são valores booleanos, enquanto os carregadores baseados no modelo mais antigo, o 1.1, tratam também yes, no, on e off da mesma forma. O TOML 1.0, segundo seus próprios objetivos, pretende ser um formato de configuração mínimo, fácil de ler por ter semântica óbvia e que mapeia de forma inequívoca para uma tabela hash. Ele tem comentários, tipos explícitos (string, inteiro, ponto flutuante, booleano, data e hora), tabelas entre colchetes, chaves com pontos e tabelas inline, que devem ficar em uma única linha.

Por que importa

Um arquivo de configuração é escrito por pessoas e lido por programas; o formato determina em qual ponta os erros acontecem. Erros de indentação e conversões silenciosas de tipo são a classe de falhas do YAML (version: 1.10 vira o número 1.1; a sigla de país NO vira false em um carregador 1.1). Falta de comentários e chaves duplicadas são a classe de falhas do JSON. O TOML, em estruturas muito aninhadas, obriga a usar caminhos de tabela longos.

Como aplicar

• Máquina para máquina (APIs, caches, exportação): JSON, validado contra um JSON Schema.
• Configuração mantida manualmente, com estrutura de plana a média: TOML. Python (pyproject.toml), Rust (Cargo) e muitas ferramentas o utilizam.
• YAML onde o ecossistema o exige (pipelines de CI, Kubernetes, Compose): coloque entre aspas as strings que se pareçam com números, booleanos ou horários; escolha um carregador que siga o esquema central do 1.2; não carregue tags personalizadas.
• Independentemente do formato, converta o resultado do parsing para um modelo tipado, rejeite chaves desconhecidas e interrompa a execução com uma mensagem clara (arquivo, linha, chave).
• Ao trocar de formato, converta com uma ferramenta e compare o resultado do parsing dos dois arquivos, não o texto.

Armadilhas

Segundo a RFC, um parser JSON pode aceitar extensões; comentários ou vírgulas finais que uma ferramenta tolera fazem a próxima falhar. Âncoras e múltiplos documentos em YAML são difíceis de revisar para humanos. Tabelas inline do TOML não aceitam vírgula final. 1e3 é um número de ponto flutuante no esquema central do YAML 1.2, mas uma string em carregadores 1.1, mais um motivo para usar aspas.