TOML — что это за формат: синтаксис, примеры, сравнение с YAML и JSON

Введение

TOML (Tom's Obvious, Minimal Language) — молодой конфигурационный формат, созданный в 2013 году Томом Престон-Вернером, одним из основателей GitHub. Цель TOML — быть одновременно человекочитаемым, как YAML, и однозначным в парсинге, как JSON. За десятилетие TOML стал стандартом в экосистемах Rust (Cargo), Python (PEP 518, pyproject.toml), Go (только частично) и многих статических генераторах сайтов. В этой статье разберём, что такое TOML, какой у него синтаксис, чем он лучше YAML и JSON, и где его применять уместнее всего.

Что такое TOML

Что такое TOML простыми словами? Это текстовый формат для конфигурационных файлов с предсказуемой семантикой. В отличие от YAML, где тип значения определяет парсер по контексту (и это приводит к сюрпризам), в TOML тип явный: число — это число, строка в кавычках — это строка, дата парсится только в специфическом формате. У формата есть формальная грамматика и спецификация (актуальная версия — 1.0.0), что исключает неоднозначности.

Простой пример TOML-файла:

# Метаданные проекта
title = "ConvertHub"
version = "2.4.1"
debug = false

[database]
host = "localhost"
port = 5432
name = "converthub_prod"
pool = 20

[features]
auth = true
billing = true
analytics = false

TOML за 60 секунд: минимальный пример

Минимум, с которого можно начать: короткий файл с именем, версией, зависимостями и секцией настроек — с комментарием к каждой строке:

name = "my-app"            # строка: имя проекта
version = "1.0.0"          # тоже строка, хотя внутри цифры
retries = 3                # число: без кавычек
tags = ["cli", "beta"]     # массив строк

[dependencies]             # заголовок секции
serde = "1.0"              # этот ключ живёт внутри [dependencies]

[tool.ruff]                # вложенная секция: точка = иерархия
line-length = 88           # целое число

Комментарии после # парсер пропускает — они для людей.name и version лежат в корневой таблице, всё после[dependencies] попадает внутрь неё. [tool.ruff] создаёт вложенность: ruff внутри tool. Отступы в примере — чисто косметика, иерархию задают только квадратные скобки.

Версии спецификации

Актуальная версия стандарта — 1.1.0 (релиз 18 декабря 2025 года), она закрепила ряд уточнений парсеров. Долгоживущая базовая версия — 1.0.0 (январь 2021): именно на неё ориентируются большинство библиотек, и файл, валидный для 1.0.0, читается практически любым парсером TOML.

Синтаксис TOML

Ключи и значения

Базовая конструкция TOML — пара ключ = значение. Ключ — это «голый» (bare) идентификатор из букв, цифр, дефисов и подчёркиваний, либо строка в кавычках для ключей с exotic-символами. Значения бывают разных типов: строки, числа, булевы, даты, массивы, таблицы.

Таблицы

Таблицы (аналог объектов в JSON) объявляются строкой в квадратных скобках:[section]. Все пары «ключ-значение» после этой строки до следующего заголовка таблицы принадлежат указанной секции. Вложенные таблицы задаются точечной нотацией: [section.subsection].

[server]
host = "0.0.0.0"
port = 8080

[server.tls]
enabled = true
cert = "/etc/ssl/cert.pem"
key = "/etc/ssl/key.pem"

Массивы таблиц

Чтобы описать список объектов (например, несколько серверов), используют двойные квадратные скобки [[items]]. Каждое вхождение добавляет новый элемент в массив:

[[servers]]
name = "web-1"
ip = "10.0.0.1"

[[servers]]
name = "web-2"
ip = "10.0.0.2"

Это эквивалентно такому JSON:

{
  "servers": [
    { "name": "web-1", "ip": "10.0.0.1" },
    { "name": "web-2", "ip": "10.0.0.2" }
  ]
}

Типы данных

В отличие от YAML, здесь нет «магического» приведения типов: true всегда булево, "true" всегда строка, yes не валиден вообще. Это избавляет от класса ошибок, типичных для YAML.

Многострочные строки

TOML поддерживает три формы строк. Обычные — в двойных кавычках с экранированием. Литеральные — в одинарных кавычках, без экранирования. Многострочные — в тройных кавычках:

path = "C:\\Users\\Anna"          # с экранированием
regex = '^[a-z]+@example\.com$'   # без экранирования
description = """
Это многострочный текст.
Переносы сохраняются.
"""

TOML vs YAML vs JSON

Частый вопрос в сравнении toml vs yaml: что выбрать? У каждого формата своя ниша. JSON оптимален для машинного обмена, YAML — для сложных человекочитаемых конфигов с большим количеством вложенных структур, TOML — для плоских или умеренно вложенных конфигов, где важна однозначность.

Если конфиг в основном плоский — TOML выигрывает за счёт ясности. Если конфиг описывает сложные деревья (как манифесты Kubernetes) — YAML удобнее. JSON подходит, когда конфиг генерируется программно и человеком не редактируется.

Применение TOML в реальных проектах

Cargo и Rust

Файл Cargo.toml — основа любого Rust-проекта. Он описывает зависимости, метаданные пакета, фичи и профили сборки. TOML выбран именно из-за предсказуемости и удобства редактирования людьми.

[package]
name = "converthub"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

[profile.release]
lto = true
codegen-units = 1

Python и pyproject.toml

PEP 518 стандартизировал pyproject.toml как единый файл конфигурации Python-проектов. Он пришёл на смену setup.py и setup.cfg, объединяя настройки сборки, линтеров, форматеров и тестов.

[project]
name = "converthub"
version = "2.4.1"
requires-python = ">=3.10"
dependencies = ["fastapi", "uvicorn", "pydantic"]

[tool.ruff]
line-length = 100
target-version = "py310"

Статические генераторы сайтов

Hugo, Zola, Pelican и другие генераторы используют TOML для front matter — метаданных в начале Markdown-файлов. Это делает метаданные читаемыми и однозначными.

+++
title = "Установка Hugo"
date = 2025-01-30
draft = false
tags = ["hugo", "tutorial"]
+++

Кто использует TOML

Карта экосистемы одним взглядом: где TOML — основной формат и что в нём хранится. Cargo и pyproject.toml разобраны выше с примерами, в таблице — остальные пользователи формата.

Безопасность и производительность

TOML принципиально безопаснее YAML: он не поддерживает инстанциацию произвольных объектов, не имеет «опасных» тегов и не требует небезопасных режимов парсера. Парсеры TOML относительно простые, что снижает риск уязвимостей в самом парсере. Скорость парсинга сопоставима с JSON, иногда выше за счёт меньшей избыточности.

Конвертация TOML и JSON

Не все системы поддерживают TOML нативно, поэтому часто возникает задача перевода между TOML и JSON. Для этого используйте наши инструменты: JSON в TOML и TOML в JSON. Они корректно обрабатывают массивы таблиц, многострочные строки и типы данных. Также можно конвертировать TOML в YAML через промежуточный JSON.

Лучшие практики

• Группируйте настройки по логическим секциям, не оставляйте всё в корне.
• Используйте точки в ключах таблиц для иерархии: [server.tls] читается лучше, чем [server_tls].
• Комментируйте неочевидные значения — TOML поддерживает # комментарии.
• Для списков однотипных объектов применяйте [[items]], а не массивы встроенных таблиц.
• Берите строки в кавычки всегда, когда есть сомнения в их типе.
• Валидируйте TOML в CI: ошибка в синтаксисе сломает сборку так же, как в YAML.

Сравнение с другими конфиг-форматами

На практике TOML сравнивают не только с YAML и JSON, но и с INI, конфигами в стиле Apache, HOCON. INI — простейший формат с секциями в квадратных скобках и парами «ключ=значение». Он интуитивен, но не поддерживает массивы, вложенные таблицы и строгие типы. TOML развивает идеи INI, добавляя современную типизацию и структуру.

HOCON (Human-Optimized Config Object Notation) — формат, используемый в экосистеме Lightbend (Scala, Akka). Он ближе к JSON, но с комментариями и более лаконичным синтаксисом. HOCON мощнее TOML, но сложнее в парсинге и меньше распространён за пределами JVM-мира.

Поддержка в инструментах и редакторах

TOML хорошо поддерживается современными редакторами. VS Code имеет расширенияtombi и Even Better TOML с подсветкой синтаксиса, форматированием и валидацией. JetBrains IDE (IntelliJ, PyCharm, WebStorm) включают поддержку TOML «из коробки». Vim и Emacs имеют плагины. Это снимает классическую проблему YAML — необходимость в специальных плагинах для удобной работы.

Линтинг TOML развит лучше, чем у YAML. Инструменты вроде tombi иtaplo проверяют синтаксис, форматируют файл и предлагают автодополнение по схеме. Для pyproject.toml есть специализированные линтеры, проверяющие соответствие стандартам PEP. В CI имеет смысл добавить шаг taplo checkдля всех TOML-файлов проекта.

Эволюция и стандартизация

Спецификация TOML прошла долгий путь от версии 0.1 до актуальной 1.0.0, выпущенной в 2021 году. Версия 1.0 зафиксировала синтаксис и гарантирует обратную совместимость. Это устранило главную претензию к формату — нестабильность в ранних версиях. Сейчас все основные парсеры соответствуют 1.0, и можно рассчитывать на предсказуемое поведение.

Активно развивается версия 2.0, в которой обсуждаются расширения: типизированные массивы, дженерики, улучшенная поддержка дат. Пока рано использовать новинки в продакшене, но интересно следить за развитием. Сообщество TOML компактное, но активное, и быстро реагирует на запросы пользователей.

Частые ошибки в TOML

• Дублирование ключей — TOML запрещает определять один и тот же ключ дважды в одной таблице. Парсер выдаст ошибку.
• Порядок таблиц — после определения таблицы все пары «ключ-значение» до следующего заголовка принадлежат ей. Нельзя вернуться к родительской таблице.
• Массивы таблиц без двойных скобок — обычная таблица[item] не создаёт элемент массива, для этого нужны[[items]].
• Булевы значения в кавычках — "true" это строка,true это булево. Не путайте.
• Целые числа с плавающей точкой — 3.14 это float,3 это int. Смешивание в одном поле невозможно.
• Даты без кавычек — date и datetime записываются без кавычек, и парсер распознаёт их по формату ISO 8601.

Типичные ошибки синтаксиса

Выше были семантические ловушки — неверные типы и дубли. Отдельный класс — синтаксис. Чаще всего ломается файл, скопированный из YAML или переписанный по памяти.

Заключение

TOML — современный и продуманный toml формат конфигурации, который решает главные проблемы YAML: неоднозначность типов и сложность парсинга. Его ниша — конфигурационные файлы среднего уровня сложности: Cargo.toml,pyproject.toml, front matter, настройки инструментов. Для глубоких иерархий, как в манифестах Kubernetes, YAML пока удобнее, но TOML наступает. Если вы начинаете новый проект и выбираете формат конфигурации — присмотритесь к TOML: его предсказуемость и читаемость окупятся в долгосрочной перспективе. А для конвертации между форматами используйте инструменты ConvertHub и сравнительный обзор «Сравнение форматов данных».