JSON, TOML, YAML nebo CSON: volba konfiguračního formátu

Stručně: JSON použijte pro výměnu dat mezi stroji a pro konfiguraci udržovanou lidmi zvolte TOML nebo YAML podle ekosystému (YAML pro Kubernetes a CI, TOML pro ploché struktury nebo nativní data); k JSONC se uchylte jen tehdy, když si nejste jisti, zda čtečka dialekt podporuje.

JSON existuje pro stroje vyměňující data; konfigurační soubor píší lidé pro lidi. Zaměňte to a dostanete config.json, který nepojme komentář a kterého se nikdo neodváží prořezat.

1. Začněte dvěma různými druhy souborů

Výměna dat a konfigurace nesdílejí stejný cíl, i když je často píše stejná osoba na stejném stroji.

JSON skóruje téměř dokonale v levém sloupci: minimální gramatika, parser v každém jazyce a žádné komentáře znamenají žádný problém „komentář se rozešel s hodnotou“. V pravém sloupci je jeho přísnost čisté tření: žádné komentáře, žádné koncové čárky, žádná data a víceřádkový text se musí slisovat do jednoho řádku s \n.

2. Čtyři kandidáti a jejich syntaxe

• JSON: definován RFC 8259 a ECMA-404, přesně se šesti typy hodnot: objekt, pole, řetězec, číslo, boolean a null. Je de facto standardem výměny a jediným formátem, který nevyžaduje rozhodnutí o volbě.
• TOML: vytvořil Tom Preston-Werner, v1.0.0 publikována v lednu 2021. Deklarovaným cílem je minimální konfigurační formát se zřejmou sémantikou, který se jednoznačně mapuje na hash tabulku. Cargo.toml a pyproject.toml ho používají ve výchozím nastavení.
• YAML: aktuální specifikace je 1.2.2. Odsazení vyjadřuje hierarchii a podporuje komentáře, kotvy a více dokumentů. Manifesty Kubernetes, GitHub Actions a Ansible na něm závisí, za cenu rozsáhlé specifikace a rozdílů mezi implementacemi.
• CSON: CoffeeScript Object Notation, který píše konfiguraci pomocí objektových literálů CoffeeScriptu. Používal ho config.cson v Atomu. Podporuje komentáře, klíče bez uvozovek a koncové čárky, ale jeho ekosystém nikdy neopustil svět JavaScriptu.

2.1 Srovnání schopností

Dvě buňky si zaslouží poznámku. TOML nemá null, což je nejčastější selhání při převodu z JSON. Chování „nativního data“ v YAML znamená, že parser 1.1 automaticky změní 2026-10-31 na objekt data, takže typ driftuje napříč jazyky.

3. Komentáře: jediná slabina JSON

Nejprve závěr: pokud soubor udržuje člověk a potřebuje vysvětlit, proč má hodnota právě tuto podobu, nepoužívejte standardní JSON.

Existují čtyři praktické cesty, seřazené podle invazivnosti:

1. Přejděte k JSONC, což je standardní JSON plus komentáře a koncové čárky. Používá ho settings.json a tsconfig.json ve VS Code. Cenou je, že čtečka musí použít parser respektující komentáře, například jsonc-parser; obyčejný JSON.parse selže. Podrobnosti najdete v JSON5 a JSONC: JSON s komentáři.
2. Udržujte doprovodný dokument. config.json zůstane strojově čitelný, zatímco config.md vysvětluje, co každé pole znamená a proč nese tuto hodnotu. Oba žijí ve stejném adresáři a mění se ve stejném commitu.
3. Dejte vysvětlení do schématu. Klíčová slova description a $comment v JSON Schema umějí dokumentovat pole, ale schémata se zřídka dodávají spolu s běhovou konfigurací, takže ten, kdo konfiguraci čte, je nemusí nikdy vidět.
4. Přejděte k TOML nebo YAML a nechte formát sám poskytnout komentáře, kterým rozumí každý parser.

复制{
  // Pevně 8080: build skript frontendu čte tento port pro svou proxy
  "port": 8080,
  // Vypněte sledování, abyste v CI nevyčerpali inody
  "watch": false
}

JSONC je stále dialekt: přípona zůstává .json, ale rozumí mu jen některé nástroje. Když data opouštějí tým nebo překračují hranici služby, musí být hranice mezi JSONC a standardním JSON zdokumentována.

4. Data a víceřádkové řetězce: domácí půda TOML

TOML povyšuje datum a čas na prvotřídní typ se čtyřmi variantami: datum a čas s offsetem, místní datum a čas, místní datum a místní čas. Víceřádkové řetězce mají věnovanou syntaxi, která zachovává zalomení řádků:

复制title = "json-toolkit"
created = 2026-10-31T09:00:00+08:00
description = """
A JSON toolkit for developers.
Every operation runs locally in the browser.
"""

Stejná informace v JSON musí degradovat datum na řetězec a escapovat zalomení řádků:

复制{
  "title": "json-toolkit",
  "created": "2026-10-31T09:00:00+08:00",
  "description": "A JSON toolkit for developers.\nEvery operation runs locally in the browser."
}

V JSON je "created" jen řetězec, který náhodou vypadá jako datum, takže typová informace musí žít ve smlouvě pole: obě strany musí souhlasit, že pole je vždy RFC 3339. TOML dává parseru skutečný objekt data bez verbální dohody.

YAML také umí nést víceřádkový text, ale dva blokové styly znamenají různé věci: | zachovává zalomení řádků, zatímco > je skládá do mezer. Zvolte špatný a adresa nebo příkaz SQL se slisuje do jednoho řádku – chyba, kterou je v revizi velmi těžké zachytit.

5. Čísla: nejvíce přehlížený rozdíl

Specifikace JSON nestanoví limit přesnosti čísel, ale RFC 8259 také varuje, že interoperabilita je nejbezpečnější, když se čísla považují za doubly IEEE 754. V JavaScriptu celá čísla nad 2^53 - 1 tiše ztrácejí přesnost:

复制JSON.parse('{"id":9007199254740993}').id
// 9007199254740992: poslední číslice je pryč

TOML vyžaduje, aby se se znaménkem 64bitová celá čísla zpracovávala bezztrátově a aby se vyhodila chyba, místo aby se tiše zkracovala; desetinná čísla následují binary64 a mohou být také inf nebo nan. YAML 1.1 nese starší břemeno: 1:30 se parsuje jako 90 (šedesátinné) a booleany přijímají yes, no, on a off. Odtud klasický „norský problém“, kdy se kód země NO stane false.

U peněz se v žádném z těchto formátů nikdy nespoléhejte na plovoucí desetinnou čárku: použijte celá čísla v nejmenších jednotkách, řetězce nebo databázový desetinný typ. Formátování a přesnosti se podrobněji věnuje Hranice převodu JSON, YAML a XML.

6. Tabulky a vnoření: tvrdé hranice TOML

TOML vyjadřuje vnoření pomocí tabulek a polí tabulek:

复制[server]
port = 8080

[[routes]]
path = "/parse"
method = "POST"

[[routes]]
path = "/minify"
method = "POST"

Má dvě tvrdé hranice, které musíte znát před převodem:

• Kořenem dokumentu TOML je tabulka, takže dokument JSON, jehož nejvyšší úrovní je pole (například [1, 2, 3]), nemá legální reprezentaci v TOML; musí se obalit jako {"items": [...]};
• TOML nemá null, takže pole JSON null se musí buď zahodit, nebo nahradit prázdným řetězcem či sentinelovou hodnotou, přičemž sémantika se přesune na konzumenta.

YAML je opak: hloubka vnoření je neomezená a kotvy plus merge klíče umějí znovu použít fragmenty:

复制defaults: &defaults
  retries: 3
  timeoutMs: 5000

server:
  <<: *defaults
  port: 8080

Kotvy jsou schopnost pouze YAML a zaručená ztráta při převodu: JSON nemá syntaxi referencí, takže expandovaný soubor roste a nic nezaznamenává, že obě části bývaly stejnou konfigurací.

7. Volba podle scénáře

Pravidlo palce: nechte konfigurační formát zvolit ekosystém, nikoli osobní preference. Psaní v Rustu znamená Cargo.toml, nasazení do Kubernetes znamená YAML a stavba rozšíření VS Code znamená JSONC. Jen v novém projektu bez ekosystémových omezení je „co se lépe píše“ skutečnou otázkou.

8. Hranice převodu

Převodní nástroje zaručují hodnoty, nikdy komentáře. Neprojektujte proto obousměrnou pipeline, kde „JSON je zdroj a YAML je build artefakt“. Buď generujte jen jedním směrem, nebo udržujte jeden zdrojový soubor.

9. Kontrolní seznam

• [ ] Zdokumentujte, které typy souborů používají který formát, a vypište povolené dialekty;
• [ ] Pro konfiguraci udržovanou lidmi preferujte TOML nebo YAML a JSON pro výměnu mezi stroji;
• [ ] Data v JSON ukládejte jako řetězce RFC 3339 a formát označte ve schématu;
• [ ] Peníze a celá čísla nad 2^53 vyjadřujte jako řetězce nebo nejmenší jednotky, nikdy jako desetinná čísla;
• [ ] Každý formát validujte v CI jeho vlastním parserem, nikdy YAML pomocí JSON.parse;
• [ ] Migrujte formáty jen jedním směrem a starý soubor smažte, aby se nemohly rozejít.

Časté dotazy

Proč převod JSON do TOML u některých polí selhává?

TOML nemá null a kořenem dokumentu TOML je tabulka, takže pole JSON null se musí zahodit nebo nahradit prázdným řetězcem či sentinelem a pole na nejvyšší úrovni se musí obalit jako {"items": [...]}. Komentáře, typy data a inf/nan se také ztrácejí při pohybu opačným směrem, a proto má být převod jednosměrný.

Mám udržovat dva konfigurační soubory v různých formátech?

Ne. Převodní nástroje zaručují hodnoty, ale nikdy komentáře, takže pipeline, kde „JSON je zdroj a YAML je build artefakt“, bude driftovat. Buď generujte jen jedním směrem, nebo udržujte jeden zdrojový soubor a po migraci starý smažte.

Jak přidat komentáře do konfiguračního souboru JSON?

Standardní JSON komentáře nemá. Můžete přejít k JSONC (dialekt VS Code, čtený pomocí jsonc-parser), udržovat doprovodný dokument vysvětlující každé pole, nebo přejít k TOML či YAML. Soubory odesílané do jiných systémů by měly zůstat standardním JSON, s vysvětleními v dokumentaci nebo schématu.

Je TOML nebo YAML lepší pro konfiguraci aplikace?

TOML zvolte, když je struktura plochá, převážně dvojice klíč-hodnota a záleží na nativních datech; jeho sémantika je předvídatelnější a rozdíly mezi parsery menší. YAML zvolte, když potřebujete hluboké vnoření, více dokumentů, znovupoužití kotev, nebo když je cílový ekosystém YAML-first, například Kubernetes nebo CI. Oba podporují komentáře, takže skutečným rozlišovacím faktorem je strukturální složitost a uzamčení ekosystémem.

Proč se v YAML mění NO na false?

YAML 1.1 považuje yes, no, on, off, y a n za booleany, takže kód země Norska NO se parsuje jako false. To je „norský problém“. Vyhněte se mu použitím implementace, která se řídí YAML 1.2, nebo citováním každého řetězce, který by mohl být chybně interpretován.

Stojí CSON ještě za použití?

Pro nové projekty ne. CSON závisí na ekosystému CoffeeScriptu, má málo udržovaných nástrojů a omezenou podporu editorů i CI; poté co Atom přestal být udržován, jeho případy použití ještě zmenšily. Pokud projekt už konfiguraci CSON má, naplánujte jednorázovou migraci do JSON, TOML nebo YAML, místo abyste ho přidávali.