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