JSON в YAML конвертер: конвертируйте конфиги без проблемы Норвегии

В первый раз, когда YAML правильно сожгла меня, это был код страны. Я перемещал конфигурацию локали из файлов JSON проекта Laravel в удобный для развертывания формат YAML, когда я пошел, потому что «это просто меняет скобки на отступ». "country": "NO". В YAML без кавычек этот 's не является строкой - в соответствии с правилами YAML 1.1, которые все еще применяются PyYAML и многие другие парсеры, NO Булево false, йо- Сценарий развертывания, написанный на Python, весело оценивает норвежских пользователей как country: false и направил их в запасной локаль. у этой ошибки есть имя - сообщество называет это проблемой Норвегии - и я обнаружил это кустарным способом, по одному запутанному билету поддержки за раз.

Преобразование ручного преобразования JSON в YAML выглядит тривиально и на самом деле является минным полем, потому что в этих двух форматах есть совершенно разные представления о том, что означает голое слово. В JSON все явно: строки имеют кавычки, числа не, true/false/null являются ключевыми словами, концом истории. В YAML не цитируется скаляр интерпретированный, no становится ложным, 3000 становится целым числом, 1.10 становится плавающим 1.1 (до свидания, строка версии), 08 подавляет некоторые парсеры как недопустимую восьмеричную дробь, и значение с блуждающим пространством двоеточия становится вложенной картой, когда вы меньше всего этого ожидаете. Каждый из них является тихим повреждением данных - файл хорошо анализируется, типы просто неправильные.

равняется JSON в YAML конвертер это понимает эти правила получает вас читабельность YAML был изобретен для без типа рулетки. тот, который я построил для Toolz.dev обнаруживает каждый неоднозначный скаляр - логические двойники, числовые двойники, устаревшие значения YAML 1.1, строки со специальными символами - и цитирует именно их, так что то, что было строкой в вашем JSON, все еще является строкой после того, как следующий инструмент анализирует YAML. Это "точно те " имеет значение: цитирование все Было бы безопасно, но выход перестает выглядеть как идиоматический yaml, и идиоматический вся в этом смысл.

В этом руководстве рассматривается, как преобразование обрабатывает острые края YAML, почему JSON уже является YAML (и почему этот факт вам не помогает), а рабочими процессами Kubernetes, CI и Docker составляют рабочие процессы, где это преобразование происходит еженедельно.

TL;DR: Вставьте JSON в Toolz.dev json в конвертер YAMLвыберите отступ в 2 или 4 пространства и получите чистый YAML в блочном стиле с безопасным для типа цитированием - "3000" Остается струной, "no" Остается струной, "1.10" Остается версией. Ключевой порядок сохранен, пустые коллекции выходят как [] а {}, и все работает на стороне клиента, поэтому конфиги с секретами никогда не покидают ваш браузер. Обратно-поездка с Валидатор YAML, и отформатируйте источник сначала с помощью Форматтер JSON, йо-

Является ли JSON уже действительным YAML?

Да - и it's самый бесполезный & quot;yes& quot; в управлении конфигурацией. YAML 1.2 был явно разработан как надмножество JSON: каждый действительный документ JSON анализируется как действительный YAML. Вы можете вставить необработанный JSON в манифест Kubernetes и kubectl принял бы это.

Никто этого не делает, потому что причина, по которой существует yaml, эргономика человека. Манифесты Kubernetes, рабочие процессы GitHub Actions, файлы Docker Compose, проигрыватели Ansible, конфигурации Home Assistant - это YAML, потому что люди постоянно их читают и редактируют вручную, и replicas: 3 при сканировании с отступом лучше, чем {"replicas":3} Вложенные в скобки. Когда кто-то говорит: «Преобразовать JSON в YAML», они имеют в виду блочный YAML: вдавливаем вместо брекетов, - Штрихи вместо массивов с скобками, без кавычек, где их нет.

В последнем пункте живет трудность. Переход от JSON «все явный синтаксис» к минимальному синтаксису YAML Решая, для каждой струны, может ли она смело потерять свои котировки- и это решение требует знания правил скалярного разрешения YAML's лучше, чем большинство людей надежно делают это в 17:00 в пятницу. Это и #39;s фактическая работа преобразователя; часть скобок в отступы тривиальна.

Что ломается тихо, когда вы переделываете вручную?

Случаи сбоев делятся на четыре семьи, и я поразил каждого из них в реальных конфигах:

Логические двойники. YAML 1.1 разрешает yes, no, on, off, y, n (в разных оболочках) как булевы, а YAML 1.2 сохраняет true/false. PyYAML - по-прежнему библиотека YAML по умолчанию в большинстве кодовых баз Python - реализует 1.1. Итак "debug": "no" преобразованный в ручную debug: no становиться debug: false в вашем инструменте развертывания Python. проблема Норвегии (NO → false) и его двоюродный брат проблема Онтарио (ON → true) являются лучшими хитами этой семьи.

двойники. "port": "3000" преобразованный в port: 3000 теперь является целым числом. Kubernetes делает ' плевать в одних полях и с трудом в других - например, значения env var должны быть строками, и kubectl apply отклонит там целое число с ошибкой, которая именует поле, но не почему, йо- Строки версий хуже, потому что ничего не выходит из строя: version: 1.10 синтаксический анализ как поплавок 1.1и ваш сценарий развертывания с радостью сообщает неверную версию навсегда. Ведущие нули - почтовые индексы, номера телефонов, восьмеричные идентификаторы типа 0755- завершать семью.

специальные символы. двоеточие, за которым следует пробел внутри не процитируемого значения, запускает сопоставление (message: error: not found является ошибкой синтаксического анализа или вложенной картой, в зависимости от анализа). равняется # Запускает комментарий в середине значения. ведущий *, &, ! Столкнувшись с якорем YAML, псевдонимом и синтаксисом тегов. Строки с новыми строками нуждаются в сбросе или блокировке скаляров.

пустая струна. Не цитируемая пустота в YAML null, не "", йо- Любое поле JSON, содержащее пустую строку, должно выйти в кавычки или изменить тип.

выше преобразователь сверяет каждую строку со всеми четырьмя семействами и цитирует те, которые в ней нуждаются - и только те. production Выходит голым, потому что это однозначно; "3000", "no", "1.10", и "" Выходите цитируемым, потому что они не являются. Есть также «цитата» всех строк», когда вы кормите синтаксический анализатор, которому не доверяете, и не хотите, чтобы вообще не было скалярного разрешения.

Как преобразовать json в yaml с помощью инструмента?

Шаг 1: Вставьте свой JSON

Любой действительный JSON работает - объекты, массивы, глубокое гнездование, юникод. Кнопка Загрузить образец дает вам реалистичную конфигурацию службы, которая выполняет интересные случаи: цифровой порт строки, логическое значение, пустой массив, вложенные карты. Если на вашем входе есть проблемы с синтаксисом, конвертер сообщает синтаксический анализатор's точная ошибка, а не преобразование усеченного документа; для поиска вниз где Ошибка в большом капле, Форматтер JSON это лучший микроскоп.

Шаг 2: Выберите отступ

Два пробела или четыре. Два - это подавляющее соглашение: документы Kubernetes, примеры действий GitHub, ссылки на Docker Compose и yamllint по умолчанию все используют его - но некоторые команды стандартизируют четыре для читаемости в глубоком вложенье. какой бы вы ни выбрали, конвертер согласован в этом, включая тонкий случай элементов списка под ключом, где противоречивое отступление рукой является классическим источником & quot; значения сопоставления не допускаются здесь& quot; ошибки.

Шаг 3: конвертировать и пересматривать

Выходные данные отображаются с подсчетом строк и байтов. Пропустите его один раз - не для правильности (это задание 's конвертера и #39;s), а для того, чтобы здравомыслие - проверить решения о цитировании на соответствие вашим ожиданиям. Видя PORT: "3000" цитируется, пока NODE_ENV: production Разве это не инструмент, который сообщает вам, какие значения были опасны.

Шаг 4: Скопируйте или скачайте

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

JSON против YAML: Когда победит каждый формат?

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

Каковы повседневные рабочие процессы для этого преобразования?

Kubernetes манифесты из вывода API

kubectl get deployment my-app -o json дает вам JSON; манифест, который вы проверяете в Git, - это YAML. Преобразование ответов API в чистый YAML - это самый быстрый способ загрузить манифест с живого ресурса - конвертировать, удалять заполненный сервером status а metadata.managedFields блоки, и у вас есть декларативная отправная точка. Сохранение типа «безопасное» здесь зарабатывает здесь: значения env в Kubernetes должник быть строками, и настойчиво цитировать конвертера "3000" Разница между kubectl apply преуспевая и не удастся.

Конфигурация трубопровода C

Действия GitHub и GitLab CI - только YAML. Когда I'm генерирует шаги рабочего процесса программно - матрица версий PHP и Node для тестирования WP Adminify против, скажем - генератор естественным образом производит JSON, и последний шаг - преобразование. Строки версий в тестовых матрицах - это именно те значения, которые искажаются наивным преобразованием: матрица ["1.9", "1.10", "1.11"] Конвертировано вручную без кавычек тесты на PHP 1.1 дважды выше Коллекция инструментов кодирования Охватывает больше этого шаблона генерации, а затем преобразования.

Docker Compose из проверки вывода

docker inspect испускает JSON; docker-compose.yml хочет YAML. Обратная инженерия файла Compose из работающего контейнера - порты, тома, env - это работа по преобразованию и перенастройке. Пустые массивы и объекты преобразуются в [] а {} Синтаксис потока, который принимается, и который сохраняет читаемость стадии обрезки.

Сделать конфигурацию доступной для проверки

Это недооценено: JSON-конфиги с десятками вложенных ключей в обзоре кода отвратительны, отчасти потому, что они не могут нести комментарии. Преобразование в YAML позволяет вам аннотировать почему rateLimit 250 рядом со значением. Для самого обзора соедините преобразование с Структурный диффер До/после JSON сохраняет «что на самом деле изменилось» вопрос честно, в то время как версия YAML обрабатывает "Почему».

Документы OpenAPI и схемы

Спецификации OpenAPI обычно создаются в YAML, но генерируются и служат JSON. Преобразование сгенерированной спецификации в YAML для редактирования человеком, а затем проверка туда и обратно - является стандартным рабочим процессом команды API, а гарантии точности (сохраненный порядок ключей, цитируемые типы) означают, что версия YAML остается различимой по отношению к своему предку JSON.

Почему важно сохранить ключевые заказы?

Согласно спецификации JSON, порядок объектных ключей не имеет значения - {"a":1,"b":2} а {"b":2,"a":1} являются одним и тем же объектом. Таким образом, конвертер может сортировать ключи в алфавитном порядке и быть технически правильным. Это также было бы практически враждебно, потому что конфигурационные файлы гласить По порядку: развертывание Kubernetes читается естественным образом как apiVersion, kind, metadata, spec- сортировка их по алфавиту дает манифест, который анализируется одинаково и читается как записка о выкупе.

Преобразователь излучает ключи в порядке исходного кода. Ваша ментальная модель документа выдерживает преобразование, YAML чисто дифференцируется с предыдущими преобразованиями того же источника и обычных заказов (имя перед значением, apiVersion Во-первых) оставайтесь условными. если вы хотеть каноническое упорядочение для целей сравнения, это's проблема diff-tool - the json diff чеккер Сравнивается по ключу независимо от порядка, который является подходящим уровнем для этой проблемы.

Безопасно ли конвертировать конфиги, содержащие секреты?

Конфигурация - это наиболее плотный секретный текст, с которым работает разработчик: URL-адреса баз данных со встроенными паролями, токены API в блоках env, внутренние имена хостов, отображающие вашу инфраструктуру. It's также именно то, что люди вставляют в онлайн-конвертеры, обычно в середине развертывания, обычно в спешке.

выше Конвертер Toolz.dev полностью работает в вашем браузере: анализ, скалярный анализ, сериализация - все это JavaScript на стороне клиента, ни один сетевой запрос не несет ваши данные, и инструмент продолжает работать с вашим отключением соединения. Это & # 39; это факт архитектуры, а не обещание политики конфиденциальности. Философия дизайна, основанная на браузере, изложена во всем наборе инструментов Руководство по набору инструментов для разработчиков веб-разработчикаЭтот инструмент заключается в том, что философия применяется к самому чувствительному типу документа в вашем рабочем процессе.

Очевидная оговорка: преобразование на стороне клиента защищает переделка, йо- В то, где вы вставляете вывод, это его собственное решение по безопасности.

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

Как преобразовать json в yaml онлайн?

Вставьте свой JSON в JSON в YAML конвертер, выбрать отступ 2- или 4-х пробелов, и нажмите Convert.You get block-style YAML с типом-безопасным цитированием, готовый к копированию или загрузке в виде файла.yaml.Conversion полностью выполняется в вашем браузере - ничего не загружается.

JSON уже действителен?

Технически да - YAML 1.2 является надмножеством JSON, поэтому любой действительный документ JSON анализируется как YAML. Но синтаксис JSON противоречит цели читаемости YAML's. Преобразование создает YAML в блочном стиле с отступом вместо брекетов, что и проявляет Kubernetes, рабочие процессы CI и файлы Compose, которые люди ожидают читать и редактировать.

Какая проблема Норвегии в YAML?

В соответствии со скалярными правилами YAML 1.1, которые все еще применяются анализаторы, такие как PyYAML, некотируемые значения нет, да, включены и не анализируются как логические значения - поэтому код страны NO молча становится ложным. Преобразователь предотвращает это, автоматически цитируя любую строку, которую анализатор YAML может интерпретировать как логическое значение, число или нуль.

Сохранятся ли числовые строки, подобные "3000" после преобразования?

да. Преобразователь обнаруживает строки, которые выглядят как числа, и цитируют их в выводе, поэтому "3000" остается строкой, а не ставит целым числом 3000. Это имеет значение для портов, таких как "1.10" (которые в противном случае урезали бы поплавок 1.1), почтовые индексы и идентификаторы с ведущими нулями.

Конверт сохраняет порядок моих ключей JSON?

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

Могу ли я использовать вывод непосредственно в Kubernetes или Docker Compose?

Да. на выходе стандартный блочный YAML с отступом пробелов (никогда не вложенных вкладок), который принимают kubectl, Docker Compose, GitHub Actions и GitLab CI. Значения, которые должны быть строками - например, значения Kubernetes env var - выходят в кавычки, избегая ошибок типа, которые kubectl поднимает в некотируемых цифрах.

Как преобразовать yaml обратно в json?

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

Безопасно ли конвертировать файлы конфигурации, содержащие секреты?

Да. преобразование полностью выполняется в JavaScript в вашем браузере - ни один сетевой запрос не несет ваши данные, ничего не хранится и не регистрируется, и инструмент работает в автономном режиме.Конфигурации с учетными данными базы данных, токенами API или внутренними именами хостов никогда не покидают вашу машину.

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