TOML vs YAML: ta sama konfiguracja w trzech formatach
TOML vs YAML
TOML vs YAML (i JSON): ta sama konfiguracja na trzy sposoby | We.Inc
Porównaj TOML, YAML i JSON na tych samych plikach konfiguracyjnych, obok siebie. Zobacz, gdzie każdy format jest wymagany, od pyproject.toml i Cargo.toml po compose.yaml.
TOML to format podobny do INI, stworzony dla plików konfiguracyjnych: jawne nagłówki [table], stringi w cudzysłowach, prawdziwe typy dat i wcięcia bez znaczenia. YAML opiera się na wcięciach, zgaduje typy z wartości bez cudzysłowów i dodaje kotwice oraz wiele dokumentów. Przy płytkich ustawieniach TOML trudniej zepsuć; przy głębokim zagnieżdżeniu YAML czyta się lepiej.
TOML, YAML i JSON w skrócie
TOML 1.0
YAML 1.2
JSON
Zagnieżdżanie
Nagłówki [table] i [a.b]
Wcięcia
Nawiasy klamrowe
Komentarze
Brak
Stringi
Zawsze w cudzysłowach
Cudzysłowy opcjonalne
Zawsze w podwójnych cudzysłowach
Daty i czas
Wbudowane typy
Brak w schemacie core 1.2
Tylko jako stringi
Rozróżnia wielkość liter
Tak
Tak
Tak
Typ MIME
application/toml
application/yaml
application/json
Zwykle nie masz wyboru: pakiety Pythona czytają pyproject.toml, Rust czyta Cargo.toml, a GitHub Actions i Docker Compose czytają YAML. Gdy jednak możesz wybrać, zobaczenie jednej konfiguracji we wszystkich trzech formatach sprawia, że kompromisy stają się oczywiste. Wybierz przykład poniżej i porównaj.
Wybierz jedną z przykładowych konfiguracji: ustawienia aplikacji, manifest pakietu lub listę serwerów.
Przeczytaj te same dane w TOML, YAML i JSON obok siebie.
Zwróć uwagę, gdzie TOML potrzebuje nagłówków ([[servers]]), a gdzie YAML wymaga starannych wcięć.
Skopiuj wersję, której oczekuje Twoje narzędzie.
Długie listy podobnych rekordów to miejsce, gdzie TOML robi się rozwlekły: każdy wpis potrzebuje własnego nagłówka [[name]].
TOML zabrania dwukrotnego definiowania tego samego klucza lub tabeli, co wyłapuje błędy kopiuj-wklej, które YAML może przepuścić w zależności od parsera.
W YAML umieszczaj numery wersji w cudzysłowach. TOML nie ma tej pułapki, bo tekst bez cudzysłowów nigdy nie jest tam poprawnym stringiem.
Tam, gdzie to możliwe, trzymaj jeden format na repozytorium. Mieszanie formatów jest w porządku tylko wtedy, gdy każde narzędzie wymaga własnego.
Najczęściej zadawane pytania
Czy TOML jest lepszy niż YAML?
Żaden nie wygrywa wszędzie. Jawne nagłówki i obowiązkowe cudzysłowy w TOML sprawiają, że małe i średnie pliki konfiguracyjne trudno źle odczytać. YAML obsługuje głębokie zagnieżdżenie i długie listy z mniejszym szumem, za cenę składni wrażliwej na białe znaki i niejawnego typowania.
Dlaczego Python używa pyproject.toml?
Przewodniki po pakietach Pythona definiują pyproject.toml z trzema tabelami: [build-system] dla backendu budowania, [project] dla metadanych, takich jak nazwa, wersja i zależności, oraz [tool] dla ustawień poszczególnych narzędzi, na przykład linterów.
Czy TOML może wyrazić wszystko, co YAML?
Nie wszystko. TOML nie ma kotwic ani aliasów, wielu dokumentów w jednym pliku ani null, bo każdy klucz musi mieć wartość. W konfiguracji rzadko ma to znaczenie, ale danych YAML opartych na tych funkcjach nie da się przekonwertować jeden do jednego.
Jakie formaty akceptują Docker Compose i GitHub Actions?
Oba używają YAML. Workflowy GitHub Actions znajdują się w .github/workflows z rozszerzeniem .yml lub .yaml, a Compose domyślnie szuka compose.yaml, nadal akceptując docker-compose.yaml w starszych projektach.
Czy TOML obsługuje stringi wieloliniowe?
Tak. Trzy podwójne cudzysłowy rozpoczynają wieloliniowy string podstawowy, który pozwala na escapowanie, a trzy pojedyncze cudzysłowy rozpoczynają wieloliniowy string literalny, który zachowuje treść dokładnie tak, jak została zapisana.
Gdzie każdy format jest wymagany
Projekty Pythona opisują się w pyproject.toml, a crate'y Rusta w Cargo.toml, więc w tych ekosystemach normą jest TOML. Hugo akceptuje też front matter w TOML między liniami +++.
Pipeline'y CI, konfiguracje kontenerów i manifesty wdrożeń opierają się na YAML: workflowy GitHub Actions i pliki Docker Compose to YAML, a wybór rozszerzenia to głównie kwestia spójności.
Z czego TOML rezygnuje dla bezpieczeństwa
Celem TOML, według jego własnej specyfikacji, jest jednoznaczne mapowanie na tablicę haszującą. To oznacza brak zgadywania: tekst wymaga cudzysłowów, wartości logiczne to tylko true i false, a każda tabela jest nazwana w nagłówku.
Ceną jest powtarzalność w zagnieżdżonych danych. Przy trzech poziomach głębokości plik TOML powtarza ścieżkę tabeli w każdym nagłówku, podczas gdy YAML po prostu dodaje wcięcie.
Które pliki używają którego formatu
Popularne pliki konfiguracyjne i wymagany przez nie format
Plik
Format
Czytany przez
TOML
Narzędzia do budowania i pakowania w Pythonie
Cargo.toml
TOML
Cargo, menedżer pakietów Rusta
.github/workflows/*.yml
YAML
GitHub Actions
YAML
Docker Compose
JSON
npm i inne menedżery pakietów Node
Front matter w Markdown
YAML (TOML z +++ w Hugo)
Generatory stron statycznych
Składnia TOML, którą warto znać
Klucze z kropkami, tabele inline i daty
Klucze z kropkami i tabele inline pozwalają uniknąć dodatkowych nagłówków dla małych grup, a daty to otypowane wartości, a nie stringi.
Jedna konfiguracja w TOML, YAML i JSON
Wybierz przykład. Wszystkie trzy wersje zawierają dokładnie te same dane, więc możesz porównać, jak każdy format je zapisuje.
Przykładowa konfiguracja
TOML
YAML
JSON
W przykładzie ustawień aplikacji TOML przechowuje opens jako prawdziwy czas lokalny, a wersje YAML i JSON trzymają go jako string.