JSON5 a JSONC: JSON s komentáři

Stručně: JSONC použijte pro komentáře v konfiguraci VS Code a TypeScript, JSON5 použijte, když potřebujete širší literálovou syntaxi ES5.1, například jednoduché uvozovky nebo klíče bez uvozovek, a veřejná API držte na standardním JSON.

Standardní JSON komentáře nepovoluje, takže si je každý tým stejně tiše píše – až jednoho dne sestavení selže. Místo tajného obcházení si zvolte řádný dialekt.

1. Dva dialekty mají různé motivace

• JSONC (JSON with Comments): standardní JSON plus komentáře a koncové čárky, téměř bez dalších syntaktických změn. Je to de facto standard ekosystému VS Code – settings.json, tsconfig.json i .eslintrc.json ho používají.
• JSON5: mnohem ambicióznější, srovnává se přímo s objektovým literálem ES5.1 – jednoduché uvozovky, klíče bez uvozovek, hexadecimální čísla, Infinity/NaN, pokračování řádku zpětným lomítkem a úvodní znaménka +.

Jedna věta k rozlišení: JSONC jen činí psaní pohodlnějším; JSON5 vám dovolí napsat konfigurační soubor, jako by šlo o JavaScript.

2. Srovnávací tabulka syntaxe

Úplná specifikace JSON5 má sotva o něco víc než stránku; balíček json5 dlouho udržuje komunita a prohlížeče i Node se chovají identicky.

3. Parsování: dvě API, dva druhy schopnosti lokalizace

3.1 JSON5: jednoduché parsování celého dokumentu

复制import JSON5 from 'json5';

const config = JSON5.parse(`
{
  // port služby
  port: 8080,
  host: '0.0.0.0',
  features: ['json5', 'jsonc',],
  retries: 0x10,
}
`);

console.log(config.port, config.retries); // 8080 16

JSON5.parse vrací obyčejný objekt bez informace o offsetu – protože není určen pro editační scénáře, jen pro „čtení konfigurace“.

3.2 JSONC: syntaktický strom s offsety

Hodnota jsonc-parser není v parsování, ale v úpravách. Nabízí tři vrstvy API:

复制import { parseTree, findNodeAtLocation, modify, applyEdits } from 'jsonc-parser';

const text = `{
  // konfigurace portu
  "server": {
    "port": 8080 // v produkci 80
  }
}`;

const tree = parseTree(text);
const portNode = findNodeAtLocation(tree!, ['server', 'port']);
console.log(portNode?.offset, portNode?.length);

const edits = modify(text, ['server', 'port'], 3000, {
  formattingOptions: { insertSpaces: true, tabSize: 2 },
});
console.log(applyEdits(text, edits));

Výstup zachová původní komentáře a nahradí jen tři znaky 8080:

复制{
  // konfigurace portu
  "server": {
    "port": 3000 // v produkci 80
  }
}

To je přesně to, co „úprava konfigurace regulárními výrazy“ neumí: regulární výraz neví, který 8080 změnit, a neví, že 8080 uvnitř řetězce musí zůstat nedotčené.

3.3 Chybové zprávy musí nést offsety

Chybové kódy z jsonc-parser jsou hodnoty výčtu; běžné jsou:

Jakmile se offset převede na řádek a sloupec, editor může nakreslit vlnovku přesně na problematické místo.

4. Kdy použít který

Pravidlo palce: pokud soubor bude číst „ne‑lidský nástroj“, preferujte standardní JSON; dialekt zvažte jen tehdy, když máte jistotu, že ho čte výhradně váš vlastní kód.

5. Tři druhy rizik, které dialekty přinášejí

5.1 Přelévání požadavku

Když jiný nástroj čte konfigurační soubor JSON5 a zavolá JSON.parse, rovnou spadne. Typickým příznakem je „lokálně to funguje, v Dockeru ne“ – protože kontejner běží jinou čtecí cestu.

Protiopatření: přidejte do repozitáře kontrolu v CI, která explicitně vypisuje, které soubory smějí používat dialekt; všechno ostatní se validuje jako standardní JSON.

5.2 Překvapení kolem odvozování typů

JSON5 povoluje klíče bez uvozovek a jednoduché uvozovky, ale neumožňuje přinést literálové konstrukty jako data nebo regulární výrazy – je to stále datový formát, nikoli vyhodnocování JavaScriptu. Lidé předpokládali, že JSON5 umí vyjádřit new Date(), a dočkali se selhání parsování. JSON5 není eval.

5.3 Tiše zahazované komentáře

Ani JSON5.stringify, ani JSON.stringify komentáře nezachovává. Takže „načíst, upravit hodnotu, zapsat zpět“ ztratí každý komentář. Když komentáře musí přežít, jediné možnosti jsou editační API jsonc-parser nebo knihovna YAML, která podporuje zachování komentářů.

6. Praktická doporučení

• [ ] Držte v týmové dokumentaci tabulku „typ souboru → formát“, aby nikdo neimprovizoval;
• [ ] Čtení konfigurace obalte do jediného loadConfig(), který interně rozhodne, který parser použít, aby obchodní kód nikdy nevolal JSON.parse přímo;
• [ ] Při programové úpravě konfigurace s komentáři používejte modify + applyEdits; nikdy nepřepisujte celý soubor;
• [ ] Validujte soubory dialektu i v CI (jsonc-parser pro JSONC, JSON5.parse pro JSON5), jinak se syntaktické chyby objeví až za běhu;
• [ ] Pro veřejná rozhraní, klíče cache a payloady front zpráv používejte standardní JSON.

Časté dotazy

Jak volit mezi JSON5 a JSONC?

Vybírejte podle běhového prostředí, nikoli podle počtu syntaxí: VS Code, TypeScript a ESLint čtou JSONC ve výchozím nastavení, takže JSONC dává nejlepší kompatibilitu; JSON5 sáhněte jen tehdy, když potřebujete širší literálovou syntaxi ES5.1, například jednoduché uvozovky, klíče bez uvozovek nebo Infinity. Ani jeden dialekt není vhodný pro odpovědi veřejného API.

Proč standardní parser JSON nemůže číst JSONC přímo?

JSONC povoluje komentáře a koncové čárky, zatímco JSON.parse přijímá jen JSON podle RFC 8259 a na obojím vyhodí chybu. Čtení JSONC vyžaduje parser jako jsonc-parser, nebo odstranění komentářů před předáním textu standardnímu parseru.

Mají komentáře v JSONC přežít úpravy souboru?

Ano, ale jen prostřednictvím editačního API. modify a applyEdits v jsonc-parser mění cílový uzel při zachování ostatních komentářů; parsování do objektu a jeho stringify zahodí každý komentář.