YAML é uma linguagem usada por diversas tecnologias, geralmente para escrever arquivos de configuração. Por exemplo, você pode usar YAML para:

• Criar recursos no Kubernetes [2];
• Fazer pipelines de integração contínua (IC) e entrega contínua (EC) no GitHub Actions [3];
• Escrever playbooks no Ansible [4];
• Criar pipelines de IC e EC no Azure DevOps.

Durante seu surgimento, YAML era um acrônimo para “Yet Another Markup Language” (“Mais uma linguagem de marcação”) [5]. Conforme a linguagem se desenvolveu, seus autores (Oren Ben-Kiki, Clark Evans, Ingy döt Net) notaram que ela se aproximava mais de uma linguagem de serialização. Dessa forma, o nome YAML foi transformado no acrônimo recursivo “YAML Ain’t Markup Language” (“YAML não é uma linguagem de marcação”).

Com esse artigo, pretende-se olhar a superfície da gramática, para que o leitor se familiarize e possa escrever, por exemplo, pipelines para o Azure DevOps e GitHub com fluência.

Visão Geral

YAML é uma linguagem de serialização de dados com a proposta de ser de fácil escrita e leitura por humanos. Essa linguagem buscar ser sucinta, minimizando o uso de caracteres de estrutura para que os dados se destaquem. Em sua versão 1.2, ela se apresenta como um superconjunto da linguagem JSON (ou seja, todo texto em JSON é um YAML, mas nem todo texto em YAML é um JSON), mas é mais conhecida pelo uso da indentação como estruturação, dois pontos para separar chave de valor e hífen para a criação de listas. [1]

A linguagem YAML foi pensada para armazenar e transferir dados, atendendo aos seguintes casos de uso:

• Arquivos de configuração;
• Arquivos de log;
• Mensagens entre processos;
• Compartilhamento de dados entre diferentes linguagens de programação;
• Persistência de objetos;
• Análise de estruturas de dados complexas.

Tipos Primitivos

São definidos três tipos primitivos:

Escalares (scalars): números e strings. Qualquer caractere ou sequência de caracteres Unicode válidos (printable Unicode characters) é um escalar, por exemplo:

Com esses três tipos, podemos criar algumas estruturas de exemplo:

Sequência de escalares, exemplo com nomes de estados brasileiros:

– Amazonas
– São Paulo
– Pará
– Mato Grosso

Exemplo de mapeamento de um escalar para outro escalar, com número de gols feitos pela seleção brasileira:

Gols Marta : 117
Gols Pelé : 77
Gols Neymar : 70
Gols Ronaldo : 62

Exemplo mapeando sequência para um escalar:

Jogadores Brasileiros:
– Rivaldo
– Romário
– Ronaldo
Jogadores Holandeses:
– Dennis Bergkamp
– Johan Cruyff
– Clarence Seedorf

Exemplo de sequência de mapeamentos:

–  nome : Pelé
  média de gols :  0.84
–  nome : Marta
  média de gols :  0.68

Comentários

YAML aceita o uso de comentários com o caractere “#”, veja exemplo abaixo:

Aliases e Âncoras

Quando é feito o uso repetido de um mesmo objeto, é uma opção utilizar âncoras e aliases, evitando repetição de código. Para definir uma âncora, utiliza-se o “&” e para fazer referência a ela, utiliza-se o “*”. No exemplo abaixo é criado uma âncora para Brasil, sempre que “*br” for referenciado, ele será substituído por “Brasil”.

jogador1:
– país: &br Brasil
– nome: Rivaldo
jogador2:
– país: *br
– nome: Ronaldo

Quebra de linha em escalares

Por padrão, ao escrever um escalar, as quebras de linhas se tornarão espaços. Entretanto é possível respeitar quebras de linha com o símbolo “|”, dessa forma, as quebras de linha não se tornarão espaços. Por exemplo (atenção aos espaços):

quebras viram espaços:
YAML é
um supersert de
JSON
quebras são respeitadas: |
YAML é
um supersert de
JSON

O objeto acima é equivalente a:

O objeto acima é uma sequência de dois mapeamentos, mapeando “oi” para “ela disse” e mapeando “bom dia” para “ela disse também”. No objeto abaixo as aspas serão usadas para transformar esse objeto em uma sequência de dois escalares “ela disse: oi” e “ela disse também: bom dia”:

– “ela disse: oi”
– “ela disse também: bom dia”

Validador de YAML no VS Code

Existe uma extensão no VS Code para validar seu e-mail, ela aponta erros de sintaxe e pode trazer gaho de produtividade. Para instalar, basta abrir o VS Code e ir na aba Extensões. Feito isso, procure por “docs-yaml” (Figura 1). Para instalar, clique em “Install.”

Com isso, crie um arquivo YAML e veja a extensão apontar erros na sintaxe (Figura 2):

Exemplo em pipeline do GitHub e uso dos espaços

É comum o uso da linguagem YAML é para descrever pipelines de integração e entrega contínua. Abaixo um exemplo de pipeline no GitHub Actions [3] para que seja feita sua análise quanto aos conceitos apresentados:

sses passos acima, quando executados pelo GitHub Actions, escreverão as mensagens no log (executando os comandos “echo”), farão checkout do repositório no qual se encontra o arquivo YAML e listarão todos os arquivos na raiz desse diretório. Para maiores informações, ver a referência [3].

Ainda no exemplo acima, é possível notar:

Mapeamento do escalar “GitHub Actions Demo” para o escalar “name”:

Uso do caractere “|” para preservar quebras de linha em escalares:

Mapeamento de uma sequência para o escalar “steps”:

No objeto acima os mapeamentos “steps” e “runs-on” estão sendo mapeados no escalar “Explore-GitHub-Actions”. Note como os espaços são usados para reforçar as relações entre os tipos primitivos. Nesse exemplo, retirado do GitHub, foram adicionados mais espaços do que o mínimo exigido pela sintaxe, ilustrando que existe flexibilidade na linguagem para melhorar a leitura. Veja abaixo o mesmo exemplo com apenas os espaços exigidos pela sintaxe.

Compare o primeiro exemplo com o segundo para ter uma ilustração da relação entre os espaços e a hierarquia dos objetos.

Conclusão

Quando se começa a trabalhar com YAML é comum ter alguma dificuldade com a sintaxe, principalmente no uso dos espaços. Espero que esse artigo tenha ajudado a entender um pouco mais sobre a gramática e assim aumentar a produtividade no uso do YAML. Além de dar uma ideia do poder e flexibilidade da linguagem, ajudando a entender sua popularidade.

Referências

 

[1]	C. E. I. d. N. Oren Ben-Kiki, “YAML Ain’t Markup Language (YAML™) version 1.2,” 1 10 2021. [Online]. Available: https://yaml.org/spec/1.2.2/. [Accessed 17 1 2022].
[2]	Kubernetes, “Managing Resources,” 10 8 2021. [Online]. Available: https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/. [Accessed 2022 1 20].
[3]	GitHub, “Início rápido para GitHub Actions,” GitHub, [Online]. Available: https://docs.github.com/pt/actions/quickstart. [Accessed 2022 1 18].
[4]	RedHat, “What is YAML?,” 18 6 2021. [Online]. Available: https://www.redhat.com/en/topics/automation/what-is-yaml. [Accessed 20 1 2022].
[5]	I. d. N. Clark Evans, “Stack Overflow – If YAML ain’t markup language, what is it?,” 6 8 2011. [Online]. Available: https://stackoverflow.com/questions/6968366/if-yaml-aint-markup-language-what-is-it. [Accessed 17 1 2022].