JSON5 ve JSONC: Daha Esnek JSON Biçimlendirme Rehberi

Katı JSON, eksik tek bir virgül yüzünden gece yarısına kadar hata ayıklamanıza neden olduğunda, onun daha esnek kuzenleriyle — JSON5 ve JSON with Comments (JSONC) ile — tanışmanın zamanı gelmiş demektir.

JSON5 Nedir?

JSON5, ECMAScript 5.1’in özelliklerini içeren bir JSON uzantısıdır; tırnaksız anahtarlar, son virgüller, tek tırnaklı karakter dizileri, yorumlar ve onaltılı sayılar gibi özellikler sunar. Topluluk tarafından sürdürülen bu format, elle yazılan yapılandırma dosyalarını katı JSON’a göre daha okunaklı ve daha esnek hale getirmek için tasarlanmıştır.

JSONC Nedir?

JSONC (JSON with Comments), standart JSON’un asgari düzeyde bir uzantısıdır; JSON’a tek satırlı (//) ve çok satırlı (/* */) yorumlar ekler. Son virgüllere izin verilip verilmediği ise ayrıştırıcıya bağlıdır. VS Code ayarları, tsconfig.json ve diğer TypeScript yapılandırma dosyaları için yerel formattır.

Neden “Esnek” JSON’a İhtiyacımız Var

Okunabilirlik darboğazları: Standart JSON yorumlara, son virgüllere, tek tırnaklara vb. izin vermez; bu da yapılandırmaların ve örneklerin anlaşılmasını zorlaştırır.
Ekip iş birliği sorunları: Satır içi notları olmayan devasa JSON dosyalarının bakımı zordur; küçük bir değişiklik tüm dosyayı bozabilir.
DevOps gerçekleri: Kubernetes ve CI/CD pipeline’ları sıklıkla JSON’u çalışma anında birleştirir veya üretir; esnek söz dizimi elle yapılan düzeltmeleri büyük ölçüde azaltır.

JSON5 ile JSONC Karşılaştırması

Özellik	JSON (RFC 8259)	JSONC	JSON5
`//` ve `/* */` yorumlar	Hayır	Evet	Evet
Son virgüller	Hayır	Ayrıştırıcıya bağlı (aşağıya bakın)	Evet, nesne veya dizi başına bir tane
Tırnaksız anahtarlar	Hayır	Hayır	Evet
Tek tırnaklı karakter dizileri	Hayır	Hayır	Evet
Birden fazla satıra yayılan karakter dizileri (kaçış karakterli satır sonu)	Hayır	Hayır	Evet
Onaltılı sayılar (`0x1F`)	Hayır	Hayır	Evet
`.5`, `5.`, baştaki `+`	Hayır	Hayır	Evet
`Infinity`, `NaN`	Hayır	Hayır	Evet
İkili sayılar (`0b101`)	Hayır	Hayır	Hayır
Belirtim	RFC 8259 / ECMA-404	Resmî standart yok; pratikte VS Code ve `jsonc-parser` belirler	JSON5 belirtimi 1.0.0
Yerleşik `JSON.parse` / `json.loads`	Evet	Hayır	Hayır

Kaynaklar: JSON5 belirtimi, VS Code JSON dokümantasyonu ve RFC 8259. Ayrıca JSON5.parse('{a: 0b101}') çağrısını json5 2.2.3 ile çalıştırdık; çağrı JSON5: invalid character 'b' at 1:6 hatasıyla başarısız oluyor.

Tek cümlede: JSON5 bir JavaScript nesne sabitini andırır; JSONC ise yorumlara göz yuman sıradan JSON’dur — anahtarlar da karakter dizileri de yine çift tırnak içinde yazılmalıdır.

JSONC’de son virgüller ayrıştırıcıya bağlıdır

JSONC’nin resmî bir belirtimi yoktur. Microsoft bu formatı VS Code’un yapılandırma dosyaları için gayriresmî olarak kullanıma sokmuş ve yanında jsonc-parser ayrıştırıcısını yayımlamıştır. jsonc.org adresindeki bir topluluk taslağı formatı resmîleştirmeye çalışıyor; taslak son virgüller konusunda yalnızca şunu söylüyor: ayrıştırıcılar “MAY support trailing commas” (son virgülleri destekleyebilir). Gerçek araçlar ise farklı davranıyor:

Ayrıştırıcı veya araç	Son virgül	Kaynak
VS Code, JSON with Comments modu	Kabul edilir, ancak uyarı verilir	VS Code dokümantasyonu
`jsonc-parser` 3.3.1, varsayılan seçenekler	`PropertyNameExpected` / `ValueExpected` hatası olarak raporlanır, ancak yine de bir değer döndürülür	Aşağıdaki test
`jsonc-parser` 3.3.1, `allowTrailingComma: true`	Kabul edilir	Aşağıdaki test
TypeScript 5.9.3 (`tsc -p`)	Kabul edilir	Aşağıdaki tsconfig örneğiyle test
Deno (`deno.jsonc`)	Kabul edilir	Deno yapılandırma dokümantasyonu

Her JSONC okuyucusunun kabul edeceği bir dosya istiyorsanız son virgül kullanmayın.

Söz Dizimi Örnekleri

Klasik JSON (katı)

{
  "name": "Go Tools",
  "features": ["Base64", "JSON Formatter"]
}

JSON5 Örneği

Bir JSON5 dosyası, config.json5:

// geliştirme yapılandırması
{
  name: 'go-tools',
  port: 0x1F90,       // onaltılı 8080
  tags: ['json', 'json5',],
}

JSONC Örneği

Bir JSONC dosyası, tsconfig.json:

{
  // katı tür denetimi
  "compilerOptions": {
    "strict": true,
    "target": "ES2022", /* modern çıktı */
  },
  "include": ["src"],
}

Dosyanız hangi formatta?

Uzantıya bakmak tek başına yetmez: .json uzantılı bir dosya da JSONC veya JSON5 olarak ayrıştırılabilir. Önce bu tabloya, ardından dosyayı okuyan aracın dokümantasyonuna bakın.

Dosya	Format	Notlar	Kaynak
`tsconfig.json`, `jsconfig.json`, `tsconfig.*.json`	JSONC	VS Code bu dosyaları JSONC modunda açar; `tsc` 5.9.3 yorumları ve son virgülleri kabul eder	VS Code kaynak kodu (`typescript-basics`), kendi testimiz
`.vscode/settings.json`, `tasks.json`, `launch.json`	JSONC	JSON with Comments dosyaları olarak listelenir	VS Code dokümantasyonu
`devcontainer.json`	JSONC	Belirtim bu dosyayı “a JSON with Comments file” (yorumlu bir JSON dosyası) olarak tanımlar	Dev Container belirtimi
`deno.jsonc`	JSONC	“with `deno.jsonc` you can add comments and trailing commas” (`deno.jsonc` ile yorum ve son virgül ekleyebilirsiniz)	Deno dokümantasyonu
`babel.config.json`, `.babelrc.json`	`.json` uzantısına rağmen JSON5	Babel bu dosyaları JSON5 olarak ayrıştırır; VS Code ise JSONC olarak renklendirir	Babel dokümantasyonu, VS Code kaynak kodu
`renovate.json5`, `.renovaterc.json5`	JSON5	`renovate.json` da JSONC kabul eder	Renovate dokümantasyonu
Tüm `*.json5` dosyaları	JSON5	—	—
`package.json`	Katı JSON	npm: “It must be actual JSON, not just a JavaScript object literal.” (Yalnızca bir JavaScript nesne sabiti değil, gerçek JSON olmalıdır.)	npm dokümantasyonu, kendi testimiz

Babel, babel.config.json5 adlı bir dosya aramaz: .json5, dokümantasyonunda listelenen uzantılar arasında yer almaz. Babel’in JSON5 olarak okuduğu dosyalar .json uzantılı varyantlardır.

Karşınıza çıkacak hata mesajları (birebir)

Aynı iki küçük dosyayı her ortamda ayrıştırmayı denedik. comment.json bir yorum içeriyor:

{
  // geliştirme sunucusu portu
  "port": 8080
}

trailing.json ise bir son virgül içeriyor:

{
  "port": 8080,
}

Node.js 26.10.0, JSON.parse (ikisi de V8 kullandığı için Chrome Headless Shell 156 aynı metni verir):

comment.json  -> SyntaxError: Expected property name or '}' in JSON at position 4 (line 2 column 3)
trailing.json -> SyntaxError: Expected double-quoted property name in JSON at position 18 (line 3 column 1)

Python 3.13.5, json.loads:

comment.json  -> json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes: line 2 column 3 (char 4)
trailing.json -> json.decoder.JSONDecodeError: Illegal trailing comma before end of object: line 2 column 15 (char 16)

jq 1.7:

comment.json  -> jq: parse error: Invalid numeric literal at line 2, column 5
trailing.json -> jq: parse error: Expected another key-value pair at line 3, column 1

npm 11.19.1, package.json içinde bir // comment satırı varken:

npm error code EJSONPARSE
npm error JSON.parse Invalid package.json: JSONParseError: Expected property name or '}' in JSON at position 4 (line 2 column 3) while parsing near "{\n  // comment\n  \"name\":..."
npm error JSON.parse Failed to parse JSON data.
npm error JSON.parse Note: package.json must be actual JSON, not just JavaScript.

Bu mesajları şöyle okuyabilirsiniz:

position 4 (line 2 column 3), yorumun ilk / karakterini gösterir. Hata // veya /* ile başlayan bir satırın başına denk geliyorsa dosya neredeyse kesinlikle JSONC ya da JSON5 formatındadır.
Son virgüllerde V8 ile Python farklı yerleri gösterir. V8 kapanış } karakterini (3. satır) raporlarken Python 3.13.5 virgülün kendisini (2. satır, 15. sütun) raporlar. Başka sürümler bu mesajları farklı ifade edebilir; yukarıdaki metinler bu sürümlerin birebir çıktısıdır.
Hata mesajı göremediğiniz bir karakteri alıntılıyorsa, örneğin Node 26’nın Unexpected token '', "{}" is not valid JSON mesajında olduğu gibi (iki tırnaklı kısmın ikisinde de aslında görünmez bir U+FEFF vardır), dosya büyük olasılıkla bir yorumla değil, görünmez bir bayt sırası işaretiyle (BOM) başlıyordur. Ayrıntılar için UTF-8 BOM: JSON ayrıştırma ve CSV hatalarını çözün yazısına bakın.

JSONC veya JSON5’i standart JSON’a dönüştürme

Dönüştürme sırasında tüm yorumlar silinir, çünkü JSON’da onları saklayacak bir yer yoktur. Yorumlu dosyayı kaynak olarak tutun; .json çıktısını ise otomatik üretilen bir dosya olarak görün.

Node.js: `json5` ile JSON5’ten JSON’a

// json5-to-json.mjs (kurulum: npm install json5)
import { readFileSync, writeFileSync } from 'node:fs';
import JSON5 from 'json5';

const data = JSON5.parse(readFileSync('config.json5', 'utf8'));
writeFileSync('config.json', JSON.stringify(data, null, 2) + '\n');

Yukarıdaki JSON5 örneği üzerinde json5 2.2.3 ile çalıştırıldığında config.json şu hale gelir:

{
  "name": "go-tools",
  "port": 8080,
  "tags": [
    "json",
    "json5"
  ]
}

Node.js: `jsonc-parser` ile JSONC’den JSON’a

jsonc-parser, Microsoft’un yorumlu JSON için geliştirdiği ayrıştırıcıdır. parse() fonksiyonu söz dizimi hatalarında istisna fırlatmaz. Sorunları bir errors dizisinde toplar ve yine de elinden gelen en iyi sonucu döndürür; bu yüzden diziyi kendiniz kontrol etmelisiniz:

// jsonc-to-json.mjs (kurulum: npm install jsonc-parser)
import { readFileSync } from 'node:fs';
import { parse, printParseErrorCode } from 'jsonc-parser';

const errors = [];
const data = parse(readFileSync('tsconfig.json', 'utf8'), errors, {
  allowTrailingComma: true,
});
if (errors.length > 0) {
  for (const e of errors) console.error(printParseErrorCode(e.error), 'at offset', e.offset);
  process.exit(1);
}
console.log(JSON.stringify(data, null, 2));

jsonc-parser 3.3.1 ve yukarıdaki tsconfig örneğiyle bu betik temiz JSON yazdırır ve 0 koduyla çıkar. allowTrailingComma: true olmadan aynı dosya, her son virgülün hemen ardından gelen } karakterinde PropertyNameExpected ve ValueExpected hatalarını raporlar.

Python: `json5` paketi

Standart kütüphanedeki json modülünde yorumlara izin veren bir seçenek yoktur. json5 paketi JSON5 okur; yorumlar ve son virgüller JSON5’te geçerli olduğu için JSONC dosyalarını da okuyabilir:

# kurulum: pip install json5
import json

import json5

with open("tsconfig.json", encoding="utf-8") as f:
    data = json5.load(f)

print(json.dumps(data, indent=2, ensure_ascii=False))

Python 3.13.5 ve json5 0.17.3 ile test edildi; Node sürümüyle aynı JSON’u yazdırır.

Komut satırı: `json5` CLI

json5 npm paketi, JSON’a dönüştüren ve doğrulayan bir CLI içerir. Bu CLI JSONC dosyalarını da okur:

npx json5 config.json5                      # stdout'a kompakt JSON
npx json5 -s 2 -o config.json config.json5  # girintili, dosyaya yazılır
npx json5 -v tsconfig.json                  # yalnızca doğrulama; söz dizimi hatasında çıkış kodu 1

-v söz dizimi hatasında 1 koduyla çıktığı için aynı komut, elle düzenlenen JSON5 veya JSONC dosyalarını denetleyen bir CI adımı olarak da kullanılabilir.

jq burada işe yaramaz: yukarıda görüldüğü gibi jq 1.7 ilk yorumda durur.

`Infinity` ve `NaN` değerlerine dikkat edin

JSON5 Infinity ve NaN değerlerine izin verir, ancak JSON’da bunları yazmanın bir yolu yoktur ve iki dil bu durumu farklı ele alır:

JSON.stringify(JSON5.parse('{a: Infinity, b: NaN}'));
// '{"a":null,"b":null}'  (sessizce null olur)

json.dumps(json5.loads('{a: Infinity, b: NaN}'))
# '{"a": Infinity, "b": NaN}'  (geçerli JSON olmayan bir çıktı)
json.dumps(json5.loads('{a: Infinity}'), allow_nan=False)
# ValueError: Out of range float values are not JSON compliant: inf

Bir JSON5 dosyası bu değerleri içerebiliyorsa Python’da allow_nan=False parametresini verin ya da dönüştürmeden önce bu değerleri kontrol edin. " veya ters eğik çizgi içeren tek tırnaklı JSON5 karakter dizileri, JSON.stringify tarafından yeniden kaçış karakteriyle korunur. Kurallar JSON dizelerini escape etme rehberinde anlatılıyor.

Dönüştürülen JSON’u doğrulayın

Dönüştürdükten sonra çıktıyı JSON Biçimlendirici aracına yapıştırarak doğrulayabilir ve pretty-print ile okunaklı hale getirebilirsiniz. Araç tarayıcınızda çalışır.

Biçimlendiricinin yalnızca katı JSON kabul ettiğini unutmayın. Ayrıştırma için tarayıcının JSON.parse fonksiyonunu kullanır; bu yüzden bir JSONC veya JSON5 dosyasını olduğu gibi yapıştırırsanız söz dizimi hatası alırsınız ve araç ayrıştırmanın durduğu satırı ve sütunu gösterir. Önce dönüştürün, sonra doğrulayın.

JSONC veya JSON5 ne zaman kullanılmamalı

API payload’ları ve veri alışverişi. RFC 8259’a göre JSON üreten bir uygulama “MUST strictly conform to the JSON grammar” (JSON gramerine kesinlikle uymalıdır). Alıcı taraf genellikle JSON.parse veya json.loads kullanır ve ikisi de yorumları reddeder.
package.json. npm katı JSON ister. Tek bir yorum bile npm run gibi npm komutlarının EJSONPARSE hatasıyla başarısız olmasına yeter.
Kontrolünüzde olmayan araçların okuduğu dosyalar. Node’un require('./tsconfig.json') çağrısı katı JSON ayrıştırıcısını kullanır ve yorumlu bir tsconfig’de başarısız olur (SyntaxError: …tsconfig.json: Expected property name or '}' in JSON at position 4). JSONC dosyası okuyan her betik bir JSONC ayrıştırıcısı kullanmalıdır.
Sessizce JSONC’ye dönüşmüş bir .json dosyası. Renovate dokümantasyonu, yorumlu bir .json dosyası yerine .jsonc dosyası kullanmayı önerir; çünkü yorumlu .json dosyası “can cause issues with editors and syntax highlighting” (editörlerde ve söz dizimi vurgulamada sorunlara yol açabilir). Açık bir uzantı, her araca ne beklemesi gerektiğini söyler.

Sıfırdan bir yapılandırma formatı seçiyorsanız ve her yerde yorum yazabilmek istiyorsanız TOML ve YAML yorumları yerel olarak destekler. Karşılaştırma için TOML vs JSON vs YAML: Hangi Yapılandırma Biçimini Seçmeli? yazısına bakın.

Gerçek Dünyadaki Yapılandırma Dosyaları

JSON5 ve JSONC, her gün karşılaştığınız yapılandırma dosyalarında zaten yaygın olarak kullanılıyor. İşte somut örnekler:

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"],
}

TypeScript’in tsconfig.json dosyası JSONC’yi yerel olarak kullanır — yorumlar ve son virgüller varsayılan olarak çalışır. Bu, herhangi bir JavaScript/TypeScript projesinde en sık karşılaşılan JSONC dosyalarından biridir.

Babel (babel.config.json — JSON5)

Babel, babel.config.json ve .babelrc.json dosyalarını JSON5 olarak ayrıştırır; bu yüzden bu dosyalarda tırnaksız anahtarlar ve tek tırnaklar kullanılabilir.

{
  // 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',
  ],
}

VS Code Çalışma Alanı Ayarları (.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",
  },
}

Pratik İpuçları ve Dikkat Edilmesi Gerekenler

1. Üretime Geçmeden Önce Dönüştürün

Tarayıcıların JSON.parse fonksiyonu yalnızca katı JSON kabul eder. Yapılandırmayı, yukarıdaki dönüştürme bölümünde gösterildiği gibi derleme sırasında dönüştürün.

2. Güvenlik ve Güvenilirlik

Esneklik, hatalı alanları gizleyebilir. Yapılandırmayı kullanmadan önce JSON Schema veya zod ile her zaman doğrulayın:

// Validate config shape with zod after parsing
import { readFileSync } from 'node:fs';
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 invalid

3. Ekip Konvansiyonları

README dosyasında *.json5 dosyalarının yalnızca yapılandırma için kullanıldığını belirtin; yayımlanan paketler katı .json ile gönderilmelidir.
Diff’lerde gürültüyü azaltmak için Prettier kurallarını standartlaştırın.
JSON, JSON5 ve JSONC dosyaları arasında tutarlı girinti uygulamak için .editorconfig kullanın.

4. Performans

JSON5/JSONC ayrıştırması bağımlılık ve hafif bir yük getirir — CLI ile geliştirme araçları için sorun değildir, ancak üretimde mutlaka ölçün. Başlangıçta bir kez yüklenen yapılandırma dosyaları için bu ek yük ihmal edilebilir. Saniyede binlerce nesneyi ayrıştıran kritik kod yollarında ise katı JSON’a sadık kalın.

Sıkça Sorulan Sorular

JSON5 ile JSONC arasındaki fark nedir?

JSONC, standart JSON’a tek satırlı (//) ve blok (/* */) yorumlar ekler; son virgüllerin kabul edilip edilmediği ayrıştırıcıya bağlıdır. JSON5 ise ES5.1 söz dizimiyle daha ileri gider: tırnaksız anahtarlar, tek tırnaklar, onaltılı sayılar, Infinity/NaN ve son virgüller. Geçerli bir JSONC dosyası genellikle geçerli bir JSON5 dosyasıdır, ancak tersi doğru değildir. Yorumların yeterli olduğu yapılandırma dosyaları için JSONC’yi seçin; daha zengin söz dizimine ihtiyacınız varsa JSON5’i tercih edin.

Üretim API’lerinde JSON5 veya JSONC kullanabilir miyim?

Hayır — JSON5 ve JSONC, veri alışverişi için değil yapılandırma dosyaları için tasarlanmıştır. API’ler, en yüksek birlikte çalışabilirlik için standart JSON (RFC 8259) kullanmalıdır. JSON5/JSONC’yi tsconfig.json, .vscode/settings.json veya ortam yapılandırması gibi insan tarafından okunabilirliğin makine ayrıştırmasından daha önemli olduğu yerel yapılandırma dosyalarına saklayın.

VS Code, JSON5’i yerel olarak destekliyor mu?

Ek kurulum gerektirmeden desteklemez. VS Code’un yerleşik JSON eklentisi json, jsonc ve jsonl gibi dil kimlikleri tanımlar, ancak json5 için bir dil kimliği tanımlamaz. Bu yüzden .json5 dosyalarında söz dizimi vurgulaması için marketplace’ten bir eklenti kurmanız gerekir. JSONC ise yerleşik olarak desteklenir: ayarlar, tasks.json, launch.json ve tsconfig.json JSON with Comments modunda açılır.

JSON5’i standart JSON’a nasıl dönüştürürüm?

json5 npm paketini kullanın: JSON5.parse() JSON5’i okur, ardından JSON.stringify() standart JSON çıktısı verir. CLI kullanımı için npx json5 < input.json5 > output.json komutunu çalıştırın. Dönüştürme sırasında yorumlar silinir. Infinity ve NaN değerleri JSON.stringify ile null olur; bu yüzden önce bu değerleri kontrol edin. JSON Biçimlendiricimiz gibi çevrimiçi araçlar da dönüştürülen çıktının doğruluğunu denetleyebilir.

JSONC ile JSON with Comments aynı şey mi?

Evet — JSONC, “JSON with Comments” ifadesinin kısaltmasıdır. “JSON with Comments”, VS Code’daki dil modunun adıdır; jsonc ise bu modun dil kimliği ve dosya uzantısıdır. Formatın resmî bir standardı yoktur; jsonc.org, jsonc-parser’ın varsayılan olarak kabul ettiği söz dizimine dayanan bir topluluk taslağı yayımlar. JSONC standart JSON’a // ve /* */ yorumlarını ekler; son virgül desteği ise ayrıştırıcıya bağlıdır. Ayrıştırıcılar yorumları işlemeden önce kaldırır, böylece elde edilen veri yapısı standart JSON ile birebir aynıdır.

Yapılandırma dosyalarınızda zaman damgalarını da görüyorsanız, kayıt birimlerinden DST tuzaklarına kadar tüm konuları kapsamlı şekilde işleyen Unix Timestamp Rehberi yazımıza göz atın.

Sonuç

Okunabilirlik ile titizlik arasındaki dengeyi kurmak, klasik bir geliştirici mücadelesidir. JSON5 ve JSONC, yazma deneyimini iyileştirir; doğru derleme ve doğrulama pipeline’ıyla “esnek JSON”un avantajlarından güvenle yararlanabilirsiniz.