YAML в JSON: конвертируйте манифесты, составляйте файлы и трубопроводы без потери данных

В прошлом году я провел день, отлаживая файл значений Helm, который, поклялся коллега, был правильным. Каждый ключ выглядел правильно. Сервис отказался запускаться. Виновником оказались четыре персонажа: NO как код страны, без кавычек, в списке регионов. парсер YAML прочитал его как логическое значение false, шаблон визуализирован false в заголовок, и запрос был отклонен вниз по течению с сообщением об ошибке, в котором не упоминались ни YAML, ни Норвегия. Эта ошибка достаточно известна, чтобы иметь имя - проблема Норвегии - и это лишь один из семейства сюрпризов, ожидающих в формате, который большинство из нас рассматривают как & quot;JSON с более приятным пробелом.& quot;

TL;DR: выше YAML в JSON конвертер анализирует документ YAML и печатает эквивалентный JSON, разрешая привязки, псевдонимы, ключи слияния и скаляры блоков по пути. просмотр конфигурации в JSON показывает вам, что именно синтаксический анализатор решил, что означают ваши значения - какие типы он вывел, какие ссылки он расширил - до того, как эта интерпретация достигнет кластера. Он полностью работает в вашем браузере.

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

Что на самом деле делает преобразование YAML в JSON?

Отношения определены, а не случайны: Спецификация ЯМЛ 1.2 утверждает, что YAML является супермножеством JSON, поэтому каждый документ JSON уже является действительным YAML. YAML и JSON описывают те же три вещи: отображения ключей в значения, упорядоченные последовательности и скаляры. Conversion обходит документ YAML и излучает каждую конструкцию в его эквиваленте JSON. Сопоставление блоков становится объектом. Последовательность блоков становится массивом. Скаляр становится строкой, числом, логическим значением или нулем, в зависимости от того, как схема ядра YAML разрешает его.

Структурная часть неинтересна, потому что она механическая. интересная часть - это все, что YAML может выразить, что JSON не может, потому что именно здесь конвертер должен принять решение от вашего имени:

Функция ЯМЛ	Что получает JSON	Почему это важно
Комментарии (# ...))	Сбросил	у JSON нет синтаксиса комментариев; документация в вашей конфигурации не сохранилась
Якоря и псевдонимы (&base, *base))	Расширенные копии	JSON не имеет опорного синтаксиса, поэтому общие блоки дублируются
Объединить ключи (<<: *base))	Сплющивается в предмет	Явные ключи переопределяют объединенные ключи согласно спецификации ключа слияния
Блокировать скаляры (`	, &gt;`)	Единственная струна с побегами
Несколько документов (---))	Массив документов	Пакет Kubernetes становится массивом JSON, по одному элементу на ресурс
Неявная типизация	Разрешенные типы	Нецитированный 8080 становится числом, true логическое, null нуль

Эта последняя строка - та, на которую стоит смотреть JSON заставляет каждое значение объявлять свой тип через синтаксис: кавычки означают строку, голые цифры означают число. YAML делает вывод о типе по форме текста. Преобразование в JSON делает вывод видимым. Если вы ожидали строку версии, и JSON вам покажет 1.1 где ЯМЛ сказал 1.10, вы нашли ошибку, которую в противном случае отправили бы.

Почему неявный набор текста YAML's вызывает реальные сбои

Схема ядра YAML 1.2 разрешает скаляр без кавычек по шаблону. Цифры становятся целыми числами. Цифры с десятичной точкой или показателем степени становятся плавающими. true а false стать булеанами. null а ~ стать нулевым Все остальное - строка.

Это звучит аккуратно, пока вы не достигнете значений, которые выглядят как один тип и подразумеваются как другой:

• Порты и идентификаторы. port: 08080 не является числом 8080. ведущий ноль делает его недопустимым целым числом под основной схемой, поэтому большинство парсеров возвращают строку, а некоторые старые интерпретируют ее как восьмеричную. Почтовые коды, номера телефонов и идентификаторы учетных записей с ведущими нулями имеют ту же проблему.
• Версии. version: 1.10 является поплавком 1.1. Задний ноль исчез, и ни один анализатор вас не предупреждает. Сравните это с тегом контейнера, и поиск не удался.
• Коды стран и языков. В YAML 1.1, которому по умолчанию по-прежнему следует PyYAML, а также в большом количестве инструментов Ruby и более старых Java y, n, yes, no, on, и off являются логическими. NO, ON, и NA это совершенно обычные двухбуквенные коды в реальном мире.
• Времена и шестидесятеричные. ЯМЛ 1.1 также анализирует 12:30 в виде числа по основанию 60, которое составляет 750. Строки, подобные Cron или длительности, могут исчезать в целых числах.

Каждый из них является тихим повреждением данных, а не ошибкой анализа. документ действителен, конвейер зеленый, и значение неверно. конвертер's Держите струны опция существует именно для этого класса исследования: включите его, и каждый простой скаляр возвращается в виде строки, поэтому вы можете сравнить два преобразования рядом и точно увидеть, какие значения синтаксический анализатор переосмысливал. Что бы JSON ни показал без этой опции, это то, что ваш производственный парсер, скорее всего, делает сегодня.

Исправление в вашем источнике YAML всегда одно и то же: цитируйте все, значение чего текстовое. port: "8080", version: "1.10", region: "NO". Цитаты ничего не стоят и удаляют всю категорию ошибок. Если вы генерируете YAML из JSON, а не пишете его, JSON в YAML конвертер применяет это автоматическое цитирование неоднозначных значений.

Как преобразуются якоря, псевдонимы и ключи слияния

Якоря - YAML's отвечают на повторение. Вы отмечаете узел &nameзатем обратитесь к нему позже *name,

defaults: &defaults
  restartPolicy: Always
  terminationGracePeriodSeconds: 30

web:
  <<: *defaults
  replicas: 3

worker:
  <<: *defaults
  terminationGracePeriodSeconds: 120

У JSON нет возможности сказать & quot; то же значение, что и там. & quot; так что конвертер расширяет каждую ссылку в полную копию Выход выше становится тремя объектами, каждый из которых несет свои собственные restartPolicy, и JSON длиннее, чем YAML, который его произвел Это не недостаток в преобразовании - это то, что означает YAML, выписанный.

Ключ слияния << заслуживает собственного примечания, потому что его правило приоритета легко получить назад Ключи, написанные явно в дочернем отображении выигрывают над ключами, втянутыми слиянием В примере, worker в конечном итоге с льготным периодом 120, а не 30, независимо от того, появляется ли линия слияния выше или ниже явного ключа. конвертер реализует это правило, поэтому JSON показывает вам эффективную конфигурацию после слияния - что обычно является тем, что вы действительно хотели проверить.

Из этого следуют два практических применения. во-первых, когда конфигурация использует тяжелое закрепление, преобразование в JSON - это самый быстрый способ ответить & quot; к чему на самом деле решает эта среда? & quot; без запуска развертывания. во-вторых, если псевдоним не имеет соответствующего якоря - распространенный результат разделения одного большого файла на несколько - конвертер сообщает об этом как об ошибке с номером строки, а не молча выдает нуль.

Как преобразуются скаляры блоков

У YAML есть два способа встроить многострочный текст, и они ведут себя по-разному:

• Буквальный (|)) сохраняет каждый разрыв строки точно таким, как написано. Используйте его для сценариев оболочки, сертификатов PEM, SQL и всего, что чувствительно к пробелам.
• Сложенный (>)) соединяет последовательные строки с одним пробелом и рассматривает пустую строку как разрыв абзаца. Используйте его для прозы, которую вы хотите завернуть в исходный файл, но добавить в значение.

Оба принимают индикатор chomping, который управляет конечными newlines. по умолчанию, называемый клиппинг, держит ровно одну конечную newline.A minus (минус)|-) снимает все последние линии. Плюс (|+) хранит каждого из них.

В JSON все это сворачивается в одну строку \n побеги. это еще одна причина, по которой точка зрения JSON полезна: она однозначна. А | блок, последняя строка которого случайно была отрезана, или a > блокируйте две линии, соединенные по складке, которые вы хотели сохранить отдельными, это очевидно в JSON и почти невидимо в YAML. Преобразователь также обрабатывает случай, который ловит наивные реализации - a # символ внутри буквального блока - это контент, а не комментарий, который имеет значение в тот момент, когда вы встраиваете сценарий оболочки, начиная с шебанга.

Как использовать конвертер YAML в JSON

Шаг 1: Вставьте документ

Вставьте любой YAML на панель ввода: манифест Кубернета, a docker-compose.ymlрабочий процесс GitHub Actions, учебник Ansible, a .gitlab-ci.yml, или конфигурация приложения. Многодокументные файлы с --- сепараторы в порядке - каждый документ анализируется независимо Нажать Образец нагрузки начнем с реалистичного развертывания, которое выполняет вложенные карты, последовательности, пустую коллекцию и скаляр буквального блока.

Единственное, что не будет анализировать, это отступ с символами табуляции. YAML запрещает вкладки сразу, и конвертер говорит так с номером оскорбительной строки, а не с гаданием.Редакторы, которые вставляют вкладку в Enter, являются обычным источником; у большинства есть & quot; конвертировать отступ в пробелы иquot; команда, которая исправляет весь файл сразу.

Шаг 2: Выберите выходную форму

Выбирать 2 пробела, 4 пробела, или Минимизированный. Минизированный - это то, что вы хотите, когда собираетесь вставить результат в a curl тело или переменная окружения. вывод с отступом - это то, что вы хотите, когда человеку нужно его прочитать.

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

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

Шаг 3: Преобразование и чтение ошибок

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

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

Шаг 4: Скопируйте, загрузите или продолжайте

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

Это соответствует реальным рабочим процессам

Отладка манифеста, который & quot; выглядит нормально& quot;

Когда развертывание ведет себя неожиданно и YAML читает правильно, преобразуйте его. Девять раз из десяти JSON показывает проблему сразу: значение, которое стало логическим, вложенный ключ на один уровень меньше, чем предполагалось из-за блуждающего пространства, якорь, который расширился до чего-то устаревшего. представление JSON устраняет двусмысленность пробелов, которая сделала ошибку невидимой.

Скрипт против конфигурации

Сценарии оболочки и узла изначально обрабатывают JSON; YAML нужна зависимость. Когда мне нужно вытащить каждый тег изображения из пакета манифестов, сначала преобразуя в JSON и проходя через него jq быстрее, чем добавление библиотеки YAML в одноразовый сценарий. поддержка мультидокументов converter's имеет здесь значение - пакет Kubernetes из шести ресурсов становится массивом JSON, который можно перебирать.

Строительные испытательные приспособления

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

Проверка конфигурации в запросе на вытягивание

Различия сильно закрепленного YAML трудно прочитать, потому что однострочное изменение якоря бесшумно меняет каждого потребителя. Преобразование обеих версий с Сортировать ключи включение и распределение JSON показывает истинный радиус взрыва: каждое измененное разрешенное значение, а не только отредактированную строку.

Миграция между инструментами

Множество платформ принимают JSON, но не YAML, или наоборот. Конвертация обычно является всей миграцией. Когда вам нужно вернуться в другую сторону - JSON в руке, YAML требует - JSON в YAML конвертер замыкает петлю, и Валидатор YAML подтверждает анализ результата перед его выполнением.

YAML и JSON сравнили

Размерность	бахвалиться	JSON
замечания	да	нет
Редактирование человека	На основе отступов, легко просматривать	Перфораторно-тяжелый, многословный
Машинный синтаксический анализ	Более медленные, большие парсеры, больше краевых корпусов	Быстрые, крошечные парсеры повсюду
Тип вывода	Неявный, схемазависимый	Явно из синтаксиса
справка	Якоря, псевдонимы, слияние клавиш	ни один
Несколько документов в файле	Да, через ---	нет
Типичный дом	Конфигурируйте файлы, конвейеры CI, манифесты	API, обмен данными, хранение

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

Конфиденциальность: почему это работает в вашем браузере

Файлы конфигурации являются одними из самых чувствительных артефактов открытого текста, которые есть у команды. Они содержат внутренние имена хостов, имена кластеров, пути к реестру, учетные записи служб, идентификаторы баз данных и - несмотря на все & #39;s из лучших побуждений - случайные учетные данные, которые еще не превратились в секретный менеджер.

Конвертер является клиент-сторона JavaScript Ваш документ анализируется на странице, JSON производится на странице, и ни один запрос не несет ваши данные где-либо Загрузите инструмент один раз и он продолжает работать с сетью выключен, что является разумной привычкой для всего, в что вы вставляете манифест Это тот же принцип за каждым инструментом на сайте, и аргументация изложена в руководстве на Конфиденциальность данных в онлайн-инстру. Если вы собираете набор инструментов для браузера общего назначения, Набор инструментов для веб-разработчиков руководство охватывает то, что еще в нем принадлежит.

Ограничения, которые стоит знать

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

Сложные ключи отображения - явные ? key форма, где ключ сам является последовательностью или отображением - не поддерживаются, потому что ключи объекта JSON должны быть строками. Введите теги, такие как !!binary или пользовательский !MyType директивы не интерпретируются; значение приходит через как текст. специальные значения float .inf, -.inf, и .nan сохраняются в виде строк, поскольку в JSON нет буквального значения для них и он молча преобразуется в null потеряет больше информации, чем сэкономит. Директивы, такие как %YAML 1.2 игнорируются, а не принимаются меры.

Ни один из них не появляется в обычных файлах Kubernetes, Compose, Actions или Ansible.Если вы нажмете один, вы работаете с документом, написанным для определенного языка & #39;s Библиотека YAML, и эта библиотека & #39;s собственный дампер - правильный инструмент.

часто задаваемые вопросы

Как конвертировать yaml в json онлайн?

Вставьте свой YAML в панель ввода и нажмите «Преобразовать». Парсер считывает документ, разрешает привязки и скаляры блоков, а также печатает форматированный JSON, который можно скопировать или загрузить. Все происходит в вашем браузере, поэтому файл не загружается.

Является ли JSON подмножеством YAML?

да. YAML 1.2 был переопределен как строгий надмножеств JSON, поэтому любой допустимый документ JSON также действителен. Обратное неверно: YAML добавляет комментарии, привязки, скаляры блоков, несколько документов для каждого файла и нестроковые ключи, ни один из которых не может выражаться непосредственно в JSON.

Как якоря и псевдонимы YAML преобразуются в JSON?

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

Что происходит с объединением клавиш, таких как двойной угловой кронштейн?

Связанное сопоставление сливается с текущим объектом. Ключи, написанные явно в дочернем сопоставлении, выигрывают по объединенным ключам, что соответствует поведению спецификации ключа слияния YAML, а также Kubernetes и инструментария Ansible.

Почему мой YAML потерпел неудачу из-за ошибки вкладок?

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

Могу ли я преобразовать многодокументный файл YAML с помощью разделителей документов?

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

Сохранят ли номера портов и строки версии свой тип?

Простые скаляры разрешаются базовой схемой YAML, поэтому некотируемый 8080 становится числом 8080, а некотируемый 1.10 становится 1.1. Цитируйте значение в своем YAML, чтобы сохранить строку, или включите опцию "Сохранить строки", чтобы отключить всю скалярную коэрцицию.

Как преобразуются скаляры буквальных и сложенных блоков?

Буквальный блок сохраняет каждую новую строку, поэтому он становится строкой JSON со снятыми разрывами строк. Сложенный блок соединяет последовательные строки с пробелом и обрабатывает пустые строки как разрывы абзацев. Показатели сжимания соблюдаются: минус опускает конечную новую строку, а плюс сохраняет каждую конечную пустую строку.

---