JSON5’ten JSONC’ye: Daha Esnek Bir JSON Biçimlendirme Deneyimi

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; tek satırlı (//) ve çok satırlı (/* */) yorumlar ile son virgül desteği ekler. Microsoft tarafından sürdürülen bu format; 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 (katı)	JSON5	JSONC
`//` tek satırlı yorumlar	Hayır	Evet	Evet
`/* */` çok satırlı yorumlar	Hayır	Evet	Evet
Son virgüller	Hayır	Evet	Evet
Tek tırnaklı karakter dizileri	Hayır	Evet	Hayır
Tırnaksız anahtarlar	Hayır	Evet	Hayır
Sayısal işaretler `+` / `-`	Hayır	Evet	Hayır
Onaltılı / ikili sayılar	Hayır	Evet	Hayır
Belirtim sahipleri	ECMA	Topluluk (A. Rauschmayer)	Microsoft / VS Code

Tek cümlede: JSON5 bir JavaScript nesne sabitini andırırken, JSONC sadece standart JSON’a yorum eklenmiş halidir.

Söz Dizimi Örnekleri

Klasik JSON (katı)

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

JSON5 Örneği

// Project config
{
  name: 'Go Tools',      // single quotes & unquoted keys
  features: [
    'Base64',
    'JSON Formatter',    // trailing comma
  ],
  version: 1.0,          // non-string number allowed
}

JSONC Örneği

{
  // Project name
  "name": "Go Tools",
  // Feature list
  "features": [
    "Base64",
    "JSON Formatter", // trailing comma
  ]
}

Biçimlendirme ve Ayrıştırma Desteği

Senaryo	JSON5	JSONC	Önerilen kütüphaneler / araçlar
Tarayıcı	`JSON5.parse()` polyfill, dahili `json5` ayrıştırıcılı Prettier (>= v1.13)	VS Code `settings.json` yerel desteği	—
Node.js	`json5` npm paketi	`comment-json`, `jsonc-parser`	CLI biçimlendirme ve AST ayrıştırma desteği
IDE	VS Code, WebStorm eklentileri	VS Code yerel, WebStorm eklentisi	Prettier biçimlendirmeyi tek tipleştirebilir
CI / Lint	`eslint-plugin-json5`	`eslint-plugin-jsonc`	Husky ve lint-staged ile entegrasyon
Çevrimiçi araç	Go Tools JSON Formatter (JSON5/JSONC’yi güzelleştirir ve doğrular)	Aynı	JSON Biçimlendirici

VS Code’da Hızlı Biçimlendirme

settings.json dosyasına ekleyin:

"[jsonc]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Ardından herhangi bir JSONC dosyasını güzelleştirmek için Alt + Shift + F tuşlarına bası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.

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

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 JSON.parse için hâlâ katı JSON gerektirir. Yorumları ve son virgülleri kaldırmak için derleme adımı araçları kullanın:

// 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));

Bundler kullananlar için rollup-plugin-json5 veya vite-plugin-json5, dönüşümü derleme sırasında otomatik olarak halleder.

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 { 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. json5 npm paketi minified halde yaklaşık 8 KB’dir ve ayrıştırma yerel JSON.parse’a göre kabaca 2–5 kat daha yavaştır. Başlangıçta bir kez yüklenen yapılandırma dosyaları için bu fark 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?

JSON5, JSON’u JavaScript benzeri söz dizimiyle genişletir: tırnaksız anahtarlar, son virgüller, tek satırlı ve blok yorumlar, onaltılı sayılar ve çok satırlı karakter dizileri. JSONC daha basittir — standart JSON’a yalnızca tek satırlı (//) ve blok (/* */) yorumlar ekler. 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?

VS Code, JSONC’yi yerel olarak destekler (kendi ayar dosyaları JSONC kullanır), ancak JSON5’i ek kurulum gerektirmeden desteklemez. JSON5 için VS Code marketplace’ten “JSON5 syntax” gibi özel bir eklenti yükleyebilirsiniz. Ayarlarınızdan .json5 dosyalarını JSON5 dil moduyla da ilişkilendirebilirsiniz.

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. 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 ve VS Code, TypeScript (tsconfig.json) ile diğer Microsoft araçları tarafından kullanılan formattır. Standart JSON belirtimini takip eder; tek farkı // ve /* */ yorumlarını eklemesidir. 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.

JSON5 ve JSONC: Daha Esnek JSON Biçimlendirme Rehberi