YAML recursos perdidos em uma conversão JSON: comentários, âncoras e tags

O arquivo voltou mais tempo e sem um único comentário — uma configuração YAML convertida para JSON e vice-versa, e tudo que não sobreviveu

Um arquivo YAML pode retornar de JSON por mais tempo, mesmo depois que cada comentário desaparece. As âncoras que compartilhavam um mapeamento são resolvidas em dados de objetos repetidos, de modo que o serializador grava cada cópia de forma independente. Os valores ainda podem concordar, mas a estrutura de autoria e a explicação desapareceram.

É por isso que uma viagem de ida e volta de YAML-to-JSON-to-YAML deve ser julgada como conversão de dados, não como preservação de fonte. ToolAcre lê um gráfico de valores restritos e grava um novo documento. Ele nunca retém uma árvore de sintaxe concreta contendo comentários, nomes de âncoras, opções de cotação ou apresentação escalar de bloco.

Comentários — por que JSON não tem lugar para eles e cada # linha desaparece após a conversão

Os comentários são descartados pelo analisador YAML porque JSON não possui nó de comentários. Uma linha começando com `#` pode explicar por que existe um tempo limite ou quem possui um serviço; uma vez removido, nenhum algoritmo pode inferir o texto ou posicionamento. A conversão de volta cria YAML válido sem esse contexto operacional.

Preserve o arquivo original no controle de versão e revise as diferenças antes de substituí-lo. Se o objetivo é apenas inspecionar valores resolvidos, JSON é útil. Se o objetivo é reformatar mantendo os comentários, este conversor de valor genérico é a representação errada.

Âncoras e aliases — &default e *default expandidos em cópias repetidas e como o arquivo cresce como resultado

Âncoras e aliases são aceitos dentro dos limites de segurança e depois resolvidos. `base: &b {x: 1}` e `copy: *b` tornam-se dois caminhos de objeto contendo `x: 1`. A saída YAML usa `noRefs`, portanto, a identidade do objeto compartilhado não cria novas âncoras. O relacionamento compacto desaparece mesmo quando os valores repetidos sobrevivem.

Aliases recursivos são recusados ​​porque JSON não pode expressar ciclos. A expansão de alias é limitada pela contagem de alias, aninhamento e medição de nó expandido; um documento curto que seria restringido em mais de um milhão de valores é interrompido. Isso protege a guia sem reivindicar suporte YAML arbitrário.

Chaves de mesclagem - a convenção <<: de YAML 1.1, como os analisadores que a suportam nivelam o mapeamento mesclado e o que acontece naqueles que não o suportam

O esboço pressupõe que YAML 1.1 chaves de mesclagem sejam niveladas. ToolAcre carrega apenas o esquema JSON ou Core do js-yaml, nenhum dos quais habilita o tipo de mesclagem. Nesses esquemas, uma chave `<<` são dados comuns, em vez de uma instrução para mesclar mapeamentos. Apresentar uma mesclagem nivelada como comportamento enviado seria, portanto, falso.

Se a sua fonte depende da semântica da chave de mesclagem, resolva-a no aplicativo que possui essa convenção ou reescreva os valores explicitamente antes da conversão. Um alias usado como valor de `<<` comum ainda pode ser resolvido para um objeto, mas a chave permanece `<<`; isso não é equivalente a mesclar seus membros no pai.

As chaves de mesclagem não são habilitadas pelos dois esquemas restritos que este conversor envia

Tags explícitas padrão reconhecidas pelo esquema restrito podem escolher tipos básicos, como `!!str` ou `!!int`. Tags personalizadas e mais ricas – incluindo binário, carimbo de data/hora, conjunto, mapa ordenado, função JavaScript e construtores de objeto Python – são rejeitadas. Eles não são restringidos e nunca são executados.

Um fluxo YAML separado por `---` é aceito. Um documento torna-se um valor; vários se tornam uma matriz com um aviso nomeando a contagem de documentos. Um separador final pode criar um documento final vazio de acordo com o esquema selecionado. Nenhum alvo aqui possui um modelo de fluxo, então o array é uma convenção declarada.

Tags inseguras são recusadas; fluxos de vários documentos tornam-se matrizes

Use `defaults: &d` com novas tentativas e tempo limite, um comentário explicando o tempo limite e, em seguida, `service:` com `inherited: *d`. JSON contém padrões e um objeto herdado repetido; o comentário e o nome da âncora estão ausentes. A conversão de JSON de volta emite dois mapeamentos em vez de um relacionamento de âncora.

Adicione `---` seguido por outro documento e a raiz JSON se tornará uma matriz de documentos. Adicione `!!binary` e a conversão será interrompida com uma dica de esquema restrito. Essas três mudanças distinguem dados suportados resolvidos, convenção estrutural e construção totalmente não suportada.

O que isso não cobre — ordem das chaves e estilo de cotação, que geralmente sobrevivem, mas não são garantidos por nenhum dos formatos

A ordem comum de inserção de objetos geralmente permanece visível, mas não é uma preservação do estilo de origem, e a seleção de chaves de classificação a altera deliberadamente. Citações, fluxo versus estilo de bloco, ortografia escalar e comentários não sobrevivem. As chaves de mapeamento duplicadas mantêm o último valor com um aviso em vez de preservar ambas as entradas inválidas.

O escritor protege strings ambíguas citando valores que um consumidor YAML 1.1 pode interpretar mal, mas essa escolha de segurança pode diferir do estilo original do autor. A igualdade de dados é o teste defensável para valores comuns em formato JSON; a igualdade textual não é.

A ordem das teclas pode permanecer, enquanto os comentários, as âncoras, a ortografia e o estilo das tags não são preservados

YAML-to-JSON apresenta perdas sempre que o significado está fora do valor em forma de JSON: comentários, aliases, tags não suportadas, limites de fluxo como tal e estilo. ToolAcre torna visíveis várias perdas e recusa construções perigosas ou cíclicas em vez de fingir preservá-las.

Converta um arquivo representativo antes de adotar o fluxo de trabalho. Inspecione os avisos, compare os valores resolvidos e mantenha o YAML de autoria. O painel é uma lente excelente para o que um analisador vê, mas não é um editor de preservação de comentários ou um transformador de modelo de objeto YAML completo.

Para uma revisão de migração, separe as alterações de valor das alterações somente de origem. Uma comparação profunda JSON pode estabelecer se os valores comuns sobreviveram, enquanto uma comparação de texto revela comentários, âncoras e estilo que necessariamente mudaram. Nenhum cheque substitui o outro. Chamar a comparação de valores de sem perdas ignoraria as informações de origem; chamar cada alteração textual de falha de dados ignoraria a re-serialização válida.