JSON vs YAML — Diferenças explicadas

Você provavelmente já reparou que alguns projetos usam arquivos .json para config enquanto outros usam .yaml ou .yml. Os dois formatos representam dados estruturados. Os dois são legíveis por humanos. Então qual é a diferença de verdade, e quando você deve usar um ou outro?

Eu usei os dois extensamente — JSON é meu driver diário para APIs e troca de dados, YAML é meu goto para manifestos do Kubernetes, GitHub Actions e Docker Compose. Eles resolvem problemas parecidos mas têm personalidades bem diferentes.

Lado a lado: o mesmo config nos dois formatos

Aqui está um objeto de config de banco de dados escrito em JSON:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp",
    "ssl": true,
    "pool": {
      "min": 2,
      "max": 10
    },
    "replicas": ["replica1.db", "replica2.db"]
  }
}

E aqui está o mesmo config em YAML:

database:
  host: localhost
  port: 5432
  name: myapp
  ssl: true
  pool:
    min: 2
    max: 10
  replicas:
    - replica1.db
    - replica2.db

YAML está visivelmente menos poluído. Sem aspas na maioria das strings, sem chaves, sem vírgulas. Para um arquivo de config que humanos editam com frequência, essa clareza faz diferença. Mas o YAML alcança isso sendo significativamente mais complexo por baixo dos panos.

Onde o YAML brilha

• Arquivos de config editados por humanos. Pipelines CI/CD (GitHub Actions, GitLab CI), manifestos Kubernetes, Docker Compose, playbooks Ansible. Tudo YAML. Não é coincidência — são arquivos que humanos escrevem à mão.
• Comentários. YAML suporta comentários com #. Isso é enorme para arquivos de config onde você quer explicar por que uma configuração existe. JSON não suporta comentários.
• Strings multiline. YAML tem block scalars para conteúdo multiline que se lê naturalmente. JSON exige sequências de escape \n.
• Menos ruído visual. Sem necessidade de colocar aspas na maioria das strings, sem chaves de fechamento, sem se preocupar com trailing commas.
• Anchors e aliases. YAML permite definir um valor uma vez e referenciá-lo em outro lugar com &anchor e *alias — útil para arquivos de config DRY.

Onde o JSON vence

• Rigor. JSON tem uma representação válida para qualquer estrutura de dados. YAML tem uma dúzia de formas de escrever a mesma coisa, o que gera inconsistência entre equipes.
• Sem armadilhas de indentação. JSON usa chaves e colchetes. YAML usa indentação, o que significa que um espaço mal colocado pode silenciosamente quebrar toda a sua config.
• Performance de parse. Parsers JSON são rápidos e simples. Parsers YAML são complexos — YAML 1.1 tem regras de coerção de tipo implícita notoriamente complicadas.
• Suporte universal de bibliotecas. Toda linguagem tem um parser JSON battle-tested e sem dependências. Bibliotecas YAML variam em qualidade e conformidade com a spec.
• Tooling. Linters, formatters, validators de schema — o tooling JSON é mais maduro e amplamente disponível.
• Payloads de API. JSON é a língua universal das APIs web. Enviar YAML por HTTP seria não convencional e causaria atrito.

As pegadinhas do YAML que vão te pegar

YAML tem alguns comportamentos genuinamente surpreendentes que causaram incidentes reais em produção. A maioria vem das regras de tipo implícito do YAML 1.1, que o YAML 1.2 ajustou. Conheça esses antes de depender do YAML para algo crítico:

# YAML 1.1 implicit type coercion — all of these become booleans:
enabled: yes   # → true
disabled: no   # → false
country: NO    # → false (!)  ← the Norway Problem

# Safe practice: quote strings that look like booleans
country: "NO"
enabled: "yes"

• Inteiros octais. No YAML 1.1, 010 é interpretado como 8 (octal), não 10. Relevante para coisas como permissões de arquivo.
• Tabs vs espaços. YAML proíbe tabs para indentação. Coloque um tab do editor de código e seu arquivo quebra silenciosamente ou lança um erro críptico.
• Nulls implícitos. Um valor vazio em YAML vira null. Fácil de passar batido quando editando à mão.
• Ambiguidade string vs número. port: 8080 te dá um inteiro. version: 1.0 pode te dar um float. Às vezes você quer a string "1.0". Sempre use aspas quando isso importar.

Guia prático de decisão

Vá de YAML quando:

• Escrever arquivos de config que humanos editam diretamente: CI/CD, Kubernetes, Docker Compose, Ansible
• O arquivo vai ter comentários explicando as configurações
• Valores de string multiline são comuns
• O ecossistema em que você está trabalhando já usa YAML (não briga com a convenção)

Vá de JSON quando:

• Enviar ou receber dados por uma API
• Os dados são gerados e consumidos programaticamente (sem edição humana)
• Você precisa de consistência de parse garantida entre diferentes ferramentas e linguagens
• Trabalhando num ecossistema que padroniza em JSON: npm (package.json), VS Code (settings.json), Angular, TypeScript

Convertendo entre os dois

Precisa converter config YAML em JSON para uma ferramenta que não fala YAML? Use o conversor YAML para JSON. Indo no sentido contrário? O conversor JSON para YAML resolve. O YAML Formatter também é útil quando você cola YAML que ficou desalinhado. E se seu YAML não estiver parseando, o YAML Validator vai te dizer exatamente onde está o problema.

Resumindo

JSON e YAML são complementares, não concorrentes. Use JSON para troca de dados — APIs, armazenamento programático de dados, serialização. Use YAML para arquivos de config que humanos leem e editam. A maioria dos projetos maduros usa os dois: package.json para dependências, .github/workflows/*.yml para CI. Quando você entende para o que cada formato é otimizado, a escolha fica óbvia.