Converter vários documentos YAML em JSON

Como os documentos são separados

Uma linha com --- inicia um novo documento. O marcador ... pode encerrar explicitamente o documento atual, embora nem sempre seja necessário.

Os separadores precisam fazer parte da sintaxe YAML, e não de um bloco literal ou string.

Representação em JSON

Este conversor retorna um array JSON quando há mais de um documento. Cada posição preserva o valor raiz do documento YAML correspondente.

Quando existe apenas um documento, sua raiz é mantida sem criar um array desnecessário.

O que revisar

Confirme se o sistema de destino espera um objeto, um array ou arquivos independentes. Muitos consumidores aceitam apenas um valor JSON.

Documentos vazios entre separadores também merecem atenção, pois podem virar valores nulos.

Fluxo confiável passo a passo

Trate fluxos YAML com vários documentos como uma transformação de dados com entrada, estrutura esperada e destino definidos. Trabalhe em uma cópia, valide antes de mudar a representação e isole uma amostra mínima. Isso separa falhas de sintaxe de problemas do modelo de dados ou da aplicação.

Faça uma alteração por vez e repita a mesma validação. Em pipelines automatizados, interrompa o processo diante de um erro do analisador, em vez de publicar um resultado parcial ou presumido. Preserve a entrada original junto do artefato gerado quando precisar de rastreabilidade.

• Comece com uma entrada representativa e preserve uma cópia intacta para revisar ou repetir a transformação.
• Inspecione a estrutura analisada, não só o texto exibido: chaves, tipos escalares, ordem das listas e valores nulos são o que o sistema de destino recebe.
• Teste o resultado no destino real e registre as premissas de analisador, esquema, codificação e formatação.

Exemplo prático e verificação

O exemplo abaixo é pequeno de propósito para permitir inspeção visual. Aplique o mesmo método a um documento real: confirme cada chave, tipo escalar, ordem de lista e limite de aninhamento antes de aceitar a saída.

Uma conversão ou minificação concluída só comprova que a entrada pôde ser analisada. Compare o valor estruturado antes e depois e carregue o resultado com a mesma biblioteca ou plataforma que o consumirá em produção.

---
name: first
---
name: second

Limites e casos especiais

Os casos difíceis de fluxos YAML com vários documentos geralmente surgem quando validade sintática é confundida com validade para a aplicação. Um analisador pode aceitar dados incompletos, ambíguos, grandes demais ou incompatíveis com o esquema de destino.

Não corrija nem normalize às cegas um documento desconhecido. Chaves duplicadas, tipos implícitos, aliases, precisão numérica, Unicode, finais de linha e entradas enormes exigem uma política explícita. Se o destino tiver regras mais rígidas, elas prevalecem.

Checklist para produção

Antes de publicar, teste um documento normal, um valor vazio, dados muito aninhados, texto não ASCII e um exemplo malformado. Registre a versão da ferramenta ou biblioteca se outro sistema precisar reproduzir exatamente a saída.

Inclua a validação no CI quando os dados afetarem builds, implantações, APIs ou configuração. Revise diferenças, mantenha uma cópia para reversão e monitore o primeiro consumidor após a implantação.

• Comece com uma entrada representativa e preserve uma cópia intacta para revisar ou repetir a transformação.
• Inspecione a estrutura analisada, não só o texto exibido: chaves, tipos escalares, ordem das listas e valores nulos são o que o sistema de destino recebe.
• Teste o resultado no destino real e registre as premissas de analisador, esquema, codificação e formatação.