JSON vs YAML: diferenças e quando usar cada um

JSON e YAML resolvem o mesmo problema —— representar dados estruturados como texto —— mas fazem trade-offs opostos. JSON é otimizado para parse de máquina sem ambiguidade; YAML é otimizado para escrita humana. Desde o YAML 1.2, todo documento JSON válido também é YAML válido. Este guia compara a sintaxe, os tipos e as funcionalidades dos dois, e explica quando usar cada um.

A resposta curta

Use JSON para dados trocados entre programas —— respostas de API, payloads de mensagem, qualquer coisa gerada por máquina. Use YAML para arquivos que humanos escrevem e editam à mão —— pipelines de CI, manifests do Kubernetes, configuração de aplicação —— onde comentários e legibilidade importam.

Sintaxe lado a lado

Os mesmos dados em ambos os formatos:

# YAML
service: api
replicas: 3
ports:
  - 8080
  - 8443
env:
  LOG_LEVEL: info
  DEBUG: false

// JSON
{
  "service": "api",
  "replicas": 3,
  "ports": [8080, 8443],
  "env": {
    "LOG_LEVEL": "info",
    "DEBUG": false
  }
}

YAML usa indentação em vez de chaves e colchetes, descarta a maioria das aspas e permite comentários. JSON é mais verboso mas não tem whitespace significativo, o que torna ele bem mais fácil de parsear e gerar de forma confiável.

YAML é um superconjunto do JSON

Desde o YAML 1.2 (2009), YAML é um superconjunto estrito do JSON —— todo documento JSON válido é YAML válido, porque YAML adotou direto a sintaxe «flow» do JSON. É por isso que você pode colar JSON num arquivo YAML e ele simplesmente funciona. Para o histórico por trás disso, veja YAML 1.2 e compatibilidade com JSON.

# Isto é YAML válido —— também é JSON válido
{"service": "api", "replicas": 3}

Comparação de funcionalidades

Tratamento de tipos: as arestas afiadas do YAML

A pressa do YAML em inferir tipos causa surpresas que as aspas explícitas do JSON evitam:

# O "Norway problem" —— estes viram boolean em parsers YAML 1.1
countries:
  - NO   # → false (!)
  - SE
  - true # → boolean, não a string "true"

version: 1.20   # → o número 1.2, o zero do final se perde
zip: 01234      # → 668 (parseado como octal) em alguns parsers

JSON não tem nenhuma dessas ambiguidades: "NO" é sempre a string NO, e "01234" é sempre aquela string. Quando um valor YAML precisa ser string, coloque aspas explicitamente.

Onde TOML e JSON5 se encaixam

Outros dois formatos comuns de config «amigáveis ao humano» que aparecem na mesma conversa:

• TOML —— estilo section/key, desenhado para configuração de app editada à mão (Cargo, Poetry, Hugo). Mais estrito que o YAML, sem indentação significativa, valores com tipos nativos (datetime, integer, float, array, inline table). Melhor quando os dados são em grande parte tabelas planas.
• JSON5 —— JSON com relaxamentos amigáveis ao desenvolvedor: comentários, vírgulas no final, keys sem aspas, aspas simples, strings multilinha. Não é algo que um parser JSON padrão aceita; você opta por uma lib JSON5 (ou um parser JSONC para o subconjunto comentários + vírgulas no final, por exemplo tsconfig.json).

Encaixe aproximado: JSON para troca entre máquinas, YAML para config profundamente aninhada editada por humanos, TOML para config plana de app/ferramenta, JSON5/JSONC quando você quer JSON-com-comentários para configs de editor sem adotar as regras de whitespace do YAML.

Quando usar cada um

• Use JSON para: APIs REST/GraphQL, filas de mensagem, localStorage do navegador, package.json, qualquer coisa gerada ou consumida por código.
• Use YAML para: GitHub Actions / GitLab CI, Kubernetes e Docker Compose, playbooks do Ansible, config de app que humanos editam e querem comentar.

Um padrão comum: escrever a config em YAML para legibilidade, e então converter para JSON no build ou no load para que sua aplicação só parseie JSON.

Convertendo entre JSON e YAML

# Python —— YAML para JSON
import yaml, json
data = yaml.safe_load(open('config.yaml'))
print(json.dumps(data, indent=2))

# Linha de comando com yq
yq -o=json '.' config.yaml      # YAML → JSON
yq -P '.' config.json           # JSON → YAML

Ou converta na hora no seu navegador com o conversor YAML ⇄ JSON do fixjson —— cole YAML, pegue JSON (ou ao contrário), sem dados enviados a qualquer servidor.

Perguntas frequentes

YAML é melhor que JSON?

Nenhum é «melhor» —— estão afinados para trabalhos diferentes. YAML é melhor para config editada por humanos (comentários, legibilidade); JSON é melhor para troca de dados entre máquinas (parse simples, rápido e sem ambiguidade).

JSON é YAML válido?

Sim. Desde o YAML 1.2, YAML é um superconjunto estrito do JSON, então qualquer documento JSON válido é também YAML válido. O contrário não é verdade —— a maioria do YAML não é JSON válido.

Por que o YAML transforma «NO» em false?

O YAML infere tipos a partir de escalares sem aspas, e alguns parsers leem NO, yes, on, off como boolean (o «Norway problem»). Coloque o valor entre aspas ("NO") para forçar string. JSON evita isso completamente com aspas obrigatórias.

Devo usar YAML ou JSON para arquivos de config?

Use YAML se humanos editam o arquivo e se beneficiam de comentários e strings multilinha; use JSON se for gerado ou consumido por tooling. Muitos times escrevem YAML e convertem para JSON na hora do load.

Converta e valide no seu navegador

• Conversor YAML ⇄ JSON —— converta em qualquer direção, do lado do cliente
• Formatador YAML —— formate, re-indente e valide YAML
• O que é JSON? —— o formato do qual o YAML é superconjunto
• Como formatar JSON —— pretty-print da saída convertida
• YAML 1.2 e compatibilidade com JSON —— como o YAML virou um superconjunto do JSON