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

YAML vs JSON, em resumo: ambos são formatos de texto para os mesmos dados (objetos, listas, strings, números, booleanos e null). JSON é estrito, usa chaves e aspas e é o padrão das APIs web. YAML usa indentação, aceita comentários, âncoras e vários documentos por arquivo, e é popular para configuração. YAML 1.2 é quase um superconjunto do JSON.

Experimente grátis: Conversor de YAML para JSON Gratuito e sem necessidade de conta.

O JSON (JavaScript Object Notation, definido na RFC 8259) foi criado para programas trocarem dados. Então, o que é YAML? O nome significa "YAML Ain't Markup Language", e ele foi criado para pessoas lerem e editarem dados à mão. Este guia mostra os mesmos dados nos dois formatos, compara os dois e explica as armadilhas de cada um. Para ver como qualquer arquivo fica no outro formato, cole-o no conversor de YAML para JSON gratuito ou no conversor de JSON para YAML.

Os mesmos dados em JSON e em YAML

Esta é uma pequena configuração de aplicação em JSON:

{
  "name": "web-app",
  "version": "2.4.1",
  "replicas": 3,
  "debug": false,
  "database": {
    "host": "db.example.com",
    "port": 5432
  },
  "features": ["login", "search"],
  "maintainer": null
}

E os mesmos dados em YAML, com um comentário a mais, algo que o JSON não consegue guardar:

# Settings for the web app
name: web-app
version: 2.4.1
replicas: 3
debug: false
database:
  host: db.example.com
  port: 5432
features:
  - login
  - search
maintainer: null

Os dois resultam exatamente no mesmo objeto após o parsing. O JSON marca a estrutura com {}, [], vírgulas e aspas; o YAML a marca com indentação, pares key: value e - para os itens de lista. A maioria das strings em YAML dispensa aspas, e é por isso que ele se parece mais com um arquivo de configurações do que com código.

YAML vs JSON: principais diferenças

Alguns formatos aceitam os dois: descrições OpenAPI podem ser escritas em qualquer um deles, e o kubectl apply lê manifestos JSON além dos YAML. Em geral, o JSON leva vantagem quando programas escrevem e leem os dados; o YAML leva vantagem quando pessoas os mantêm à mão e precisam de comentários.

YAML é um superconjunto de JSON?

Quase. A especificação YAML 1.2 (2009) teve como objetivo tornar o YAML um superconjunto estrito do JSON e, na prática, um parser de YAML 1.2 lê quase qualquer documento JSON e retorna os mesmos dados. Há duas ressalvas:

• Chaves duplicadas. A RFC 8259 só diz que as chaves de um objeto deveriam ser únicas, mas o YAML exige isso, então {"a": 1, "a": 2} é rejeitado por um parser YAML estrito.
• Parsers de YAML 1.1. Muitas bibliotecas amplamente usadas ainda seguem as regras antigas do YAML 1.1. O PyYAML, por exemplo, só reconhece floats que contêm um ponto, então o número JSON 1e3 volta como a string "1e3".

O contrário não vale: a maior parte do YAML não é JSON válido.

Armadilhas do YAML que você precisa conhecer

O problema da Noruega (Norway problem): NO vira false

No YAML 1.1, as palavras sem aspas yes, no, on e off (em minúsculas, com inicial maiúscula ou em maiúsculas) são booleanos, junto com true e false. Assim, esta lista de códigos de país:

countries:
  - GB
  - NO
  - SE

é carregada como ["GB", false, "SE"] por um parser de YAML 1.1 como o PyYAML. A mesma regra transforma a chave on: de um workflow do GitHub Actions no booleano True quando você carrega o arquivo com o PyYAML. O schema core do YAML 1.2 corrigiu isso: só true e false (também escritos True ou TRUE) são booleanos, então um parser 1.2 mantém NO como string. Como raramente você controla qual parser vai ler o seu arquivo, o hábito mais seguro é colocar esses valores entre aspas: - "NO".

Números que não deveriam ser números

• Zeros à esquerda. O YAML 1.1 lê 0755 como um número octal, 493. O YAML 1.2 o lê como o decimal 755 e escreve octais como 0o755. Um código postal como 01234 vira 668 ou 1234, dependendo do parser. Coloque entre aspas.
• Números de versão. python-version: 3.10 é o float 3.1, e não "3.10". Escreva "3.10".
• Zeros à direita. 1.0 é um float, então vira 1 quando convertido para JSON em JavaScript.

Tabs e espaços significativos

A especificação do YAML proíbe caracteres de tab na indentação, então um tab no início de uma linha é um erro de sintaxe, e não uma questão de estilo. A indentação também tem significado: mover uma chave dois espaços para a esquerda a leva para outro objeto pai, e o arquivo pode continuar perfeitamente válido enquanto passa a significar outra coisa.

Strings multilinha: | e >

Um bloco literal (|) mantém as quebras de linha; um bloco dobrado (>) junta as linhas com espaços:

literal: |
  Line one
  Line two
folded: >
  This long sentence is
  folded into one line.

literal vira "Line one\nLine two\n" e folded vira "This long sentence is folded into one line.\n". Os dois mantêm uma quebra de linha final; escreva |- ou >- para removê-la.

Âncoras, aliases e merge keys

O YAML permite definir um bloco uma vez e reutilizá-lo:

defaults: &defaults
  adapter: postgres
  port: 5432
production:
  <<: *defaults
  host: db.example.com

&defaults dá nome ao bloco, *defaults faz referência a ele e << mescla as suas chaves, então production acaba com adapter, port e host. O JSON não tem equivalente: ao converter para JSON, os valores são copiados para cada lugar onde são usados. As merge keys vêm do YAML 1.1 e não fazem parte do schema core do 1.2, mas a maioria dos parsers mais usados ainda as suporta.

Armadilhas do JSON que você precisa conhecer

O JSON é estrito, e três regras causam a maioria dos erros:

• Sem comentários. // e /* */ são erros de sintaxe.
• Sem vírgulas finais. ["a", "b",] é inválido.
• Só aspas duplas. As chaves precisam estar entre aspas, e aspas simples não são permitidas.

Por isso, este arquivo falha com JSON.parse:

{
  // port for local development
  'port': 8080,
  "tags": ["api", "v2",],
}

Para arquivos escritos à mão, existem variantes mais flexíveis: o JSONC ("JSON with comments") é usado nas configurações do VS Code e no tsconfig.json, e o JSON5 também permite aspas simples, chaves sem aspas e vírgulas finais. Nenhum dos dois é aceito por um parser JSON padrão. O formatador JSON aceita entrada em JSON5, marca-a como "JSON5 válido — convertido para JSON estrito" e devolve JSON padrão.

.yaml vs .yml

YAML vs YML não é uma questão de formato: as duas extensões indicam o mesmo formato, e os parsers não se importam com qual você usa. A RFC 9512, que registrou o media type application/yaml em 2024, define .yaml como a extensão preferida e observa que .yml ainda é usada. O FAQ do projeto YAML também recomendava .yaml, e o Docker Compose procura compose.yaml antes de compose.yml. O GitHub Actions aceita as duas em .github/workflows. Escolha uma por projeto e não mantenha config.yaml e config.yml lado a lado.

Segurança: carregue YAML não confiável com segurança

Loaders YAML completos podem construir objetos específicos da linguagem a partir de tags. Em Python, yaml.load(data, Loader=yaml.UnsafeLoader) pode criar objetos Python arbitrários e, com um arquivo malicioso, executar código. Use sempre yaml.safe_load() para arquivos que você não escreveu; ele só constrói dicts, listas, strings, números, booleanos e null simples. Desde o PyYAML 6.0, yaml.load() se recusa a rodar sem um Loader explícito. Tome cuidado também com aliases profundamente aninhados (arquivos "billion laughs") que se expandem em estruturas enormes. O JSON não tem tags nem aliases, então JSON.parse e o json.loads do Python sempre retornam apenas dados simples.

Conversão entre YAML e JSON

Os dois conversores rodam inteiramente no seu navegador e usam a biblioteca open source yaml para JavaScript.

O conversor de YAML para JSON faz o parsing de YAML 1.2, expande âncoras e aliases, aplica merge keys << e transforma um arquivo com vários documentos --- em um array JSON. Você pode escolher 2, 3 (o padrão) ou 4 espaços, tabs ou saída minificada, ordenar as chaves em ordem alfabética e baixar o resultado como converted.json. Erros de sintaxe, como um tab usado na indentação, são exibidos com a linha e a coluna. Os comentários se perdem, porque o JSON não consegue armazená-los.

O conversor de JSON para YAML lê JSON padrão e JSON5, então comentários e vírgulas finais na entrada são aceitos, mas não são levados para a saída. Ele gera YAML com indentação de dois espaços e não tem opções. A saída segue o YAML 1.2: strings como "0755" e "true" ficam entre aspas, mas NO, yes ou on ficam sem aspas, porque no 1.2 são strings comuns. Se uma ferramenta de YAML 1.1 como o PyYAML for ler o arquivo, adicione você mesmo as aspas a esses valores.

Na linha de comando, o yq de Mike Farah converte nas duas direções, e o jq valida e formata JSON:

yq -o json config.yaml
yq -P -oy config.json
jq . config.json

Quando usar YAML e quando usar JSON

A escolha entre JSON vs YAML geralmente depende de quem escreve o arquivo:

• Use JSON para dados que programas trocam entre si: requisições e respostas de API, mensagens entre serviços, logs, armazenamento do navegador e tudo o que for gerado por código. Ele não tem ambiguidades e é suportado em todo lugar.
• Use YAML para configurações que pessoas editam e revisam: manifestos de deploy, pipelines de CI, arquivos do Compose. Comentários e uma sintaxe mais leve deixam os diffs mais fáceis de ler.
• Siga a ferramenta. Se uma plataforma espera YAML (GitHub Actions) ou JSON (package.json), use esse formato em vez de converter.

Se escolher YAML, mantenha tudo sem surpresas: indentação de dois espaços, aspas em tudo o que possa ser lido como booleano ou número e um linter como o yamllint no CI.

Perguntas frequentes

YAML é melhor que JSON?

Nenhum dos dois é melhor em geral. O JSON é mais simples e mais estrito, o que o torna a escolha mais segura para dados trocados entre programas. O YAML é mais fácil de ler e editar para pessoas e aceita comentários, e é por isso que tantos arquivos de configuração o usam.

Posso usar JSON dentro de um arquivo YAML?

Sim. O flow style do YAML usa os mesmos colchetes e chaves do JSON, então ports: [80, 443] ou db: {"host": "localhost"} funcionam dentro de um arquivo YAML, e um parser de YAML 1.2 aceita quase qualquer documento JSON completo. Chaves duplicadas são a principal exceção.

JSON pode ter comentários?

Não no JSON padrão: a RFC 8259 não tem sintaxe de comentários, e JSON.parse falha com // ou /* */. Algumas ferramentas aceitam JSONC ou JSON5, que permitem comentários, mas você precisa removê-los antes de passar o arquivo para um parser estrito.

Qual é a diferença entre YAML e YML?

No conteúdo, nenhuma: .yaml e .yml são duas extensões de arquivo para o mesmo formato. A RFC 9512 indica .yaml como a preferida, mas os parsers de YAML não se importam com a extensão.

Por que o YAML transforma NO ou on em false ou true?

Porque o YAML 1.1 trata yes, no, on e off como booleanos. O YAML 1.2 só trata true e false como booleanos, mas muitos parsers, incluindo o PyYAML, ainda usam as regras do 1.1. Coloque esses valores entre aspas, por exemplo country: "NO", e todo parser vai lê-los como strings.

Experimente grátis: Conversor de YAML para JSON Gratuito e sem necessidade de conta.