O que é YAML? Entenda os fundamentos, a sintaxe e os casos de uso

Ao longo dos anos, trabalhei com incontáveis arquivos de configuração, e o YAML sempre se destacou pela simplicidade e legibilidade. Seja configurando workflows no Kubernetes, definindo serviços no Docker ou estruturando requisições de API, o YAML torna configurações complexas mais fáceis de gerenciar. Sua estrutura limpa, baseada em indentação, elimina a verbosidade de formatos como XML, mantendo a flexibilidade.

Neste guia, vou apresentar a sintaxe, a estrutura, os recursos avançados e as boas práticas do YAML para você trabalhar 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 XML usa uma mistura de tags aninhadas (parecidas com HTML) e JSON usa chaves e aspas, assim como dicionários em Python, o YAML é mais conciso e usa indentação para definir a estrutura, o que o torna mais amigável para humanos.

O YAML oferece suporte a vários tipos de dados, incluindo escalares (strings, números, booleanos), sequências (listas) e mapeamentos (pares chave-valor). É 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 de JSON, o que significa que arquivos JSON válidos podem ser interpretados como YAML. Arquivos YAML normalmente têm as extensões .yaml ou .yml.

Você também pode saber mais sobre YAML no site oficial.

Sintaxe e estrutura do YAML

Nesta seção, vamos explorar os princípios fundamentais da sintaxe do YAML, incluindo pares chave-valor, listas, dados aninhados e comentários.

Regras básicas de sintaxe

Algumas regras básicas do YAML: 

• O recuo com espaços define a estrutura, então evite usar tabs! 
• Pares chave-valor seguem a estrutura chave: valor, como em outras linguagens. 
• Hífens no início das linhas indicam uma lista. 
• O uso de # cria linhas de comentário.

# Aqui está um exemplo de YAML
name: John Doe
age: 30
skills:
  - Python
  - YAML

Pares chave-valor

O YAML representa dados como pares chave-valor, semelhante a dicionários em Python. Isso geralmente indica informações para diferentes arquivos e configurações. Não é necessário colocar aspas em strings ou chaves; basta escrever a chave e os valores necessários:

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

Listas no YAML

Listas são representadas usando hífens (-). Isso permite listar vários objetos sob uma única chave. Em editores de markup, isso costuma ser exibido visualmente como marcadores.

fruits:
  - Apple
  - Banana
  - Cherry

Dados aninhados

Estruturas aninhadas permitem representar hierarquias usando indentação. Pense nelas como dicionários aninhados. Ao usar indentação, você indica quais chaves são subconjuntos de outras.

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

Comentários

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

# Este é um comentário
username: admin
password: secret

Recursos avançados do YAML

O YAML inclui recursos poderosos, como strings multilinha, tipos de dados e anchors, que tornam os documentos mais eficientes e organizados. Nesta seção, vamos explorar essas capacidades com exemplos práticos.

Strings multilinha

O YAML suporta strings multilinha usando | (bloco literal) ou > (bloco dobrado). 

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

literal: |
  This is a
  multi-line string.

folded: >
  This is another
  multi-line string.

O entendimento fica mais claro vendo a saída.

• Para | (bloco literal):

This is a
multi-line string.

• Para > (bloco dobrado):

This is another multi-line string.

Tipos de dados no YAML

O YAML suporta vários tipos de dados, incluindo strings, números, booleanos e valores nulos. Ele detecta automaticamente os tipos pelo formato, mas também permite definições explícitas.

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

string_implicit: Hello, YAML!  # Não precisa de aspas, a menos que necessário
string_double_quoted: "Supports escape sequences like \n and \t"
string_single_quoted: 'Raw text, no escape sequences'

integer: 42  # Números inteiros
float: 3.14  # Números com decimais

boolean_true: true
boolean_false: false

null_value: null  # Valor nulo
null_tilde: ~  # Outra forma de representar null

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

explicit_string: !!str 123  # Força 123 a ser string
explicit_integer: !!int "42"  # Força "42" a ser inteiro
explicit_float: !!float "3.14"  # Força "3.14" a ser float

Como o YAML é frequentemente usado para dados estruturados, ele oferece suporte a:

• Listas (sequências):

fruits:
  - Apple
  - Banana
  - Cherry

• Dicionários (mapeamentos):

person:
  name: Alice
  age: 30
  is_student: false

Anchors e aliases

O YAML permite definir valores reutilizáveis usando anchors (&) e referenciá-los depois com aliases (*). Isso ajuda a reduzir redundância em arquivos de configuração, deixando-os mais limpos e fáceis de manter.

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  host: example.com
  retries: *default_settings  # Reutiliza o valor de retries de defaults

A sintaxe <<: permite mesclar pares chave-valor de uma anchor em outro mapeamento. Se uma chave existir em ambos, o novo valor substitui o original.

defaults: &default_settings
  retries: 3
  timeout: 30

server1:
  <<: *default_settings  # Mescla todos os pares de default_settings
  host: example.com  # Esta chave é adicionada aos dados mesclados

Esta é a estrutura final resolvida:

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

Anchors e aliases são especialmente úteis em arquivos grandes, onde repetir valores manualmente seria ineficiente. Eles ajudam a manter os arquivos YAML DRY (Don't Repeat Yourself) e facilitam atualizações.

Casos de uso comuns do YAML

O YAML é amplamente usado em desenvolvimento de software, automação de infraestrutura e gestão de APIs. Sua sintaxe legível o torna um formato preferido para arquivos de configuração, serialização de dados e Infrastructure as Code (IaC). Vamos ver suas aplicações mais comuns.

Arquivos de configuração

O YAML é muito usado para configuração em aplicativos como Docker Compose, Kubernetes e pipelines de CI/CD. Sua facilidade de leitura permite que qualquer pessoa entenda rapidamente arquivos de configuração YAML do Docker e saiba o que está acontecendo.

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

A legibilidade do YAML e o suporte a anchors e aliases ajudam a reduzir repetição, tornando-o mais sustentável do que JSON ou XML.

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

Serialização e transferência de dados

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

Por exemplo, um corpo de requisiçã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 sintaxe desnecessária, tornando-o mais leve, legível e fácil de modificar em comparação ao JSON.

Infrastructure as Code (IaC)

Ferramentas de gestão de configuração como Ansible e Kubernetes utilizam YAML para definir estados do sistema, automatizar processos e garantir consistência entre ambientes.

• No Ansible, o YAML é usado para escrever playbooks que definem estados, tarefas e dependências, garantindo que componentes de infraestrutura sejam configurados de forma consistente. 
• O Kubernetes utiliza manifestos YAML para definir recursos como pods, serviços e deployments, possibilitando a orquestração automatizada de aplicações containerizadas.

Veja um exemplo de configuração de um Pod no 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 Kubernetes neste curso de Introdução ao Kubernetes.

Documentação de APIs

Especificações de API como OpenAPI e Swagger usam YAML para definir endpoints e estruturas de dados de forma fácil de ler. O YAML descreve métodos de API, parâmetros de requisição, formatos de resposta e métodos de autenticação.

Veja um exemplo de especificação 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 OpenAPI, por exemplo, usam YAML para documentar APIs REST. Isso permite criar um blueprint claro para gerar SDKs de cliente, documentação interativa e testes automatizados. Esse formato estruturado garante consistência entre implementações de API.

Trabalhando com arquivos YAML

O YAML é amplamente usado para arquivos de configuração, automação e serialização de dados, mas como depende de indentação, a formatação correta é crucial. Veja como ler, escrever, validar e editar YAML com eficiência.

Lendo e escrevendo YAML em Python

A biblioteca PyYAML do Python consegue analisar e gerar YAML.

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

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

Veja como trabalhar com esse arquivo de configuração em Python:

import yaml

# Carregar dados YAML
with open("config.yaml", "r") as file:
    data = yaml.safe_load(file)  # safe_load evita execução arbitrária de código

# Modificar dados (opcional)
data["database"]["user"] = "new_user"

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

Se você quer trabalhar com dados JSON em Python, confira o tutorial completo de Python JSON.

Validando arquivos YAML

Para garantir a estrutura correta, use ferramentas para detectar tabs no lugar de espaços ou problemas como caracteres repetidos, erros de sintaxe e espaços extras no final das linhas.

Alguns validadores populares de YAML:

• Ferramenta de CLI: yamllint (linter em Python)
• Validadores online: YAML Lint, YAML Validator do JSON Formatter

Editando YAML

Você pode escrever e editar YAML em qualquer editor de texto, mas ferramentas de lint e realce de sintaxe melhoram muito a leitura.

Alguns dos meus editores favoritos:

• VS Code (com plugins de YAML)
• PyCharm (suporte nativo)
• Sublime Text (com realce de sintaxe YAML)

Erros comuns para evitar no YAML

Apesar da simplicidade, ainda é fácil esbarrar em problemas e typos ao trabalhar com YAML. Esta seção aborda esses erros e traz boas práticas para escrever arquivos limpos e corretos. Por isso também recomendo usar um linter ou um bom editor de texto!

Misturar tabs e espaços

O YAML depende de espaços para indentação — nunca misture espaços e tabs. Tabs simplesmente quebram seu YAML. Isso é proposital: sistemas diferentes interpretam tabs de formas distintas; para minimizar impactos, o padrão é usar espaços.

Indentação incorreta

Garanta indentação consistente para evitar erros de parsing. Como as indentações são o único método do YAML para indicar hierarquia, problemas de parsing podem afetar seu código. É fácil colocar um par key: value no lugar errado; então, fique de olho na indentação!

Esquecer aspas para caracteres especiais

Use aspas para strings com caracteres especiais ou espaços. Itens como barras invertidas, vírgulas, pontos de exclamação e afins precisam de aspas para serem lidos como strings.

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

Com validação adequada, edição estruturada e o PyYAML no Python, você consegue trabalhar com eficiência com arquivos YAML e evitar armadilhas comuns.

Conclusão

O YAML é um formato poderoso e simples, amplamente usado em configurações, serialização de dados e automação de infraestrutura. Ao entender sua sintaxe, estrutura e boas práticas, você trabalha com YAML de forma eficiente em diversas aplicações.

Se você quer aplicar YAML em cenários reais:

• Aprenda como o YAML é usado em workflows de CI/CD neste curso de CI/CD para Machine Learning.
• Explore como APIs usam YAML em suas especificações neste curso de Introdução a APIs em Python.
• Aprofunde-se em conteinerização e automação de infraestrutura nesta trilha de Containerization and Virtualization.