YAML e JSON: preserve os dados, não a aparência do arquivo
Uma configuração em YAML pode precisar virar JSON para outro serviço. Estruturas parecidas não significam que tudo no arquivo tenha representação equivalente.
O tipo vale mais que a aparência
A string "003" não é o número 3, nem "false" entre aspas é o booleano false. Use texto para identificadores cujo zero inicial ou grafia exata importa.
O conversor aceita dados YAML 1.2 Core compatíveis com JSON. Não transfira expectativas de sistemas antigos automaticamente: certas palavras podem ser interpretadas de outra forma em versões diferentes.
Referências: YAML 1.2.2 — Core types and comments as presentation
Comentários falam com quem mantém o arquivo
Comentários ajudam na manutenção do YAML, mas não integram os dados. Aqui não passam ao JSON nem reaparecem ao converter de volta.
Guarde a fonte comentada e trate o resultado como exportação de dados. Cores de sintaxe e ordem familiar das linhas não comprovam tipos corretos.
Referências: YAML 1.2.2 — Core types and comments as presentation
Rejeitar evita perda silenciosa
O fluxo aceita um documento com chaves textuais. Rejeita chaves duplicadas, aliases, âncoras, tags personalizadas e recursos fora do mapeamento suportado.
Números fora do intervalo representável são rejeitados, não arredondados silenciosamente. Use texto para identificadores longos. Converter não executa a configuração nem prova aceitação pelo serviço de destino.
Exemplo: três tipos intencionalmente diferentes
code: "003", enabled: false e retries: 3 produzem a string "003", o booleano false e o número 3. Os zeros ficam porque code é texto, não por uma inferência sobre identificadores.
Adicionar # staging antes não cria propriedade JSON. Ao voltar para YAML, aspas e formatação podem mudar, mantendo valores e tipos; o comentário original não retorna.