Валидация TOML: синтаксические правила, ошибки и лучшие практики

Что такое TOML?

TOML (Tom's Obvious, Minimal Language) — это формат конфигурационного файла, разработанный для удобного чтения и записи. Созданный Томом Престоном-Вернером (соучредителем GitHub), TOML явно отображается на хэш-таблицу и задуман как однозначный — каждый документ TOML имеет ровно одну корректную интерпретацию.

TOML является предпочтительным форматом конфигурации для Rust (Cargo.toml), Python (pyproject.toml) и многих генераторов статических сайтов. Он поддерживает комментарии, литералы даты и времени и вложенные таблицы, оставаясь проще YAML и удобнее для человека, чем JSON.

Правила синтаксиса TOML

Синтаксис TOML разработан минимальным и однозначным. Вот основные элементы языка.

• Пары ключ/значение — основной строительный блок, записываемый как ключ = значение на каждой строке. Ключи могут быть голыми (без кавычек), в кавычках или с точками для вложенного доступа.
• Таблицы — разделы, определяемые заголовками [table_name], которые группируют связанные пары ключ/значение. Таблицы можно вкладывать с помощью ключей с точками или синтаксиса [[array_of_tables]].
• Массивы — упорядоченные списки, определяемые квадратными скобками [1, 2, 3]. Все элементы должны быть одного типа. Разрешены многострочные массивы с завершающими запятыми.
• Литералы даты и времени — TOML нативно поддерживает даты RFC 3339, например 2026-03-15T14:30:00Z, локальные даты (2026-03-15), локальное время (14:30:00) и смещения даты-времени.
• Многострочные строки — строки с тройными кавычками ("""текст""") сохраняют переносы строк и позволяют длинное содержимое без escape-последовательностей. Литеральные строки используют одинарные кавычки ('no\escape').

Распространённые шаблоны TOML

TOML широко используется в конфигурационных файлах проектов в различных экосистемах.

• Cargo.toml — менеджер пакетов Rust использует TOML для метаданных проекта, зависимостей, профилей сборки и конфигурации рабочего пространства
• pyproject.toml — современная конфигурация системы сборки Python, определённая в PEP 517/518, заменяет setup.py и setup.cfg стандартизированным файлом TOML
• Конфигурация Hugo — генератор статических сайтов Hugo использует TOML (или YAML/JSON) для конфигурации сайта, включая темы, меню, таксономии и настройки сборки
• Конфигурация Netlify — netlify.toml настраивает команды сборки, правила перенаправления, переменные среды и контексты развёртывания для сайтов Netlify

Распространённые ошибки валидации

TOML строг по своей природе — многие ошибки, которые YAML молча принял бы, приведут к сбою в TOML. Вот наиболее распространённые проблемы валидации.

• Дублирующиеся ключи — TOML запрещает определять один и тот же ключ дважды в одной таблице. Это включает ключи, заданные через точечную нотацию и обычные заголовки таблиц.
• Неверный формат даты — TOML требует даты RFC 3339. Распространённые ошибки: отсутствующий разделитель T (2026-03-15 14:30:00 вместо 2026-03-15T14:30:00) или использование косой черты вместо дефиса.
• Смешанные типы массивов — все элементы в массиве TOML должны быть одного типа. [1, "два", 3] недопустимо, так как смешивает целые числа и строки.
• Незакрытые строки — забытое закрытие строки в кавычках или использование неправильного типа кавычек вызывает ошибки парсинга. Следите за несовпадающими тройными кавычками в многострочных строках.

TOML против YAML против JSON

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

• Читаемость — TOML и YAML оба хорошо читаются людьми. TOML использует явный синтаксис (скобки, знаки равенства), тогда как YAML опирается на отступы. JSON менее читаем для конфигурации из-за обязательных кавычек и отсутствия комментариев.
• Строгость — TOML является наиболее строгим из трёх форматов. Он отвергает неоднозначные конструкции и не имеет неявного приведения типов. Гибкость YAML (yes/no как булевы значения, голые строки) часто вызывает неожиданное поведение.
• Комментарии — и TOML, и YAML поддерживают комментарии (TOML использует #, YAML использует #). JSON вообще не поддерживает комментарии, что делает его менее подходящим для конфигурационных файлов, требующих документации.

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

Как работают вложенные таблицы в TOML?

TOML поддерживает вложенные таблицы через два механизма: ключи с точками (a.b.c = значение) и заголовки таблиц ([parent.child]). Оба создают одинаковую вложенную структуру. Для массивов таблиц (например, нескольких зависимостей пакета) используйте двойные скобки ([[array_name]]). Каждый блок [[array_name]] добавляет новый элемент в массив.

В чём различия между TOML v1.0 и более ранними версиями?

TOML v1.0 (выпущен в январе 2021 года) — первый стабильный релиз. Ключевые изменения по сравнению с черновиками до 1.0 включают уточнённую обработку даты и времени, формализованную семантику встроенных таблиц и улучшенное поведение массивов таблиц. Большинство современных инструментов используют TOML v1.0 — если вы пишете новые конфигурационные файлы, ориентируйтесь на v1.0.

Как преобразовать YAML в TOML?

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