JSON vs YAML: Quando Usar Cada Formato (com Conversor)

JSON e YAML são os dois formatos mais usados para configuração e troca de dados no desenvolvimento moderno. Mas quando escolher um ou outro? Este guia explica as diferenças práticas e ajuda você a decidir.

---

Índice

• Visão geral
• JSON: o formato universal de dados
• YAML: o formato legível para humanos
• Comparação direta
• Quando usar JSON
• Quando usar YAML
• Armadilhas comuns do YAML
• Como converter entre os formatos
• Perguntas Frequentes
• Ferramentas relacionadas

---

Visão geral

Ambos os formatos representam dados estruturados (objetos, arrays, strings, números, booleanos), mas com filosofias diferentes:

• JSON prioriza simplicidade e interoperabilidade entre máquinas
• YAML prioriza legibilidade humana e expressividade

---

JSON: o formato universal de dados

JSON (JavaScript Object Notation) é o formato padrão para APIs REST, comunicação entre serviços e armazenamento de dados estruturados.

{
  "name": "meu-app",
  "version": "2.0.0",
  "dependencies": {
    "react": "^18.0.0",
    "next": "^15.0.0"
  },
  "scripts": {
    "dev": "next dev",
    "build": "next build"
  }
}

Vantagens:

• Parsing rápido e simples
• Suporte nativo em todas as linguagens
• Sem ambiguidade — a especificação é minimalista
• Amplamente usado em APIs e bancos de dados

Desvantagens:

• Não suporta comentários
• Verboso (muitas aspas e chaves)
• Não suporta referências ou âncoras
• Difícil de editar manualmente para configs grandes

---

YAML: o formato legível para humanos

YAML (YAML Ain't Markup Language) foi criado para ser o mais legível possível. É o formato preferido para configurações que humanos precisam ler e editar frequentemente.

name: meu-app
version: "2.0.0"
dependencies:
  react: "^18.0.0"
  next: "^15.0.0"
scripts:
  dev: next dev
  build: next build

Vantagens:

• Muito legível — sem ruído visual
• Suporta comentários (#)
• Suporta strings multiline
• Referências e âncoras evitam repetição
• Menos caracteres para os mesmos dados

Desvantagens:

• Indentação significativa (espaços, nunca tabs!)
• Parsing mais complexo e lento
• Armadilhas sutis (sim/não como booleanos, por exemplo)
• Múltiplas formas de representar o mesmo dado

---

Comparação direta

| Critério | JSON | YAML | |----------|------|------| | Legibilidade | ⭐⭐ | ⭐⭐⭐⭐ | | Parsing | ⭐⭐⭐⭐ | ⭐⭐ | | Comentários | ❌ | ✅ | | Multiline strings | ❌ | ✅ | | Ambiguidade | Nenhuma | Alguma | | Tabs | Permitidos | Proibidos | | Trailing comma | ❌ | N/A | | Tamanho do arquivo | Maior | Menor |

---

Quando usar JSON

• APIs REST e GraphQL
• Comunicação entre microserviços
• Bancos de dados (MongoDB, CouchDB)
• package.json, tsconfig.json, composer.json
• Qualquer contexto onde máquinas são as consumidoras principais
• Quando a especificação exige JSON

---

Quando usar YAML

• Docker Compose (docker-compose.yml)
• Kubernetes manifests (deployment.yaml)
• GitHub Actions (.github/workflows/*.yml)
• Ansible playbooks
• Configurações que humanos editam frequentemente
• Quando comentários no arquivo são importantes
• CI/CD pipelines (GitLab CI, CircleCI, Travis)

---

Armadilhas comuns do YAML

1. Booleanos implícitos

# "yes", "no", "on", "off" são booleanos em YAML 1.1!
country: no      # Isso vira false, não a string "no"!
answer: yes      # Isso vira true!

# Solução: use aspas
country: "no"
answer: "yes"

2. Números com zero à esquerda

version: 010     # Isso é 8 (octal)!
version: "010"   # Isso é a string "010"

3. Indentação inconsistente

# ERRADO — misturar tabs e espaços
server:
	port: 3000    # tab! vai dar erro

# CORRETO — sempre espaços
server:
  port: 3000

4. Dois-pontos em strings

# ERRADO
message: erro: conexão recusada

# CORRETO
message: "erro: conexão recusada"

---

Como converter entre os formatos

Se você tem um arquivo JSON e precisa converter para YAML (ou vice-versa), use o Conversor JSON ↔ YAML do Toolbox Brasil.

Também é possível converter via linha de comando:

# JSON para YAML (com yq)
cat config.json | yq -P

# YAML para JSON (com yq)
cat config.yaml | yq -o=json

# Com Python
python3 -c "import json, yaml, sys; print(yaml.dump(json.load(sys.stdin)))" < config.json

Antes de converter, pode ser útil formatar o JSON para garantir que está válido e bem indentado.

---

Perguntas Frequentes

Posso usar YAML em APIs?

Tecnicamente sim, mas não é recomendado. APIs devem usar JSON por ser mais rápido de parsear, ter suporte universal e ser o padrão da indústria.

---

YAML é mais seguro que JSON?

Não necessariamente. YAML pode ser até mais perigoso se o parser suportar execução de código (como o yaml.load() sem safe loader em Python). Use sempre parsers seguros.

---

JSON5 resolve os problemas do JSON?

JSON5 adiciona comentários, trailing commas e strings sem aspas, mas não é tão bem suportado. Para configs onde você controlaria o parser, pode ser uma boa opção.

---

Ferramentas relacionadas

• Conversor JSON ↔ YAML — Converta entre formatos instantaneamente
• Formatador de JSON — Formate JSON antes de converter
• Validador de JSON — Verifique se o JSON é válido
• Diff de Texto — Compare configurações

---

Abrir Conversor JSON ↔ YAML →