JSON é um subconjunto de YAML?

O YAML 1.2 foi explicitamente projetado para ser um superconjunto estrito de JSON, então qualquer documento JSON válido também é YAML válido. O YAML 1.1, que ainda é o padrão em uma quantidade surpreendente de ferramentas (incluindo PyYAML mais antigo), não é — ele analisa algumas strings JSON-válidas de forma diferente. Se você precisa da garantia de superconjunto, confirme que seu analisador é YAML 1.2.

Por que o YAML analisa 'no' como false?

As regras booleanas do YAML 1.1 tratam 'yes', 'no', 'on', 'off', 'true', 'false', 'y', 'n' (e várias capitalizações) como booleanos. Uma lista de países com 'NO' (código ISO da Noruega) torna-se [false, ...]. O YAML 1.2 corrigiu isso — apenas 'true' e 'false' são booleanos. Se você está preso em um analisador YAML 1.1, coloque strings ambíguas entre aspas.

JSON pode ter comentários?

Não no padrão. O RFC 8259 exclui explicitamente comentários. Alternativas: JSON5 e JSONC adicionam suporte a comentários, mas não são interoperáveis com analisadores JSON estritos, ou inclua uma chave irmã como '_comment' que o código downstream ignora. Se comentários são imprescindíveis, use YAML, TOML ou HCL.

O YAML é realmente inseguro?

Carregadores YAML padrão em alguns idiomas (notavelmente yaml.load do Python antes de 2020, Psych do Ruby) podem instanciar classes arbitrárias a partir da entrada, o que é um risco de execução remota de código se a entrada for controlada por um invasor. A correção é usar o carregador 'seguro' (yaml.safe_load em Python, YAML.safe_load em Ruby) que emite apenas tipos primitivos. Nunca alimente YAML não confiável para um carregador padrão.

E quanto ao TOML ou HCL?

Ambos são excelentes para configuração. TOML é o formato que o Cargo do Rust e o pyproject.toml do Python usam — previsível, amigável a comentários e mais difícil de ler errado do que o YAML. HCL é o formato da HashiCorp (Terraform). Para novos projetos onde você controla a ferramenta, TOML é frequentemente o melhor dos três. JSON e YAML ainda dominam onde o consumidor é fixo (manifestos Kubernetes são YAML; package.json é JSON).

Por que meus números grandes voltam errados do JSON?

Os números JSON não têm limite de precisão na especificação, mas o JavaScript (e muitos analisadores JSON) os desserializa em doubles IEEE 754, que perdem precisão acima de 2^53 - 1 (cerca de 9.007 × 10^15). Um ID snowflake do Twitter de 19 dígitos ou um ID de objeto Stripe acima desse limite será arredondado. Codifique inteiros grandes como strings, ou use um analisador que suporte BigInt.

Guide

JSON vs YAML: Escolhendo o formato de configuração certo

Um é verboso e previsível. O outro é conciso e tem opiniões sobre a Noruega. Escolha pelo motivo certo.

By Buğra SözeriPublished May 31, 2026

JSON e YAML parecem a mesma coisa em fantasias diferentes até você tentar manter um arquivo de configuração de mil linhas em qualquer um dos dois. As diferenças importam, e a maioria delas não é sobre sintaxe — é sobre o que cada formato faz quando você está ligeiramente errado.

O mesmo exemplo em ambos

A maneira mais rápida de sentir a diferença é ler dados idênticos lado a lado.

JSON

{
  "name": "convertitive",
  "version": "1.4.0",
  "ports": [80, 443],
  "features": {
    "darkMode": true,
    "telemetry": false
  },
  "owners": ["[email protected]", "[email protected]"]
}

YAML

name: convertitive
version: 1.4.0
ports:
  - 80
  - 443
features:
  darkMode: true
  telemetry: false
owners:
  - [email protected]
  - [email protected]

O YAML é cerca de 30% mais curto e indiscutivelmente mais legível para um humano que nunca viu nenhum dos dois antes. O JSON é inequívoco para uma máquina, amigável a analisador e sobrevive a copiar e colar por qualquer editor de texto em qualquer sistema operacional sem dano de caractere invisível.

Esse resumo é a maior parte da escolha, mas os detalhes abaixo são onde os projetos se complicam.

No que o YAML vence

Comentários

YAML suporta # comentários de linhaem qualquer lugar. JSON não — o RFC 8259 os exclui deliberadamente. Para um arquivo de configuração que humanos lerão e editarão, comentários não são um luxo; são como você documenta por que um sinalizador está desativado ou qual intervalo de valor uma configuração realmente aceita.

# fixar em uma versão de patch específica; não atualizar automaticamente
version: 1.4.0

ports:
  - 80
  # 443 está aqui para que a verificação de saúde do LB funcione; não remova
  - 443

JSON5 e JSONC adicionam suporte a comentários, mas não são JSON — um analisador estrito os rejeitará. Se sua configuração será consumida por código que você não controla, isso é um problema.

Strings de múltiplas linhas

YAML tem dois estilos de escalar em bloco para strings de múltiplas linhas. | preserva novas linhas, > as dobra em espaços. Ambos permitem escrever valores de comprimento de parágrafo sem uma sopa de escape.

description: |
  Convertitive é um site de ferramentas.
  Carrega rápido e não tem pop-ups.

summary: >
  Uma única frase escrita em
  várias linhas para conforto do editor.

O equivalente JSON é uma longa linha com escapes \n, o que é bom para um campo e miserável para cinquenta.

Âncoras e aliases

YAML permite rotular um nó com & e referenciá-lo em outro lugar com *. Chaves de mesclagem (<<) estendem um mapeamento com outro. O resultado é um DRY real em um arquivo de configuração:

defaults: &defaults
  retries: 3
  timeout_ms: 5000

production:
  <<: *defaults
  endpoint: api.example.com

staging:
  <<: *defaults
  endpoint: staging.api.example.com
  timeout_ms: 30000  # substitui o padrão

JSON não tem equivalente. A solução alternativa é templates (Jinja, Helm) ou pós-processamento em tempo de carregamento, ambos os quais adicionam complexidade que as configurações nativas de JSON evitam.

Legibilidade visual

Indentação como estrutura é a única maior razão pela qual as equipes escolhem YAML. Um documento profundamente aninhado é lido de cima para baixo; você não perde o lugar contando chaves. É por isso que todo manifesto Kubernetes é YAML e todo playbook Ansible é YAML.

No que o JSON vence

Análise sem ambiguidade

JSON tem uma gramática de cinco páginas. Dois analisadores corretos concordarão em todo documento. YAML tem uma gramática de noventa páginas com múltiplas interpretações válidas do mesmo documento dependendo da versão do analisador. A estritez do JSON é o recurso.

Ubiquidade de ferramentas

Todo idioma vem com um analisador JSON em sua biblioteca padrão. YAML requer uma dependência de terceiros na maioria dos ambientes — PyYAML, js-yaml, snakeyaml, go-yaml. Para um arquivo de configuração incorporado em uma ferramenta que precisa funcionar em qualquer lugar, a história de zero dependências do JSON importa.

Ciclos de ida e volta por qualquer canal de texto

JSON não tem espaço em branco significativo. Você pode colá-lo em um cliente de chat, um e-mail, um prompt de shell; você pode minificá-lo; você pode transmiti-lo em um corpo HTTP sem pensar. YAML tem espaço em branco significativo e um único erro de tabulação vs. espaços quebra o documento.

O problema da Noruega — literalmente

A armadilha de YAML mais famosa: no YAML 1.1, a string NO é analisada como o booleano false. Listas de países que incluem o código ISO da Noruega (NO) tornam-se [false, ...] a menos que entre aspas. O mesmo acontece com YES, ON, OFF e várias capitalizações. O YAML 1.2 corrige isso tratando apenas true e false em minúsculas como booleanos, mas uma quantidade surpreendente de ferramentas usa 1.1 por padrão em 2026.

JSON não tem surpresa equivalente. “NO” é uma string. true é um booleano. Não há ambiguidade de versão para herdar.

Padrões de segurança

A especificação do YAML inclui tags de tipo que permitem que um documento instrua o analisador a instanciar classes arbitrárias. Várias ligações de linguagem honraram isso por padrão por anos, o que significa que carregar um documento YAML controlado por um invasor poderia executar código arbitrário — a mesma classe de bug que a desserialização Java. A correção é usar um carregador “seguro” (yaml.safe_load em Python, YAML.safe_load em Ruby).

JSON não tem tal mecanismo. O pior que um documento JSON malicioso pode fazer é travar o analisador com uma estrutura profundamente aninhada ou esgotar a memória com uma string longa.

Armadilhas compartilhadas

Precisão de números JSON

A especificação do JSON diz que os números podem ser de magnitude e precisão arbitrárias. O JSON.parse do JavaScript e a maioria das implementações não-JS na verdade os desserializam em doubles IEEE 754, que podem representar inteiros exatamente apenas até 2^53 - 1 (cerca de 9.007 × 10^15). Um ID snowflake do Twitter, um ID de cobrança Stripe ou qualquer inteiro de 19 dígitos será arredondado silenciosamente. A correção é codificar inteiros grandes como strings (Twitter, Discord e Stripe fazem isso em suas APIs JSON) ou usar um analisador com suporte a BigInt.

YAML herda o mesmo problema em qualquer idioma que desserializa inteiros em um tipo de largura fixa. A mitigação é a mesma: coloque inteiros grandes entre aspas se a precisão importar.

Deriva de versão YAML

YAML 1.1 (2005) e YAML 1.2 (2009) são as duas versões em uso. 1.2 é um superconjunto estrito de JSON, corrigiu o problema da Noruega e apertou consideravelmente a especificação. Muitos analisadores ainda usam 1.1 como padrão silenciosamente. A primeira coisa a fazer com uma nova base de código YAML é estabelecer qual versão o analisador está usando e registrar a resposta no README.

Chaves duplicadas

A especificação JSON não diz o que fazer com chaves duplicadas; os analisadores discordam (a maioria pega o último valor, alguns lançam erro, alguns retornam ambos). A especificação YAML diz que duplicatas são um erro, mas muitos analisadores as toleram. Em ambos, nunca escreva chaves duplicadas e valide com um esquema se sua entrada não for confiável.

Uma árvore de decisão

Para novos projetos onde você controla o consumidor:

Formato de transmissão máquina-a-máquina? Use JSON. Todo idioma o analisa, comentários não importam e a estritez elimina toda uma classe de bugs de integração.
Configuração editada por humanos com menos de 100 linhas? Use YAML se o consumidor espera YAML, TOML caso contrário. Ambos suportam comentários; TOML é menos surpreendente.
Configuração editada por humanos com mais de 100 linhas, profundamente aninhada? As âncoras e escalares de bloco do YAML começam a compensar nesse tamanho. Fixe ao YAML 1.2 na documentação.
Entrada não confiável? JSON é mais seguro por padrão. Se você precisar aceitar YAML, use o carregador seguro e um esquema.
O consumidor é fixo (Kubernetes, npm)? Combine com o consumidor. Não lute contra o ecossistema.

Convertendo entre eles

A conversão é mecânica porque o YAML 1.2 é um superconjunto de JSON. JSON para YAML é sempre sem perdas. YAML para JSON é sem perdas apenas se o YAML usar tipos primitivos e nenhuma âncora/alias que exigiria expansão.

Nosso conversor JSON ↔ YAML lida com ambas as direções no navegador e mostra a linha onde a análise falha se a entrada for inválida. Para trabalho JSON puro — formatação, validação, minificação — o formatador JSON é uma ferramenta mais precisa.

A conclusão honesta

JSON é o padrão certo para qualquer coisa que dois programas precisem concordar. YAML é o padrão certo para qualquer coisa que um humano editará extensivamente. A maioria dos sistemas de produção acaba com ambos: YAML na fronteira humana (gráficos Helm, fluxos de trabalho do GitHub Actions, configuração de aplicativo), JSON sobre o fio e em repouso em bancos de dados.

A resposta errada é escolher qualquer formato que você viu primeiro e usá-lo para tudo. JSON para uma configuração de mil linhas sem comentários é hostil. YAML para um corpo de resposta HTTP convida cada armadilha deste artigo. Combine o formato com o consumidor e o editor, e releia a história da Noruega uma vez por trimestre para permanecer paranóico.

Frequently asked questions

JSON é um subconjunto de YAML?: O YAML 1.2 foi explicitamente projetado para ser um superconjunto estrito de JSON, então qualquer documento JSON válido também é YAML válido. O YAML 1.1, que ainda é o padrão em uma quantidade surpreendente de ferramentas (incluindo PyYAML mais antigo), não é — ele analisa algumas strings JSON-válidas de forma diferente. Se você precisa da garantia de superconjunto, confirme que seu analisador é YAML 1.2.
Por que o YAML analisa 'no' como false?: As regras booleanas do YAML 1.1 tratam 'yes', 'no', 'on', 'off', 'true', 'false', 'y', 'n' (e várias capitalizações) como booleanos. Uma lista de países com 'NO' (código ISO da Noruega) torna-se [false, ...]. O YAML 1.2 corrigiu isso — apenas 'true' e 'false' são booleanos. Se você está preso em um analisador YAML 1.1, coloque strings ambíguas entre aspas.
JSON pode ter comentários?: Não no padrão. O RFC 8259 exclui explicitamente comentários. Alternativas: JSON5 e JSONC adicionam suporte a comentários, mas não são interoperáveis com analisadores JSON estritos, ou inclua uma chave irmã como '_comment' que o código downstream ignora. Se comentários são imprescindíveis, use YAML, TOML ou HCL.
O YAML é realmente inseguro?: Carregadores YAML padrão em alguns idiomas (notavelmente yaml.load do Python antes de 2020, Psych do Ruby) podem instanciar classes arbitrárias a partir da entrada, o que é um risco de execução remota de código se a entrada for controlada por um invasor. A correção é usar o carregador 'seguro' (yaml.safe_load em Python, YAML.safe_load em Ruby) que emite apenas tipos primitivos. Nunca alimente YAML não confiável para um carregador padrão.
E quanto ao TOML ou HCL?: Ambos são excelentes para configuração. TOML é o formato que o Cargo do Rust e o pyproject.toml do Python usam — previsível, amigável a comentários e mais difícil de ler errado do que o YAML. HCL é o formato da HashiCorp (Terraform). Para novos projetos onde você controla a ferramenta, TOML é frequentemente o melhor dos três. JSON e YAML ainda dominam onde o consumidor é fixo (manifestos Kubernetes são YAML; package.json é JSON).
Por que meus números grandes voltam errados do JSON?: Os números JSON não têm limite de precisão na especificação, mas o JavaScript (e muitos analisadores JSON) os desserializa em doubles IEEE 754, que perdem precisão acima de 2^53 - 1 (cerca de 9.007 × 10^15). Um ID snowflake do Twitter de 19 dígitos ou um ID de objeto Stripe acima desse limite será arredondado. Codifique inteiros grandes como strings, ou use um analisador que suporte BigInt.

Published May 31, 2026