Os mesmos dados nos dois formatos
Aqui está uma configuração pequena em JSON: {"name": "shop", "port": 8080, "debug": false, "hosts": ["a.example.com", "b.example.com"]}. Em YAML, os mesmos dados são escritos com indentação em vez de chaves: name: shop numa linha, port: 8080 na seguinte, debug: false, e hosts: seguido de duas linhas indentadas que começam com hífen.
Os dois viram exatamente o mesmo objeto em qualquer linguagem de programação. A diferença está em como são escritos e no que mais cada formato permite.
| JSON | YAML | |
|---|---|---|
| Estrutura | Chaves e colchetes | Indentação, ou chaves se você preferir |
| Texto | Sempre entre aspas duplas | Aspas quase sempre opcionais |
| Comentários | Não permitidos | Linhas que começam com # |
| Texto em várias linhas | Só com \n dentro de uma string | Blocos com | ou > |
| Reaproveitar partes | Não é possível | Âncoras (&nome) e aliases (*nome) |
| Vários documentos num arquivo | Não | Sim, separados por uma linha de três hífens |
| Uso típico | APIs, troca de dados, navegadores | Configuração: Docker Compose, Kubernetes, CI |
Experimente aqui: YAML para JSON
Abrir a página completa da ferramentaPor que o YAML é agradável de escrever
O YAML precisa de menos caracteres. Não há chaves de fechamento para contar, vírgulas para esquecer entre os itens nem aspas na maior parte do texto. Os comentários permitem explicar por que uma configuração existe, e é por isso que ferramentas que as pessoas editam todo dia, como Docker Compose, Kubernetes, GitHub Actions e Ansible, escolheram o YAML.
As âncoras evitam repetição: você define um bloco uma vez com &defaults e reaproveita com *defaults, ou mescla esse bloco em outro com <<: *defaults e sobrescreve só algumas chaves. Os blocos de texto mantêm as quebras de linha, o que deixa scripts e mensagens longas legíveis dentro do arquivo.
Armadilhas do YAML que mudam os seus dados
A liberdade de deixar as aspas de fora tem um preço: o YAML adivinha o tipo de cada valor sem aspas, e o palpite nem sempre é o que você queria. A maioria desses problemas some quando o texto fica entre aspas.
- O problema da Noruega: no YAML 1.1, que muitas ferramentas ainda usam, NO, no, yes, on e off são booleanos. Uma lista de códigos de país com NO para a Noruega vira false.
- Números de versão: 1.10 é o número 1.1, e 3.0 pode virar 3. Escreva "1.10" para manter como texto.
- Zeros à esquerda: CEPs e códigos de produto como 0123 podem virar números, e o YAML 1.1 lê esses valores como octal, então 0123 vira 83.
- Horários: no YAML 1.1, 12:30 é um número em base 60, 750.
- Dois pontos e cerquilha: um valor que contém ": " ou " #" termina antes da hora ou começa um comentário. Coloque esse texto entre aspas.
- Tabulações: o YAML não permite tabulação na indentação, e uma chave indentada com um espaço a mais vai parar no bloco errado sem nenhum erro em alguns editores.
Por que o JSON é melhor para programas
O JSON tem um só jeito de escrever cada coisa e não adivinha nada: texto sempre fica entre aspas, então "NO" continua texto e 1.10 é claramente um número. Os parsers são pequenos, rápidos e existem em todas as linguagens, e os navegadores leem JSON nativamente. Isso faz do JSON a escolha mais segura sempre que os dados são produzidos e lidos por software, como respostas de API, logs, caches e arquivos de dados.
A falta de comentários é a reclamação mais comum. Algumas ferramentas aceitam JSON com comentários (muitas vezes chamado de JSONC), mas os parsers padrão rejeitam, então não é um bom formato para arquivos que outros programas precisam ler.
Como converter entre YAML e JSON com segurança
O YAML 1.2 foi projetado como um superconjunto do JSON, então quase todo documento JSON também é YAML válido. A direção contrária precisa de um parser de verdade, porque os recursos do YAML precisam ser resolvidos: âncoras e merge keys são expandidas, blocos de texto viram uma string com \n e vários documentos viram uma lista. Os comentários não podem ser levados junto, já que o JSON não tem lugar para eles.
Quando você converte JSON para YAML, todo valor que um leitor de YAML poderia interpretar errado precisa ficar entre aspas. O conversor desta página confere cada texto pelas regras do YAML 1.1 e do YAML 1.2 e só coloca aspas quando é necessário, então yes, NO, 0123 e 1.10 voltam sem mudança. Converter o resultado de volta com Inverter é um jeito rápido de provar que nada mudou.
Qual usar?
- Use YAML para configuração que as pessoas escrevem e revisam à mão, principalmente quando os comentários ajudam.
- Use JSON para dados que programas trocam, guardam ou enviam pela rede.
- Use JSON quando o arquivo é gerado por código, mesmo que uma pessoa leia depois.
- Se uma ferramenta aceita os dois, como muitas aceitam, mantenha o formato que a sua equipe já usa: a consistência importa mais que as pequenas diferenças.
- Se ficar com o YAML, coloque entre aspas os textos que parecem números, datas ou yes/no, e confira os arquivos com um parser antes do deploy.