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.

Ustawienia aplikacji

Manifest pakietu

Lista serwerów

Zacznij za darmo · Bez karty kredytowej

Powiązane: Poradniki

Produkt

Dla kogo

Funkcje

Zasoby

Firma

Mapa strony