Formatador YAML

YAML é sensível a espaços em branco, o que o torna agradável de ler e implacável de editar. A ferramenta acima faz três coisas: deixa seu YAML em uma forma canônica, converte-o para JSON e converte JSON de volta para YAML. Tudo acontece no seu navegador, então um manifesto do Kubernetes ou um arquivo de CI com segredos nunca sai da sua máquina.

Como funciona

Escolha um modo, cole o documento e selecione uma indentação de 2 ou 4 espaços.

• Formatar YAML faz o parsing do documento e o serializa de novo. Isso normaliza a indentação, as aspas e o estilo das listas, e reduz as várias formas de escrever o mesmo valor a uma só.
• YAML → JSON faz o parsing do YAML e gera JSON com a indentação escolhida. É útil para entregar um arquivo de configuração a algo que só entende JSON, e para ver exatamente o que um parser acha que o seu YAML significa.
• JSON → YAML faz o caminho inverso, e é o jeito mais rápido de tornar revisável, em um pull request, um bloco de JSON gerado.

O parsing usa um parser YAML 1.2 aderente à especificação, então os erros chegam como mensagens reais do parser, com linha e coluna, em vez de um genérico "entrada inválida". Esse texto de erro muitas vezes é a saída mais útil que a ferramenta produz.

Observe que a formatação é uma ida e volta pelo modelo de dados, não uma transformação de texto. Isso tem uma consequência que vale conhecer desde já: os comentários são descartados. Se os comentários do seu arquivo importam (e, em um arquivo de Kubernetes ou de CI, geralmente importam), use o modo de formatação para conferir a estrutura e depois aplique as correções à mão no original.

As armadilhas do YAML

A indentação precisa ser feita com espaços. Tabs são proibidos na indentação YAML, ponto final. Um editor configurado para inserir tabs gera um arquivo que falha no parsing, com um erro que aponta para o lugar errado.

O problema da Noruega. O YAML 1.1 tratava yes, no, on, off, y e n como booleanos, então uma lista de países contendo NO virava false. O YAML 1.2 removeu isso, mas muitos parsers em produção ainda implementam o comportamento do 1.1. Coloque escalares ambíguos entre aspas: "NO", "on", "1.0".

Números de versão sem aspas. 1.0 é um float, 1.10 é o float 1.1 e 1.0.0 é uma string. Tags de imagem e versões fixadas devem sempre ficar entre aspas.

Zeros à esquerda. Em parsers mais antigos, 08 pode ser lido como um octal inválido; "08" é seguro. O mesmo vale para qualquer coisa que pareça número mas seja um identificador: números de telefone, CEPs, referências de conta.

Chaves duplicadas. A especificação diz que são inválidas, mas muitos parsers ficam com a última sem avisar. Em um arquivo longo, uma chave repetida é um defeito que nenhuma mensagem de erro vai apontar.

Passar um arquivo pelo YAML → JSON responde a todas essas dúvidas de uma vez, porque JSON não tem ambiguidade: o que aparece como true ou 1.1 na saída JSON é exatamente o que o seu parser enxergou.

YAML ou JSON?

Os dois expressam o mesmo modelo de dados, então a escolha depende de quem vai ler. YAML é para arquivos que pessoas escrevem e revisam: comentários, escalares em bloco e âncoras existem para isso. JSON é para máquinas: sem comentários, sem ambiguidade, uma única forma de escrever cada valor e um parser em toda linguagem. Todo documento JSON é YAML 1.2 válido, e é por isso que a conversão desta ferramenta não perde nada nessa direção e, na outra, preserva apenas a estrutura.

Onde ele aparece

YAML é a linguagem de configuração do mundo dos contêineres e da CI, e na maioria das vezes em que você esbarra nele está depurando um problema de indentação no arquivo de outra pessoa. Redes e volumes no Docker Compose percorre a estrutura de um arquivo Compose, Fundamentos de Kubernetes cobre manifestos e o modelo de apply, e Pipelines do Jenkins e o Jenkinsfile trata da definição de pipelines. No lado da aplicação, Starters, propriedades e perfis explica como o application.yml é resolvido e sobrescrito.

Para JSON puro, o formatador de JSON é a ferramenta mais direta; para marcação, o formatador de HTML.