TOML vs JSON vs YAML: który format konfiguracji wybrać?

Oto krótka wersja porównania TOML vs JSON vs YAML: JSON to domyślny format wymiany danych między maszynami, który parsuje każdy język, YAML to przyjazny człowiekowi format napędzający Kubernetes i potoki CI, a TOML to jawny, typowany format stworzony do konfiguracji narzędzi i aplikacji, takich jak Cargo.toml czy pyproject.toml. Żaden pojedynczy format nie wygrywa wszędzie. Właściwy format pliku konfiguracyjnego zależy od trzech rzeczy: kto go edytuje, czy potrzebne są komentarze oraz jak rygorystyczne muszą być typy.

Szybka zasada praktyczna. Jeśli plik zapisuje maszyna i odczytuje maszyna, sięgnij po JSON. Jeśli ktoś codziennie ręcznie edytuje głęboko zagnieżdżoną infrastrukturę, YAML odpłaca się za swoją złożoność. Jeśli potrzebna jest oczywista, typowana konfiguracja, którą trudno zepsuć, TOML jest najbezpieczniejszym wyborem. Te formaty nie są konkurentami. Zajmują różne pasy: JSON dla maszyn, YAML dla DevOps, TOML dla konfiguracji narzędzi. Reszta przewodnika pokazuje to na przykładach zestawionych obok siebie oraz na różnicach, które naprawdę powodują błędy, i kończy się macierzą decyzyjną gotową do użycia w kolejnym projekcie.

Odpowiedź w 30 sekund

Jeśli masz tylko pół minuty, ta tabela to porównanie formatów plików konfiguracyjnych, po które tu zaglądasz.

	JSON	YAML	TOML
Komentarze	Nie	Tak (#)	Tak (#)
Typy danych	Jawne, minimalne	Niejawne (wnioskowane z postaci)	Jawne, bogate
Natywne daty	Nie	Zależne od wersji	Tak (cztery typy)
Styl zagnieżdżania	Nawiasy klamrowe {}	Wcięcia	Nagłówki [section]
Wrażliwość na wcięcia	Nie	Tak (tabulatory zakazane)	Nie
Ciągi wielowierszowe	Nie (tylko \n)	Tak (| i >)	Tak (""")
Przecinki kończące	Zakazane	Nie dotyczy	Dozwolone w tablicach
Nadzbiór JSON	—	Tak (1.2)	Nie
Najlepszy do	API, wymiana danych	K8s, CI, Ansible	konfiguracji narzędzi Rust/Python

Z tej tabeli wynikają trzy jednozdaniowe werdykty:

• Wybierz JSON, gdy plik jest tworzony i odczytywany przez programy: payloady API, package.json, tsconfig.json, wszystko, co przekracza granicę systemu.
• Wybierz YAML, gdy ludzie ręcznie edytują głęboką, zagnieżdżoną konfigurację, a ekosystem już tego oczekuje: manifesty Kubernetes, GitHub Actions, Docker Compose, playbooki Ansible.
• Wybierz TOML, gdy potrzebujesz przejrzystej, typowanej konfiguracji narzędzia lub aplikacji, przeważnie płaskiej, z kilkoma sekcjami, edytowanej przez współautorów o różnym poziomie umiejętności: Cargo.toml, pyproject.toml, Hugo, Netlify.

Powody, dla których te werdykty się bronią, wyjaśniają kolejne sekcje; to właśnie w nich kryją się prawdziwe błędy.

Ta sama konfiguracja na trzy sposoby

Nic nie tłumaczy różnicy szybciej niż jedna konfiguracja zapisana trzy razy. Oto niewielka konfiguracja usługi: nazwa i wersja, kilka flag na najwyższym poziomie, lista funkcji oraz zagnieżdżony blok bazy danych.

JSON:

{
  "name": "acme-api",
  "version": "2.4.0",
  "debug": false,
  "released": "2026-07-02",
  "features": ["auth", "metrics", "tracing"],
  "database": {
    "host": "db.internal",
    "port": 5432,
    "max_connections": 100
  }
}

YAML:

name: acme-api
version: "2.4.0"
debug: false
released: "2026-07-02"
features:
  - auth
  - metrics
  - tracing
database:
  host: db.internal
  port: 5432
  max_connections: 100

TOML:

name = "acme-api"
version = "2.4.0"
debug = false
released = "2026-07-02"
features = ["auth", "metrics", "tracing"]

[database]
host = "db.internal"
port = 5432
max_connections = 100

Wszystkie trzy opisują identyczne dane. Zwróć uwagę na to, o co potyka się wzrok. JSON niesie najwięcej interpunkcji: każdy klucz jest w cudzysłowie, każdy poziom dodaje nawiasy klamrowe, a jeden zbłąkany przecinek kończący to błąd składni. YAML pozbywa się niemal wszystkiego, więc struktura wynika z samych wcięć, co czyta się świetnie, dopóki nie wkradnie się tabulator. TOML jest gdzieś pośrodku: cudzysłowy tylko przy ciągach znaków, pary key = value i nagłówek [database], który nazywa zagnieżdżony blok tak, jak robił to dawny plik INI. Zauważ, że pole released jest ciągiem w cudzysłowie we wszystkich trzech formatach, dzięki czemu dane pozostają tu identyczne. To celowe, bo daty to dokładnie ten punkt, w którym te formaty przestają się zgadzać.

JSON — domyślny format wymiany między maszynami

JSON to format, po który sięgasz bez namysłu, i zwykle ten instynkt jest słuszny. Każdy popularny język dostarcza parser, każde API HTTP nim mówi, a jego gramatyka jest na tyle mała, że mieści się w głowie. Jest rygorystyczny i jednoznaczny: ciąg znaków to ciąg znaków, 5432 to liczba, true to wartość logiczna, i istnieje dokładnie jeden sposób zapisania każdej z nich. To właśnie ta rygorystyczność sprawia, że JSON można bezpiecznie przesyłać między systemami, które nigdy się nie spotkały. Gdy usługa w Node wysyła JSON do usługi w Go, obie zgadzają się co do znaczenia bajt po bajcie.

Ta sama sztywność jest powodem, dla którego JSON dominuje na swoim własnym terenie. package.json, tsconfig.json i composer.json to JSON, ponieważ narzędzia bez przerwy je generują i przepisują, a konfiguracja zapisywana przez maszynę potrzebuje formatu rygorystycznego dla maszyn. W przypadku payloadów API i kolejek komunikatów po prostu nie ma powodu, by wybrać cokolwiek innego.

Wszystkie słabości JSON-a ujawniają się w chwili, gdy człowiek musi go edytować ręcznie. Nie ma komentarzy. Nie ma przecinków kończących, więc zmiana kolejności elementów listy oznacza poprawianie przecinków. Nie ma ciągów wielowierszowych, jedynie sekwencje \n. Każdy klucz wymaga cudzysłowów. I nie ma typu daty, więc 2026-07-02 musi istnieć jako ciąg w cudzysłowie i być parsowane zgodnie z konwencją. W przypadku pliku konfiguracyjnego utrzymywanego przez człowieka te braki sumują się w wyraźną uciążliwość.

Problem „JSON nie ma komentarzy”

Najczęściej wnioskowana funkcja JSON-a to ta, którą Douglas Crockford świadomie pominął: komentarze. Jego argumentacja brzmiała tak, że komentarze zachęcają do przemycania dyrektyw parsowania do plików konfiguracyjnych, co psuje interoperacyjność. Cokolwiek myślisz o tej decyzji, zwykłej konfiguracji JSON nie da się opatrzyć adnotacjami, co jest bolesne przy wszystkim, co utrzymują ludzie. Praktycznym rozwiązaniem jest nadzbiór. JSON5 dodaje komentarze, przecinki kończące, klucze bez cudzysłowów i pojedyncze cudzysłowy; JSONC (JSON with Comments) to lżejszy wariant, którego VS Code używa do swoich ustawień. Oba zachowują postać JSON-a, jednocześnie czyniąc go edytowalnym. Jeśli potrzebujesz komentarzy, ale chcesz pozostać w rodzinie JSON, przeczytaj nasz przewodnik po formatowaniu JSON5 i JSONC, by dowiedzieć się, kiedy używać którego i jak zadbać, aby narzędzia działały bez zgrzytów.

YAML — przyjazny człowiekowi standard DevOps

YAML jest zoptymalizowany pod człowieka przy klawiaturze. Obsługuje komentarze, jego układ oparty na wcięciach utrzymuje głęboko zagnieżdżone struktury w czystości, a kotwice (anchors) pozwalają zdefiniować blok raz i użyć go ponownie przez alias, zamiast kopiować i wklejać:

defaults: &defaults
  timeout: 30
  retries: 3

staging:
  <<: *defaults
  host: staging.internal

production:
  <<: *defaults
  host: prod.internal

Kotwica &defaults nadaje nazwę blokowi, a <<: *defaults scala go do obu środowisk, więc zmiana wspólnego limitu czasu następuje w jednym miejscu. Ani JSON, ani TOML nie ma niczego podobnego. To właśnie ta czytelność sprawiła, że YAML stał się lingua franca operacji: manifesty Kubernetes, przepływy pracy GitHub Actions, pliki Docker Compose i playbooki Ansible — wszystko to YAML. Gdy konfiguracja sięga pięciu poziomów w głąb, a człowiek modyfikuje ją codziennie, oszczędna interpunkcja YAML-a jest prawdziwą ulgą.

Ceną jest złożoność i niespodzianki. Specyfikacja YAML 1.2 jest obszerna, a pełna zgodność z nią rzadka, więc różne parsery różnią się na obrzeżach. Wcięcia są znaczące, tabulatory są wprost zakazane, a źle wyrównana spacja może zmienić znaczenie albo uniemożliwić parsowanie. Najostrzejszą krawędzią jest niejawne typowanie: YAML zgaduje typ nieujętego w cudzysłów skalara na podstawie jego postaci i myli się na tyle często, że dorobił się przezwiska.

Problem Norwegii w jednym akapicie

Napisz w YAML country: NO, a wiele parserów zwróci Ci wartość logiczną false, a nie ciąg "NO", ponieważ YAML 1.1 — którego wciąż trzyma się większość narzędzi Kubernetes — traktuje NO, YES, ON, OFF, Y i N jak wartości logiczne. Kod kraju Norwegii po cichu staje się false, bez żadnego błędu. To samo niejawne typowanie zmienia 0755 w liczbę ósemkową, a 1.20 w 1.2. Rozwiązanie jest nudne, ale niezawodne: ujmuj w cudzysłów ciągi, które można pomylić z czymś innym. Ten samostrzał jest na tyle sławny, że zasługuje na osobne, dogłębne omówienie (wraz z prawdziwymi awariami i historią sporu YAML 1.1 kontra 1.2) w naszym przewodniku po problemie Norwegii w YAML. Na potrzeby tego artykułu wniosek jest prosty: wygoda YAML-a i jego niebezpieczeństwo biorą się z tej samej cechy.

YAML wygrywa, gdy ludzie codziennie edytują głęboko zagnieżdżoną konfigurację, a otaczający ekosystem już tego wymaga. Jeśli piszesz chart Helma, piszesz YAML — i to jest w porządku.

TOML — jawna konfiguracja stworzona dla narzędzi

TOML (Tom’s Obvious, Minimal Language, stworzony przez Toma Preston-Wernera) został zaprojektowany jako format konfiguracji, o jakim marzyli użytkownicy YAML-a: czytelny, ale bez zgadywania. Jego cechą definiującą jest jawność. Typy są jednoznaczne, więc port = 5432 to zawsze liczba całkowita, a name = "acme" to zawsze ciąg znaków, bez wnioskowania z postaci, o które można się potknąć. Składnia TOML zapożycza nagłówek [section] z plików INI, dzięki czemu najwyższy poziom konfiguracji da się objąć wzrokiem, i nie jest wrażliwa na wcięcia, więc białe znaki nigdy nie zmieniają znaczenia. Specyfikacja TOML 1.0.0 jest mała i stabilna, co jest zaletą: mniej rzeczy można źle zapamiętać.

Sztandarową możliwością TOML-a są natywne typy daty i czasu, których ani JSON, ani zwykły YAML nie obsługują czysto. Ma ich cztery: date-time z przesunięciem i strefą czasową (1979-05-27T07:32:00Z), lokalny date-time bez strefy, lokalną datę (1979-05-27, sam dzień kalendarzowy) oraz lokalny czas (07:32:00). Oznacza to, że data wdrożenia pozostaje prawdziwą datą, zamiast ciągiem, który trzeba ponownie parsować.

Trzy elementy składni TOML wykonują większość pracy. Nagłówek [section] otwiera tabelę; nagłówek z kropką, taki jak [tool.ruff], zagnieżdża jedną tabelę wewnątrz drugiej bez dodatkowego wcięcia; a tabela inline { version = "1.0", features = ["derive"] } upycha mały obiekt w jednej linii. Powtarzające się sekcje używają podwojonego nagłówka — tablicy tabel:

[[servers]]
name = "alpha"
ip = "10.0.0.1"

[[servers]]
name = "beta"
ip = "10.0.0.2"

Ten blok staje się tablicą JSON złożoną z dwóch obiektów pod kluczem servers. Czyta się dobrze dla płaskiej listy, a właśnie tego potrzebuje większość konfiguracji narzędzi.

Słabości są realne, ale wąskie. TOML nie ma typu null, więc brakująca wartość to po prostu pominięty klucz. Głębokie zagnieżdżanie robi się rozwlekłe, bo każdy poziom powtarzanej, zagnieżdżonej struktury powtarza pełny nagłówek [[path]], co staje się bardziej hałaśliwe niż odpowiednik w YAML. A TOML jest młodszy i mniej powszechny niż JSON czy YAML, więc nie każde narzędzie nim mówi. TOML najlepiej sprawdza się przy konfiguracji, która jest przeważnie płaska, z garstką nazwanych sekcji, a to opisuje przytłaczającą większość konfiguracji narzędzi.

Dlaczego TOML dla Rusta i Pythona?

Wzrost popularności TOML-a idzie w parze z dwoma ekosystemami, które przyjęły go jako standard. Menedżer pakietów Rusta, Cargo, używa Cargo.toml dla każdego crate’a, więc każdy programista Rusta czyta i pisze TOML od pierwszego dnia. Python poszedł tym śladem: PEP 518 wprowadził pyproject.toml do deklarowania wymagań budowania, a PEP 621 ujednolicił metadane projektu (nazwa, wersja, zależności oraz sekcje [tool.*]) w tym samym pliku, zastępując rozproszenie plików setup.py, setup.cfg i konfiguracji poszczególnych narzędzi. Poza tą dwójką TOML jest domyślny także dla Hugo, Netlify, Poetry i Foundry. Wspólnym mianownikiem jest konfiguracja narzędzi, którą współautorzy edytują ręcznie i która zyskuje na tym, że jest oczywista, a nie przemądrzała.

Starcie bezpośrednie: różnice, które naprawdę bolą

Tabele funkcji są uporządkowane. Błędy nie. Oto konkretne różnice, które powodują realne problemy, każda z małym przykładem, który przepuścisz przez dowolny parser.

Komentarze

JSON w ogóle nie ma składni komentarzy. TOML i YAML używają # do końca wiersza.

# TOML: a leading comment
port = 5432  # and a trailing one

# YAML: identical comment style
port: 5432   # trailing comment

W chwili, gdy wkleisz // lub # do rygorystycznego JSON-a, parsowanie się nie powiedzie. To nie jest kwestia kosmetyki. Konfiguracja utrzymywana przez człowieka bez komentarzy gromadzi wiedzę plemienną, która żyje wyłącznie w czyjejś głowie.

Typy danych i daty

Typy JSON-a są jawne, ale ubogie, bez typu daty. Typy TOML-a są jawne i bogate. Typy YAML-a są niejawne i, jak wyżej opisano, czasem błędne. Daty to najwyraźniejsza linia podziału. TOML wyraża wszystkie cztery rodzaje natywnie:

odt = 1979-05-27T07:32:00Z   # offset date-time (has timezone)
ldt = 1979-05-27T07:32:00    # local date-time (no timezone)
ld  = 1979-05-27             # local date (a calendar day)
lt  = 07:32:00               # local time

Przekonwertuj ten TOML na JSON, a każda wartość stanie się ciągiem, który zachowuje swoje znaczenie: lokalna data pozostaje "1979-05-27", zamiast zostać rozdmuchana do postaci fałszywego znacznika czasu o północy. Nasz konwerter TOML na JSON zachowuje ten rodzaj daty dokładnie, co wiele naiwnych konwerterów robi źle. YAML z kolei może potraktować 1979-05-27 jako datę albo nie, w zależności od parsera i wersji schematu, a to dokładnie ta niejednoznaczność, której nie chcesz w konfiguracji produkcyjnej.

Głębokość zagnieżdżenia

Im głębiej zagnieżdża się konfiguracja, tym bardziej formaty się rozchodzą. Weźmy małe drzewo w stylu Docker Compose:

services:
  web:
    build:
      context: .
      args:
        NODE_ENV: production
    ports:
      - "8080:8080"

YAML wyraża głębokość samymi wcięciami i pozostaje zwięzły. Ta sama struktura w TOML zmusza do wypisania pełnej ścieżki w każdym nagłówku oraz do umieszczenia wartości skalarnych przed tabelami podrzędnymi:

[services.web]
ports = ["8080:8080"]

[services.web.build]
context = "."

[services.web.build.args]
NODE_ENV = "production"

JSON niesie drzewo w zagnieżdżonych nawiasach klamrowych, co jest jednoznaczne, ale obfite w interpunkcję. Przy płytkiej konfiguracji cała trójka wydaje się podobna; powyżej trzech czy czterech poziomów YAML jest wyraźnie oszczędniejszy, a TOML wyraźnie bardziej powtarzalny. Ta jedna różnica tłumaczy, dlaczego Kubernetes wybrał YAML, a Cargo wybrało TOML.

Wrażliwość na wcięcia

Tylko YAML przejmuje się białymi znakami. W JSON i TOML można wcinać dowolnie — albo wcale — i znaczenie pozostaje identyczne. W YAML to wcięcie jest strukturą, a tabulatory są niedozwolone, więc edytor, który wstawi tabulator, albo blok wklejony na złej głębokości po cichu zmienia dokument lub odmawia wczytania. Element listy wcięty o jedną spację za daleko może przyczepić się do niewłaściwego klucza nadrzędnego bez żadnego błędu, a taki błąd doprowadza do szału, gdy wypatruje się go wzrokiem, bo plik wciąż wygląda sensownie. Jeśli współautorzy używają różnych edytorów i ustawień, to jest to stały podatek, który YAML pobiera, a pozostałe dwa formaty nie. To mocny argument, by na każdej dużej konfiguracji YAML uruchamiać linter w CI.

Ciągi wielowierszowe

JSON nie potrafi pomieścić dosłownego znaku nowej linii wewnątrz ciągu; trzeba go zapisać jako \n. YAML i TOML mają prawdziwe ciągi wielowierszowe.

{ "note": "line one\nline two" }

note: |
  line one
  line two

note = """
line one
line two
"""

YAML-owy | zachowuje znaki nowej linii (blok > zamiast tego zwija je w spacje), a TOML-owy """ zachowuje się podobnie, ucinając znak nowej linii, który następuje bezpośrednio po otwierających cudzysłowach. Przy osadzonych skryptach, kodzie SQL albo tekstach pomocy to samo w sobie może przesądzić o wyborze formatu.

Przecinki kończące i rygor

JSON jest najbardziej rygorystyczny z całej trójki. Przecinek kończący po ostatnim elemencie tablicy to błąd składni:

# valid TOML — the trailing comma is fine
ports = [
  8001,
  8002,
]

Ten sam przecinek kończący po 8002 w JSON-ie powoduje błąd parsowania, dlatego dodanie wiersza do tablicy JSON tak często oznacza również poprawienie przecinka w wierszu powyżej. TOML dopuszcza przecinek kończący, a YAML-owa składnia listy z myślnikiem na wiersz omija ten problem w całości. Rygor jest cnotą przy wymianie między maszynami i utrapieniem przy ręcznej edycji: to ten sam kompromis widziany z drugiej strony. To także dokładnie to tarcie, które JSON5 i JSONC postanowiły usunąć konkretnie dla JSON-a.

Duże liczby całkowite i sufit 2^53

Wszystkie trzy formaty potrafią zapisać 64-bitową liczbę całkowitą jako tekst. Kłopot zaczyna się, gdy ta wartość przechodzi przez JavaScript, ponieważ liczby JSON w przeglądarce to liczby zmiennoprzecinkowe IEEE-754 podwójnej precyzji i potrafią dokładnie reprezentować liczby całkowite jedynie do 2^53 − 1 (9007199254740991). Identyfikator Snowflake albo znacznik czasu w nanosekundach jest większy, więc przejście tam i z powrotem przez narzędzie oparte na JS zaokrągla go i uszkadza wartość:

snowflake = 1420070400000000000   # exact in TOML text

{ "snowflake": "1420070400000000000" }

Niezawodne rozwiązanie w każdym formacie to przechowywanie takich wartości jako ciągów w cudzysłowie, aby żaden parser liczbowy nigdy ich nie dotknął. To nie jest wada któregokolwiek z formatów; to ograniczenie środowiska uruchomieniowego wykonującego konwersję. Nasze konwertery ostrzegają, gdy liczba całkowita przekracza tę granicę, zamiast po cichu ją uszkadzać.

Jak wybrać — macierz decyzyjna i schemat blokowy

Gdy faktycznie decydujesz, którego formatu konfiguracji użyć, przejdź pytania po kolei i zatrzymaj się przy pierwszym zdecydowanym „tak”.

1. Czy plik jest zapisywany i odczytywany głównie przez programy, albo czy ekosystem już narzuca format? Jeśli tak, użyj JSON-a. Payload API to JSON. Plik obok package.json to JSON. Nie walcz z narzędziami.
2. Czy ludzie codziennie ręcznie edytują głęboką, zagnieżdżoną konfigurację w stosie, który tego oczekuje (Kubernetes, CI, Ansible)? Jeśli tak, użyj YAML-a i przyjmij konwencję ujmowania w cudzysłów, by ominąć problem Norwegii.
3. Czy to konfiguracja narzędzia lub aplikacji, przeważnie płaska, z kilkoma sekcjami, edytowana przez współautorów o różnym poziomie umiejętności, gdzie typowane i oczywiste wygrywa z lakonicznym? Jeśli tak, użyj TOML-a.

Jeśli dwie odpowiedzi remisują, rozstrzygnij to według tej mapy osi:

Wymaganie	Najlepszy wybór	Dlaczego
Komentarze w pliku	TOML lub YAML	JSON ich nie ma
Natywne wartości daty/czasu	TOML	Cztery jawne typy dat
Bardzo głębokie zagnieżdżanie	YAML	Wcięcia pozostają zwięzłe
Zero niespodzianek z białymi znakami	JSON lub TOML	Brak wrażliwości na wcięcia
Przywiązanie do pliku ekosystemu	JSON	package.json, tsconfig.json
Edycja przez człowieka, kilka sekcji	TOML	Jawne typy, nagłówki w stylu INI
Wymiana maszyna-maszyna	JSON	Uniwersalny, rygorystyczny, szybki
Wnioskowanie typów nigdy nie może zgadywać	JSON lub TOML	YAML wnioskuje niejawnie

Większość projektów kończy z więcej niż jednym formatem. Repozytorium może mieć plik package.json w JSON-ie, którego nigdy nie tyka się ręcznie, plik pyproject.toml w TOML-u dla narzędzi Pythona, przepływy pracy w YAML w .github oraz plik .env na lokalne sekrety, który nie trzyma się żadnej z tych gramatyk. Ta mieszanka jest normalna i o to właśnie chodzi: każdy plik żyje w formacie, który pasuje do tego, kto go edytuje. Jeśli warstwa .env wchodzi w skład konfiguracji, nasz przewodnik po formacie plików .env omawia, gdzie mieści się obok konfiguracji JSON i jak konwertować między jednym a drugim.

Konwersja między TOML, JSON i YAML

Konwertować między tymi formatami przychodzi częściej, niż można się spodziewać. Zadanie CI czyta ręcznie napisany pyproject.toml i potrzebuje go w JSON-ie, by zasilić pulpit zależności. Migracja przenosi aplikację z konfiguracji YAML do TOML dla ściślejszego typowania. Przegląd kodu jest łatwiejszy, gdy porównuje się różnice postaci JSON dwóch plików, zamiast ich oryginałów wrażliwych na białe znaki. Każdy kierunek ma pułapkę, którą warto poznać, zanim wkleisz.

TOML na JSON. Głównym ryzykiem są daty. Lokalna data taka jak 1979-05-27 powinna pozostać datą kalendarzową, a nie stać się znacznikiem czasu UTC o północy, który wymyśla godzinę i strefę czasową. Komentarze także są odrzucane, skoro JSON nie potrafi ich pomieścić. Konwerter TOML na JSON wiernie zachowuje każdy rodzaj daty, dzięki czemu konwersja w obie strony pozostaje bezstratna.

JSON na TOML. TOML jest bardziej rygorystyczny co do struktury, więc dwie rzeczy mogą zablokować konwersję. Najwyższy poziom musi być obiektem, ponieważ dokument TOML jest w swoim korzeniu zawsze tabelą; goła tablica czy skalar nie mają się gdzie podziać. A TOML nie ma typu null, więc wartość null w obiekcie zostaje odrzucona (wraz z ostrzeżeniem wyliczającym, których kluczy dotyczy), podczas gdy null wewnątrz tablicy nie ma w ogóle poprawnej reprezentacji w TOML. Konwerter JSON na TOML jawnie ujawnia oba przypadki, zamiast produkować uszkodzone wyjście.

JSON i YAML, w obu kierunkach. Tu na oku trzeba mieć problem Norwegii: nieujęte w cudzysłów NO albo 0755 może zmienić typ przy przekraczaniu granicy. Konwerter JSON na YAML oraz konwerter YAML na JSON zajmują się cudzysłowami, dzięki czemu ciąg pozostaje ciągiem.

Po każdej konwersji warto zweryfikować wynik. Przepuszczenie wyjścia przez formater JSON potwierdza, że JSON jest poprawnie zbudowany i spójnie wcięty, zanim go zatwierdzisz lub wyślesz dalej. A ponieważ pliki konfiguracyjne przenoszą sekrety (tokeny rejestrów, dane logowania do baz danych, klucze wdrożeniowe), wszystkie te narzędzia działają w całości w przeglądarce: nic nie jest wysyłane, więc Cargo.toml z prywatnym tokenem rejestru ani plik values z danymi logowania nigdy nie opuszcza komputera.

FAQ

Czy TOML jest lepszy niż YAML?

Żaden nie jest lepszy w każdych warunkach; wybór TOML vs YAML sprowadza się do kształtu konfiguracji. W TOML-u trudniej o pomyłkę dzięki jawnym typom i brakowi pułapek z wcięciami, więc wygrywa przy przeważnie płaskiej konfiguracji narzędzi. YAML wyraża głębokie zagnieżdżanie zwięźlej, więc wygrywa przy dużej, warstwowej infrastrukturze, takiej jak Kubernetes.

JSON czy YAML do plików konfiguracyjnych?

Do konfiguracji edytowanej przez człowieka lepszy jest YAML: pozwala na komentarze i czyta się przejrzyście, czego JSON nie oferuje. Do konfiguracji, którą programy generują i odczytują, lepszy jest JSON: jest rygorystyczny, szybki i uniwersalny. Linią podziału jest to, kto edytuje — człowiek czy maszyna.

Dlaczego JSON nie pozwala na komentarze?

Twórca JSON-a, Douglas Crockford, usunął komentarze celowo. Obawiał się, że ludzie będą osadzać w nich dyrektywy parsowania i psuć interoperacyjność między parserami. Jeśli potrzebujesz komentarzy w pliku o kształcie JSON, użyj JSON5 lub JSONC, które przywracają je bez zmiany podstawowej struktury.

Czym jest problem Norwegii w YAML?

To YAML 1.1 traktujący pewne nieujęte w cudzysłów słowa jako wartości logiczne, więc country: NO staje się false, zamiast ciągiem "NO". YES, ON i OFF zachowują się tak samo. Ujęcie wartości w cudzysłów temu zapobiega; pełną historię znajdziesz w dedykowanym przewodniku podlinkowanym powyżej.

Czy TOML obsługuje komentarze?

Tak. TOML używa # do komentarzy, zarówno we własnym wierszu, jak i na końcu wartości, dokładnie tak jak YAML. Pamiętaj, że komentarze giną przy konwersji TOML na JSON, skoro JSON nie ma składni komentarzy, by je pomieścić.

Czy TOML potrafi wyrazić wszystko to, co JSON?

Prawie. Różnica JSON vs TOML jest niewielka, ale realna: TOML nie ma typu null, więc null-e z JSON-a są przy konwersji odrzucane lub pomijane, a dokument TOML musi być tabelą na najwyższym poziomie, więc gołej tablicy ani skalara z JSON-a nie da się skonwertować bez wcześniejszego opakowania pod kluczem.

Czy YAML jest nadzbiorem JSON-a?

Od YAML 1.2 tak: każdy poprawny dokument JSON jest również poprawnym YAML-em, więc parser YAML potrafi odczytać JSON bezpośrednio. To przydatny fakt, ale nie opieraj na nim granicy bezpieczeństwa, ponieważ parsery YAML dodają funkcje (takie jak kotwice), których JSON nie ma.

Który format konfiguracji parsuje się najszybciej?

JSON jest zwykle najszybszy, z najbardziej dojrzałymi i zoptymalizowanymi parserami w każdym języku. YAML jest najwolniejszy i najbardziej złożony w parsowaniu z powodu obszernej specyfikacji i niejawnego typowania. TOML plasuje się pośrodku, pod względem szybkości bliżej JSON-a niż YAML-a.