Преобразуване между JSON и YAML

Табло
Документация
API

преобразува JSON в YAML (и обратно), запазвайки структурата, с конфигурируемо отстъпление. Практично за миграция на конфигурация между файлове .json и .yaml

За какво е този JSON / YAML конвертор?

Този инструмент трансформира YAML документ в JSON и обратно, като запазва структурата на данните (обекти, таблици, скаларни типове). Преобразуването на JSON в YAML или YAML в JSON е обичайна операция в разработката: генерираме OpenAPI YAML файл от JSON спецификация, преобразуваме изхода на REST API в YAML, за да го ангажираме в хранилище за конфигурация, превеждаме YAML манифест на Kubernetes в JSON, за да го предадем на kubectl --dry-run=client -o json, или подравняваме GitHub работен поток Действия с JSON схема. В по-широк план това е мостът между света на обмена на данни (JSON) и света на ръчно редактируемата конфигурация (YAML).

YAML срещу JSON: директно сравнение

JSON и YAML отговарят на подобни нужди, но различни случаи на употреба. Следната таблица обобщава основните технически разлики, полезни за избор между двете в зависимост от контекста.

Критерий	JSON	YAML
Човешка четливост	Средно (скоби, кавички навсякъде)	Силно (отстъп, малка пунктуация)
Многословие	По-многословен	По-сбито
Коментари	Не се поддържа	Поддържа се (`# коментар`)
Множество документи в един файл	Не	Да, чрез разделителя `---`
Котви и псевдоними (повторно използване)	Не	Да (`&anchor` и `*anchor`)
Въведете система	Строго (низ, число, булево, нула, масив, обект)	Неявна принуда (`да`, `не`, `null`, дати, интерпретирани скалари)
Ефективност на синтактичния анализ	Много бързи, собствени парсери навсякъде	По-бавна, много по-широка граматика
Приемане за REST API	Фактически стандарт	Рядък
Приемане за конфигурация	Редки (с изключение на `package.json`, `tsconfig.json`)	Фактически стандарт (Kubernetes, CI/CD, Ansible)

Кога да използваме JSON?

JSON се изисква винаги, когато една програма говори с друга програма. Неговите типични случаи на употреба:

REST и GraphQL API: полезни натоварвания за заявка и отговор.
Обмен на данни между микроуслуги и опашки за съобщения.
Собствен JavaScript код: JSON.parse и JSON.stringify без зависимости.
Съхранение от страна на браузъра: localStorage, sessionStorage, IndexedDB.
AJAX и fetch заявки.
Двоични или ориентирани към потока варианти: BSON (MongoDB), JSON линии (регистрационни файлове, ML набори от данни), MessagePack.
Конфигурация на JS / TS инструменти: package.json, tsconfig.json, composer.json.

Кога да използвам YAML?

YAML се изисква веднага щом човек редовно редактира файла. Неговите типични случаи на употреба:

Docker Compose (docker-compose.yml) и стек профили.
Манифести на Kubernetes (диаграми за внедряване, услуга, вход, Helm).
Книги за игра и описи.
CI/CD конвейери: GitHub Actions, GitLab CI, CircleCI, Bitbucket конвейери.
Спецификации на OpenAPI/Swagger и AsyncAPI.
Анотирана конфигурация на приложение (Symfony, Spring Boot, Rails), където коментарите са полезни.
Файлове, редактирани често на ръка, където сбитостта и четливостта имат предимство пред скоростта на анализиране.

Често срещани клопки в YAML

YAML е по-разрешителен от JSON, което го прави мощен, но коварен формат. Най-честите клопки:

Отстъп: разделите са забранени от спецификацията, валидни са само интервали. Смесването на двете или промяната на броя на интервалите в един и същ блок прекъсва анализирането.
Автоматична скаларна принуда: yes, no, on, off, true, false, null, None, ~ се анализират като булеви или нулеви. Пример за прихващане: пощенски код без кавички 01234 става цяло число 1234, а име на държава NO (Норвегия) става false. Винаги поставяйте двусмислени низове в кавички.
Многоредови низове: | (блоков литерал) запазва прекъсванията на редовете такива, каквито са, докато > (сгънат) замества прекъсванията на редовете с интервали. Флаговете за дъвчене - и + коригират поведението при последния скок.
YAML 1.1 срещу 1.2: 1.1 (все още много често, например чрез PyYAML по подразбиране) третира yes/no/on/off като булеви стойности, които 1.2 премахна. Поведенията също се различават при основа 8 числа.
Подразбиращи се дати: 2024-01-15 без кавички се интерпретира като обект за дата от някои анализатори, а не като низ.

Примери един до друг

Същият документ, изразен в JSON и след това в YAML. Проста конфигурация на приложение с неговите зависимости и неговата среда:

JSON версия

<пре>

{
    "име": "cdrn-приложение",
    "версия": "1.14.2",
    "среда": "производство",
    "зависимости": {
        "php": "^8.3",
        "symfony/framework-bundle": "^7.0",
        "doctrine/orm": "^3.0"
    },
    "функции": ["кеш", "поща", "опашка"],
    "debug": невярно
}

Еквивалентна YAML версия

# Конфигурация на приложението
име: cdrn-app
версия: 1.14.2
среда: производство
зависимости:
    php: '^8.3'
    symfony/framework-bundle: '^7.0'
    доктрина/форма: '^3.0'
функции:
    - кеш памет
    - пощальон
    - опашка
отстраняване на грешки: невярно

YAML версията е с около 25% по-кратка в знаците, приема водещ коментар и се чете като списък със свойства без синтактичен шум.

Как да използвате конвертора

Стъпки за конвертиране на вашите данни:

Поставете своя изходен документ (JSON или YAML) в полето за въвеждане.
Изберете желаната посока на преобразуване (JSON към YAML или YAML към JSON).
Щракнете върху бутона за конвертиране: форматираният резултат се появява в изходната област.
Проверете изобразяването, след което използвайте бутона за копиране, за да извлечете резултата в клипборда си.

Преобразуването се извършва локално във вашия браузър или чрез маршрут на специален сървър в зависимост от инструментите: не се запазват чувствителни данни.

Често задавани въпроси

JSON или YAML за моите конфигурационни файлове?

Ако екосистемата налага формат (Kubernetes в YAML, package.json в JSON), следвайте конвенцията. В противен случай предпочитайте YAML за дълги, анотирани конфигурации, които редактирате на ръка, и JSON за конфигурации, генерирани от програма или консумирани от код. Наличието на полезни коментари често е решаващият аргумент в полза на YAML.

Как да запазите коментарите по време на двупосочно пътуване от YAML към JSON към YAML?

не можеш JSON не поддържа коментари: веднага щом конвертирате YAML в JSON, коментарите се губят завинаги. За да запазите коментарите по време на програмно редактиране, използвайте анализатор, който запазва форматирането, като ruamel.yaml в Python в двупосочен режим, или избягвайте изобщо използването на JSON.

Защо моят YAML файл анализира правилно локално, но не успява в производството?

Често срещани причини: различни версии на анализатора (YAML 1.1 срещу 1.2), табулатори, въведени от редактор, стойности без кавички, които изглеждат като булеви стойности (NO, off) или числа (01234), кодиране на файла (UTF-8 BOM се обработва лошо). Систематично цитирайте двусмислени низове и задайте версията на анализатора във вашия проект.

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

От YAML 1.2, да на практика: всеки валиден JSON документ е валиден YAML 1.2 документ. Обратното е невярно: YAML документ, който използва коментари, котви, неявни дати или множество документи във файл, не може да бъде изразен директно в JSON без загуба на информация.

Какви алтернативи на JSON и YAML трябва да знаете?

TOML: популярен за конфигурация (Cargo, pyproject.toml), добър компромис между четимост и изрично въвеждане. INI: много проста, но без стандартна вложена структура. XML: подробен, но все още подходящ за SOAP и някои наследени конфигурации на Java. HCL: използва се от Terraform. JSON5 и JSONC: JSON разширения, които позволяват коментари и запетаи в края.

Каква е тежестта на YAML спрямо JSON?

За еквивалентна структура YAML обикновено е с 15 до 30% по-къс в байтове, благодарение на липсата на кавички около ключове и повечето низове, както и липсата на скоби. По кабела (HTTP транспорт) минимизираният JSON остава сравним, но YAML остава по-компактен в четлива версия. За чиста производителност от страна на анализирането, JSON е няколко пъти по-бърз, което оправдава използването му за API с голям трафик.

Пример за заявка

curl -X POST https://cdrn.fr/api/v1/tools/json-yaml-converter/execute \
  -H "Content-Type: application/json" \
  -d '{"json":"...","space_tabulation":1}'

Входна схема

Поле	Тип	Задължително	По подразбиране
`json`	text	✓	–
`space_tabulation`	integer	✓	–

Крайни точки

GET https://cdrn.fr/api/v1/tools - изброява всички достъпни инструменти
GET https://cdrn.fr/api/v1/tools/json-yaml-converter - извлича схемата на този инструмент
POST https://cdrn.fr/api/v1/tools/json-yaml-converter/execute - изпълнява този инструмент с JSON payload