Converter JSON para YAML

JSON e YAML 1.2 descrevem a mesma família de dados: objetos com chaves, arrays ordenados, strings, números, booleanos e `null`. Nesta conversão, o navegador primeiro lê o JSON para uma estrutura JavaScript e o escritor de YAML serializa essa mesma árvore. Um objeto dentro de `spec.template.spec`, por exemplo, continua aninhado; uma lista de contêineres continua sendo uma lista; `false` não vira texto e `null` não vira campo vazio. Não existe a transformação em colunas que seria necessária ao sair para CSV ou XLSX, portanto níveis profundos não são condensados em nomes pontuados.

É por isso que YAML 1.2 define JSON como um subconjunto: um documento JSON válido já pertence ao espaço de documentos que um leitor YAML 1.2 entende. A conversão serve para mudar a representação, não o modelo. Isso combina bem com um manifesto exportado por uma API, uma política gerada por código ou uma configuração que chegou cheia de aspas e chaves, mas passará a ser mantida em um repositório. O ganho é de leitura e edição; não aparece um campo novo, uma regra de negócio ou um comentário que não existia na origem.

A promessa de preservar a árvore começa depois que o parser do navegador conseguiu representar o JSON. Números JSON são lidos como números JavaScript, portanto inteiros acima da faixa segura podem perder precisão antes de o serializador YAML recebê-los. Um identificador como `9007199254740993`, escrito sem aspas, pode chegar à etapa seguinte com outro último dígito. CPF, CNPJ, código de rastreio, chave de banco e identificador de pedido não são quantidades para cálculo: mantenha esses valores como strings no JSON, especialmente quando houver muitos dígitos ou zeros à esquerda.

Chaves repetidas são outro problema de entrada, não de YAML. Em `{"porta": 8080, "porta": 9090}`, o parser conserva apenas a última ocorrência, porque um objeto JavaScript só pode ter um valor por chave. O resultado será YAML válido com `porta: 9090`, mas a primeira definição já terá desaparecido. Validadores de JSON mais rigorosos costumam sinalizar duplicatas; o parser usado na conversão não fornece uma segunda representação para guardá-las. Quando o arquivo veio de uma ferramenta desconhecida, vale procurar chaves repetidas e revisar números longos antes de tratar qualquer serialização como uma cópia perfeita.

As chaves de um objeto aparecem em linhas `chave: valor`, e cada nível acrescenta recuo. A saída atual usa YAML em estilo de bloco, com dois espaços para o conteúdo aninhado. Arrays recebem um hífen por item. Assim, uma lista JSON de serviços como `[{"nome":"api","porta":8080},{"nome":"worker","porta":8081}]` vira duas entradas claramente separadas, cada uma com `nome` e `porta` alinhados. É a forma reconhecível em manifestos de Kubernetes, etapas de pipelines e arquivos Compose, e permite enxergar onde um item termina sem contar chaves de fechamento.

A ordem de listas é parte dos dados e permanece intacta. A ordem visual das chaves também acompanha a enumeração do objeto criado pelo JavaScript, o que normalmente mantém a sequência do JSON. Existe uma exceção técnica: chaves que parecem índices inteiros, como `"2"` e `"10"`, seguem as regras de ordenação de propriedades do JavaScript e podem aparecer antes das demais. Como a ordem de chaves de um objeto não deveria carregar significado, isso não muda a árvore; ainda assim, pode produzir um diff inesperado. Se a sequência é semântica, represente-a como array, não como objeto numerado.

O escritor segue YAML 1.2. Nessa versão, as palavras nuas `no`, `yes`, `on` e `off` são strings comuns, por isso a saída atual pode deixá-las sem aspas. Um leitor 1.2 recupera exatamente o texto original. O problema aparece quando o arquivo segue para um leitor baseado nas regras de YAML 1.1: ali essas palavras podem ser resolvidas como booleanos. Uma resposta `"no"`, um código de país ou uma flag legada pode virar `false` sem que o arquivo deixe de ser sintaticamente válido. Essa diferença de interpretação é mais perigosa que um erro explícito, porque a aplicação continua rodando com outro valor.

Leitores configurados com regras de YAML 1.1 são o caso que merece atenção. Se qualquer etapa posterior usar essas regras, procure valores nus iguais a `yes`, `no`, `on` e `off` e coloque aspas manualmente. Faça a conferência nos valores, não apenas nas chaves: `enabled: false` é um booleano intencional, enquanto `resposta: no` talvez fosse uma string. O objetivo não é encher o arquivo de aspas, e sim tornar explícitos os poucos pontos em que duas versões do padrão discordam sobre o tipo.

Aspas são escolhidas valor por valor. A string JSON `"1.0"` precisa continuar texto, então sai entre aspas para não ser lida como número. O mesmo vale para `"null"`, que não pode se confundir com o valor nulo, para `"#hash"`, cujo primeiro caractere poderia iniciar um comentário, e para strings com espaço no começo ou no fim. Já números e booleanos reais saem sem aspas: `8080`, `3.5`, `true` e `false` mantêm seus tipos. Essa economia deixa o YAML legível sem transformar toda configuração numa parede de pontuação.

Datas com formato ISO pedem uma revisão separada. Na saída atual, uma string como `"2024-01-01"` pode aparecer como `2024-01-01`, sem aspas, porque YAML 1.2 a trata como texto. Leitores 1.1 podem resolvê-la como timestamp. Para uma data de vigência, talvez o programa aceite os dois; para um código de versão, uma partição ou uma chave de mapa, a troca de tipo pode quebrar validação e comparação. Se o consumidor não declara claramente YAML 1.2, colocar aspas em datas e nas quatro palavras ambíguas é uma defesa pequena, localizada e fácil de revisar.

No JSON, uma quebra de linha dentro de uma string aparece escapada como `\n`. Um script de inicialização, uma consulta SQL ou uma mensagem com dez linhas vira uma sequência longa em uma única linha lógica, e uma alteração no meio dela é difícil de conferir. O serializador YAML transforma strings com quebras em escalares de bloco: coloca um `|` e escreve o conteúdo nas linhas seguintes, com recuo. As quebras deixam de ser códigos espalhados no texto e voltam a ocupar o lugar em que uma pessoa espera vê-las.

Pense num `ConfigMap` com um pequeno script de shell ou numa pipeline que incorpora um arquivo de configuração. Depois da conversão, um revisor consegue comparar comandos linha por linha, perceber uma opção removida e comentar o motivo da mudança. O conteúdo continua sendo uma única string, não um array de linhas. O indicador do bloco e a forma como ele termina dizem ao parser como tratar a quebra final; por isso não remova símbolos ou recuos apenas para deixar o arquivo mais compacto. Em YAML, o recuo faz parte da sintaxe, não é decoração aplicada por um formatador.

JSON não possui comentários em sua gramática, então não há comentário para transportar. O YAML gerado também não inventa nenhum. Isso é importante quando a origem veio de JSON com uma extensão informal, como arquivos que aceitam `// comentário` ou vírgula final: o parser padrão do navegador considera essas construções JSON inválido e a conversão para antes de produzir a saída. Remova a sintaxe específica da ferramenta ou exporte JSON estrito primeiro; aceitar silenciosamente um dialeto seria arriscar interpretar o documento de outra maneira.

A possibilidade de comentar é, porém, uma boa razão para adotar o YAML depois. Acrescente contexto que não cabe no valor: por que `replicas` é três, qual serviço depende daquele nome, por que o timeout não deve ser reduzido, quem renova um certificado ou qual ambiente pode usar determinada imagem. Evite comentários que apenas repetem `porta: 8080` em palavras. O arquivo convertido fornece um ponto de partida fiel à estrutura disponível; a explicação operacional precisa vir de quem conhece o sistema, porque nenhum conversor consegue deduzi-la do JSON.

YAML permite âncoras e aliases para definir um bloco uma vez e reutilizá-lo, documentos múltiplos separados por `---` e tags que orientam um parser sobre tipos específicos. Nada disso tem equivalente direto no modelo JSON usado como origem. Por esse motivo, a conversão não cria âncoras ao encontrar objetos parecidos, não divide automaticamente um array em vários documentos e não adivinha tags. Repetição presente no JSON continua repetida no YAML, que é a escolha previsível quando a ferramenta não conhece a intenção por trás dos dados.

Esses recursos podem ser adicionados depois, mas com critério. Uma âncora ajuda quando três serviços realmente compartilham a mesma política e devem mudar juntos; ela atrapalha quando a semelhança é apenas coincidência. Um array de manifestos pode precisar virar vários documentos para uma ferramenta específica, mas também pode ser uma lista válida esperada por outra API. A conversão preserva o que consegue demonstrar. Refatorar a configuração, escolher fronteiras entre documentos e criar abstrações são decisões de manutenção, não tarefas seguras para um serializador automático.

Considere uma configuração de integração com `{"cep":"01310-100","tentativas":3,"ativo":false,"inicio":"2024-01-01"}`. O CEP deve continuar string porque contém hífen e pode começar com zero; `tentativas` deve continuar número porque participa de cálculo; `ativo` deve continuar booleano; e `inicio` merece aspas na saída se um consumidor antigo puder tratá-lo como data. O mesmo raciocínio vale para CPF, CNPJ, DDD, número de agência e IDs emitidos por outro sistema. A aparência numérica não transforma um identificador em quantidade.

Em manifestos de infraestrutura, o equivalente é separar tipo de conveniência visual. `containerPort: 8080` é número; uma variável de ambiente com valor `"8080"` frequentemente é string porque o processo a recebe como texto; `image: "registry.interna/equipe/api:2024-01-01"` é uma referência inteira, não uma data. Depois de converter, leia os campos que cruzam limites entre sistemas e confira o esquema do consumidor. YAML oferece mais maneiras de escrever o mesmo valor que JSON, e exatamente por isso o tipo percebido pelo parser seguinte deve fazer parte da revisão.

A primeira validação deve ser feita pela ferramenta que realmente consumirá o arquivo. Para Kubernetes, um `kubectl apply --dry-run=client` verifica a leitura e a estrutura conhecida pelo cliente; para Compose, `docker compose config` resolve e apresenta a configuração; para uma pipeline, use o linter ou validador associado ao serviço. Um parser YAML genérico confirma sintaxe, mas não sabe que `replicas` deveria ser número, que uma chave foi colocada no nível errado ou que uma versão de API não existe no ambiente de destino.

Depois, faça uma busca dirigida pelos casos que passam em qualquer parser: `yes`, `no`, `on`, `off`, datas nuas, identificadores longos e strings que perderiam zeros à esquerda se fossem números. Compare também a quantidade de itens das listas e as chaves principais do JSON original. Um teste de dry run pode aceitar um valor com significado indesejado, enquanto uma comparação visual pode não perceber que o runtime converteu seu tipo. Usar as duas verificações cobre problemas diferentes sem exigir uma auditoria linha por linha de um arquivo grande.

YAML é melhor quando pessoas precisam editar, comentar e revisar uma estrutura aninhada. JSON costuma ser melhor quando o arquivo é apenas uma saída de máquina, atravessa APIs ou será regenerado a cada execução. A pontuação explícita do JSON reduz ambiguidades de versão e torna mais óbvio onde strings começam e terminam. Converter um artefato gerado para YAML e depois editá-lo à mão cria duas fontes de verdade; na próxima exportação, a versão comentada pode ser sobrescrita ou divergir silenciosamente do sistema que a produziu.

Decida com base no ciclo de vida. Um manifesto exportado uma vez e adotado pelo repositório se beneficia da conversão. Um snapshot usado apenas para depuração provavelmente deve continuar JSON. Uma configuração que precisa de comentários duráveis favorece YAML; um payload assinado, comparado byte a byte ou enviado a uma API deve permanecer no formato exigido pelo protocolo. O conversor muda a forma de leitura, não o contrato do sistema seguinte. Se esse sistema pede JSON, uma extensão `.yaml` mais agradável para humanos não cria compatibilidade.

O arquivo é lido nesta aba pelo parser JSON do navegador, e o YAML é escrito por uma biblioteca carregada para a conversão. O par está registrado como processamento no cliente, portanto o documento não precisa ser enviado a um servidor para virar YAML. Isso importa para manifestos que revelam nomes de clusters, caminhos de registry, contas de serviço, URLs internas e referências a segredos. Referência não é o segredo em si, mas ainda descreve a arquitetura e pode ser informação que a equipe não quer colocar num conversor remoto.

O limite gratuito registrado para essa conversão é de 100 MB. A implementação lê o texto inteiro e mantém a árvore em memória antes de gerar a saída, então o consumo real é maior que o tamanho do arquivo no disco. Um manifesto comum fica muito abaixo disso; um dump enorme de API talvez não seja mais configuração e pode merecer processamento por streaming em uma ferramenta local. Para vários arquivos, revise cada saída no contexto do consumidor em vez de juntar documentos por conta própria: converter e combinar são operações diferentes, e só a segunda exige decidir fronteiras.