JSON z komentarzami

JSONC (JSON with Comments) rozszerza standardowy JSON o komentarze w stylu JavaScript. Wiele narzędzi deweloperskich używa JSONC dla plików konfiguracyjnych, gdzie komentarze pomagają dokumentować ustawienia. Ten parser usuwa komentarze, tworząc prawidłowy JSON, zachowując strukturę danych.

Specyfikacje

• jsonc-parser (VS Code)
• TypeScript tsconfig.json

Typowe zastosowania

• Parsowanie tsconfig.json i jsconfig.json dla projektów TypeScript/JavaScript
• Odczyt settings.json VS Code i konfiguracji rozszerzeń
• Przetwarzanie plików konfiguracyjnych Cloudflare wrangler.jsonc
• Edycja konfiguracji ESLint, Prettier i innych narzędzi z dokumentacją inline

Funkcje

• Parsowanie komentarzy jednoliniowych (// komentarz)
• Parsowanie komentarzy wieloliniowych (/* komentarz */)
• Obsługa końcowych przecinków (powszechnych w plikach JSONC)
• Usuwanie komentarzy w celu uzyskania prawidłowego wyjścia JSON
• Wszystkie standardowe funkcje parsera JSON (widok drzewa, konwersja)

Przyklady

{
  // Compiler options for the project
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    /* Enable all strict type checking options */
    "strict": true
  }
}

Wskazowki

• VS Code, TypeScript i wiele nowoczesnych narzędzi natywnie obsługuje JSONC.
• Udostępniając konfigurację, rozważ, czy narzędzia odbiorców obsługują komentarze.
• Konwertuj do standardowego JSON, usuwając komentarze, gdy narzędzia wymagają ścisłego JSON.

Zrozumienie JSON z komentarzami

JSONC (JSON with Comments) to rozszerzenie standardowego JSON, które pozwala na jednoliniowe (//) i wieloliniowe (/* */) komentarze w stylu JavaScript, a także końcowe przecinki po ostatnim elemencie w tablicach i obiektach. Choć nie jest oficjalnym standardem, JSONC stał się de facto formatem dla plików konfiguracyjnych skierowanych do deweloperów, gdzie dokumentacja inline poprawia utrzymywalność.

Microsoft spopularyzował JSONC poprzez Visual Studio Code, który używa go dla settings.json, keybindings.json, launch.json i extensions.json. Plik tsconfig.json TypeScript i jsconfig.json JavaScript to pliki JSONC, podobnie jak wiele plików konfiguracyjnych ESLint, Prettier i Babel przy użyciu rozszerzenia .json. Cloudflare wrangler.jsonc jawnie używa rozszerzenia .jsonc, aby zasygnalizować obsługę komentarzy.

Kluczową zaletą JSONC nad zwykłym JSON jest dokumentacja. Pliki konfiguracyjne często zawierają ustawienia, których cel nie jest oczywisty z samej nazwy klucza. Komentarze pozwalają deweloperom wyjaśnić, dlaczego dane ustawienie istnieje, jakie wartości są prawidłowe i jakie mogą być konsekwencje zmian. Końcowe przecinki zmniejszają szum w kontroli wersji, pozwalając ostatniemu elementowi mieć ten sam format co wszystkie inne, więc dodanie nowego elementu pokazuje tylko jedną zmienioną linię w diffie zamiast dwóch.

Pod maską parsery JSONC działają, usuwając komentarze i końcowe przecinki przed przekazaniem wyniku do standardowego parsera JSON. Oznacza to, że model danych jest identyczny z JSON — komentarze to metadane dla ludzi, nie dane dla programów. Przy konwersji JSONC do JSON dla narzędzi wymagających ścisłej zgodności z JSON, komentarze są po prostu usuwane. Biblioteka node-jsonc-parser Microsoftu, używana w VS Code, jest referencyjną implementacją parsowania JSONC.

JSONC nie jest oficjalnym standardem zdefiniowanym przez jakąkolwiek specyfikację RFC czy ECMA. To konwencja spopularyzowana przez Microsoft poprzez VS Code i TypeScript, z zachowaniem dobrze zdefiniowanym przez bibliotekę jsonc-parser, która służy jako referencyjna implementacja. Inne narzędzia obsługujące JSONC — ESLint, Prettier i różne edytory — podążają za tymi samymi konwencjami dla komentarzy jednoliniowych, wieloliniowych i końcowych przecinków. Typowe pliki JSONC to tsconfig.json i jsconfig.json (TypeScript/JavaScript), pliki ustawień VS Code (settings.json, launch.json, tasks.json, keybindings.json), wrangler.jsonc (Cloudflare Workers), devcontainer.json (VS Code Dev Containers) i różne inne konfiguracje narzędzi. Każdy plik JSON edytowany głównie przez deweloperów, który mógłby skorzystać z komentarzy, prawdopodobnie obsługuje JSONC.

JSONC powinien być używany tylko dla plików konfiguracyjnych odczytywanych przez narzędzia z jawną obsługą JSONC. Odpowiedzi API, przechowywanie danych i komunikacja między serwisami powinny zawsze używać standardowego JSON, ponieważ większość parserów JSON odrzuci komentarze jako błędy składniowe. Aby przetworzyć plik konfiguracyjny JSONC programowo za pomocą standardowego parsera JSON, najpierw usuń komentarze za pomocą biblioteki obsługującej JSONC.

JSONC jest bardziej konserwatywny niż JSON5, który jest bardziej rozbudowanym nadzbiorem JSON. Podczas gdy JSONC dodaje tylko komentarze i końcowe przecinki, JSON5 pozwala również na ciągi w pojedynczych cudzysłowach, niecytowane klucze obiektów, liczby szesnastkowe, wiodące i końcowe kropki dziesiętne, Infinity i NaN oraz ciągi wieloliniowe. JSONC ma szerszą obsługę narzędzi w ekosystemie deweloperskim, podczas gdy JSON5 jest używany w konkretnych plikach konfiguracyjnych, takich jak babel.config.json5 Babela, ale ma węższą adopcję ogólną.