O que é um arquivo YAML?

YAML é um formato de texto puro que abre em qualquer editor. Ele é usado para mover dados entre programas e a edição.

A extensão é .yaml e o nome por extenso é YAML Ain't Markup Language. Os dois importam menos do que aquilo que o arquivo consegue carregar, e é disso que trata o resto desta página.

Ele remonta a 2001. A especificação é YAML 1.2.

A idade interessa por um motivo prático: quanto mais antigo o formato, mais programas tiveram tempo de aprendê-lo.

Ela está publicada por inteiro, então dá para implementá-la a partir do documento em vez de por observação — é por isso que o formato aparece em tantos programas e por isso que arquivos escritos há vinte anos ainda abrem. Especificação publicada não é o mesmo que livre de royalties: quando o formato embrulha um codec, o licenciamento das patentes é uma questão à parte, que a norma não resolve.

YAML guarda o conteúdo exatamente. Salvar de novo não muda nada, então dá para abrir, editar e salvar quantas vezes você quiser sem acumular estrago — e é isso que faz dele um formato de trabalho e não de entrega.

YAML tem sintaxe de comentário — essa é a diferença entre um arquivo que uma pessoa mantém e um que um programa escreve. Os comentários são a primeira coisa perdida na conversão para um formato que não os tem, e nada avisa.

Visual Studio Code e yq leem esse formato, e a maioria dos programas do mesmo tipo também.

Quando um arquivo não abre, o formato raramente é o problema — mais comum é o programa ser mais antigo que ele. Converter para algo mais antigo é o caminho confiável, e é para isso que serve o resto deste site.

Nenhum navegador lê o formato.

Esse é de longe o motivo mais comum para convertê-lo: não que o formato seja ruim, mas que o lugar onde você quer mostrar o arquivo não consegue lê-lo.

YAML foi feito para ser aberto e alterado. Mantenha o arquivo nesse formato enquanto o trabalho estiver em andamento e exporte a partir dele sempre que precisar de uma cópia pronta.

Pouquíssima gente escolhe YAML. É entregue: manifesto do Kubernetes, pipeline de integração contínua, script de automação de infraestrutura, Docker Compose, especificação de API, metadado de site estático. Todos esses se firmaram nele, e o ecossistema ao redor é grande o bastante para que o formato deixe de ser uma decisão que alguém possa revisitar.

Isso molda o que uma página útil sobre o formato precisa fazer. A pergunta raramente é se vale usar YAML — é como evitar os jeitos específicos de dar errado, porque ele falha em silêncio mais que qualquer outro formato de configuração de uso comum.

Não há colchete e não há marcador de fechamento. O quanto uma linha está recuada determina a que ela pertence, então um espaço fora do lugar muda o significado do documento — e frequentemente produz um documento ainda válido, só diferente do que você queria dizer.

Duas regras evitam a maior parte disso. Nunca use tabulação: a especificação proíbe, e um editor que insere uma produz um erro de interpretação cuja mensagem raramente explica isso claramente. E mantenha a indentação consistente, dois espaços por nível por convenção, porque misturar larguras dentro de um arquivo é legal e torna a estrutura impossível de ler de relance.

O YAML tenta adivinhar o que um valor solto é, e esses palpites já causaram falha real em produção. A mais famosa é o problema da Noruega: na versão 1.1 do YAML, um "no" sem aspas é o booleano falso, então uma lista de códigos de país transforma a sigla de um país em falso. O mesmo acontece com "sim", "não", "y" e "n".

Número de versão é a segunda armadilha: "1.20" vira o decimal 1.2, e o zero à direita some. Horário é a terceira: um valor como "22:30" pode ser lido como um número em base sessenta em vez de uma string. E um valor como "0755" pode ser lido como número octal.

A defesa é um hábito, não conhecimento: coloque entre aspas tudo que deveria ser texto. Número de versão, código de país, identificador, horário, qualquer coisa com zero à esquerda. A versão 1.2 do YAML corrigiu várias dessas armadilhas, e muito interpretador por aí ainda implementa a 1.1, então o hábito é o que protege, não a especificação.

O YAML consegue definir um bloco uma vez e reutilizar. Uma âncora marca ele, um alias se refere a ele, e uma chave de mesclagem dobra um bloco compartilhado em vários lugares — é assim que um pipeline de integração contínua evita repetir as mesmas seis linhas em cada tarefa.

É genuinamente útil e é onde o YAML deixa de ser legível para quem nunca viu essa sintaxe antes. Duas cautelas práticas: um alias é uma referência, não uma cópia, então o que é compartilhado é de fato compartilhado; e várias ferramentas que consomem YAML não implementam âncora nenhuma, ou expandem de um jeito surpreendente. Confira antes de construir uma configuração grande em cima disso.

Um bloco escrito com uma barra vertical mantém as quebras de linha: certo para um script, um certificado, uma mensagem com parágrafos. Escrito com um sinal de maior dobra as linhas numa só, certo para uma frase longa quebrada só por legibilidade no arquivo.

Cada um aceita um sufixo controlando a quebra final — um sinal de menos remove, um sinal de mais mantém todas as finais. Isso importa bem mais do que parece quando o valor é uma chave, um token ou um script: uma quebra de linha final inesperada é o motivo clássico de um certificado ser rejeitado ou um comando se comportar diferente num pipeline do que na sua máquina.

Três hífens sozinhos numa linha começam um documento novo, então um único arquivo pode guardar uma sequência deles. O Kubernetes usa isso o tempo todo — uma implantação, um serviço e um mapa de configuração num arquivo só — e toda ferramenta que lê isso espera essa separação.

Vale saber porque muda o que "interpretar este arquivo" significa. Um interpretador que lê um documento só ignora silenciosamente tudo depois do primeiro separador, o jeito de metade de uma configuração sumir sem erro nenhum. A função correspondente costuma ter um nome indicando que carrega todos os documentos, não um só.

Todo documento JSON é YAML válido, já que o YAML 1.2 foi definido como um superconjunto. Então converter JSON para YAML é trivial e principalmente cosmético — o resultado é o mesmo dado, mais fácil de ler e agora capaz de carregar comentário.

A outra direção perde coisas que o JSON não tem onde colocar: comentário, âncora, e a distinção entre os vários jeitos de escrever uma string de várias linhas. Fazer um manifesto do Kubernetes ir e voltar pelo JSON, portanto, remove todo comentário explicativo dele, o tipo de perda que ninguém percebe até voltar ao arquivo seis meses depois.

Use um editor com modo YAML. Ele vai mostrar guia de indentação, converter tabulação, e sinalizar um erro de estrutura no lugar em vez de deixar um pipeline achar isso depois. Para qualquer coisa indo para um repositório, um verificador automático no momento do commit vale os dez minutos que leva para configurar.

E valide antes de publicar quando existe um esquema. Kubernetes, especificação de API e a maioria dos sistemas de integração contínua publicam um, e uma checagem de validação pega a chave fora do lugar que um interpretador aceita de bom grado e o sistema rejeita às três da manhã.