Самый быстрый способ конвертировать TOML в YAML — команда yq -oy '.' file.toml. При ручной конверсии сопоставьте заголовки таблиц TOML [table] блокам с отступами в YAML, массивы TOML — спискам с дефисами, и всегда заключайте в кавычки неоднозначные строки, чтобы избежать «Проблемы Норвегии».
Быстрая конверсия: использование CLI yq
TOML (Tom’s Obvious, Minimal Language) достиг версии 1.1.0 в декабре 2025 года, однако YAML остаётся стандартом для CI/CD-пайплайнов и манифестов Kubernetes. Инструмент yq выполняет конверсию одной командой.
Установка yq
| Платформа | Команда |
|---|---|
| macOS/Linux | brew install yq |
| Windows | choco install yq |
| Python (pip) | pip install yq |
Предпочтительна версия на Go от Майка Фараха благодаря скорости. Как отмечается в документации yq Майка Фараха, инструмент декодирует структуру TOML и перекодирует её в корректный YAML.
Выполнение конверсии
Вывод в терминал:
yq -oy '.' your-config.toml
Сохранение в файл:
yq -oy '.' your-config.toml > your-config.yaml
Флаг -oy устанавливает формат вывода YAML. Он обрабатывает пары ключ-значение, вложенные таблицы и массивы.
Карта перевода синтаксиса: структура TOML в YAML
Разработчик Дрю Дево отмечал, что хотя TOML популярен, YAML лучше справляется с глубокой вложенностью. Вот точное сопоставление:
Таблицы в ключи с отступами
TOML использует заголовки в квадратных скобках; YAML использует отступы.
| TOML | YAML |
|---|---|
[server] |
server: |
host = "127.0.0.1" |
host: 127.0.0.1 |
port = 8080 |
port: 8080 |
Ключевое отличие: В TOML отступы имеют косметическое значение. В YAML отступы структурны — один лишний пробел ломает весь конфиг.
Массивы в списки с дефисами
TOML: ports = [ 8000, 8001 ]
YAML:
ports:
- 8000
- 8001
Как объясняет Knightli.com, «блочный стиль» YAML делает списки удобочитаемыми при условии вертикального выравнивания.
Встроенные таблицы и ключи с точками
| Конструкция TOML | Эквивалент в YAML |
|---|---|
[a.b.c] (заголовок с точками) |
a: → b: → c: (вложенные отступы) |
point = { x = 1, y = 2 } (встроенная таблица) |
point: → x: 1 → y: 2 |
Практические примеры использования
Конфигурация статического сайта Hugo
Hugo поддерживает hugo.toml, hugo.yaml или hugo.json. Большинство проектов начинают с TOML (по умолчанию), затем переходят на YAML, когда конфигурацию нужно синхронизировать с платформами развёртывания вроде Netlify или GitHub Actions. Hammer Europe отмечает, что команда hugo читает эти файлы, чтобы определить, как Markdown преобразуется в рабочий сайт.
Пакетирование Python: pyproject.toml в CI/CD YAML
Сообщество Python стандартизировало pyproject.toml через PEP 518. Эти настройки часто требуется перевести в YAML для рабочих процессов CI/CD GitHub Actions. В рабочих процессах ИИ-агентов CocoIndex сообщает, что оптимизированные конфигурации YAML могут сократить использование токенов до 70%.
Проблема Норвегии и другие подводные камни конверсии
Баг кода страны NO
В YAML 1.1 «голые» строки вроде NO, OFF и YES автоматически преобразуются в булевы значения false или true. TOML избегает этого, требуя кавычки для всех строк. При конверсии всегда заключайте неоднозначные значения в кавычки:
| Значение | Интерпретация YAML 1.1 | Исправление |
|---|---|---|
NO |
false |
"NO" |
OFF |
false |
"OFF" |
YES |
true |
"YES" |
On |
true |
"On" |
YAML 1.2 (текущая спецификация) устраняет большинство этих приведений, но многие парсеры по-прежнему работают в режиме 1.1.
Ошибки отступов
Парсеры YAML отклоняют файлы с несовместимыми отступами. Типичные ошибки:
- Смешивание табуляции и пробелов (YAML запрещает табуляцию)
- Использование 3 пробелов в одном блоке и 2 в другом
- Несогласованные элементы списков
Генерация с помощью ИИ
Такие инструменты, как AgentBuilder, позволяют описать конфигурацию на естественном языке и получить валидированный YAML. Этот цикл «описать → сгенерировать → проверить» помогает избежать как ошибок отступов, так и Проблемы Норвегии.
Заключение
Используйте yq -oy '.' file.toml для автоматической конверсии. При ручной работе сопоставляйте таблицы TOML с отступами YAML, массивы — спискам с дефисами и всегда заключайте в кавычки строки, которые могут быть приняты за булевы значения. После любой конверсии проверяйте вывод YAML перед развёртыванием — один неверный пробел или незакавыченный NO может сломать весь пайплайн.
FAQ
Поддерживает ли YAML комментарии, как TOML?
Да. Оба формата используют # для однострочных комментариев. Комментарии YAML могут мешать парсингу многострочных строк, поэтому при сомнениях размещайте их на отдельных строках.
Что такое «Проблема Норвегии» в YAML?
В YAML 1.1 «голые» строки вроде NO (код страны Норвегии) автоматически преобразуются в булево значение false. TOML избегает этого, требуя кавычки для всех строковых значений. При конверсии TOML в YAML заключайте любые потенциально неоднозначные строки в кавычки.
Какой формат лучше справляется с глубокой вложенностью?
YAML. TOML требует повторения длинных заголовков вроде [table.subtable.subsubtable] для каждого уровня, что становится громоздким. YAML представляет ту же иерархию с помощью отступов — более компактно и читаемо на большой глубине.
Добавить комментарий