У цій статті
Що таке TOML?
TOML (Tom's Obvious, Minimal Language) — це формат файлу конфігурації, розроблений для зручного читання та запису. Створений Томом Престоном-Вернером (співзасновником GitHub), TOML чітко відображається на хеш-таблицю та призначений бути однозначним — кожен документ TOML має рівно одне дійсне тлумачення.
TOML є форматом конфігурації за замовчуванням для Rust (Cargo.toml), Python (pyproject.toml) та багатьох генераторів статичних сайтів. Він підтримує коментарі, літерали дати й часу та вкладені таблиці, залишаючись простішим, ніж YAML, та більш зручним для людини, ніж JSON.
Правила синтаксису TOML
Синтаксис TOML розроблений мінімальним і однозначним. Ось основні елементи мови.
- Пари ключ/значення — основний будівельний блок, записаний як ключ = значення на кожному рядку. Ключі можуть бути голими (без лапок), у лапках або з крапками для вкладеного доступу.
- Таблиці — розділи, визначені заголовками [назва_таблиці], які групують пов'язані пари ключ/значення. Таблиці можна вкладати за допомогою ключів з крапками або синтаксису [[масив_таблиць]].
- Масиви — впорядковані списки, визначені квадратними дужками [1, 2, 3]. Усі елементи мають бути одного типу. Багаторядкові масиви допускаються із завершальними комами.
- Літерали дати й часу — TOML нативно підтримує дати RFC 3339, як-от 2026-03-15T14:30:00Z, локальні дати (2026-03-15), локальний час (14:30:00) та зміщення дати й часу.
- Багаторядкові рядки — рядки з потрійними лапками ("""текст""") зберігають розриви рядків і допускають довгий вміст без послідовностей екранування. Літеральні рядки використовують одинарні лапки ('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 онлайн →Поширені помилки валідації
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 = значення) та заголовки таблиць ([батьківська.дочірня]). Обидва створюють однакову вкладену структуру. Для масивів таблиць (наприклад, кількох залежностей пакетів) використовуйте подвійні дужки ([[назва_масиву]]). Кожен блок [[назва_масиву]] додає новий елемент до масиву.
Які відмінності між TOML v1.0 та попередніми версіями?
TOML v1.0 (випущений у січні 2021 р.) є першим стабільним релізом. Ключові зміни порівняно з чернетками до v1.0 включають уточнену обробку дати й часу, формалізовану семантику вбудованих таблиць і вдосконалену поведінку масивів таблиць. Більшість сучасних інструментів використовують TOML v1.0 — якщо ви пишете нові файли конфігурації, орієнтуйтеся на v1.0.
Як конвертувати YAML у TOML?
YAML і TOML мають різні моделі даних, тому конвертація не завжди є взаємно однозначною. Прості структури ключ-значення та вкладені об'єкти конвертуються безпосередньо. Функції YAML, такі як якорі, псевдоніми та складні ключі, не мають аналогів у TOML. Для більшості файлів конфігурації конвертація проста — зіставте словники YAML з таблицями TOML, а списки YAML — з масивами TOML.