JSON (JavaScript Object Notation), web servisleri, uygulamalar ve yapılandırma dosyaları arasında veri alışverişi için en yaygın biçimdir. Metin tabanlıdır, insanlar için okunması kolaydır ve neredeyse her programlama dili tarafından desteklenir.
Yapı taşları
JSON'da yalnızca birkaç tür vardır: süslü parantez içinde "anahtar": değer çiftlerinden oluşan nesneler, köşeli parantez içinde diziler, çift tırnaklı dizgeler, sayılar, true, false ve null. Tarih gibi diğer her şey anlaşma gereği dizge veya sayı olarak yazılır.
En sık yapılan hatalar
- Bir nesnenin veya dizinin son öğesinden sonra fazladan virgül konulamaz.
- Anahtarlar ve dizgeler çift tırnak kullanmalıdır. Tek tırnak geçersizdir.
- Yorum satırları standardın parçası değildir.
- Dizge içindeki kaçışsız satır sonları ve tırnaklar ayrıştırıcıyı bozar.
- Sayılar baştaki sıfırla yazılamaz; NaN veya undefined gibi değerler yoktur.
Biçimlendirici ve doğrulayıcı sorunun tam yerini gösterir ve yapıyı girintilerle sunar; bu, tek uzun bir satırı okumaktan çok daha kolaydır.
Biçimlendirmeli mi, küçültmeli mi?
Girintili JSON insanlar içindir: hata ayıklarken, bir yanıtı incelerken veya yapılandırmayı bir depoda saklarken kullanın. Küçültülmüş JSON tüm isteğe bağlı boşlukları kaldırır ve makineler içindir; isteği veya dosyayı küçültür. İçerik her iki durumda aynıdır; bu yüzden hiçbir şey kaybetmeden ikisi arasında gidip gelebilirsiniz.
Diğer biçimlere dönüştürme
Hesap tabloları ve veritabanları genellikle tablolarla çalışır, API'ler ise iç içe nesneler döndürür. JSON ile CSV arasında dönüştürmek, API verisini hesap tablosunda açmaya veya bir tabloyu uygulamaya aktarmaya yardımcı olur. İç içe yapıların CSV için düzleştirilmesi gerektiğini ve CSV'de tür bilgisi olmadığı için sayı ile metnin karışabileceğini unutmayın.
Geliştiriciler için ipuçları
- Veriyi uygulamanıza girdiği sınırda doğrulayın.
- Araç yerel çalıştığını belirtmiyorsa, erişim belirteci gibi gizli bilgileri çevrimiçi araçlara yapıştırdığınız JSON'un içine koymayın.
- Bir API genelinde tutarlı anahtar adlandırması (camelCase veya snake_case) kullanın.
Bu sitedeki JSON araçları tarayıcınızda çalışır; yapıştırdığınız metin cihazınızda kalır.
Veri türleri ve yol açtıkları sürprizler
JSON'da yalnızca altı tür değer vardır: metin, sayı, mantıksal değer, null, dizi ve nesne. Bu sadelik gücüdür; yine de birkaç ayrıntı sık sık hataya yol açar:
- JSON'da tarih türü yoktur. Tarihler genellikle 2026-03-14T09:30:00Z gibi ISO 8601 biçiminde metin olarak tutulur. Ayrıştırıcılar, söylenmedikçe bunları dönüştürmez.
- Sayıların belirtilmiş bir boyutu yoktur. JavaScript'te 9.007.199.254.740.991 üzerindeki tam sayılar hassasiyet kaybeder; bu yüzden büyük veritabanı kimliklerini metin olarak tutmak çoğu zaman daha güvenlidir.
- null, eksik anahtardan farklıdır. Bir API güncellemesinde null göndermek "bu değeri temizle", anahtarı hiç göndermemek ise "değiştirme" anlamına gelebilir.
- Anahtar sırasının bir anlamı yoktur. Anahtarların belirli bir sırayla gelmesine dayanan kod veya test yazmayın.
Uzun JSON'ları verimli okumak
Gerçek API yanıtları binlerce satır olabilir. Birkaç alışkanlık işe yarar:
- Belgeyi okumadan önce biçimlendirin ve ihtiyaç duymadığınız bölümleri daraltın.
- Önce yapıyı bulun. En üst düzey bir nesne mi, dizi mi? Kayıtların listesi nerede?
- Binlerce kaydı işleyecek kodu yazmadan önce tek bir kaydı dikkatle inceleyin.
- Hangi alanların null ya da eksik olabildiğini not edin; canlı sistemde kodu çökertenler bunlardır.
Bir hata mesajı satır ve sütun bildiriyorsa bir önceki satıra da bakın. Eksik virgül, genellikle virgülün olması gereken yerde değil, sonraki öğenin başında bildirilir.
Yalnızca söz dizimini değil, yapıyı da doğrulamak
Bir belge tamamen geçerli JSON olup yine de uygulamanız için yanlış olabilir. Söz dizimi kontrolü yalnızca ayrıştırılabildiğini doğrular. Bir alanın var olduğunu, doğru türde olduğunu veya izin verilen aralıkta bulunduğunu denetlemek için projeler JSON Schema ya da doğrulama kodu kullanır. Bu en çok sistem sınırlarında önemlidir: tarayıcıdan, iş ortağının API'sinden veya yüklenen bir dosyadan gelen her şey doğrulanana kadar güvenilmez sayılmalıdır.
Günlükler ve büyük veriler için JSON Lines
Normal JSON tek bir belge olarak okunmak zorundadır; bu da çok büyük dosyalarda zorluk çıkarır. Çoğunlukla .jsonl uzantısıyla kaydedilen JSON Lines, her satırda eksiksiz bir JSON nesnesi tutar. Program dosyayı satır satır işleyebilir, yeni kayıtları kolayca ekleyebilir ve bozuk tek bir satırdan sonra devam edebilir. Günlük dosyaları ve veri aktarımlarında yaygındır; ancak bir JSON Lines dosyasının bütün olarak geçerli bir JSON belgesi olmadığını unutmayın.
Yorumlar ve sondaki virgüller
Katı JSON, yorumlara ve son öğeden sonra virgüle izin vermez. Bazı düzenleyicilerin kullandığı JSONC gibi yapılandırma biçimleri daha hoşgörülüdür; bir dosyanın bir araçta çalışıp diğerinde hata vermesinin sebebi budur. Katı bir ayrıştırıcı yapılandırma dosyasından şikâyet ediyorsa önce bu iki şeye bakın.
Gizli bilgilere ve yapıştırılan verilere dikkat
API yanıtları çoğu zaman belirteçler, e-posta adresleri ve müşteri kayıtları içerir. Böyle bir metni çevrimiçi bir hizmete yapıştırmadan önce nerede işlendiğini öğrenin. Hata raporlarına, kayıtlara veya belgelere koyduğunuz örneklerden hassas değerleri çıkarın ve gerçekçi sahte değerlerle değiştirin. Sızan bir anahtarı yenilemek, bir örneği temizlemek için harcanacak birkaç saniyeden çok daha pahalıdır.
Ayrıştırırken güvenlik
JSON okumak için JavaScript'in eval işlevi gibi genel kod çalıştırıcıları asla kullanmayın; dilin gerçek JSON ayrıştırıcısını kullanın. Ayrıştırılan nesneleri mevcut nesnelerle birleştirirken dikkatli olun; özel hazırlanmış anahtarlar bazı dillerde paylaşılan nesneleri değiştirebilir. Kabul ettiğiniz girdinin boyutunu sınırlayın ki çok büyük bir istek hizmetinizin belleğini tüketemesin.