JSON Toolkit

JSON ou YAML

Resumo: JSON delimita com chaves e YAML com indentação: máquinas ficam com JSON, humanos editando configuração ficam com YAML. Comentários, âncoras e estrutura de múltiplos documentos não sobrevivem.

Iniciante~4 min de leituraPublicado em 2026-10-30Atualizado em 2026-10-30
Quando usar JSON e quando usar YAML

Resumo da ópera: use JSON para dados de máquina para máquina e YAML para configuração editada por humanos; prefira YAML quando precisar de comentários, texto multilinha ou âncoras, e JSON quando toda linguagem precisar analisar o mesmo payload sem ambiguidade.

Lado a lado

{
  "server": {
    "host": "127.0.0.1",
    "port": 8080
  }
}

server:
  host: 127.0.0.1
  port: 8080

A mesma estrutura. O YAML descarta a pontuação e ganha um lugar para comentário.

Onde eles diferem

JSON YAML
Estrutura Chaves e vírgulas Indentação
Comentários Nenhum Sim
Strings Aspas duplas, escape obrigatório Geralmente sem aspas
Texto multilinha Escapes \n ou arrays Escalares em bloco `
Reuso Nenhum Âncoras & e aliases *
Múltiplos documentos Envolva em um array Separadores ---
Velocidade de análise Rápida Mais lenta, regras de indentação
Ambiguidade Muito baixa no analisado como booleano, indentação desalinhada

Essa última linha é o custo real do YAML. No YAML 1.1, country: NO produz o booleano false, e version: 1.0 pode virar float. O JSON não tem tipagem implícita nenhuma.

Escolhendo

JSON: corpos de requisição e resposta, mensagens de serviço a serviço, colunas JSON em bancos de dados, qualquer coisa que precise ser analisada de forma idêntica em toda linguagem.

YAML: ecossistemas onde ele é o padrão (Kubernetes, Ansible, GitHub Actions, Docker Compose); configuração que precisa de explicação; arquivos dominados por texto longo, como certificados, scripts ou SQL.

O que a conversão perde

YAML → JSON: todos os comentários, o reuso por âncoras (expandido em duplicatas), todos os documentos exceto o primeiro, e a grafia original de datas e booleanos.

JSON → YAML: a distinção string/número enfraquece, então "8080" e 8080 precisam ambos de aspas explícitas para se manterem seguros.

Converta para migrações e inspeção pontual. Não mantenha o mesmo arquivo em dois formatos como visões paralelas.

Perguntas frequentes

Como devo decidir entre JSON e YAML?

Comece por quem lê e mantém o arquivo: use JSON quando um programa o gera, ele cruza fronteiras de linguagem e precisa ser analisado de forma previsível; use YAML quando um humano o edita e precisa de explicações de campo ou texto multilinha longo. Eles se convertem entre si, mas não mantenha a mesma configuração em ambos os formatos a longo prazo.

Por que o YAML produz mais ambiguidade de tipos?

O YAML tem tipagem implícita, então valores como NO, on ou 1.0 podem virar booleanos, datas ou números. O JSON tem apenas tipos explícitos: uma string precisa de aspas, o que torna a análise mais previsível entre linguagens.

Comentários e âncoras devem sobreviver ao converter YAML para JSON?

Não. Comentários, âncoras e múltiplos documentos do YAML não podem ser representados em JSON; as âncoras são expandidas em conteúdo duplicado. Se precisar preservá-los, use uma biblioteca YAML com Document API em vez de uma ida e volta por objeto.

Leitura adicional