JSON Nedir? Sözdizimi, Yaygın Hatalar ve Doğrulama

JSON (JavaScript Object Notation), yapılandırılmış verileri saklamak ve değiş tokuş etmek için kullanılan hafif, metin tabanlı bir biçimdir; anahtar/değer çiftlerinden oluşan nesnelerden, sıralı dizilerden ve bir avuç değer türünden (dize, sayı, true, false ve null) oluşur. İnsanlar için okunması kolay ve her programlama dili için ayrıştırması basit olduğundan web API'leri ile birçok yapılandırma dosyasının varsayılan biçimidir. JSON katıdır: anahtarlar ve dizeler çift tırnak ister; sondaki virgüllere ve yorumlara izin verilmez.

JSON nasıl görünür

JSON, JavaScript'in nesne sabitleri (object literal) için kullandığı sözdiziminden doğmuştur, ancak dilden bağımsızdır. RFC 8259'da ve ECMA-404 standardında tanımlanmıştır; json.org adresindeki tek sayfalık özet de dilbilgisinin tamamını anlatır. Tipik bir belge şöyle görünür:

{
  "id": 1042,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "active": true,
  "score": 98.5,
  "manager": null,
  "roles": ["admin", "editor"],
  "address": {
    "city": "London",
    "postcode": "N1 9GU"
  }
}

Öğeler arasındaki boşluklar (boşluk, sekme ve satır sonları) yok sayılır; bu yüzden aynı veri tek satıra yazılabilir ya da girintilerle açılabilir. Bir JSON belgesinin en üst düzeyi herhangi bir değer olabilir, ancak API'ler hemen her zaman bir nesne veya dizi kullanır.

JSON veri türleri

Tarih türü yoktur. Tarihler genellikle "2026-10-13T09:30:00Z" gibi ISO 8601 biçiminde dize olarak ya da sayı biçiminde Unix zaman damgası olarak yazılır; Unix Zaman Damgası Dönüştürücü ikisi arasında çeviri yapar.

Sayılar ve hassasiyet

JSON standardı sayıların boyutunu veya hassasiyetini sınırlamaz, ancak onu okuyan programlar sınırlar. JavaScript sayıları 64 bitlik kayan noktalı değerler olarak saklar; bu yüzden 9.007.199.254.740.991'den (2⁵³ − 1) büyük tamsayılar sessizce hassasiyet kaybedebilir. Büyük kimlikleri birçok API dize olarak gönderir; örneğin "id": "1234567890123456789".

İnsanların takıldığı kurallar

JSON, JavaScript'e, Python sözlüklerine ve YAML'a benzer; insanların kazara geçersiz JSON yazmasının tam nedeni budur. Standart JSON'da bu kuralların istisnası yoktur:

• Anahtarlar çift tırnak içinde dize olmalıdır. {name: "Ada"} geçerli JavaScript'tir ama geçersiz JSON'dur; {"name": "Ada"} yazın.
• Yalnızca çift tırnak. 'Ada' bir JSON dizesi değildir.
• Sondaki virgül yok. [1, 2, 3,] ve {"a": 1,} geçersizdir.
• Yorum yok. Ne // ... ne de /* ... */ kullanılabilir.
• Sabit değerler küçük harflidir. True, FALSE ve None (Python'un yazımı) geçersizdir; true, false ve null kullanın.
• undefined, işlev veya özel sayı yok. Bunlar JavaScript'te vardır ama JSON'da karşılıkları yoktur.
• Anahtarlar benzersiz olmalıdır. Standart, bir nesnedeki adların benzersiz olması gerektiğini söyler; yinelenenlerde ayrıştırıcılar farklı davranır ve çoğu sessizce yalnızca sonuncusunu tutar.

Bazı araçlar gevşetilmiş türevleri kabul eder. VS Code'un settings.json ve TypeScript'in tsconfig.json gibi dosyaları yorumlara izin veren ayrıştırıcılarla (çoğunlukla JSONC denir) okunur; JSON5 ise yorumlara, tek tırnağa ve sondaki virgüllere izin verir. Bunlar ayrı biçimlerdir: API istemcinizin veya sunucunuzun kullandığı ayrıştırıcı dahil standart bir JSON ayrıştırıcısı bunları reddeder.

Yaygın JSON hataları ve nasıl düzeltilir

Hata ifadeleri ayrıştırıcıdan ayrıştırıcıya değişir. Tablo, Python'un json modülünden veya bir tarayıcının JSON.parse işlevinden göreceğiniz ileti türünü, bunun genellikle ne anlama geldiğini ve çözümünü gösterir. Bildirilen konum çoğu zaman gerçek hatanın hemen sonrasını gösterir; bu yüzden ondan önceki karaktere de bakın.

Son satır pratikte en sık görülenlerden biridir: kod, <!DOCTYPE html> ile başlayan bir hata sayfası üzerinde JSON.parse veya response.json() çağırır ve < beklenmeyen bir belirteç olarak bildirilir.

JSON, YAML ve XML karşılaştırması

YAML 1.2, nadir uç durumlar dışında JSON belgelerinin aynı zamanda geçerli YAML olacağı şekilde tasarlandı; bu da aralarında dönüştürmeyi kolaylaştırır. JSON ↔ YAML Dönüştürücü her iki yönü de işler, YAML Biçimlendirici ve Doğrulayıcı ile XML Biçimlendirici ve Doğrulayıcı diğer iki biçimi doğrular, CSV ↔ JSON Dönüştürücü ise e-tablo dışa aktarımlarını nesne dizilerine çevirir.

Güzel biçimlendirme ve küçültme

Boşluk önemsiz olduğundan aynı JSON, insanlar veya makineler için biçimlendirilebilir:

• Güzel biçimlendirilmiş (pretty-printed) JSON, iç içe yapının görünmesi için satır sonları ve genellikle iki ya da dört boşluklu girinti ekler. Yapılandırma dosyalarında, belgelerde ve hata ayıklamada kullanın.
• Küçültülmüş (minified) JSON, yükü küçültmek için tüm isteğe bağlı boşlukları kaldırır. Ağ üzerinden gönderilen veya toplu olarak saklanan veriler için kullanın; HTTP sıkıştırması da boyutu azalttığından kazanç çoğu zaman mütevazıdır.

{"name":"Ada","roles":["admin","editor"],"active":true}

Çoğu dil ikisini de yapabilir. JavaScript'te JSON.stringify(data, null, 2) iki boşluklu girintiyle güzel biçimlendirir, JSON.stringify(data) ise küçültür. Python'da json.dumps(data, indent=2) güzel biçimlendirir, json.dumps(data, separators=(",", ":")) ise en kompakt çıktıyı verir.

JSON nasıl doğrulanır

JSON doğrulamanın iki düzeyi vardır: önce sözdizimi açısından geçerli bir JSON mu, sonra uygulamanızın beklediği yapıya sahip mi?

1. Sözdizimini katı bir ayrıştırıcıyla kontrol edin. Metni, ilk hatanın satırını ve sütununu bildiren ve tarayıcınızda çalışan JSON Biçimlendirici ve Doğrulayıcı'ya yapıştırın. Komut satırında python3 -m json.tool data.json veya jq . data.json biçimlendirilmiş belgeyi ya da bir hata yazdırır.
2. Hataları tek tek düzeltin. Ayrıştırıcı ilk sorunda durur; bu yüzden başarılı olana kadar her düzeltmeden sonra yeniden çalıştırın.
3. Yapıyı kontrol edin. Gerekli alanların var olduğunu ve doğru türde olduğunu, ya kodda ya da bir JSON Schema doğrulayıcısıyla doğrulayın.
4. Kodlamayı kontrol edin. Sistemler arasında alışverişi yapılan JSON, UTF-8 olmalıdır. Başka bir kodlamayla kaydedilmiş bir dosya, İngilizce olmayan metinde garip karakterlere veya hatalara yol açabilir.

Kısaca JSON Schema

JSON Schema, geçerli bir belgenin neye benzediğini (hangi özelliklerin zorunlu olduğunu, her birinin hangi türde olması gerektiğini, izin verilen değerleri, dize kalıplarını, sayı aralıklarını ve benzerlerini) tanımlamak için JSON'un kendisiyle yazılan bir sözlüktür. Çoğu dil için doğrulayıcılar vardır ve OpenAPI gibi API tanım biçimleri istek ve yanıt gövdelerini tanımlamak için JSON Schema kullanır. Belirtim json-schema.org adresinde yayımlanır. Küçük bir örnek:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "roles": { "type": "array", "items": { "type": "string" } }
  }
}

email alanı eksik olan ya da id'si dize olan bir belge geçerli JSON olur ama bu şemada başarısız olur. Birçok doğrulayıcının format'ı bir açıklama olarak ele aldığını ve yapılandırılmadıkça zorunlu kılmadığını unutmayın.

Sıkça sorulan sorular

JSON'da yorum olabilir mi?

Hayır. Standart JSON hiçbir türde yoruma izin vermez. Bazı araçlar yorumlara izin veren JSONC veya JSON5'i kabul eder, ancak başka programlar tarafından okunması amaçlanan dosyalar düz JSON'a bağlı kalmalıdır. Bir not gerekiyorsa "_comment" gibi bir alan ekleyin.

JSON neden sondaki virgüllere izin vermiyor?

Dilbilgisi bilerek asgari tutuldu ve onları içermiyor. Birçok JavaScript motoru ve diğer diller kendi sözdizimlerinde sondaki virgülleri kabul eder; bu yüzden elle yazılmış JSON'da sık sık yanlışlıkla görünürler.

JSON ile JavaScript nesnesi arasındaki fark nedir?

JSON bir metin biçimidir; JavaScript nesnesi ise bellekteki bir veri yapısıdır. JSON'un sözdizimi, JavaScript sabit sözdiziminin daha katı bir alt kümesidir. Aralarında JSON.parse ve JSON.stringify ile dönüşüm yaparsınız.

"Unexpected token < in JSON at position 0" ne anlama gelir?

Ayrıştırılan metin < ile başlıyor; bu hemen her zaman JSON yerine bir hata veya giriş sayfası gibi HTML aldığınız anlamına gelir. İstek URL'sini, HTTP durum kodunu ve ham yanıt gövdesini kontrol edin.

Bir JSON nesnesindeki anahtarların sırası korunur mu?

Standart nesneleri sırasız olarak ele alır; bu yüzden anahtar sırasına güvenmemelisiniz. Pratikte çoğu modern ayrıştırıcı okuduğu sırayı korur, ancak JSON'un garanti ettiği tek sıra dizi sırasıdır.

JSON hangi dosya uzantısını ve MIME türünü kullanır?

Dosyalar .json uzantısını kullanır ve medya türü, RFC 8259'da kayıtlı olduğu gibi application/json'dır.