YAML функции, потерянные при преобразовании JSON: комментарии, привязки и теги

Файл вернулся дольше и без единого комментария — конфиг YAML конвертированный в JSON и обратно, и всё, что не сохранилось

Файл YAML может возвращаться из JSON дольше, даже после исчезновения каждого комментария. Якоря, которые разделяли одно сопоставление, преобразуются в повторяющиеся данные объекта, поэтому сериализатор записывает каждую копию независимо. Ценности все еще могут совпадать, но авторская структура и объяснение исчезли.

Вот почему переход туда и обратно от YAML к JSON к YAML следует рассматривать как преобразование данных, а не сохранение источника. ToolAcre считывает график ограниченных значений и записывает новый документ. Он никогда не сохраняет конкретное синтаксическое дерево, содержащее комментарии, имена привязок, варианты кавычек или блочно-скалярное представление.

Комментарии — почему в JSON для них нет места и после конвертации исчезла каждая # строка

Комментарии отбрасываются анализатором YAML, поскольку JSON не имеет узла комментариев. Строка, начинающаяся с `#`, может объяснить, почему существует тайм-аут или кому принадлежит служба; после удаления ни один алгоритм не сможет определить формулировку или размещение. Обратное преобразование создает действительный YAML без этого рабочего контекста.

Сохраните исходный файл в системе контроля версий и просмотрите различия перед его заменой. Если целью является только проверка разрешенных значений, полезно использовать JSON. Если целью является переформатирование с сохранением комментариев, этот универсальный преобразователь значений является неправильным представлением.

Якоря и псевдонимы — &default и *default расширяются до повторяющихся копий, и как в результате увеличивается размер файла

Привязки и псевдонимы принимаются в пределах безопасности, а затем разрешаются. `base: &b {x: 1}` и `copy: *b` становятся двумя путями к объектам, содержащими `x: 1`. Выходные данные YAML используют `noRefs`, поэтому идентификатор общего объекта не создает новых привязок. Компактная связь исчезает, даже если повторяющиеся значения сохраняются.

Рекурсивные псевдонимы отклоняются, поскольку JSON не может выражать циклы. Расширение псевдонимов ограничивается количеством псевдонимов, вложением и измерением расширенного узла; короткий документ, который может быть преобразован в более чем один миллион значений, останавливается. Это защищает вкладку, не требуя произвольной поддержки YAML.

Ключи слияния — соглашение <<: из YAML 1.1, как парсеры, которые его поддерживают, сглаживают объединенное сопоставление и что происходит в тех, которые этого не делают.

В схеме предполагается, что ключи слияния YAML 1.1 сглажены. ToolAcre загружает только схему JSON или базовую схему js-yaml, ни одна из которых не поддерживает тип слияния. В этих схемах ключ `<<` представляет собой обычные данные, а не инструкцию по объединению сопоставлений. Поэтому представление плоского слияния как поставляемого поведения было бы неверным.

Если ваш источник зависит от семантики ключей слияния, разрешите его в приложении, которому принадлежит это соглашение, или явно перепишите значения перед преобразованием. Псевдоним, используемый в качестве значения обычного `<<`, по-прежнему может разрешаться в объект, но ключ остается `<<`; это не эквивалентно слиянию его членов с родительским.

Ключи слияния не поддерживаются двумя ограниченными схемами, поставляемыми в этом конвертере.

Стандартные явные теги, распознаваемые ограниченной схемой, могут выбирать базовые типы, такие как `!!str` или `!!int`. Пользовательские и более расширенные теги, включая двоичные теги, метки времени, наборы, упорядоченные карты, функции JavaScript и конструкторы объектов Python, отклоняются. Они не являются строковыми и никогда не выполняются.

Принимается поток YAML, разделенный `---`. Один документ становится одной ценностью; некоторые из них становятся массивом с предупреждением о количестве документов. Завершающий разделитель может создать пустой итоговый документ в соответствии с выбранной схемой. Ни одна из целей здесь не имеет потоковой модели, поэтому массив является объявленным соглашением.

Небезопасные теги отклоняются; потоки нескольких документов становятся массивами

Используйте `defaults: &d` с повторами и тайм-аутом, комментарий, объясняющий тайм-аут, затем `service:` с `inherited: *d`. JSON содержит как значения по умолчанию, так и повторяющийся унаследованный объект; комментарий и имя якоря отсутствуют. Преобразование этого JSON обратно создает два сопоставления, а не связь привязки.

Добавьте `---`, а затем еще один документ, и корень JSON станет массивом документов. Добавьте `!!binary`, и преобразование остановится с подсказкой об ограниченной схеме. Эти три изменения различают разрешенные поддерживаемые данные, структурные условности и полностью неподдерживаемые конструкции.

Чего это не касается — порядок ключей и стиль цитирования, которые обычно сохраняются, но не гарантируются ни одним из форматов.

Обычный порядок вставки объектов часто остается видимым, но это не сохранение исходного стиля, и выбор ключей сортировки намеренно меняет его. Цитаты, поточный стиль вместо блочного, скалярное написание и комментарии не сохранились. Дублирующиеся ключи сопоставления сохраняют последнее значение с предупреждением, а не сохраняют обе недопустимые записи.

Средство записи защищает неоднозначные строки, заключая значения в кавычки, которые потребитель YAML 1.1 может неправильно прочитать, но этот выбор безопасности может отличаться от исходного стиля автора. Равенство данных — это оправданный тест для обычных значений в форме JSON; текстовое равенство нет.

Порядок ключей может сохраняться, но комментарии, привязки, написание и стиль тегов не сохраняются.

YAML-to-JSON теряет смысл всякий раз, когда значение находится за пределами значения в форме JSON: комментарии, псевдонимы, неподдерживаемые теги, границы потока как таковые и стиль. ToolAcre делает несколько потерь видимыми и отказывается от опасных или циклических конструкций, вместо того, чтобы делать вид, что сохраняет их.

Прежде чем переходить к рабочему процессу, преобразуйте репрезентативный файл. Просматривайте предупреждения, различайте разрешенные значения и сохраняйте созданный YAML. Панель представляет собой отличный объектив для того, что видит анализатор, но она не является редактором, сохраняющим комментарии, или полноценным преобразователем объектной модели YAML.

При проверке миграции отделите изменения значений от изменений только исходного кода. Глубокое сравнение JSON может установить, сохранились ли обычные значения, а текстовые различия выявляют комментарии, привязки и стиль, которые обязательно изменились. Ни одна проверка не заменяет другую. Вызов сравнения значений без потерь приведет к игнорированию исходной информации; вызов каждого текстового изменения сбоем данных будет игнорировать допустимую повторную сериализацию.