YAML para JSON: convertendo configurações sem perder a cabeça

O que uma conversão de YAML para JSON realmente faz

YAML e JSON descrevem as mesmas formas — mapas, listas, strings, números, booleanos e nulos — então a conversão é principalmente uma questão de re-serializar uma sintaxe como a outra. O que muda é a superfície: o recuo se transforma em colchetes, os comentários desaparecem, as âncoras se tornam cópias e as strings multilinhas se transformam em `\n` escapes. Cada uma dessas transformações apresenta perdas de uma forma importante, e é por isso que vale a pena fazer a etapa de conversão deliberadamente, em vez de tratá-la como uma reflexão tardia de formatação.

A razão prática para converter é que JSON é o que a próxima ferramenta deseja. Kubernetes aceita YAML, mas `kubectl`, pipelines jq, chamadas API e JavaScript falam JSON com mais conforto. Converter uma vez, corretamente, é melhor do que editar manualmente dois formatos em paralelo.

Multidocumentos YAML: o problema silencioso do primeiro documento

Um arquivo YAML pode conter vários documentos separados por `---`. A maioria dos conversores retorna silenciosamente o primeiro e joga o resto fora – então, um pacote de manifesto com uma implantação, um serviço e um ConfigMap se torna um objeto sem aviso prévio. Uma conversão correta emite uma série de documentos ou pergunta explicitamente qual deles você deseja. Se um conversor não oferecer esse controle, ele estará perdendo dados.

Os erros devem apontar para uma linha e coluna

A tolerância de YAML com espaços em branco é exatamente o motivo pelo qual pequenos erros são difíceis de encontrar. Tabulações são ilegais para indentação, dois pontos ausentes transformam um mapeamento em uma string e chaves duplicadas são aceitas por alguns analisadores e rejeitadas por outros. Quando uma conversão falha, a única mensagem útil nomeia a linha e a coluna e mostra o trecho incorreto:

                spec:
  containers:
	- name: web      # tab used for indentation
error: line 3, column 0 — tabs cannot be used for indentation
              

Chaves duplicadas são o caso perigoso: os analisadores YAML geralmente mantêm o último valor e não dizem nada. Se `replicas: 3` aparecer duas vezes, o JSON obtido parece perfeitamente válido – e é o número errado.

Citando regras que sobrevivem à viagem

JSON é mais rigoroso com strings do que YAML, então as conversões adicionam aspas em torno de valores que estavam vazios. Isso é normal, mas duas peculiaridades de YAML causam erros reais: `yes`, `no`, `on` e `off` são booleanos em YAML 1.1, mas strings na semântica de JSON e valores de zero à esquerda, como códigos postais e números de telefone, perdem seu zero quando tratados como números. Se um campo precisar permanecer como uma string durante a conversão, cite-o na fonte.

Execute-o localmente, especialmente para configurações de cluster

Os manifestos Kubernetes carregam rotineiramente credenciais em objetos `Secret`, strings de conexão em ConfigMaps e tokens em arquivos CI. Colá-los em um serviço da Web os entrega a um servidor que você não controla. Um conversor baseado em navegador faz a análise e a serialização na mesma aba que você está lendo, então nada é transmitido – e uma página que continua funcionando com a rede cortada é uma prova disso, e não uma promessa.

Um fluxo de trabalho sensato

1. Valide o YAML primeiro e corrija qualquer linha, coluna e trecho relatado.
2. Escolha como os arquivos de vários documentos devem ser tratados – array ou um documento específico.
3. Converta com recuo que corresponda ao seu estilo de base de código (2 ou 4 espaços) e classifique as chaves se estiver diferenciando a saída.
4. Mantenha YAML como a fonte da verdade no git e trate JSON como um artefato gerado; os comentários ficam apenas no YAML.