O que é YAML

YAML, que significa recursivamente "YAML Ain't Markup Language", é um formato de serialização de dados projetado para ser legível por humanos. Foi criado em 2001 com o objetivo de ser mais simples e intuitivo do que formatos como XML e JSON para arquivos de configuração.

A principal característica do YAML é o uso de indentação (espaços) para definir a hierarquia dos dados, tornando os arquivos visualmente limpos e fáceis de entender sem a necessidade de colchetes ou chaves.

YAML é frequentemente descrito como "JSON sem as chaves e colchetes" — mas vai muito além disso, suportando comentários, múltiplos documentos em um arquivo e tipos de dados mais ricos.

O que é JSON

JSON (JavaScript Object Notation) é um formato leve de intercâmbio de dados derivado do JavaScript, mas completamente independente de linguagem. Criado por Douglas Crockford nos anos 2000, se tornou o padrão de facto para APIs web e comunicação entre sistemas.

JSON é baseado em dois tipos de estrutura: coleções de pares chave-valor (objetos) e listas ordenadas de valores (arrays). Sua sintaxe é estrita e não permite comentários, o que o torna previsível e fácil de analisar por máquinas.

Diferenças entre YAML e JSON

Apesar de representarem os mesmos tipos de dados, YAML e JSON têm diferenças importantes:

• Sintaxe: YAML usa indentação; JSON usa chaves {} e colchetes []
• Comentários: YAML permite comentários com #; JSON não suporta comentários nativamente
• Strings: YAML permite strings sem aspas em muitos casos; JSON exige aspas duplas
• Tipos de dados: YAML suporta mais tipos nativos, como datas e referências internas (&anchor e *alias)
• Verbosidade: JSON é mais verboso para estruturas profundamente aninhadas; YAML é mais compacto
• Performance: JSON é geralmente mais rápido de analisar por ser mais simples

Quando usar cada formato

A escolha entre YAML e JSON depende do contexto:

• Use JSON quando: comunicando com APIs REST, armazenando dados em bancos NoSQL (MongoDB), transmitindo dados entre sistemas ou quando a performance de parsing é crítica
• Use YAML quando: escrevendo arquivos de configuração (Docker Compose, Kubernetes, GitHub Actions, Ansible), definindo pipelines CI/CD ou criando arquivos de configuração que serão editados manualmente com frequência

Erros comuns na conversão

Ao converter entre YAML e JSON, alguns problemas são recorrentes:

• Indentação inconsistente: YAML é muito sensível à indentação — misturar tabs e espaços causa erros
• Strings especiais sem aspas: valores como true, false, null, yes, no são interpretados como booleanos em YAML
• Dois pontos em strings: em YAML, strings que contêm : precisam estar entre aspas
• Caracteres Unicode: YAML suporta Unicode nativamente, mas algumas parsers JSON têm limitações
• Comentários no YAML: comentários não são preservados na conversão para JSON

Casos de uso práticos

Situações reais onde a conversão YAML ↔ JSON é necessária:

• Converter configurações do Docker Compose (docker-compose.yml) para JSON para uso em scripts
• Transformar definições da OpenAPI/Swagger entre .yaml e .json
• Converter arquivos de configuração do Kubernetes para uso em ferramentas que esperam JSON
• Integrar sistemas legados que usam JSON com ferramentas modernas de DevOps que preferem YAML
• Validar a estrutura de dados antes de publicar arquivos de configuração em produção
• Converter respostas de APIs JSON para YAML para inclusão em documentação