O que é YAML? Entendendo os conceitos básicos, a sintaxe e os casos de uso

Ao longo dos anos, trabalhei com inúmeros arquivos de configuração, e o YAML se destacou por sua simplicidade e legibilidade. Seja na configuração de fluxos de trabalho no Kubernetes, na definição de serviços no Docker ou na estruturação de solicitações de API, o YAML torna as configurações complexas mais gerenciáveis. Sua estrutura limpa e baseada em indentação elimina a desordem de formatos como XML, mantendo-se flexível.

Neste guia, mostrarei a sintaxe, a estrutura, os recursos avançados e as práticas recomendadas do YAML para que você possa trabalhar com ele com confiança. 

O que é YAML?

YAML (Yet Another Markup Language / YAML Ain't Markup Language) é um formato de serialização de dados que prioriza a legibilidade e a facilidade de uso. Enquanto o XML usa uma mistura de tags aninhadas semelhantes às do HTML e o JSON usa colchetes e aspas, como os dicionários do Python, o YAML é mais conciso e usa recuo para definir a estrutura, o que o torna mais amigável para o ser humano.

O YAML oferece suporte a vários tipos de dados, incluindo escalares (strings, números, booleanos), sequências (listas) e mapeamentos (pares de valores-chave). Ele é amplamente usado em arquivos de configuração, automação de infraestrutura e troca de dados, especialmente em ferramentas como Kubernetes, Docker e Ansible.

Além disso, o YAML é um superconjunto do JSON, o que significa que os arquivos JSON válidos podem ser analisados como YAML. Normalmente, os arquivos YAML têm uma extensão .yaml ou .yml.

Você também pode saber mais sobre o YAML em seu site !

Sintaxe e estrutura YAML

Esta seção explorará os princípios fundamentais da sintaxe YAML, incluindo pares de valores-chave, listas, dados aninhados e comentários.

Regras básicas de sintaxe

Existem algumas regras sintáticas básicas para o YAML: 

• O recuo de espaço denota estrutura, portanto, evite as tabulações! 
• Os pares chave-valor seguem uma estrutura key: value, semelhante a outras linguagens. 
• O uso de hífens no início das linhas denotará uma lista. 
• Ao usar #, você criará linhas de comentário.

# Here is an example of YAML
name: John Doe
age: 30
skills:
  - Python
  - YAML

Pares de valores-chave

O YAML representa os dados como pares de valores-chave, semelhante aos dicionários em Python. Isso geralmente denota informações fornecidas a diferentes arquivos de configuração e definições. Não há necessidade de denotar cadeias de caracteres ou chaves com aspas; basta escrever a chave e os valores necessários:

location: New York
country: USA
security-level: user

Listas em YAML

As listas são representadas com hífens (-). Isso permitirá que você liste vários objetos em uma única chave. Isso geralmente é representado visualmente com marcadores quando lido por editores de marcação.

fruits:
  - Apple
  - Banana
  - Cherry

Dados aninhados

As estruturas aninhadas permitem a representação hierárquica de dados usando indentação. Pense neles como dicionários aninhados. Ao usar a indentação, você indica quais teclas são subconjuntos de outras.

person:
  name: Alice
  details:
    age: 25
    city: London

Comentários

Os comentários começam com # e são ignorados pelos analisadores YAML. Esses comentários são comentários de linha única.

# This is a comment
username: admin
password: secret

Recursos avançados de YAML

O YAML inclui recursos avançados como strings de várias linhas, tipos de dados e âncoras que tornam os documentos mais eficientes e estruturados. Nesta seção, exploraremos esses recursos com exemplos práticos.

Cadeias de caracteres de várias linhas

O YAML oferece suporte a strings de várias linhas usando | (bloco literal) ou > (bloco dobrado). 

• | O bloco literal criará uma nova linha \n para cada quebra de linha. 
• > O bloco dobrado só criará uma nova linha para quebras de linha consecutivas.

literal: |
  This is a
  multi-line string.

folded: >
  This is another
  multi-line string.

Você entenderá melhor o que foi dito acima se mostrar o resultado.

• Para o site | (bloco literal):

This is a
multi-line string.

• Para o > (bloco dobrado):

This is another multi-line string.

Tipos de dados em YAML

O YAML oferece suporte a vários tipos de dados, incluindo strings, números, booleanos e valores nulos. Ele detecta automaticamente os tipos com base na formatação, mas também permite definições explícitas de tipos.

O exemplo a seguir mostra o uso de tipos de dados básicos em YAML:

string_implicit: Hello, YAML!  # No quotes needed unless necessary
string_double_quoted: "Supports escape sequences like \n and \t"
string_single_quoted: 'Raw text, no escape sequences'

integer: 42  # Whole numbers
float: 3.14  # Numbers with decimals

boolean_true: true
boolean_false: false

null_value: null  # Null value
null_tilde: ~  # Another way to represent null

O YAML permite declarações de tipo explícitas usando !!type quando necessário:

explicit_string: !!str 123  # Forces 123 to be a string
explicit_integer: !!int "42"  # Forces "42" to be an integer
explicit_float: !!float "3.14"  # Forces "3.14" to be a float

Como o YAML é frequentemente usado para dados estruturados, ele é compatível:

• Listas (sequências):

fruits:
  - Apple
  - Banana
  - Cherry

• Dicionários (mapeamentos):

person:
  name: Alice
  age: 30
  is_student: false

Âncoras e aliases

O YAML permite que você defina valores reutilizáveis usando âncoras (&) e faça referência a eles posteriormente usando aliases (*). Isso ajuda a reduzir a redundância nos arquivos de configuração, tornando-os mais limpos e fáceis de manter.

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  host: example.com
  retries: *default_settings  # Reuses the retries value from defaults

A sintaxe <<: permite mesclar pares de valores-chave de uma âncora em outro mapeamento. Se uma chave existir em ambos, o novo valor substituirá o original.

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  <<: *default_settings  # Merges all key-value pairs from default_settings
  host: example.com  # This key is added to the merged data

Essa é a estrutura final resolvida:

server1:
  retries: 3
  timeout: 30
  host: example.com

As âncoras e os aliases são especialmente úteis em arquivos de configuração grandes, nos quais a repetição manual de valores seria ineficiente. Eles ajudam a manter os arquivos YAML DRY (Don't Repeat Yourself) e facilitam as atualizações.

Casos de uso comuns para YAML

O YAML é amplamente usado no desenvolvimento de software, na automação de infraestrutura e no gerenciamento de APIs. Sua sintaxe legível por humanos o torna o formato preferido para arquivos de configuração, serialização de dados e Infraestrutura como Código (IaC). Vamos explorar seus aplicativos mais comuns.

Arquivos de configuração

O YAML é amplamente usado para configuração em aplicativoscomo Docker Compose, Kubernetes e pipelines de CI/CD. Sua facilidade de compreensão faz com que seja simples para qualquer pessoa pegar os arquivos de configuração YAML do Docker e entender o que está acontecendo.

version: '3'
services:
  web:
    image: nginx
    ports:
      - "80:80"
    environment:
      - NGINX_HOST=localhost
      - NGINX_PORT=80

A facilidade de leitura e o suporte a âncoras e aliases do YAML ajudam a reduzir a repetição, tornando-o mais fácil de manter do que o JSON ou o XML.

Saiba mais sobre o YAML e seu uso no Docker neste curso intermediário do Docker.

Serialização e transferência de dados

O YAML é usado para serializar dados para APIs e ferramentas de gerenciamento de configuração, convertendo estruturas de dados complexas em um formato legível por humanos e facilmente analisado por máquinas. 

Por exemplo, um corpo de solicitação de API formatado em YAML:

user:
  id: 123
  name: "John Doe"
  email: "johndoe@example.com"
  active: true

A estrutura baseada em indentação do YAML elimina a sintaxe desnecessária, tornando-o leve, legível e fácil de modificar em comparação com o JSON.

Infraestrutura como código (IaC)

As ferramentas de gerenciamento de configuração, como o Ansible e o Kubernetes, utilizam o YAML para definir os estados do sistema, automatizar processos e garantir a consistência entre os ambientes.

• No Ansible, o YAML é usado para escrever playbooks que definem os estados, as tarefas e as dependências do sistema, garantindo que os componentes da infraestrutura sejam configurados de forma consistente. 
• O Kubernetes utiliza manifestos YAML para definir recursos como pods, serviços e implantações, permitindo a orquestração automatizada de aplicativos em contêineres.

Aqui está um exemplo de uma configuração de Pod do Kubernetes:

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
    - name: app-container
      image: my-app:latest
      ports:
        - containerPort: 8080

Saiba mais sobre como o YAML é usado no Kubernetesneste curso de Introdução ao Kubernetes .

Documentação da API

As especificações de API, como OpenAPI e Swagger, usam YAML para definir pontos de extremidade e estruturas de dados de maneira fácil de ler. O YAML é usado para delinear métodos de API, parâmetros de solicitação, formatos de resposta e métodos de autenticação.

Aqui está um exemplo de uma especificação de OpenAPI em YAML:

openapi: 3.0.0
info:
  title: User API
  version: "1.0"
paths:
  /users:
    get:
      summary: Retrieve a list of users
      responses:
        "200":
          description: Successful response

As especificações da OpenAPI, por exemplo, usam YAML para documentar APIs RESTful. Isso permite que eles forneçam um plano claro para gerar SDKs de clientes, documentação de API interativa e testes automatizados. Esse formato estruturado garante a consistência entre as implementações da API.

Trabalhando com arquivos YAML

O YAML é amplamente usado para arquivos de configuração, automação e serialização de dados, mas, como ele depende de indentação, a formatação adequada é fundamental. Veja como você pode ler, gravar, validar e editar YAML com eficiência.

Leitura e gravação de YAML em Python

A biblioteca PyYAML do Python pode analisar e gerar YAML.

Imagine que você tenha o seguinte arquivo YAML de configuração:

database:
  host: localhost
  port: 5432
  user: admin
  password: secret

Veja como você pode trabalhar com seu arquivo de configuração em Python:

import yaml

# Load YAML data
with open("config.yaml", "r") as file:
    data = yaml.safe_load(file)  # safe_load prevents arbitrary code execution

# Modify data (optional)
data["database"]["user"] = "new_user"

# Write YAML data
with open("output.yaml", "w") as file:
    yaml.dump(data, file, default_flow_style=False)

Se você estiver interessado em trabalhar com dados JSON em Python, confira o tutorialabrangente sobre Python JSON.

Validação de arquivos YAML

Para garantir a estrutura correta, você pode usar ferramentas para verificar se há tabulações no lugar de espaços ou problemas estranhos, como caracteres repetidos, problemas de sintaxe e espaços à direita.

Estes são alguns validadores YAML populares:

• Ferramenta CLI: yamllint (linter baseado em Python)
• Validadores on-line: YAML Lint, validador YAML do formatador JSON

Editando YAML

Você pode escrever e editar YAML em qualquer editor de texto, mas as ferramentas de linting e o realce de sintaxe melhoram a legibilidade.

Alguns de meus editores favoritos:

• Código VS (com plug-ins YAML)
• PyCharm (suporte integrado)
• Sublime Text (com realce de sintaxe YAML)

Erros comuns que você deve evitar em YAML

Apesar de sua simplicidade, você ainda pode ter problemas e erros de digitação ao trabalhar com YAML. Esta seção discute esses erros e fornece as práticas recomendadas para escrever arquivos limpos e corretos. É também por isso que recomendo que você use um linter ou um editor de texto!

Mistura de tabulações e espaços

O YAML depende de espaços para indentação - nunca misture espaços e tabulações. As guias simplesmente quebrarão seu script YAML. Na verdade, essa é uma decisão consciente, pois sistemas diferentes leem as guias de forma diferente e, portanto, para minimizar o impacto, os espaços são o uso preferido.

Recuo incorreto

Garanta uma indentação consistente para evitar erros de análise. Como os recuos são o único método do YAML para denotar hierarquia, a análise inadequada pode causar problemas no seu código. Você pode facilmente guardar um par de key: value no lugar errado, portanto, fique atento a essas reentrâncias!

Esquecimento de aspas para caracteres especiais

Use aspas para cadeias de caracteres que contenham caracteres especiais ou espaços. Coisas como barras invertidas, vírgulas, pontos de exclamação e assim por diante precisam de aspas para serem lidas como cadeias de caracteres.

path: "/home/user/documents"
message: "Hello, World!"

Usando a validação adequada, a edição estruturada e o PyYAML do Python, você pode trabalhar de forma eficiente com arquivos YAML e evitar armadilhas comuns.

Conclusão

O YAML é um formato avançado, porém simples, amplamente usado em configuração, serialização de dados e automação de infraestrutura. Você pode trabalhar de forma eficiente com o YAML em vários aplicativos compreendendo sua sintaxe, estrutura e práticas recomendadas.

Se você estiver interessado em aplicar o YAML em cenários do mundo real:

• Saiba como o YAML é usado em fluxos de trabalho de CI/CD com este curso de CI/CD para aprendizado de máquina.
• Explore como as APIs usam YAML em suas especificações neste curso de Introdução às APIs em Python.
• Aprofunde-se na conteinerização e na automação de infraestrutura neste curso de conteinerização e virtualização.