TOML vs YAML — Escolhendo o Formato de Configuração Certo

Abra qualquer projeto Rust e você encontrará um Cargo.toml. Clone um repositório GitHub e você encontrará uma pasta .github/workflows/ cheia de YAML. Ambos os formatos estão fazendo o mesmo trabalho superficial — armazenando configuração estruturada que humanos editam — mas fazem compensações muito diferentes. Se você já teve YAML silenciosamente corrompendo um valor para você, ou se perguntou por que o Rust escolheu TOML em vez de YAML para seu manifesto de pacote, este artigo é para você.

A Diferença Central: Explícito vs Implícito

A divisão fundamental entre TOML e YAML é sobre quanto o analisador pode adivinhar. TOML é explícito: cada valor tem um tipo inequívoco. Strings são sempre entre aspas. Booleanos são exatamente true ou false. Datas/horas são valores de primeira classe com sua própria sintaxe. Não há coerção de tipo implícita — o analisador não tenta ser inteligente.

YAML pende para o outro lado. Tenta ser conveniente: você não precisa de aspas na maioria das strings, e o analisador infere tipos pela aparência do valor. Essa inferência é o que morde as pessoas. A especificação YAML 1.1 (ainda usada por muitas ferramentas) trata yes, no, on, off, true e false todos como booleanos. Trata strings de versão não citadas como 1.0 como ponto flutuante. E então há o Problema da Noruega.

As Famosas Armadilhas do YAML

O Problema da Noruega tornou-se algo de um meme nos círculos DevOps. No YAML 1.1, o código de país NO é analisado como booleano false. Assim, um mapa de configuração que mapeia códigos de país ISO para configurações converteria silenciosamente a entrada da Noruega em um booleano. A especificação YAML 1.2 corrigiu isso, mas muitos analisadores amplamente usados — incluindo o modo padrão do PyYAML até recentemente — ainda visam YAML 1.1. Verifique qual versão de especificação sua ferramenta realmente implementa antes de confiar nela.

# YAML 1.1 implicit type coercion — all of these silently become booleans:
countries:
  norway: NO        # → false  ← The Norway Problem
  sweden: SE        # → "SE"   (fine, not in the boolean list)
  enabled: yes      # → true
  disabled: no      # → false
  feature_flag: on  # → true
  another: off      # → false

# Version strings can become numbers:
python_version: 3.10   # → float 3.1 (trailing zero dropped)
api_version: 1.0       # → float 1.0

# Safe: quote anything that could be ambiguous
python_version: "3.10"
country: "NO"
enabled: "yes"

• Literais octais. No YAML 1.1, 010 é analisado como 8 (octal), não 10. Isso importa para valores de permissão de arquivo como 0755.
• Tab versus espaço. YAML proíbe caracteres tab para indentação. Cole código de um editor configurado para usar tabs e você recebe um erro de análise incompreensível — ou pior, desalinhamento silencioso.
• Nulls implícitos. Uma chave sem valor torna-se null. Fácil de criar acidentalmente ao editar à mão.
• Sensibilidade à indentação. Um espaço extra e um valor muda silenciosamente de um pai para outro. Sem erro, apenas dados errados.

TOML: Como os Tipos Explícitos Realmente Parecem

O sistema de tipos do TOML está detalhado na especificação TOML v1.0. Strings devem estar entre aspas (simples ou duplas). Booleanos são true ou false e nada mais. Inteiros são inteiros. Pontos flutuantes são pontos flutuantes. E datas/horas — algo que nem JSON nem YAML tem como tipo nativo — são valores de primeira classe no TOML.

# TOML types are always unambiguous
name = "my-app"          # string — must be quoted
version = "1.0.0"        # string — quotes make it clear this is not a float
port = 8080              # integer
debug = false            # boolean — only true/false, nothing else
threshold = 0.95         # float

# Datetime is a first-class type — no string parsing needed
created_at = 2024-01-15T09:30:00Z
build_date = 2024-03-20

# Arrays
allowed_hosts = ["localhost", "staging.example.com", "api.example.com"]

# Inline tables
[database]
host = "postgres.internal"
port = 5432
name = "payments_prod"
pool_size = 20

O código de país NO é apenas uma string no TOML porque não está entre aspas, mas o TOML não infere tipos a partir de valores semelhantes a strings — os valores não citados seguem regras sintáticas estritas. Para ser uma string, precisa de aspas. O TOML simplesmente não tem o maquinário de coerção implícita que causa as armadilhas do YAML.

Lado a Lado: Uma Configuração de Pipeline CI

Aqui está um workflow do GitHub Actions — este é o território do YAML. O formato se encaixa naturalmente porque o GitHub Actions espera YAML, o aninhamento baseado em indentação espelha a estrutura lógica, e os comentários são essenciais para explicar configurações de etapas não óbvias.

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build --if-present

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Agora aqui está o manifesto de projeto equivalente em TOML — aqui é onde o TOML brilha. Compare uma estrutura real de Cargo.toml com como a mesma configuração pareceria em YAML:

# Cargo.toml — Rust package manifest
[package]
name = "payments-service"
version = "2.4.1"
edition = "2021"
description = "Payment processing microservice"
license = "MIT"
authors = ["Alice Chen <[email protected]>"]

[dependencies]
tokio = { version = "1.35", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
sqlx = { version = "0.7", features = ["postgres", "runtime-tokio-native-tls"] }
tracing = "0.1"
anyhow = "1.0"

[dev-dependencies]
tokio-test = "0.4"
wiremock = "0.6"

[profile.release]
opt-level = 3
lto = true
codegen-units = 1

As Fraquezas do TOML: Array de Tabelas

O TOML não está sem arestas. A sintaxe para arrays de tabelas — [[colchetes duplos]] — é uma das coisas mais confusas da especificação. É como você expressa o que JSON escreveria como um array de objetos, e parece estranho a princípio.

# TOML array of tables — [[double brackets]] creates array entries
[[server]]
host = "web-01.example.com"
port = 443
region = "us-east-1"

[[server]]
host = "web-02.example.com"
port = 443
region = "us-west-2"

[[server]]
host = "web-03.example.com"
port = 443
region = "eu-west-1"

# The above is equivalent to this JSON:
# { "server": [
#   { "host": "web-01.example.com", "port": 443, "region": "us-east-1" },
#   { "host": "web-02.example.com", "port": 443, "region": "us-west-2" },
#   { "host": "web-03.example.com", "port": 443, "region": "eu-west-1" }
# ]}

Em YAML, a mesma estrutura é lida de forma mais natural — apenas uma lista com propriedades indentadas. Para dados profundamente aninhados com entradas de array repetidas, o aninhamento baseado em indentação do YAML é genuinamente menos verboso do que os cabeçalhos [[seção]] do TOML. O TOML também não tem equivalente ao sistema de âncora e alias do YAML, então você não pode definir um bloco compartilhado uma vez e referenciá-lo em outros lugares. Se você se encontrar duplicando o mesmo conjunto de valores em múltiplas tabelas TOML, ficará preso copiando manualmente.

Onde Cada Formato Vence na Prática

YAML vence por padrão nestes ecossistemas:

• GitHub Actions. Toda a sintaxe de workflow é YAML. Você não tem escolha aqui, e está bem — a indentação mapeia bem para a estrutura aninhada de jobs, steps e condições.
• Kubernetes. Todo manifesto — Deployments, Services, ConfigMaps, regras Ingress — é YAML. O modelo de objetos Kubernetes é profundamente aninhado, e o YAML lida com isso graciosamente.
• Docker Compose. Definições de serviço, redes, volumes — tudo YAML. Os comentários explicando por que uma porta está exposta ou por que um intervalo de healthcheck específico é usado fazem parte da documentação.
• Ansible. Playbooks, roles, arquivos de variáveis — YAML em todo lugar. O suporte a comentários é ativamente usado para explicar parâmetros de tarefa não óbvios.

TOML vence quando você controla o formato:

• Projetos Rust. Cargo.toml é o padrão ouro. Declarações de dependência, flags de recurso, perfis de build — tudo em TOML. Os tipos explícitos significam que strings de versão como "1.0.0" permanecem strings.
• Projetos Python. pyproject.toml tornou-se o padrão para metadados de projeto Python, configuração de build e configurações de ferramentas (Black, isort, mypy, pytest todos leem dele).
• Configuração de ferramenta onde a ambiguidade causa bugs. Se sua configuração contém strings de versão, códigos de país ou outros valores que parecem que podem ser booleanos ou números, os tipos explícitos do TOML eliminam toda uma categoria de surpresas de análise.
• Configurações planas. Quando sua configuração é principalmente pares chave-valor em um ou dois níveis de aninhamento, o TOML é mais legível que YAML e mais limpo que JSON.

O Guia de Decisão Prático

Na maioria das vezes, a escolha é feita para você pelo ecossistema. GitHub Actions é YAML. Kubernetes é YAML. Rust é TOML. Python tooling é TOML. Quando você realmente tem uma escolha livre, use isso como guia:

• Use YAML quando as ferramentas o exigem — plataformas CI/CD, Kubernetes, charts Helm, Docker Compose, Ansible. Lutar contra a convenção custa mais do que economiza.
• Use YAML quando você precisa de âncoras e aliases para manter uma configuração complexa DRY — não há equivalente TOML.
• Use TOML para manifestos de projeto e configuração de ferramentas que você controla — metadados de pacote, configurações de linter, configuração de build.
• Use TOML quando sua configuração contém valores que o YAML 1.1 pode interpretar errado — strings de versão, códigos de país, qualquer coisa que se assemelhe a um booleano ou número.
• Cite suas strings YAML sempre que o valor puder ser confundido com um booleano, número ou null. Especialmente: números de versão, códigos de país, qualquer coisa que começa com um dígito e valores como yes, no, on, off.

Trabalhando com Ambos os Formatos

Precisa validar ou pretty-print um arquivo de configuração em que está trabalhando? O Formatador TOML lida com arquivos TOML, e o Formatador YAML cobre YAML. Se você precisar migrar uma configuração de um formato para outro — digamos, converter uma configuração de ferramenta baseada em YAML para TOML para um projeto que o prefere — os conversores TOML para JSON e YAML para JSON ambos produzem JSON, que você pode então converter para seu formato alvo. Às vezes passar pelo JSON como etapa intermediária é o caminho mais confiável.

Uma coisa que vale saber: ambos os formatos têm seus próprios subconjuntos compatíveis com JSON. JSON válido é YAML válido (YAML é um superconjunto de JSON). O TOML não tem esse relacionamento com JSON, mas a especificação TOML é intencionalmente mantida simples — é uma leitura rápida, o que é mais do que você pode dizer sobre a especificação YAML 1.2 completa.

Conclusão

TOML e YAML não estão realmente competindo. Acomodaram-se em nichos diferentes com base em suas prioridades de design. Os tipos implícitos e a estrutura baseada em indentação do YAML tornam-no adequado naturalmente para configurações grandes e aninhadas mantidas por equipes — pense em manifestos Kubernetes e workflows GitHub Actions. Os tipos explícitos e a estrutura de seção plana do TOML tornam-no adequado naturalmente para manifestos de projeto e configuração de ferramentas onde uma string de versão ou código de país mal lido causaria um bug real.

A coisa a levar com você: se você está escrevendo YAML e tem valores que parecem que podem ser booleanos, números ou nulls — cite-os. É o único hábito que previne a maioria dos bugs de configuração relacionados ao YAML. E se você está iniciando um novo projeto e pode escolher livremente seu formato de configuração, o TOML vale a pena examinar. O repositório GitHub do TOML tem bons exemplos, e uma vez que você tenha escrito um Cargo.toml ou pyproject.toml, o apelo do formato torna-se bastante claro.