Formatador e validador YAML

Cole YAML para formatá-lo e validá-lo. Veja os erros instantaneamente, corrija a indentação e converta em JSON.

Processado localmente · nada é enviado a um servidor
Cole YAML para validar

O que é o YAML ?

YAML (YAML Ain't Markup Language) é um formato de serialização de dados legível por humanos, usado em arquivos de configuração (Docker, Kubernetes, GitHub Actions, Ansible), troca de dados e muito mais. Ele usa indentação em vez de chaves e é um superset do JSON.

Perguntas frequentes

Quais erros o validador detecta ?

Erros de indentação, dois-pontos ausentes, chaves duplicadas, caracteres inválidos, strings não fechadas, aninhamentos incorretos e outros problemas de sintaxe YAML. As mensagens de erro incluem os números de linha.

Posso converter o YAML em JSON ?

Sim ! Clique no botão « → JSON » para converter seu YAML em JSON bem formatado. Para a conversão inversa, use nosso JSON para YAML.

Um tour rápido pelo YAML

O YAML 1.0 foi publicado em 2001 por Clark Evans, Ingy döt Net e Oren Ben-Kiki; o YAML 1.1 veio em 2005, e a versão atual é o YAML 1.2.2, que corrigiu várias armadilhas históricas (notadamente o «problema da Noruega», veja abaixo) e foi projetado para ser um superset estrito do JSON. A especificação oficial fica em yaml.org/spec/1.2.2. Este formatador usa a biblioteca de código aberto js-yaml, que analisa contra o esquema do YAML 1.2 por padrão, então a maioria das peculiaridades legadas do 1.1 não se aplica ao texto formatado aqui, mas se aplica à maioria das ferramentas YAML do lado do servidor para onde você vai enviar a saída.

Onde o YAML realmente vive

O YAML venceu como o formato de configuração para a infraestrutura nativa de nuvem. Os lugares em que você mais vai encontrá-lo:

A armadilha dos espaços em branco (somente espaços)

O YAML usa a indentação para denotar a estrutura, e a especificação é explícita ao dizer que tabulações não são permitidas para indentação. Somente espaços. Essa é a fonte mais comum de bugs em YAML escrito à mão, especialmente porque muitos editores misturam tabulações e espaços silenciosamente, dependendo das suas configurações. A mensagem de erro que você vai receber de um analisador estrito é algo na linha de «found character '\t' that cannot start any token», em tradução: «você usou uma tabulação em algum lugar.» A correção é universal: ative «mostrar os espaços em branco» no seu editor e converta cada tabulação em dois ou quatro espaços.

O tamanho da indentação é convenção, não especificação. 2 espaços é o padrão de fato para manifestos do Kubernetes, GitHub Actions e a maior parte do YAML que você vai ler na web moderna. 4 espaços é mais comum no Ansible. A regra que importa: seja consistente dentro de um mesmo arquivo. Misturar 2 e 4 espaços entre chaves irmãs é o que confunde os analisadores, não o tamanho que você escolhe.

O problema da Noruega (e por que você deve colocar strings ambíguas entre aspas)

O YAML 1.1 (ainda o padrão no PyYAML, no snakeyaml e em muitos outros analisadores do lado do servidor) interpreta uma longa lista de grafias booleanas sem aspas como booleanos de verdade: true, True, TRUE, false, False, FALSE, yes, Yes, YES, no, No, NO, y, n, on, off. A armadilha famosa: o código de país ISO da Noruega é NO. Uma configuração YAML que lista países como strings sem aspas analisa silenciosamente a Noruega como o booleano false, e o código a jusante que lê countries[0] == 'NO' falha de forma confusa.

O YAML 1.2 (e o esquema padrão do js-yaml) restringiu os booleanos a apenas true / false, o que corrige o problema da Noruega no nível do analisador. Mas muitas ferramentas do mundo real ainda usam o esquema do YAML 1.1 por padrão, por compatibilidade retroativa. O hábito defensivo: coloque entre aspas qualquer string que pareça poder ser um booleano, número, data ou versão. country: "NO", postal_code: "01234", version: "1.10", time: "10:30". As aspas são o desambiguador universal.

Outras armadilhas de coerção de tipo

Estilo de bloco vs. estilo de fluxo

O YAML suporta duas notações para os mesmos dados:

# Block style (the standard, indentation-based)
person:
  name: Alice
  tags:
    - admin
    - billing

# Flow style (JSON-like inline)
person: { name: Alice, tags: [admin, billing] }

O estilo de bloco é o que você vai ver em 99% do YAML escrito à mão: é o que torna o formato legível. O estilo de fluxo é uma válvula de escape útil para valores curtos de uma só linha ou para gerar YAML programaticamente, quando você prefere não controlar a indentação. O formatador normaliza para o estilo de bloco na saída (a forma mais legível), independentemente do estilo que a sua entrada usou.

Âncoras e aliases (o truque DRY)

O recurso de reutilização do YAML: defina um valor uma vez com a âncora &name e referencie-o em outro lugar com o alias *name. Conveniente para arquivos de configuração longos em que o mesmo bloco de valores aparece várias vezes.

defaults: &defaults
  region: us-east-1
  log_level: info

production:
  <<: *defaults
  log_level: warn   # override

staging:
  <<: *defaults

Algumas ressalvas: nem todo processador YAML suporta âncoras e aliases (notadamente algumas ferramentas de manifesto do Kubernetes mais antigas e certos contextos do Helm). A sintaxe de «chave de mesclagem» <<: mostrada acima é uma extensão do YAML 1.1 e está oficialmente obsoleta no 1.2; o js-yaml a suporta, mas analisadores de 1.2 puro podem não suportar.

Arquivos com múltiplos documentos

Um único arquivo YAML pode conter múltiplos documentos, separados por ---. Comum no Kubernetes: um arquivo com um Deployment, um Service e um ConfigMap, separados por ---, aplicados com um único kubectl apply -f:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
---
apiVersion: v1
kind: Service
metadata:
  name: app-svc

YAML vs. JSON vs. TOML

Se você tem escolha para uma nova configuração: TOML para configuração plana, YAML se você precisa de aninhamento profundo e o ecossistema o padronizou (Kubernetes, Ansible), JSON se uma máquina o escreve. O YAML é o formato certo quando humanos precisam ler configurações profundamente aninhadas e escrever comentários significativos em linha.

Privacidade

As configurações YAML frequentemente contêm segredos que não deveriam passar pelo servidor de outra pessoa: blobs base64 de Secret do Kubernetes, senhas de banco de dados em application.yml, chaves de API em fluxos de trabalho de CI, nomes de host internos em configurações de implantação. O formatador roda inteiramente no seu navegador por meio da biblioteca de código aberto js-yaml: o conteúdo colado é analisado e reemitido localmente, sem fetch / sem upload / sem registro. Fechar a aba apaga tudo.

Erros comuns

  1. Misturar tabulações e espaços na indentação. O erro mais comum. As tabulações são proibidas pela especificação; alguns editores as inserem silenciosamente. Mostre os espaços em branco no seu editor.
  2. Indentação inconsistente entre irmãos. As chaves irmãs precisam estar alinhadas na mesma coluna. Uma indentação que mistura 2 e 4 espaços quebra a análise.
  3. Valores sem aspas que parecem booleanos, números, datas ou horas. NO, 012, 1.10, 10:30, yes: coloque-os entre aspas.
  4. Falta de espaço após os dois-pontos. key: value funciona; key:value é inválido (analisado como uma única string).
  5. Espaço em branco no final. Alguns analisadores tratam os espaços no final como significativos; outros não. O hábito seguro entre ferramentas é remover o espaço em branco no final.
  6. Strings de múltiplas linhas sem o escalar de bloco certo. Strings longas precisam de | (literal, preserva as quebras de linha) ou > (dobrado, junta as linhas). Texto simples sem aspas em múltiplas linhas raramente se comporta do jeito que você espera.
  7. Âncoras / aliases presumidos em todo lugar. O Helm e alguns contextos do Kubernetes não suportam totalmente &/*. Teste no seu pipeline real antes de depender deles.
  8. Incompatibilidades de codificação. Os arquivos YAML devem ser UTF-8. Um editor do Windows que salva como UTF-16 com BOM produz arquivos que alguns analisadores não conseguem ler.

Mais perguntas frequentes

O formatador vai preservar os meus comentários?

Não. A biblioteca js-yaml analisa o YAML em um valor JavaScript e o reemite a partir desse valor, o que significa que os comentários (# like this) são descartados: eles vivem no texto-fonte, não na estrutura analisada. Se preservar os comentários importa (e normalmente importa para arquivos de configuração curados à mão), use uma alternativa que preserva comentários, como o eemeli/yaml via a sua API CST, ou faça pequenas edições à mão em vez de fazer a ida e volta por este formatador.

Por que o meu NO é tratado como booleano pelo analisador YAML do meu servidor?

Porque esse analisador está usando o YAML 1.1 (o padrão do PyYAML, do snakeyaml e de muitos outros), que interpreta NO como o booleano false. Este formatador usa o YAML 1.2 por padrão (via js-yaml), então não dispara o bug aqui, mas no momento em que você envia o arquivo para um ambiente YAML 1.1 a armadilha é ativada. Sempre coloque strings ambíguas entre aspas: country: "NO".

Posso converter YAML em JSON?

Sim, clique em «→ JSON». A conversão é sem perdas para tudo o que pode ser representado em JSON (strings, números, booleanos, null, arrays, objetos). Coisas que não sobrevivem: os comentários (o JSON não tem sintaxe para eles), as âncoras e os aliases (o JSON não tem equivalente) e os tipos de data / timestamp do YAML (que viram strings no JSON). Para a direção inversa, use a ferramenta dedicada de JSON para YAML.

Algo é enviado a um servidor?

Não. Toda a análise, a formatação e a conversão para JSON rodam no seu navegador via js-yaml. O YAML colado nunca é transmitido a nenhum servidor. Isso importa porque as configurações YAML frequentemente contêm segredos (valores de Secret do Kubernetes, senhas de banco de dados, chaves de API, endpoints internos) que não deveriam ser enviados a um serviço de terceiros.

Qual é o limite de tamanho?

Sem limite rígido: o formatador roda na memória do seu navegador. Manifestos típicos do Kubernetes (alguns KB) e Helm charts (dezenas de KB) são formatados instantaneamente. Arquivos muito grandes com múltiplos documentos (vários MB) podem ser lentos, mas geralmente funcionam; se você tem um Helm chart de 10 MB, formate-o localmente com uma ferramenta de linha de comando.

Por que o YAML é tão propenso a erros?

Três razões que se somam: (1) o espaço em branco significativo faz com que erros de digitação causem mudanças semânticas silenciosas; (2) a coerção de tipo permissiva do YAML 1.1 transforma strings ambíguas em booleanos / números não intencionais; (3) o formato tem maneiras demais de escrever a mesma coisa (bloco vs. fluxo, aspas simples vs. duplas, três variantes de strings de múltiplas linhas). Os hábitos defensivos (sempre usar aspas, ser sempre consistente com a indentação, validar antes de implantar) resolvem a maior parte da superfície de risco.

Ferramentas relacionadas

Conversor JSON → YAML

Converta entre os formatos JSON e YAML.

Formatador JSON

Formate, valide e embeleze dados JSON.

Formatador XML

Formate, embeleze ou minifique XML.