JSON nedir ve nasıl doğru yazılır?

JSON (JavaScript Object Notation), verileri hem insanların okuyabileceği hem de programların kolayca işleyebileceği metin biçiminde saklamanın en yaygın yoludur. Bir web sitesinin API yanıtı, bir uygulamanın ayar dosyası, e-ticaret sitesindeki ürün listesi ya da sayfadaki yapısal veri çoğu zaman JSON’dır. Kuralları az ve basittir; ama tek bir eksik virgül veya yanlış tırnak tüm dosyayı geçersiz kılar. Bu rehberde JSON’ın söz dizimini, sık yapılan hataları ve CSV ile farklarını anlatıyoruz. JSON’ı biçimlendirmek ve doğrulamak için JSON düzenleyici aracımızı kullanabilirsiniz.

Basit bir JSON örneği

{
  "ad": "Ayşe Yılmaz",
  "yas": 32,
  "sehir": "İzmir",
  "aktif": true,
  "telefonlar": ["+90 532 000 00 00", "+90 232 000 00 00"],
  "adres": {
    "ilce": "Karşıyaka",
    "postaKodu": "35530"
  },
  "notlar": null
}

Bu örnekte bir nesne (süslü parantez), içinde anahtar-değer çiftleri, bir dizi (köşeli parantez) ve iç içe bir nesne bulunuyor.

Veri tipleri

JSON yalnızca altı veri tipini destekler:

JSON’da tarih tipi yoktur; tarihler genellikle ISO 8601 metni ("2026-10-08T12:00:00Z") veya Unix zaman damgası (sayı) olarak saklanır. Bu konuyu Unix timestamp rehberimizde anlattık.

Söz dizimi kuralları

1. Anahtarlar çift tırnak içinde olmalıdır: "ad", ad veya 'ad' değil.
2. Metin değerleri çift tırnak içinde olmalıdır.
3. Öğeler virgülle ayrılır; son öğeden sonra virgül olmaz.
4. Yorum satırı yazılamaz.
5. undefined, NaN, Infinity gibi değerler geçerli değildir.
6. Metin içindeki çift tırnak ve ters bölü kaçış karakteriyle yazılır: "Ali \"Usta\"", "C:\\Users".
7. Satır sonu metin içinde doğrudan yazılamaz, \n kullanılır.

Türkçe karakterler UTF-8 kodlamasıyla doğrudan yazılabilir ("Şişli") veya \u015e gibi Unicode kaçışıyla gösterilebilir. Dosyayı UTF-8 olarak kaydetmek yeterlidir.

En sık karşılaşılan hatalar

1. Sondaki virgül

{ "ad": "Ali", "yas": 30, }

30’dan sonraki virgül JSON’da geçersizdir. JavaScript koduna izin verildiği için bu hata çok sık yapılır.

2. Tek tırnak veya tırnaksız anahtar

{ ad: 'Ali' }        // geçersiz JSON (ama geçerli JavaScript)
{ "ad": "Ali" }      // geçerli JSON

3. Akıllı tırnaklar

Word veya bazı not uygulamalarından kopyalanan metinlerde " yerine “ ” gibi tipografik tırnaklar bulunabilir. Bunlar gözle fark edilmesi zor ama geçersiz karakterlerdir.

4. JSON yerine HTML dönen API

Unexpected token < in JSON at position 0 hatası genellikle sunucunun JSON yerine bir HTML hata sayfası (<html>…) döndürdüğünü gösterir. Sorun JSON’da değil, isteğin kendisindedir: yanlış URL, yetki hatası veya sunucu hatası. Yanıt başlıklarındaki Content-Type değerini kontrol edin.

5. Büyük sayılar

JavaScript, 2⁵³’ten büyük tam sayıları kesin olarak saklayamaz. Çok uzun kimlik numaralarını (ör. bazı veritabanı ID’leri) JSON’da metin olarak göndermek daha güvenlidir.

JSON’ı biçimlendirme ve doğrulama

API’lerden gelen JSON genellikle tek satırda, boşluksuz (minify edilmiş) gelir. Okumak için girintili hale getirmek (pretty print) gerekir. JavaScript’te:

const veri = JSON.parse(metin);            // metni nesneye çevirir, hatalıysa istisna fırlatır
const guzel = JSON.stringify(veri, null, 2); // 2 boşluk girintili metin
const kucuk = JSON.stringify(veri);          // tek satır, boşluksuz

Komut satırında jq aracı da çok kullanışlıdır: jq . veri.json dosyayı biçimlendirir ve hatalıysa satır numarasını gösterir.

JSON ve CSV karşılaştırması

JSON’ı CSV’ye çevirirken iç içe alanlar düzleştirilir (adres.ilce gibi sütunlara ayrılır) ve diziler tek hücrede birleştirilir. Türkiye’de Excel ondalık ayırıcı olarak virgül kullandığı için CSV’lerde ayırıcı olarak sıklıkla noktalı virgül tercih edilir; aksi halde sütunlar karışabilir. Dönüşüm için CSV-JSON dönüştürücü aracımızı kullanabilirsiniz.

JSON nerelerde karşınıza çıkar?

• REST API’ler: İstek ve yanıt gövdeleri
• Yapılandırma dosyaları: package.json, tsconfig.json, VS Code ayarları
• Web siteleri: Arama motorları için yapısal veri (JSON-LD). Ayrıntılar için schema yapısal veri rehberimize bakabilirsiniz.
• Tokenlar: JWT’nin içindeki veriler JSON’dır ve Base64URL ile kodlanır; JWT çözücü ile içeriğini görebilirsiniz.
• NoSQL veritabanları: MongoDB gibi belge tabanlı veritabanları JSON benzeri yapılar kullanır.

JSON ve güvenlik

• eval kullanmayın: JSON metnini JavaScript’te eval ile çalıştırmak, kötü niyetli kodun çalışmasına yol açabilir. Her zaman JSON.parse kullanın.
• Gizli bilgileri JSON dosyalarında saklamayın: API anahtarları ve parolalar ortam değişkenlerinde veya gizli yönetim servislerinde tutulmalıdır; config.json dosyaları kolayca sürüm kontrolüne veya herkese açık bir klasöre düşebilir.
• Gelen veriyi doğrulayın: Bir API’den gelen JSON’ın beklenen alanları ve tipleri içerdiğini kontrol edin. JSON Schema, bu kontrolü tanımlamanın standart yoludur.
• Çok büyük dosyalar: Yüz megabaytlık JSON dosyalarını tek seferde belleğe almak yerine satır satır işlenebilen JSON Lines (.jsonl) biçimi tercih edilebilir.

JSON ile ilgili kısa sözlük

• Ayrıştırma (parse): JSON metnini programlama dilindeki nesneye çevirme.
• Serileştirme (stringify/serialize): Nesneyi JSON metnine çevirme.
• Minify: Boşlukları ve satır sonlarını silerek boyutu küçültme.
• Pretty print: Girintili, okunabilir biçimde yazma.
• JSON Schema: Bir JSON belgesinin hangi alanları ve tipleri içermesi gerektiğini tanımlayan standart.

Kontrol listesi

• Tüm anahtarlar ve metinler çift tırnak içinde
• Son öğelerden sonra virgül yok
• Yorum satırı yok
• Dosya UTF-8 olarak kaydedildi
• Büyük ID’ler metin olarak saklandı
• Bir doğrulayıcıdan hatasız geçti