Нужно перевести конфиг из JSON в YAML для docker-compose, Kubernetes или GitHub Actions. Или наоборот: сервис отдаёт YAML, а приложение ждёт JSON. Вручную переписывать структуру долго и чревато ошибками: один неверный отступ — и конфиг не парсится. Конвертер JSON - YAML переводит данные между форматами в обе стороны, определяет направление автоматически и показывает ошибки синтаксиса с номером строки и столбца.
В этой статье разберём, чем YAML отличается от JSON, что происходит с комментариями и якорями, как обрабатываются несколько документов и почему открывать чужой YAML безопасно.
Что умеет конвертер
Конвертер JSON - YAML принимает JSON или YAML и переводит его в другой формат.
| Параметр | Что делает |
|---|---|
| Открыть файл | Загружает файл с компьютера |
| Направление | «Определить автоматически» или явный выбор JSON → YAML / YAML → JSON |
| Отступ | Сколько пробелов на уровень вложенности |
| Сортировать ключи по алфавиту | Располагает ключи в алфавитном порядке |
| Преобразовать | Выполняет перевод |
| Копировать / Скачать | Копирует результат или сохраняет его файлом |
Направление определяется автоматически: инструмент понимает, что перед ним, и переводит в противоположный формат. При ошибке синтаксиса показывается номер строки и столбца.
Всё выполняется в браузере: данные никуда не отправляются.
JSON и YAML: чем отличаются
Это два способа записать одни и те же данные. Разница — в синтаксисе и удобстве.
| Свойство | JSON | YAML |
|---|---|---|
| Скобки | {} и [] |
Отступы |
| Кавычки | Обязательны для строк | Часто не нужны |
| Комментарии | Нет | Есть |
| Читаемость для человека | Средняя | Высокая |
| Строгость | Высокая | Гибче, но чувствителен к отступам |
| Программная обработка | Проще | Сложнее из-за неоднозначностей |
Важное отношение: любой JSON — это корректный YAML версии 1.2, но не наоборот. JSON — подмножество YAML по синтаксису. Поэтому JSON → YAML переводится без потерь, а YAML → JSON может потерять то, чего в JSON нет: комментарии, якоря, некоторые типы.
Где используется YAML
| Инструмент | Зачем YAML |
|---|---|
| docker-compose | Описание сервисов, сетей, томов |
| Kubernetes | Манифесты ресурсов |
| GitHub Actions | Описание workflow |
| Ansible | Плейбуки и конфигурации |
| Конфигурации CMS | Настройки сайтов и плагинов |
| CI/CD | Пайплайны и параметры сборки |
JSON чаще встречается в API и обмене данными, YAML — в конфигурациях, которые читает и правит человек.
Комментарии и якоря: что теряется при переводе
Это важное ограничение, о котором стоит знать заранее.
Комментарии. В JSON комментариев нет. При переводе YAML → JSON они теряются. Если комментарии важны — сохраните исходный YAML отдельно.
Якоря и ссылки. YAML позволяет определить значение один раз и ссылаться на него: &якорь и *ссылка. В JSON такого механизма нет, поэтому при переводе якоря разворачиваются в обычные значения. Данные не теряются, но компактность записи — да.
Несколько документов. YAML поддерживает несколько документов в одном файле, разделённых ---. В JSON такого понятия нет. Инструмент превращает их в элементы одного массива и предупреждает об этом. Если документов несколько, результат будет массивом, а не объектом.
Безопасность: почему чужой YAML не опасен
YAML — мощный формат, и в некоторых реализациях он может быть опасен: поддерживаются пользовательские типы и даже выполнение кода. Инструмент этого не делает.
| Риск | Как обрабатывается |
|---|---|
| Пользовательские типы | Не поддерживаются, разбираются только данные |
| Выполнение кода | Не поддерживается |
| «YAML-бомба» | Число значений ограничено, разбор идёт в отдельном потоке с ограничением времени |
| Схема | Используется YAML 1.2 |
«YAML-бомба» — файл, в котором ссылки размножают данные до гигабайтов. Инструмент останавливает такой разбор: число значений ограничено, а разбор идёт в отдельном потоке с ограничением времени. Поэтому открывать чужой YAML безопасно.
Ошибки синтаксиса: строка и столбец
YAML чувствителен к отступам: лишний пробел или табуляция ломают структуру. Инструмент показывает номер строки и столбца, где встретилась ошибка.
Частые причины:
| Ошибка | Причина |
|---|---|
| Неверный отступ | Смешаны пробелы и табуляция или разное число пробелов |
| Пропущенное двоеточие | Ключ без : |
| Неверный уровень вложенности | Элемент на один уровень глубже или выше |
| Спецсимвол в значении без кавычек | : или # в значении ломают разбор |
| Незакрытая кавычка | Строка начата, но не закрыта |
При ошибке перейдите к указанной строке и столбцу — проблема почти всегда рядом.
Сортировка ключей и отступ
Сортировка ключей по алфавиту помогает сравнивать два файла: diff показывает только реальные изменения, а не перестановку полей.
Отступ влияет на читаемость YAML. Значение по умолчанию — 2 пробела. Для вложенных конфигов иногда удобнее 4, но 2 — стандарт де-факто.
Зачем конвертировать
| Задача | Что даёт конвертер |
|---|---|
| docker-compose | Перевести JSON-конфиг в YAML для compose-файла |
| Kubernetes | Подготовить манифест из JSON |
| GitHub Actions | Перевести workflow из JSON в YAML |
| API | Получить JSON из YAML-ответа |
| Сравнение конфигов | Отсортировать ключи и сравнить |
| Миграция | Перевести старый конфиг в новый формат |
Ограничения инструмента
- Комментарии теряются при YAML → JSON.
- Якоря разворачиваются в обычные значения.
- Несколько документов становятся массивом, а не набором объектов.
- Только данные. Пользовательские типы и выполнение кода не поддерживаются — это защита, а не ограничение.
Как пользоваться: пошагово
- Вставьте JSON или YAML либо откройте файл.
- Оставьте направление «Определить автоматически» или выберите явно.
- Настройте отступ и сортировку ключей, если нужно.
- Нажмите «Преобразовать», затем скопируйте или скачайте результат.
Типичные ошибки
Ожидать, что комментарии сохранятся. В JSON их нет. Сохраните исходный YAML отдельно, если комментарии важны.
Удивляться, что якоря исчезли. В JSON нет якорей — они разворачиваются в значения. Данные не теряются, теряется компактность.
Забывать про несколько документов. Если в YAML было несколько документов через ---, в JSON получится массив, а не объект.
Путать конвертер с JSON Formatter. Formatter форматирует JSON, конвертер переводит между форматами. Для форматирования JSON — отдельный инструмент.
Игнорировать ошибку по строке и столбцу. YAML чувствителен к отступам. Смотрите участок вокруг указанной позиции.
Считать, что YAML → JSON без потерь. Потери есть: комментарии, якоря, множественные документы. Это свойство форматов, а не ошибка инструмента.
Вопросы и ответы
Чем YAML отличается от JSON? Это два способа записать одни и те же данные. JSON строже и проще для программ, YAML удобнее читать и править вручную: вместо скобок — отступы, есть комментарии. Любой JSON — это корректный YAML версии 1.2, но не наоборот.
Что будет с комментариями YAML? В JSON комментариев нет, поэтому при переводе YAML → JSON они теряются. Якоря и ссылки (&якорь, *ссылка) разворачиваются в обычные значения.
Файл содержит несколько документов через ---. Что получится? Если документов несколько, в JSON они станут элементами одного массива — инструмент предупредит об этом.
Безопасно ли открывать чужой YAML? Да. Разбираются только данные (схема YAML 1.2), пользовательские типы и выполнение кода не поддерживаются. «YAML-бомба» — файл, где ссылки размножают данные до гигабайтов, — останавливается: число значений ограничено, а разбор идёт в отдельном потоке с ограничением времени.
Можно ли конвертировать несколько файлов сразу? Инструмент работает с одним файлом или одним блоком данных за раз.
Почему YAML чувствителен к отступам? В YAML структура задаётся отступами, а не скобками. Лишний пробел или табуляция меняют уровень вложенности и ломают разбор.
Итог
Конвертер JSON - YAML — инструмент для перевода данных между JSON и YAML в обе стороны. Он определяет направление автоматически, показывает ошибки с номером строки и столбца, позволяет отсортировать ключи, выбрать отступ, открыть файл и скачать результат, а всё выполняется в браузере. Помните, что при YAML → JSON теряются комментарии и разворачиваются якоря, а несколько документов становятся массивом, — и конвертация пройдёт без сюрпризов.