YAML é um daqueles formatos que você talvez use todos os dias sem nunca ter parado para aprender direito. Você copia um workflow do GitHub Actions de um post de blog, ajusta um arquivo do Docker Compose ou edita um manifesto do Kubernetes, e na maioria das vezes funciona. Até parar de funcionar, e você passa vinte minutos descobrindo que usou uma tabulação em vez de espaços.
Este guia cobre o que YAML realmente é, como sua sintaxe funciona e onde você provavelmente vai encontrá-lo.
TL;DR — YAML em 30 segundos
- YAML é um formato de dados que usa indentação, e não chaves, para mostrar a estrutura. Ele lida com o mesmo modelo de dados do JSON: strings, números, booleanos, null, listas e mapeamentos.
- Abrir mão das chaves e das vírgulas torna o formato mais fácil de ler e escrever por humanos, e é por isso que ele domina os arquivos de configuração.
- Kubernetes, GitHub Actions, Docker Compose e Ansible são todos baseados em YAML.
- Diferente do JSON, o YAML suporta comentários, strings de múltiplas linhas e âncoras para reúso.
- Para transformar YAML em JSON, cole o conteúdo na ferramenta YAML to JSON do FormatArc — ela roda inteiramente no seu navegador e mostra o número da linha que falhou nos erros.
O que significa YAML
YAML originalmente significava "Yet Another Markup Language" (Mais Uma Linguagem de Marcação), mas depois foi rebatizado com o acrônimo recursivo "YAML Ain't Markup Language" (YAML Não É Linguagem de Marcação). A renomeação reflete o propósito do formato: o YAML serve para serialização de dados, não para marcação de documentos. Ele não está tentando fazer o que o HTML ou o XML fazem.
O formato foi proposto pela primeira vez em 2001 por Clark Evans, e passou por várias revisões da especificação desde então. A versão amplamente usada atualmente é o YAML 1.2, que foi projetada para ser um superconjunto do JSON. Isso significa que qualquer documento JSON válido é tecnicamente um YAML válido também, embora ninguém escreva YAML assim na prática.
Como o YAML se parece
Aqui está um documento YAML simples:
name: Alice
age: 30
isStudent: false
Compare com o equivalente em JSON:
{
"name": "Alice",
"age": 30,
"isStudent": false
}
O YAML abre mão das chaves, das aspas duplas em volta das chaves e das vírgulas. Em vez disso, ele usa indentação para mostrar a estrutura. Para muita gente, isso torna o YAML mais fácil de ler de relance, especialmente em arquivos de configuração que as pessoas editam com frequência.
Regras de indentação
É aqui que o YAML ganha sua reputação de exigente. As regras são diretas, mas as consequências de quebrá-las nem sempre são óbvias.
Apenas espaços, sem tabulações
O YAML exige espaços para indentação. Tabulações não são permitidas. A maioria dos editores pode ser configurada para inserir espaços quando você aperta Tab, mas se o seu editor não estiver configurado assim, você vai obter erros de parsing que podem ser difíceis de diagnosticar.
Profundidade de indentação consistente
Você escolhe quantos espaços usar na indentação — dois espaços é a convenção mais comum — mas precisa ser consistente dentro de um mesmo bloco. Misturar indentação de dois e de quatro espaços no mesmo nível de aninhamento vai quebrar tudo.
# Isto está correto
server:
host: localhost
port: 8080
# Isto vai causar problemas
server:
host: localhost
port: 8080 # errado — nível de indentação diferente de host
O aninhamento mostra a hierarquia
A indentação define as relações pai-filho. Tudo que estiver indentado abaixo de uma chave pertence a ela.
database:
primary:
host: db-primary.example.com
port: 5432
replica:
host: db-replica.example.com
port: 5432
Isso equivale a objetos aninhados no JSON. As chaves primary e replica são filhas de database, e cada uma tem o seu próprio host e port.
Tipos de dados
O YAML infere os tipos a partir dos valores. Você não precisa declará-los, mas precisa saber como o YAML vai interpretar os seus valores.
Strings
A maioria dos valores que não são obviamente outra coisa é tratada como string. Você pode colocá-los entre aspas, mas muitas vezes não precisa.
city: Tokyo
greeting: "Hello, world"
path: '/usr/local/bin'
As aspas são obrigatórias quando o seu valor contém caracteres que o YAML interpretaria como sintaxe, como dois-pontos, cerquilhas ou caracteres especiais no início.
# Sem aspas, isto quebra
message: "Note: this needs quotes"
selector: "#main-content"
Números
Inteiros e números de ponto flutuante são reconhecidos automaticamente.
count: 42
ratio: 3.14
hex: 0xFF
Booleanos
Aqui está um dos comportamentos mais surpreendentes do YAML. Todos estes são interpretados como booleanos:
a: true
b: false
c: yes
d: no
e: on
f: off
Os apelidos yes/no e on/off pegam as pessoas de surpresa com frequência. Se você tem um campo em que "yes" ou "no" deveria ser uma string — digamos, um código de país como NO para a Noruega — você precisa colocá-lo entre aspas.
country: "NO" # string, não o booleano false
O YAML 1.2 apertou esse comportamento e reconhece apenas true e false, mas muitos parsers ainda suportam o comportamento antigo por compatibilidade retroativa.
Null
value: null
also_null: ~
and_this:
Os três representam null. Um valor vazio (apenas a chave sem nada depois dos dois-pontos) também é null.
Arrays
Os arrays usam um hífen seguido de um espaço:
colors:
- red
- green
- blue
Você também pode escrever arrays em linha usando colchetes, o que se parece exatamente com JSON:
colors: [red, green, blue]
Objetos
Objetos são simplesmente pares chave-valor indentados, como mostrado ao longo deste guia. A sintaxe em linha usa chaves:
point: {x: 10, y: 20}
Comentários
Esta é uma das vantagens reais do YAML sobre o JSON. Você pode adicionar comentários com #.
# Configuração do banco de dados
database:
host: localhost # sobrescreva em produção
port: 5432
name: myapp
Os comentários são ignorados pelo parser. Eles são valiosíssimos em arquivos de configuração onde você precisa explicar por que um determinado valor foi definido, ou deixar anotações para a próxima pessoa que editar o arquivo.
O JSON não tem nenhuma sintaxe de comentário, o que é um dos principais motivos pelos quais as pessoas preferem o YAML para configuração. Para uma comparação completa dos dois formatos, veja YAML vs JSON: escolhendo o formato certo.
Strings de múltiplas linhas
O YAML tem dois indicadores especiais para strings de múltiplas linhas, e eles se comportam de forma diferente.
Bloco literal ( | )
Preserva as quebras de linha exatamente como foram escritas:
description: |
This is line one.
This is line two.
This is line three.
A string resultante contém as quebras de linha entre cada linha.
Bloco dobrado ( > )
Dobra as quebras de linha em espaços, criando uma única linha longa:
description: >
This is a long paragraph
that will be joined into
a single line.
O resultado é "This is a long paragraph that will be joined into a single line." — útil para descrições longas que você quer quebrar visualmente no arquivo YAML por legibilidade.
Âncoras e aliases
O YAML tem um recurso para reaproveitar valores. Você define uma âncora com & e a referencia com *.
defaults: &default_settings
timeout: 30
retries: 3
production:
<<: *default_settings
timeout: 60
staging:
<<: *default_settings
A chave de mesclagem << copia todos os valores da âncora, e você pode sobrescrever chaves individuais. Isso reduz a duplicação em arquivos de configuração grandes, embora possa tornar o arquivo mais difícil de acompanhar se usado em excesso.
Onde o YAML é usado
Kubernetes
O Kubernetes é provavelmente o maior motor isolado do uso de YAML hoje. Todo recurso do Kubernetes — pods, deployments, services, configmaps — é definido em YAML.
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.25
ports:
- containerPort: 80
Esses manifestos podem ficar longos, e pequenos erros de indentação podem causar falhas de deployment confusas. Muitas equipes validam o seu YAML antes de aplicá-lo.
GitHub Actions
Os workflows do GitHub Actions ficam em .github/workflows/ e são escritos em YAML.
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm install
- run: npm test
Docker Compose
O Docker Compose usa YAML para definir aplicações com múltiplos contêineres.
services:
web:
image: nginx
ports:
- "80:80"
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: secret
Outras ferramentas
Playbooks do Ansible, charts do Helm, templates do CloudFormation, especificações Swagger/OpenAPI, configurações de site do Jekyll e do Hugo — o YAML é o formato preferido para ferramentas que precisam de configuração editável por humanos.
Erros comuns
Usar tabulações
O erro de YAML mais comum. O seu arquivo parece perfeitamente indentado no editor, mas o parser o rejeita porque há caracteres de tabulação escondidos no espaçamento. Configure o seu editor para mostrar caracteres invisíveis se estiver depurando um erro misterioso de YAML.
Strings especiais sem aspas
Valores como yes, no, on, off, null e ~ são interpretados como booleanos ou null. Timestamps como 2026-03-20 são interpretados como objetos de data em alguns parsers. Na dúvida, coloque suas strings entre aspas.
Indentação inconsistente
Misturar indentação de dois e de quatro espaços, ou indentar acidentalmente uma chave com um espaço a mais, produz erros que podem ser difíceis de localizar em um arquivo grande.
Esquecer o espaço depois dos dois-pontos
key:value não é o mesmo que key: value. O espaço depois dos dois-pontos é obrigatório.
Convertendo entre YAML e JSON
Como o YAML 1.2 é um superconjunto do JSON, a conversão entre os dois é simples. Todo documento YAML pode ser representado como JSON, embora você perca os comentários e a formatação das strings de múltiplas linhas no processo.
Converter é útil quando você precisa alimentar uma configuração YAML em uma ferramenta que espera JSON, ou quando quer validar a estrutura do seu YAML examinando-o em um formato mais explícito.
Você pode converter YAML para JSON instantaneamente usando a ferramenta YAML to JSON. Cole o seu YAML e você obtém uma saída JSON limpa. Para um passo a passo detalhado, veja Como converter YAML para JSON.
No sentido inverso, o conversor JSON to YAML transforma respostas de API ou configurações em JSON em um YAML limpo no navegador — prático para montar manifestos do Kubernetes ou arquivos do Docker Compose a partir de JSON. O guia de JSON para YAML percorre as regras de conversão em detalhes.
Perguntas frequentes
O que significa YAML?
"YAML Ain't Markup Language" (YAML Não É Linguagem de Marcação). Originalmente significava "Yet Another Markup Language" (Mais Uma Linguagem de Marcação), mas foi renomeado com esse acrônimo recursivo para deixar claro que o YAML serve para serialização de dados, e não para marcação de documentos.
YAML é uma linguagem de programação?
Não. YAML é um formato de serialização de dados usado para arquivos de configuração e troca de dados. Ele não tem fluxo de controle — sem condicionais, sem loops.
Existe diferença entre .yml e .yaml?
Não. As duas extensões são interpretadas de forma idêntica. A especificação recomenda .yaml, mas .yml também é amplamente usado — muitas vezes só para economizar um caractere.
Por que o Kubernetes e o GitHub Actions usam YAML?
Porque é legível por humanos e suporta comentários, então você pode documentar por que uma configuração é como é. A ausência de chaves e vírgulas combina com arquivos de configuração que as pessoas editam à mão.
Como o YAML difere do JSON?
YAML e JSON compartilham o mesmo modelo de dados, mas o YAML acrescenta comentários, strings de múltiplas linhas e âncoras, e usa indentação em vez de chaves. O JSON é mais rígido e mais rápido de processar, o que combina com APIs. Para uma comparação lado a lado completa, veja YAML vs JSON.
Por que country: NO virou false?
Os parsers de YAML 1.1 (como o PyYAML, ainda amplamente usado) leem o NO sem aspas como o booleano false. Esse é o famoso "problema da Noruega". Coloque-o entre aspas — country: "NO" — para mantê-lo como string. Veja o guia de sintaxe do YAML para os detalhes.
Conclusão
O apelo do YAML vem da sua legibilidade. Para arquivos de configuração que as pessoas editam com frequência, a ausência de chaves e aspas faz uma diferença real. O custo é que erros de indentação podem ser sutis e que algumas das regras de inferência de tipo do YAML são surpreendentes.
Se você trabalha com YAML regularmente, vale a pena dedicar uma hora para aprender as regras direito, em vez de copiar e colar torcendo para dar certo. Entender a indentação, as regras de uso de aspas e a coerção de tipos vai te poupar da maioria das dores de cabeça relacionadas ao YAML. Para uma referência passo a passo de cada construção do YAML — âncoras, arquivos com múltiplos documentos, indicadores de chomping — veja o guia de sintaxe do YAML.
Para uma comparação direta entre YAML e JSON, incluindo quando usar cada um, leia YAML vs JSON: escolhendo o formato certo.
Leitura relacionada
- Guia de sintaxe do YAML — cada construção, da indentação às âncoras, com exemplos
- YAML vs JSON — quando escolher cada formato
- Como converter YAML para JSON — passo a passo da conversão
- Guia de sintaxe do JSON — o formato com o qual o YAML é mais comparado
- Comentários em JSON e JSONC — o que o YAML oferece e o JSON não
- Como converter JSON para YAML — o sentido inverso, para configurações de Kubernetes e Docker