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
- 401 vs 403
- Exemplos de página 404
- Exemplos e modelos de e-mail de carrinho abandonado
- SMS de carrinho abandonado
- Exemplos de Página Sobre Nós
- Como receber pagamentos em um site
- Processo de testes de acessibilidade para equipes web
- Alternativas acessíveis ao PDF em sites públicos
Produto
Para quem é
- Para agências
- Para freelancers
- Para provedores de hospedagem
- Para plataformas SaaS
- Para startups
- Serviços financeiros
- Soluções para saúde
Recursos
Recursos
- Blog
- Central de Ajuda
- Ferramentas gratuitas para empresas
- Free UI Components
- Modelos
- Coleções de modelos
- Exemplos de sites
- Guias
- Comparações
- Alternativas
- Os melhores
- Avaliações
- Guias de preços
- Casos de uso
- Glossário e guias
- Integrações
- Desenvolvedores
- Benchmark
- Windows App