TOML versus YAML versus JSON — Formatos de configuração classificados por quão muchos os irritarão

Todo projeto acabará por exigir uma forma de configuração. O YAML está em todas as partes. O JSON é mais antigo do que alguns dos seus colegas. O TOML surgiu mais recentemente com a mão levantada, dizendo: 'na verdade, fui projetado para isso'. Os três acabarão por te trair. As traições são apenas diferentes.

Aqui está uma comparação direta — mesma configuração, três formatos — seguida exatamente pelo momento em que cada um fará você se arrepender das suas escolhas de vida.

A Mesma Configuração, Três Formas

Uma configuração básica de aplicativo web: nome, porta, bandeira de depuração, string de versão, configurações de banco de dados, origens permitidas. Nada exótico. É aqui que as diferenças entre os formatos começam a se tornar evidentes.

TOML

# App configuration
[app]
name = "my-app"
port = 3000
debug = false
version = "1.2.3"
allowed_origins = ["https://example.com", "https://api.example.com"]

[database]
host = "localhost"
port = 5432
name = "mydb"

YAML

# App configuration
app:
  name: my-app
  port: 3000
  debug: false
  version: "1.2.3"
  allowed_origins:
    - https://example.com
    - https://api.example.com

database:
  host: localhost
  port: 5432
  name: mydb

JSON

{
  "app": {
    "name": "my-app",
    "port": 3000,
    "debug": false,
    "version": "1.2.3",
    "allowed_origins": [
      "https://example.com",
      "https://api.example.com"
    ]
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "mydb"
  }
}

Visão Geral

Recurso	TOML	YAML	JSON
Comentários	✅ Sim	✅ Sim	❌ Não
Inferência de tipo	Explicita	Agressiva (muitas vezes errada)	Explicita
Matrizes	= ["a", "b"]	- item ou inline	["a", "b"]
Vírgulas no final	N / D	N / D	❌ Inválida
Configurações profundamente aninhadas	Torna-se verbosa rapidamente	Lembra-se de forma legível	Verborreia, mas clara
Estabilidade do esquema	TOML 1.0 (2021, estável)	Divergência entre versões 1.1 e 1.2 dos analisadores	Estável
Suporte a nulos	❌ Sem tipo nulo	✅ Sim (~ ou null)	✅ Sim (null)
Uso comum	Cargo.toml, pyproject.toml	GitHub Actions, k8s, Docker	package.json, tsconfig.json

YAML: Mais legível até que não seja

O YAML parece excelente em demonstrações. Uma configuração plana lê quase como um texto. O problema começa quando você atinge uma das suas situações limite — e, por então, seu arquivo de configuração já é infraestrutura essencial.

O Problema da Noruega

No YAML 1.1 — que a maioria dos analisadores ainda usa como padrão — esses valores são todos booleans: y, n, yes, no, on, off, true, false. Então country: NO é analisado como country: false. Este é o verdadeiro motivo pelo qual é chamado do Problema da Noruega — o código de país da Noruega é NO. O PyYAML resolveu isso na versão 6.0 (lançada em 2022). O SnakeYAML (usado por muitas ferramentas em Java) ainda não resolveu completamente. Verifique seu analisador antes de usar valores brutos no ou yes em configurações.

Inferência de tipo que erra

Valores não entre aspas no YAML são coercidos para tipos. port: 8080 torna-se um inteiro. version: 1.10 torna-se o float 1.1 — matematicamente iguais, semanticamente errados. Esquecer de colocar aspas em uma string de versão e você passará dez minutos tentando entender por que seu aplicativo acha que está na versão v1.1 em vez de v1.10. A solução é simples: coloque aspas em tudo que deveria permanecer como string. Mas o YAML não te obriga a isso, então ele não o faz.

A indentação é essencial

Os tabs são inválidos no YAML — não são apenas desencorajados, são inválidos. Misturar indentação com dois espaços e com quatro espaços dentro de um arquivo resulta em um erro de análise que muitas vezes aponta para a linha errada. O GitHub Actions é o ponto mais agudo aqui: um bloco mal indentado run: falha em tempo de execução, não em tempo de análise, porque os executadores de fluxo validam apenas a sintaxe, não a estrutura dos passos. Você receberá uma mensagem "valor inesperado" de um job de CI sem indicação de qual passo falhou, e você passará 20 minutos adicionando saídas de depuração antes de perceber que o problema era uma indentação com dois espaços onde quatro era esperado.

Se seu YAML se tornou uma confusão de indentação inconsistente, o Formatação YAML normalizará antes de você começar a depurar.

TOML: O formato que realmente pensou sobre configurações

Tom Preston-Werner (co-fundador do GitHub) criou o TOML porque estava cansado de escrever configurações em estilo INI com comportamento de análise inconsistente e configurações em YAML que o surpreendiam. O TOML 1.0 foi lançado em janeiro de 2021 após anos de revisões. Agora é o padrão para projetos em Rust (Cargo.toml), pacotes em Python (pyproject.toml) e sites do Hugo. O esquema é estável, os analisadores são consistentes e o sistema de tipos faz exatamente o que você espera.

O que ele faz bem

• Sem coerções de tipo inesperadas. version = "1.10" sempre é uma string. port = 3000 sempre é um inteiro. O que você escreve é o que você recebe.
• Os comentários funcionam exatamente como você espera (# até o final da linha), diferente do JSON.
• Configurações planas até moderadamente aninhadas são realmente legíveis, diferente das profundamente aninhadas em JSON.

A sintaxe de array de tabelas

O principal obstáculo do TOML é sua sintaxe de array de tabelas. Se você quiser um array de objetos — digamos, múltiplas conexões com bancos de dados — a notação é assim:

[[databases]]
name = "primary"
host = "db1.example.com"

[[databases]]
name = "replica"
host = "db2.example.com"

recebe uma parte igual do espaço restante após a margem ser subtraída. Três colunas em [[double bracket]] seção é um item no databases array. Funciona. É claro. Mas cada desenvolvedor que abre um arquivo TOML pela primeira vez pergunta: "é isso INI?" — porque parece um pouco assim. Essa insegurança tem um custo real quando você está recrutando contribuidores que nunca viram TOML antes.

O TOML também não tem null tipo — intencionalmente. Se seu esquema usa nulo para indicar "chave presente mas explicitamente ausente", você precisará modelar isso de forma diferente (omitir a chave inteira ou usar um valor sentinela). E configurações profundamente aninhadas tornam-se verbosas rapidamente: o TOML não tem o sistema de anexos/aliases do YAML para reutilizar subárvores, então há muita cópia e cola se sua configuração tiver estrutura repetida.

O Formatação TOML é útil quando você está tentando limpar um arquivo TOML que cresceu organicamente ao longo do tempo.

JSON: O demônio que você conhece

O JSON foi projetado para intercâmbio de dados — máquinas falando entre si — e não para humanos escrevendo arquivos de configuração. Acabou sendo um formato de configuração porque cada linguagem já tinha um analisador JSON, e essa conveniência venceu. Agora temos package.json, tsconfig.json, .eslintrc.json e aproximadamente 40 outros arquivos JSON em cada projeto JavaScript, todos editados manualmente.

Sem comentários. Ainda.

Douglas Crockford removeu comentários do JSON intencionalmente em 2012 — temia que os desenvolvedores os usassem como diretivas de análise (semelhantes às condições do IE). O internet reclamou disso todos os dias desde então. As soluções que as pessoas usam:

• JSONC — JSON com comentários. O VS Code o usa para settings.json e launch.json. Não é analisável por analisadores padrão de JSON. Não é padrão.
• JSON5 — adiciona comentários, vírgulas finais, chaves não entre aspas, strings multilinhas. Tem um esquema e um analisador independente. O Babel o usa para configurações. Ainda não é JSON padrão.
• A "_comment" chave — um campo de string que contém o texto do comentário. Funciona. Parece ridículo. Entra no seu modelo de dados.

Vírgulas Finais

Também inválido. Adicione uma vírgula final após o último item em um array ou objeto e JSON.parse lança SyntaxError: Unexpected token } — informando que há um problema, mas não onde está a vírgula errada. Este é o erro mais comum de análise em arquivos de configuração escritos por humanos, e acontece porque todas as demais linguagens modernas (arrays em JavaScript, listas em Python, enums em Rust) permitem vírgulas finais e os humanos escrevem JSON manualmente com essas mesmas hábitos.

O que o JSON faz bem

O sistema de tipos é claro e universal. Todos os analisadores JSON em todas as linguagens concordam sobre o que true, 1, "1"e, e null significa. O JSON Schema é a opção mais madura de validação de configuração dos três — o VS Code o usa para validar tsconfig.json e package.json no editor, com destaque de erros em tempo real. Quando ferramentas escrevem seu JSON (webpack, tsc, npm), você não se preocupa com a legibilidade — isso é o que o Formatador JSON é para.

Conclusão: Escolha com base no contexto, não na preferência

Use JSON quando as ferramentas geram ou consomem o JSON (package.json, tsconfig, configurações do AWS, respostas da API do GitHub), ou quando você precisa de validação com JSON Schema. Não force a escrita manual do JSON mais do que necessário. A falta de comentários é um problema, mas a ubiquidade e o suporte das ferramentas são difíceis de contestar.

Use YAML quando a configuração é principalmente escrita por humanos e é relativamente plana — workflows do GitHub Actions, arquivos Docker Compose, manifestos do Kubernetes. Coloque aspas em tudo que poderia ser mal interpretado como um booleano ou número (strings de versão, códigos de país, qualquer coisa que comece com um dígito). Execute um linter. Nunca use tabs. Trate a inferência de tipo como um erro, não como uma funcionalidade.

Use TOML quando você controla a escolha do formato e deseja evitar coerções de tipo inesperadas. É o mais honesto dos três sobre o que é. Se você estiver iniciando um projeto de nova geração e nenhuma das ferramentas exigir um formato, o TOML é o menos provável de te surpreender seis meses depois. A insegurança é um custo único; a clareza é permanente.

Você também pode gostar