YAML vs JSON: qual usar e por quê

YAML vs JSON

YAML vs JSON: diferenças, armadilhas e .yaml vs .yml | We.Inc

YAML vs JSON lado a lado: sintaxe, comentários, tipos, texto em várias linhas e a armadilha do yes/no. Teste como um valor sem aspas é lido e resolva de vez .yaml vs .yml.

JSON é um formato de dados rígido feito para programas: chaves, colchetes, strings entre aspas duplas e nada de comentários. YAML expressa os mesmos dados com indentação, aceita comentários e texto em várias linhas, e a versão 1.2 foi projetada como um superset de JSON. Escolha JSON para APIs e saída de máquina, YAML para arquivos que pessoas editam à mão.

YAML e JSON comparados recurso por recurso

  • Recurso
  • JSON
  • YAML 1.2
  • Estrutura
  • Chaves e colchetes
  • Indentação (só espaços) ou estilo flow como em JSON
  • Comentários
  • Não permitidos
  • Strings
  • Sempre entre aspas duplas
  • Simples, entre aspas simples ou entre aspas duplas
  • Texto em várias linhas
  • \n escapado dentro de uma string
  • Block scalars com | ou >
  • Reutilizar um valor
  • Não
  • Anchors (&) e aliases (*)
  • Vários documentos em um arquivo
  • Não
  • Sim, separados por ---
  • Media type
  • application/json
  • application/yaml

Os dois formatos descrevem as mesmas coisas: mapas, listas, strings, números, booleanos e null. As diferenças reais são quem lê o arquivo e o quanto o parser é tolerante. Use o verificador de valores abaixo para ver como um valor sem aspas recebe um tipo, depois leia os exemplos lado a lado e as armadilhas que pegam quem transita entre os dois.

  • Digite um valor solto, como yes, 0x1F, 1e3 ou ~, no verificador de valores.
  • Veja como um parser YAML 1.2 define o tipo, o que um parser YAML 1.1 mais antigo pode fazer de diferente e se o JSON aceita o valor como está.
  • Compare o mesmo registro escrito dos dois jeitos nos exemplos mais abaixo.
  • Coloque entre aspas qualquer valor cujo tipo surpreendeu você e mantenha esse hábito nos seus arquivos de configuração.
  • Indente YAML com espaços. A especificação proíbe tabs na indentação, e a maioria dos erros de parse em arquivos editados à mão vem de um tab perdido.
  • Coloque entre aspas códigos de país, números de versão e qualquer coisa como yes, no, on ou off. Alguns parsers ainda seguem as regras do YAML 1.1 e os transformam em booleanos.
  • Se uma ferramenta aceita os dois formatos, gere JSON a partir do código e deixe YAML para os arquivos que pessoas mantêm.
  • Valide os dois: passe o JSON por um formatador e carregue o YAML com a mesma biblioteca que o seu app usa, já que os parsers diferem nos casos-limite.

Perguntas frequentes

Todo arquivo JSON é YAML válido?

O YAML 1.2 foi escrito para ser um superset estrito de JSON, então na prática um documento JSON carrega em um parser YAML 1.2. Existem casos-limite, como chaves duplicadas, que parsers JSON muitas vezes toleram mas o YAML proíbe.

Devo usar .yaml ou .yml?

Use .yaml. A RFC 9512, que registra o media type application/yaml, chama .yaml de extensão preferida e observa que .yml ainda é usada. As duas funcionam em ferramentas como o GitHub Actions, então a escolha é uma questão de consistência dentro de um projeto.

Por que meu valor YAML virou true ou false?

O YAML 1.1 tratava palavras como yes, no, on, off, y e n como booleanos. O core schema do YAML 1.2 só aceita true e false em três formas de maiúsculas e minúsculas, mas parsers antigos ainda são comuns. Colocar o valor entre aspas acaba com a dúvida.

JSON pode ter comentários?

Não. A RFC 8259 lista os tokens que um JSON pode conter, e comentários não estão entre eles. Algumas ferramentas aceitam um JSON relaxado com comentários, mas um parser estrito vai rejeitar o arquivo.

Qual dos dois é mais rápido de interpretar?

A gramática do JSON é bem menor, e os navegadores trazem um parser nativo para ele, então costuma ser a opção mais rápida e segura para dados enviados pela rede. Parsers YAML têm muito mais regras a aplicar, da indentação à tipagem implícita.

Quando JSON é a melhor escolha

  • APIs, armazenamento no navegador, logs e tudo o que um programa escreve para outro programa ler. A gramática é mínima, toda linguagem tem um parser estrito e só existe um jeito de escrever cada valor, então os diffs ficam previsíveis.
  • JSON também não tem tipagem implícita. Uma string é uma string porque tem aspas, o que elimina toda uma categoria de surpresas.

Quando YAML é a melhor escolha

  • Configuração que pessoas leem e editam: workflows de CI, setups de containers, front matter de sites e manifestos de deploy. Comentários permitem explicar por que uma configuração existe, e block scalars mantêm scripts de shell e mensagens longas legíveis.
  • O custo é que os espaços em branco têm significado e valores sem aspas são adivinhados. Mantenha os arquivos curtos, coloque entre aspas tudo o que for ambíguo e rode um linter no CI.

Um registro, escrito dos dois jeitos

As mesmas configurações de site nos dois formatos. O YAML dispensa aspas e chaves e acrescenta um comentário; o JSON escreve por extenso cada string e cada nível de aninhamento.

Indentação de dois espaços, um comentário, uma lista e uma string de versão entre aspas para continuar sendo texto.

Nenhum comentário é possível, e toda chave e string leva aspas duplas.

Valores que mudam de tipo quando você esquece as aspas

Como um valor YAML sem aspas recebe um tipo, e a versão segura

  • Você escreveu
  • O core schema do YAML 1.2 lê
  • Mais seguro
  • version: 2.10
  • float 2.1 (o zero final se perde)
  • version: "2.10"
  • country: NO
  • string no 1.2, booleano false no 1.1
  • country: "NO"
  • port: 0x1F90
  • inteiro 8080
  • port: 8080
  • mode: 0o755
  • inteiro 493
  • mode: "0o755"
  • value: ~
  • value: null
  • ratio: .inf
  • float infinito (sem forma em JSON)
  • ratio: "inf"

Como este valor sem aspas será lido?

Digite um valor do jeito que ele apareceria depois dos dois-pontos em um arquivo YAML, sem aspas. O verificador aplica as regras do core schema do YAML 1.2, a lista de booleanos do YAML 1.1 e a gramática do JSON.

Valor sem aspas

Core schema do YAML 1.2

Parsers YAML 1.1

JSON, escrito como está

O mesmo valor em JSON

booleano {v} (o YAML 1.1 lê esta palavra como booleano)

Sem armadilha de booleano estilo yes/no para este valor

Valor JSON válido

Não é JSON válido sem aspas

O JSON não tem como escrever este número

Experimente um

Crie seu site grátis · Grátis para criar, sem cartão

Relacionados: Guias

Produto

Para quem é

Recursos

Recursos

Empresa

Mapa do site