JSON5 i JSONC: bardziej wyrozumiały sposób formatowania JSON
Kiedy ścisły JSON każe debugować do późnej nocy z powodu jednego brakującego przecinka, najwyższy czas poznać jego bardziej wyrozumiałych krewnych — JSON5 oraz JSON with Comments (JSONC).
Czym jest JSON5?
JSON5 to rozszerzenie JSON, które przejmuje funkcje z ECMAScript 5.1, w tym klucze bez cudzysłowów, przecinki kończące, łańcuchy w pojedynczych cudzysłowach, komentarze oraz liczby szesnastkowe. Format jest rozwijany przez społeczność i został zaprojektowany tak, aby ręcznie pisane pliki konfiguracyjne były czytelniejsze i bardziej wyrozumiałe niż w przypadku ścisłego JSON.
Czym jest JSONC?
JSONC (JSON with Comments) to minimalne rozszerzenie standardowego JSON, które dodaje obsługę komentarzy jednoliniowych (//) i wieloliniowych (/* */) oraz przecinków kończących. Jest utrzymywany przez Microsoft i pełni funkcję natywnego formatu dla ustawień VS Code, plików tsconfig.json oraz innych plików konfiguracyjnych TypeScript.
Po co nam „wyrozumiały” JSON
- Bariery czytelności: Standardowy JSON zabrania komentarzy, przecinków kończących, pojedynczych cudzysłowów itd., co utrudnia zrozumienie konfiguracji i przykładów.
- Trudność współpracy w zespole: Ogromne pliki JSON bez żadnych adnotacji są trudne w utrzymaniu; drobna edycja może uszkodzić cały plik.
- Realia DevOps: Kubernetes oraz pipeline’y CI/CD często łączą lub generują JSON w locie; wyrozumiała składnia mocno ogranicza ręczne poprawki.
JSON5 a JSONC — szybkie porównanie
| Cecha | JSON (ścisły) | JSON5 | JSONC |
|---|---|---|---|
// komentarze jednoliniowe | Nie | Tak | Tak |
/* */ komentarze wieloliniowe | Nie | Tak | Tak |
| Przecinki kończące | Nie | Tak | Tak |
| Łańcuchy w pojedynczych cudzysłowach | Nie | Tak | Nie |
| Klucze bez cudzysłowów | Nie | Tak | Nie |
Znaki liczbowe + / - | Nie | Tak | Nie |
| Liczby szesnastkowe i binarne | Nie | Tak | Nie |
| Opiekunowie specyfikacji | ECMA | Społeczność (A. Rauschmayer) | Microsoft / VS Code |
W jednym zdaniu: JSON5 sprawia wrażenie literału obiektu JavaScript, podczas gdy JSONC to po prostu standardowy JSON z komentarzami.
Przykłady składni
Klasyczny JSON (ścisły)
{
"name": "Go Tools",
"features": ["Base64", "JSON Formatter"]
}Przykład JSON5
// Project config
{
name: 'Go Tools', // single quotes & unquoted keys
features: [
'Base64',
'JSON Formatter', // trailing comma
],
version: 1.0, // non-string number allowed
}Przykład JSONC
{
// Project name
"name": "Go Tools",
// Feature list
"features": [
"Base64",
"JSON Formatter", // trailing comma
]
}Wsparcie dla formatowania i parsowania
| Scenariusz | JSON5 | JSONC | Polecane biblioteki / narzędzia |
|---|---|---|---|
| Przeglądarka | Polyfill JSON5.parse(), Prettier z wbudowanym parser json5 (>= v1.13) | Natywne wsparcie settings.json w VS Code | — |
| Node.js | Pakiet npm json5 | comment-json, jsonc-parser | Obsługują formatowanie z CLI i parsowanie AST |
| IDE | Rozszerzenia do VS Code i WebStorm | Natywne w VS Code, wtyczka do WebStorm | Prettier ujednolica formatowanie |
| CI / Lint | eslint-plugin-json5 | eslint-plugin-jsonc | Integracja z Husky i lint-staged |
| Narzędzie online | Go Tools JSON Formatter (upiększa i waliduje JSON5/JSONC) | To samo | Formatowanie JSON |
Szybkie formatowanie w VS Code
Dodaj do settings.json:
"[jsonc]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
}Następnie wystarczy nacisnąć Alt + Shift + F, aby upiększyć dowolny plik JSONC.
Pliki konfiguracyjne w realnym świecie
JSON5 oraz JSONC są już szeroko używane w plikach konfiguracyjnych spotykanych na co dzień. Oto konkretne przykłady:
TypeScript (tsconfig.json — JSONC)
{
// Strict mode catches more bugs at compile time
"compilerOptions": {
"strict": true,
"target": "ES2022",
"module": "ESNext",
"outDir": "./dist",
// Path aliases for cleaner imports
"paths": {
"@/*": ["./src/*"],
"@tests/*": ["./tests/*"],
},
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"],
}Plik tsconfig.json w TypeScript natywnie korzysta z JSONC — komentarze i przecinki kończące działają od razu. To jeden z najczęściej spotykanych plików JSONC w każdym projekcie JavaScript/TypeScript.
ESLint flat config (eslint.config.json — JSONC)
{
"rules": {
// Warn on console.log, but allow console.error
"no-console": ["warn", { "allow": ["error", "warn"] }],
"semi": ["error", "always"],
"quotes": ["error", "double"],
}
}Babel (babel.config.json5 — JSON5)
{
// Single quotes and unquoted keys make it more readable
presets: [
['@babel/preset-env', {
targets: '> 0.25%, not dead',
modules: false, // Let bundler handle modules
}],
],
plugins: [
'@babel/plugin-transform-runtime',
],
}Ustawienia obszaru roboczego VS Code (.vscode/settings.json — JSONC)
{
// Editor preferences
"editor.fontSize": 14,
"editor.tabSize": 2,
"editor.formatOnSave": true,
// Language-specific overrides
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
},
"[jsonc]": {
"editor.defaultFormatter": "esbenp.prettier-vscode",
},
}Praktyczne wskazówki i pułapki
1. Konwersja przed wdrożeniem na produkcję
Przeglądarki nadal wymagają ścisłego JSON dla JSON.parse. Warto użyć narzędzi z etapu builda, aby usunąć komentarze i przecinki kończące:
// Node.js build script: convert JSON5 config to strict JSON
import JSON5 from 'json5';
import { readFileSync, writeFileSync } from 'fs';
const config = JSON5.parse(readFileSync('config.json5', 'utf8'));
writeFileSync('config.json', JSON.stringify(config, null, 2));W przypadku bundlerów można sięgnąć po rollup-plugin-json5 lub vite-plugin-json5, które obsłużą konwersję automatycznie podczas builda.
2. Bezpieczeństwo i niezawodność
Pobłażliwość może maskować nadmiarowe pola. Konfigurację należy zawsze walidować z użyciem JSON Schema lub zod, zanim zostanie ona zużyta:
// Validate config shape with zod after parsing
import { z } from 'zod';
import JSON5 from 'json5';
const ConfigSchema = z.object({
port: z.number().min(1).max(65535),
host: z.string(),
debug: z.boolean().default(false),
});
const raw = JSON5.parse(readFileSync('config.json5', 'utf8'));
const config = ConfigSchema.parse(raw); // Throws if invalid3. Konwencje zespołowe
- Warto zaznaczyć w README, że pliki
*.json5służą wyłącznie do konfiguracji; pakiety wydawane do publikacji powinny zawierać ścisłe.json. - Należy ustandaryzować reguły Prettier, aby ograniczyć szum w diffach.
- Plik
.editorconfigpomaga wymusić spójne wcięcia w plikach JSON, JSON5 oraz JSONC.
4. Wydajność
Parsowanie JSON5/JSONC dokłada zależności i lekki narzut — to do przyjęcia w narzędziach CLI i deweloperskich, ale na produkcji warto to zmierzyć. Pakiet npm json5 waży około 8 KB po minifikacji, a parsowanie jest mniej więcej 2–5 razy wolniejsze niż natywny JSON.parse. Dla plików konfiguracyjnych ładowanych raz przy starcie różnica jest pomijalna. Dla gorących ścieżek przetwarzających tysiące obiektów na sekundę lepiej pozostać przy ścisłym JSON.
Najczęściej zadawane pytania
Jaka jest różnica między JSON5 a JSONC?
JSON5 rozszerza JSON o składnię w stylu JavaScriptu: klucze bez cudzysłowów, przecinki kończące, komentarze jednoliniowe i blokowe, liczby szesnastkowe oraz wieloliniowe łańcuchy. JSONC jest prostszy — dodaje wyłącznie komentarze jednoliniowe (//) i blokowe (/* */) do standardowego JSON. JSONC wybierze się do plików konfiguracyjnych, gdzie wystarczą komentarze; JSON5 sprawdzi się tam, gdzie potrzeba bogatszej składni.
Czy można używać JSON5 lub JSONC w produkcyjnych API?
Nie — JSON5 i JSONC są przeznaczone do plików konfiguracyjnych, a nie do wymiany danych. API powinny korzystać ze standardowego JSON (RFC 8259), aby zapewnić maksymalną interoperacyjność. JSON5/JSONC warto zarezerwować dla lokalnych plików konfiguracyjnych takich jak tsconfig.json, .vscode/settings.json lub konfiguracji środowiska, gdzie czytelność dla człowieka liczy się bardziej niż przetwarzanie maszynowe.
Czy VS Code natywnie obsługuje JSON5?
VS Code obsługuje JSONC natywnie (jego własne pliki ustawień korzystają z JSONC), ale nie wspiera JSON5 od razu po instalacji. Dla JSON5 należy zainstalować dedykowane rozszerzenie, na przykład „JSON5 syntax” z marketplace VS Code. Można też w ustawieniach skojarzyć pliki .json5 z trybem językowym JSON5.
Jak skonwertować JSON5 do standardowego JSON?
Wystarczy użyć pakietu npm json5: JSON5.parse() wczytuje JSON5, a następnie JSON.stringify() zwraca standardowy JSON. W wersji CLI można uruchomić npx json5 < input.json5 > output.json. Narzędzia online, takie jak nasz JSON Formatter, potrafią również zwalidować skonwertowany wynik, aby potwierdzić jego poprawność.
Czy JSONC to to samo co JSON with Comments?
Tak — JSONC to skrót od „JSON with Comments” i jest formatem używanym przez VS Code, TypeScript (tsconfig.json) oraz inne narzędzia Microsoftu. Format trzyma się standardowej specyfikacji JSON, dodając jedynie komentarze // i /* */. Parser usuwa komentarze przed właściwym przetwarzaniem, dzięki czemu otrzymana struktura danych jest identyczna jak w standardowym JSON.
Aby poznać więcej narzędzi deweloperskich działających w przeglądarce — w tym kodowanie Base64, generowanie sum kontrolnych i konwersję timestampów — warto zajrzeć do naszego przewodnika po niezbędnych narzędziach dla programistów.
Podsumowanie
Zachowanie równowagi między czytelnością a rygorem to klasyczne wyzwanie deweloperskie. JSON5 oraz JSONC poprawiają komfort pisania, a w połączeniu z odpowiednim pipeline’em buildowania i walidacji można bezpiecznie cieszyć się zaletami „pobłażliwego JSON”.