W tym artykule
Czym jest TOML?
TOML (Tom's Obvious, Minimal Language) to format pliku konfiguracyjnego zaprojektowany tak, aby był łatwy do odczytu i zapisu. Stworzony przez Toma Prestona-Wernera (współzałożyciela GitHub), TOML wyraźnie odwzorowuje się na tablicę haszową i ma być jednoznaczny — każdy dokument TOML ma dokładnie jedną prawidłową interpretację.
TOML jest preferowanym formatem konfiguracji dla Rust (Cargo.toml), Python (pyproject.toml) i wielu generatorów stron statycznych. Obsługuje komentarze, literały daty i czasu oraz zagnieżdżone tabele, pozostając prostszym niż YAML i bardziej przyjaznym dla człowieka niż JSON.
Zasady składni TOML
Składnia TOML jest zaprojektowana tak, aby była minimalna i jednoznaczna. Oto podstawowe elementy języka.
- Pary klucz/wartość — podstawowy element składowy, zapisywany jako klucz = wartość w każdej linii. Klucze mogą być gołe (bez cudzysłowów), w cudzysłowach lub z kropkami dla zagnieżdżonego dostępu.
- Tabele — sekcje zdefiniowane nagłówkami [table_name] grupującymi powiązane pary klucz/wartość. Tabele można zagnieżdżać za pomocą kluczy z kropkami lub składni [[array_of_tables]].
- Tablice — uporządkowane listy zdefiniowane nawiasami kwadratowymi [1, 2, 3]. Wszystkie elementy muszą być tego samego typu. Wieloliniowe tablice są dozwolone z końcowymi przecinkami.
- Literały daty i czasu — TOML natywnie obsługuje daty RFC 3339, takie jak 2026-03-15T14:30:00Z, daty lokalne (2026-03-15), czasy lokalne (14:30:00) i przesunięcia daty i czasu.
- Ciągi wieloliniowe — ciągi z potrójnymi cudzysłowami ("""tekst""") zachowują podziały linii i umożliwiają długą zawartość bez sekwencji ucieczki. Ciągi literalne używają pojedynczych cudzysłowów ('no\escape').
Popularne wzorce TOML
TOML jest szeroko stosowany w plikach konfiguracyjnych projektów w różnych ekosystemach.
- Cargo.toml — menedżer pakietów Rust używa TOML do metadanych projektu, zależności, profili kompilacji i konfiguracji przestrzeni roboczej
- pyproject.toml — nowoczesna konfiguracja systemu budowania Python, zdefiniowana przez PEP 517/518, zastępuje setup.py i setup.cfg ustandaryzowanym plikiem TOML
- Konfiguracja Hugo — generator stron statycznych Hugo używa TOML (lub YAML/JSON) do konfiguracji witryny, w tym motywów, menu, taksonomii i ustawień kompilacji
- Konfiguracja Netlify — netlify.toml konfiguruje polecenia kompilacji, reguły przekierowań, zmienne środowiskowe i konteksty wdrożeń dla witryn Netlify
Wypróbuj za darmo — bez rejestracji
Waliduj TOML online →Typowe błędy walidacji
TOML jest z założenia rygorystyczny — wiele błędów, które YAML cicho zaakceptuje, spowoduje błąd w TOML. Oto najczęstsze problemy z walidacją.
- Zduplikowane klucze — TOML zabrania definiowania tego samego klucza dwukrotnie w tej samej tabeli. Dotyczy to kluczy ustawionych za pomocą notacji z kropkami i zwykłych nagłówków tabel.
- Nieprawidłowy format daty — TOML wymaga dat RFC 3339. Typowe błędy to brakujący separator T (2026-03-15 14:30:00 zamiast 2026-03-15T14:30:00) lub używanie ukośników zamiast myślników.
- Mieszane typy tablic — wszystkie elementy w tablicy TOML muszą być tego samego typu. [1, "dwa", 3] jest nieprawidłowe, ponieważ miesza liczby całkowite i ciągi znaków.
- Niezamknięte ciągi — zapomnienie o zamknięciu ciągu w cudzysłowie lub użycie niewłaściwego rodzaju cudzysłowu powoduje błędy parsowania. Uważaj na niezgodne potrójne cudzysłowy w ciągach wieloliniowych.
TOML vs YAML vs JSON
Każdy format ma mocne strony, które czynią go lepiej odpowiednim do określonych zastosowań.
- Czytelność — TOML i YAML są oba bardzo czytelne dla ludzi. TOML używa jawnej składni (nawiasy, znaki równości), podczas gdy YAML opiera się na wcięciach. JSON jest mniej czytelny do konfiguracji ze względu na wymagane cudzysłowy i brak komentarzy.
- Rygorystyczność — TOML jest najbardziej rygorystyczny z trzech formatów. Odrzuca niejednoznaczne konstrukcje i nie ma niejawnego przekształcania typów. Elastyczność YAML (yes/no jako wartości logiczne, gołe ciągi) często powoduje nieoczekiwane zachowanie.
- Komentarze — zarówno TOML, jak i YAML obsługują komentarze (TOML używa #, YAML używa #). JSON w ogóle nie obsługuje komentarzy, co czyni go mniej odpowiednim dla plików konfiguracyjnych wymagających dokumentacji.
Często zadawane pytania
Jak działają zagnieżdżone tabele w TOML?
TOML obsługuje zagnieżdżone tabele przez dwa mechanizmy: klucze z kropkami (a.b.c = wartość) i nagłówki tabel ([parent.child]). Oba tworzą tę samą zagnieżdżoną strukturę. Dla tablic tabel (np. wielu zależności pakietów) użyj podwójnych nawiasów ([[array_name]]). Każdy blok [[array_name]] dodaje nowy element do tablicy.
Jakie są różnice między TOML v1.0 a wcześniejszymi wersjami?
TOML v1.0 (wydany w styczniu 2021) jest pierwszym stabilnym wydaniem. Kluczowe zmiany w stosunku do wersji przed 1.0 obejmują doprecyzowanie obsługi daty i czasu, sformalizowanie semantyki tabel wbudowanych oraz udoskonalenie zachowania tablic tabel. Większość nowoczesnych narzędzi używa TOML v1.0 — jeśli piszesz nowe pliki konfiguracyjne, celuj w v1.0.
Jak przekonwertować YAML na TOML?
YAML i TOML mają różne modele danych, więc konwersja nie zawsze jest jeden do jednego. Proste struktury klucz-wartość i zagnieżdżone obiekty konwertują się bezpośrednio. Funkcje YAML, takie jak kotwice, aliasy i złożone klucze, nie mają odpowiedników w TOML. Dla większości plików konfiguracyjnych konwersja jest prosta — mapuj słowniki YAML na tabele TOML i listy YAML na tablice TOML.