JSON vs YAML: Differences, Pros & Cons (With Examples)

Both formats represent the same data, but they make very different trade-offs. Here's how to decide which one fits your use case.

Equipe JSONTechFebruary 10, 20259 min read

A Resposta Curta

Use JSON quando máquinas são o público principal — APIs, troca de dados, qualquer coisa que seja analisada programaticamente. Use YAML quando humanos são o público principal — arquivos de configuração, pipelines de CI/CD, qualquer coisa que seja editada manualmente. Essa é a regra prática, e ela se mantém cerca de 90% das vezes.

Mas se você quer o quadro completo — com verdadeiros trade-offs, armadilhas e o tipo de nuance que realmente importa em produção — continue lendo.

Comparação de Sintaxe Lado a Lado

Vamos começar com os mesmos dados representados em ambos os formatos. Esta é uma configuração típica para uma aplicação web:

JSON

{
  "server": {
    "host": "0.0.0.0",
    "port": 3000,
    "ssl": true
  },
  "database": {
    "driver": "postgres",
    "host": "db.example.com",
    "port": 5432,
    "credentials": {
      "username": "app_user",
      "password": "s3cret"
    },
    "pools": [5, 10, 20]
  },
  "features": {
    "darkMode": true,
    "betaAccess": false,
    "maxUploadSizeMB": 25
  }
}

YAML

# Configuração do servidor
server:
  host: "0.0.0.0"
  port: 3000
  ssl: true

# Configurações do banco de dados
database:
  driver: postgres
  host: db.example.com
  port: 5432
  credentials:
    username: app_user
    password: s3cret
  pools:
    - 5
    - 10
    - 20

# Flags de recursos
features:
  darkMode: true
  betaAccess: false
  maxUploadSizeMB: 25

A versão YAML é mais curta, tem comentários explicando cada seção e é quase como um esboço em tópicos. A versão JSON é mais explícita — cada string é citada, a estrutura é definida por chaves e colchetes, e não há ambiguidade sobre os tipos.

Na minha experiência, desenvolvedores que escrevem código principalmente tendem a preferir a explicitude do JSON. Engenheiros de DevOps e administradores de sistemas tendem a preferir a legibilidade do YAML. Nenhum dos grupos está errado.

Converta entre formatos instantaneamente: Cole JSON em nosso conversor de JSON para YAML para ver o equivalente em YAML lado a lado. Ou faça o caminho inverso com YAML para JSON.

Comparação de Recursos

Recurso	JSON	YAML
Legibilidade humana	Boa (com formatação)	Excelente
Suporte a comentários	❌ Não	✅ Sim (sintaxe `#`)
Tamanho do arquivo	Maior (citações + chaves)	Menor (baseado em indentação)
Velocidade de análise	Muito rápida	Mais lenta (gramática mais complexa)
Amizade com máquinas	Excelente	Boa
Edição humana	Moderada (fácil perder vírgulas)	Fácil (mas sensível à indentação)
Sensibilidade à indentação	Não (espaços em branco ignorados)	Sim (a indentação define a estrutura)
Strings de múltiplas linhas	Não (use escapes `\n`)	Sim (operadores pipe `
Âncoras e aliases	Não	Sim (DRY com `&` e `*`)
Tipos de dados nativos	6 tipos (string, número, booleano, nulo, objeto, array)	Todos os tipos JSON + datas, timestamps, binário
Complexidade da especificação	~10 páginas	~80 páginas
Suporte a navegadores	Nativo (`JSON.parse`)	Requer biblioteca (js-yaml, yaml)

Quando Usar JSON

JSON é a melhor escolha quando os dados estão sendo trocados entre sistemas em vez de lidos por humanos. Especificamente:

APIs e Troca de Dados

Toda API REST principal fala JSON. Respostas GraphQL são JSON. Payloads de webhook são JSON. Todo o ecossistema da web é construído em torno de Content-Type: application/json. Usar YAML para respostas de API seria ir contra a corrente.

package.json e Arquivos de Lock

npm, Yarn e a maioria das ferramentas JavaScript usam JSON para seus arquivos de configuração e lock. A especificação do package.json requer JSON estrito. Você não pode adicionar comentários (embora haja um hack bem conhecido usando uma chave "//"), e não pode usar vírgulas finais. É irritante, mas é o padrão.

{
  "name": "my-app",
  "version": "2.1.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "^15.0.0",
    "react": "^19.0.0"
  }
}

Onde Você Precisa de Velocidade

Os analisadores JSON são extremamente rápidos porque a gramática é simples. Se você está processando milhões de mensagens em um pipeline, a vantagem de desempenho de análise do JSON em relação ao YAML é significativa. Estamos falando de 5-10x mais rápido na maioria dos benchmarks.

Quando Usar YAML

YAML brilha quando humanos são os que estão escrevendo e mantendo os arquivos. O mundo DevOps se padronizou em grande parte no YAML, e por boas razões.

Docker Compose

version: "3.8"
services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    depends_on:
      - db

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: secret

volumes:
  pgdata:

Tente escrever isso em JSON e você verá imediatamente por que o Docker escolheu YAML. A estrutura aninhada é natural de ler, os comentários permitem que você anote seções, e a falta de chaves de fechamento mantém as coisas limpas.

Manifests do Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
          ports:
            - containerPort: 80

Os arquivos YAML do Kubernetes podem ficar enormes. Sem comentários e uma estrutura baseada em indentação limpa, seriam insuportáveis de manter. Dito isso, mesmo com YAML, grandes configurações do K8s ainda são bastante dolorosas — é por isso que ferramentas como Helm e Kustomize existem.

Pipelines de CI/CD

GitHub Actions, GitLab CI, CircleCI e a maioria das plataformas de CI usam YAML para definições de pipeline. A capacidade de adicionar comentários em linha explicando por que um passo existe vale seu peso em ouro quando você está depurando uma construção com falha às 2 da manhã.

Armadilhas Comuns

Armadilhas do YAML

O Problema da Noruega: No YAML 1.1, NO é interpretado como booleano false. Códigos de país, abreviações e outras strings curtas podem ser silenciosamente mal interpretadas. O YAML 1.2 corrigiu isso, mas alguns analisadores ainda usam a especificação antiga. Sempre coloque aspas em strings que possam ser ambíguas.
Erros de indentação são silenciosos: Um nível de indentação errado nem sempre causa um erro de análise — pode apenas criar uma estrutura diferente da que você pretendia. Esta é a fonte número 1 de bugs em YAML na minha experiência.
Caracteres de tabulação são proibidos: YAML permite apenas espaços para indentação. Misture um tab e você receberá um erro de análise críptico.
Preocupações de segurança: A tag !!python/object do YAML (e similares) pode executar código arbitrário durante a análise. Sempre use funções de carregamento seguro.

Armadilhas do JSON

Sem comentários. Você vai sentir falta deles. Todos sentem falta deles. Algumas ferramentas suportam JSONC, mas o JSON padrão não.
Armadilha da vírgula final: JavaScript permite que você tenha. JSON não. Copiar e colar entre os dois vai te prejudicar regularmente.
Precisão numérica: Números JSON são doubles IEEE 754. Inteiros grandes (além de 2^53) perdem precisão. Se você está lidando com IDs grandes, passe-os como strings.
Sem strings de múltiplas linhas: Valores de texto longos requerem sequências de escape \n, o que torna o arquivo mais difícil de ler.

Experimente você mesmo: Converta um arquivo JSON complexo para YAML com nosso conversor de JSON para YAML e veja como a estrutura se mapeia entre os formatos. Ou valide seu JSON primeiro com o Validador de JSON.

Você Pode Usar Ambos?

Absolutamente, e a maioria dos projetos faz isso. Um projeto típico de Node.js pode ter package.json (JSON) ao lado de docker-compose.yml (YAML) e um .github/workflows/ci.yml (YAML). Não há nada de errado em misturar formatos — use aquele que a ferramenta espera ou aquele que faz mais sentido para o contexto.

Um detalhe importante: YAML é um superconjunto de JSON (a partir do YAML 1.2). Isso significa que todo documento JSON válido também é um YAML válido. Portanto, se você colar JSON em um analisador YAML, funcionará bem. O inverso não é verdade — YAML tem recursos que JSON não suporta.

Comparação de Desempenho

Se o desempenho importa para o seu caso de uso, JSON vence decisivamente. Aqui estão números aproximados da análise do mesmo documento de 1MB:

Operação	JSON	YAML
Tempo de análise (Node.js)	~15ms	~120ms
Tempo de stringificação	~10ms	~80ms
Tamanho do arquivo (formatado)	1.00 MB	0.75 MB
Tamanho do arquivo (minificado)	0.60 MB	N/A (não dá para realmente minificar YAML)

Os arquivos YAML são menores porque pulam as citações e chaves, mas levam significativamente mais tempo para serem analisados. Para arquivos de configuração lidos uma vez na inicialização, isso não importa. Para payloads de API processados milhões de vezes por dia, isso importa muito.

A Conclusão

Recomendo JSON como a escolha padrão para troca de dados e YAML para configuração. Se uma ferramenta lhe der a opção, pense em quem vai ler e editar o arquivo. Máquinas? JSON. Humanos? YAML. Ambos? Comece com JSON e veja se a dor da falta de comentários te empurra para o YAML.

E se você é novo em JSON, comece com nosso O que é JSON? guia para os fundamentos.

Ferramentas relacionadas:

Conversor de JSON para YAML
Conversor de YAML para JSON
Formatador de JSON
JSON vs XML — outra comparação de formatos comuns