← Todos os artigos
Atualizado em May 29, 20266 min read

Formatador YAML: formate, reidente e valide YAML

Um formatador YAML reidente e normaliza YAML para ele ficar legível e amigável a diff. Aprenda as regras de indentação, armadilhas de tipo e quando formatar vs converter para JSON.

YAML é sensível a espaços em branco, então um tab perdido ou uma indentação inconsistente não só fica feio —— muda o significado ou quebra o parse. Um formatador de YAML resolve isso: re-indenta seu YAML em uma profundidade consistente, normaliza o espaçamento e (opcionalmente) ordena as keys, deixando o arquivo legível e gerando diffs limpos. Este guia explica o que um formatador YAML faz, as regras de indentação que ele impõe, as armadilhas de tipo para ficar de olho, e quando formatar YAML vs converter para JSON.

O que um formatador YAML faz

Um formatador faz parse do seu YAML em uma estrutura de dados e re-serializa com estilo consistente. Os dados não mudam —— só a apresentação é normalizada:

  • Re-indenta cada nível para uma largura fixa (comumente 2 espaços) e substitui tabs por espaços
  • Normaliza o espaçamento ao redor dos dois pontos, dashes de lista e coleções inline
  • Opcionalmente ordena as keys para uma ordem canônica amigável a diff
  • Valida como efeito colateral —— se não der para parsear, você tem um erro de sintaxe para corrigir primeiro
# Antes —— indentação misturada, difícil de ler
server:
    host: api.example.com
    ports:
    - 8080
    - 8443
database: {name: mydb, pool: 5}

# Depois —— indent de 2 espaços, normalizado
server:
  host: api.example.com
  ports:
    - 8080
    - 8443
database:
  name: mydb
  pool: 5

Por que formatar YAML

  • Legibilidade —— pipelines de CI, manifests do Kubernetes e arquivos Docker Compose ficam profundamente aninhados; indentação consistente os torna escaneáveis.
  • Diffs e reviews limpos —— formatação normalizada (e keys ordenadas) significa que um pull request mostra só mudanças reais, não ruído de whitespace.
  • Pegar erros cedo —— formatação só tem sucesso em YAML válido, então um formatador serve também como check rápido de validade.
  • Consistência no time —— um estilo aplicado automaticamente, em vez de hábitos de indentação por autor.

As regras de indentação que um formatador impõe

A maioria dos erros de YAML são erros de indentação, e é exatamente o que um formatador padroniza:

  • Só espaços —— nunca tabs. YAML proíbe caracteres tab para indentação. Um único tab é o bug YAML mais comum do tipo «por que isso não parseia?».
  • Profundidade consistente. Keys irmãs devem ser indentadas pelo mesmo número de espaços em relação ao pai. Um formatador reescreve tudo para uma largura fixa.
  • Alinhamento de lista. Itens em uma sequência de bloco (-) se alinham abaixo da sua key; um formatador normaliza se o dash está indentado ou rente.

Armadilhas de tipo ao reformatar

Formatação preserva os dados, mas a inferência de tipos do YAML ainda pode te surpreender quando os valores estão sem aspas —— vale conhecer antes de confiar na saída:

  • O «Norway problem». Sem aspas, NO, yes, on, off podem ser lidos como boolean, então o código de país NO vira false. Coloque aspas nesses valores para mantê-los como strings.
  • Zeros à esquerda e números grandes.007 pode perder seus zeros se for lido como número; inteiros muito grandes podem perder precisão. Coloque aspas em IDs que precisam continuar strings.
  • Datas e timestamps. Alguns parsers coercem strings parecidas com datas sem aspas para tipos de timestamp. Coloque aspas se você precisa da string literal.

Estilo bloco vs estilo flow

YAML tem dois jeitos de escrever coleções: bloco (indentado, orientado a linha) e flow (inline, estilo JSON com [] / {}):

# bloco
ports:
  - 80
  - 443

# flow (mesmos dados)
ports: [80, 443]

Formatadores tipicamente normalizam para o estilo bloco por causa da legibilidade. Estilo flow é compatível com JSON —— útil ao embedar YAML dentro de tooling só-JSON —— mas mais difícil de ler à medida que o aninhamento cresce.

Anchors e aliases: trechos reutilizáveis

& marca um anchor; * referencia ele. Útil para compartilhar config entre serviços sem copia-cola, e formatadores os preservam:

defaults: &defaults
  retries: 3
  timeout: 30
api:
  <<: *defaults
  url: https://api.example.com
worker:
  <<: *defaults
  url: https://worker.example.com

Nota: anchors e aliases somem quando você converte para JSON —— JSON não tem tipo de referência, então os valores são inlinados. Um round-trip YAML → JSON → YAML os perde.

Lint além do parse: yamllint

Um formatador normaliza a forma; yamllint impõe um guia de estilo (comprimento de linha, ordem de keys, marcadores de início de documento, valores truthy, espaçamento de comentário). Combine os dois em CI: formate primeiro, depois lint com as regras que seu time escolher.

Formatar YAML vs converter para JSON

Formatar mantém o arquivo como YAML —— melhor quando humanos vão continuar editando. Converter para JSON é para quando um programa precisa consumi-lo (a maioria das apps só parseia JSON em runtime). Como YAML 1.2 é um superconjunto estrito do JSON, a conversão não tem perda de dados; veja Converter YAML para JSON e JSON vs YAML para quando usar cada um.

Formate e valide YAML no seu navegador

Cole seu YAML no validador e formatador YAML do fixjson e clique Format YAML para re-indentar e normalizar, ou To JSON para converter. Ele reporta a linha exata de qualquer erro de sintaxe, e tudo roda no seu navegador —— sem upload —— o que importa para arquivos de config que contém hosts, secrets ou configurações internas.

Perguntas frequentes

O que um formatador YAML faz?

Ele faz parse do seu YAML e re-serializa com indentação e espaçamento consistentes (e opcionalmente keys ordenadas), para que o arquivo fique legível e amigável a diff. Os dados não mudam —— só a formatação é normalizada.

Por que meu YAML falha no parse?

Quase sempre indentação: um caractere tab (YAML proíbe tabs para indentação) ou keys irmãs em profundidades inconsistentes. Um formatador reescreve tudo para uma largura única baseada em espaços, o que evidencia e corrige a maioria desses casos.

Formatar YAML muda meus dados?

Não —— ele só muda whitespace e ordem das keys. Mas vigie valores sem aspas: YAML pode inferir tipos (o «Norway problem»), então coloque aspas em valores como NO ou 007 que precisam continuar strings.

Devo formatar YAML ou converter para JSON?

Formate quando humanos vão continuar editando o arquivo; converta para JSON quando um programa consome. Muitos times escrevem YAML e convertem para JSON no momento do load.

Ferramentas & guias relacionados