JSON Biçimlendirici ve Sıkıştırıcı

Bir API yanıtını tek satır halinde ekrana döktüğünüzde gözünüzün nasıl yorulduğunu bilirsiniz. Sıkıştırılmış JSON makineler için idealdir, ama insan gözü için okunması zor bir metin yığınıdır. JSON Biçimlendirici tam da bu noktada devreye girer: veriyi girintili, hizalanmış ve okunabilir bir yapıya dönüştürür.

Biçimlendirmenin üç temel faydası vardır:

1. Okunabilirlik: İç içe geçmiş nesneler ve diziler girinti sayesinde net bir hiyerarşi kazanır. Hangi alanın hangi nesneye ait olduğunu bir bakışta görürsünüz.
2. Hata ayıklama: Bir alan eksik mi, bir değer yanlış tipte mi, kolayca fark edersiniz. Beklediğiniz true yerine "true" yazdığını görmek, saatlerce süren hata avını dakikalara indirir.
3. Daha küçük veri boyutu: Ters yönde, üretim ortamına gönderirken tüm boşlukları temizleyerek veriyi küçültebilirsiniz.

Önemli bir ayrıntı, tüm işlemin tarayıcınızda yerel olarak çalışmasıdır. Girdiğiniz veri hiçbir sunucuya gönderilmez. Bu, müşteri kayıtları veya token gibi hassas bilgileri içeren JSON'lar için kritik bir güvenlik avantajıdır.

Günlük geliştirme akışında JSON'u okunur hale getirmek lüks değil, gerekliliktir. Bir hata mesajını incelerken, bir yapılandırma dosyasını düzenlerken ya da bir iş arkadaşınıza veri gönderirken, düzgün biçimlendirilmiş JSON hem sizin hem de karşı tarafın zamanını kazandırır. Aynı mantık başka format dönüşümlerinde de geçerlidir; örneğin CSV verisini JSON'a dönüştürürken çıktının okunabilir olması, sonucu doğrulamanızı kolaylaştırır.

Güzel biçimlendirilmiş JSON'un temeli girintidir. JSON Biçimlendirici size girinti genişliğini ve karakterini seçme özgürlüğü verir. En yaygın tercihler 2 boşluk, 4 boşluk veya sekme (tab) karakteridir.

Hangisini seçeceğiniz genellikle ekibinizin veya projenizin standardına bağlıdır. İki boşluk kompakt bir görünüm sunar ve derin iç içe yapılarda satırların çok sağa kaymasını engeller. Dört boşluk ise hiyerarşiyi daha belirgin gösterir. Sekme kullanımı ise her geliştiriciye kendi editöründe girinti genişliğini ayarlama esnekliği tanır.

İki boşluk girintili basit bir örnek şöyle görünür:

`` { "ad": "Ayşe", "sehir": "İstanbul", "aktif": true } ``

İkinci güçlü seçenek anahtarları alfabetik sıralamaktır. Büyük bir nesnede aradığınız alanı bulmak zorlaşabilir. Anahtarları alfabetik sıraya dizmek, hem gözle tarama yapmayı hem de iki farklı JSON çıktısını karşılaştırmayı kolaylaştırır.

Burada kritik bir nokta var: JSON standardında anahtar sırası anlamsal olarak önemli değildir. Yani {"a":1,"b":2} ile {"b":2,"a":1} aynı veriyi temsil eder. Sıralama tamamen okunabilirlik ve karşılaştırma kolaylığı içindir, verinin anlamını değiştirmez.

Sürüm kontrol sistemlerinde (örneğin Git) bu özellik çok işe yarar. Anahtarları hep aynı düzende tutarsanız, diff çıktıları yalnızca gerçek değişiklikleri gösterir, rastgele sıra değişimlerinden kaynaklanan gürültü ortadan kalkar. Bu da kod incelemelerini hem hızlandırır hem de sadeleştirir.

Biçimlendirmenin tersi de en az onun kadar değerlidir. JSON Biçimlendirici ile veriyi küçültebilir (minify), yani tüm gereksiz boşlukları, satır sonlarını ve girintileri temizleyebilirsiniz. Sonuç, tek satırda toplanmış, en kompakt haliyle geçerli bir JSON metnidir.

Minify işleminin ana amacı boyut tasarrufudur. Girintili bir dosyadaki her boşluk ve satır sonu, aslında birer bayt yer kaplar. İç içe geçmiş büyük bir yapıda bu fazlalık toplamın önemli bir bölümünü oluşturabilir. Ağ üzerinden veri gönderirken bu tasarruf doğrudan hıza yansır.

Önce ve sonra farkını görmek için basit bir örnek:

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

Minify sonrası:

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

Küçük örnekte fark önemsiz görünür, ama binlerce kaydı taşıyan bir API yanıtında sıkıştırma toplam boyutu belirgin ölçüde düşürebilir. Mobil bağlantılarda veya yüksek trafikli servislerde bu, hem kullanıcı deneyimi hem de bant genişliği maliyeti açısından anlam taşır.

Minify edilmiş çıktının hâlâ tamamen geçerli JSON olduğunu unutmayın. Boşlukların temizlenmesi verinin yapısını değil, yalnızca sunumunu etkiler. Makineler bu haldeki veriyi sorunsuz ayrıştırır; sadece insan gözü için okunması zorlaşır. Bu yüzden pratik yaklaşım şudur: geliştirme sırasında biçimlendirilmiş halle çalışın, üretime gönderirken minify edin. İhtiyaç duyduğunuzda aynı araçla veriyi tekrar okunabilir hale getirmek yalnızca bir tık uzağınızdadır.

JSON basit görünür, ama katı kuralları vardır. Bu kurallar RFC 8259 ve ECMA-404 standartlarıyla belirlenmiştir. Küçük bir yazım hatası tüm veriyi geçersiz kılabilir, bu yüzden temel kuralları bilmek zaman kazandırır.

En sık karşılaşılan kurallar şunlardır:

En yaygın hata sondaki virgüldür (trailing comma). Bir dizinin veya nesnenin son elemanından sonra virgül bırakmak JavaScript'te sorun çıkarmaz, ama katı JSON ayrıştırıcıları bunu reddeder. Diziden bir eleman silerken virgülü unutmak çok kolaydır.

İkinci sık hata tek tırnak kullanmaktır. JavaScript kodunda tek tırnak geçerlidir, ama JSON yalnızca çift tırnağı kabul eder. Hem anahtarlar hem de metin değerleri mutlaka çift tırnak içinde olmalıdır.

Değerler yalnızca belirli tiplerde olabilir: metin, sayı, true, false, null, nesne ve dizi. Sayılar tırnaksız yazılır; "yas": 30 ile "yas": "30" farklı anlamlar taşır, ilki sayı ikincisi metindir.

JSON Biçimlendirici geçersiz bir girdiyle karşılaştığında size tam olarak hangi konumda sorun olduğunu bildiren net bir hata mesajı verir. Bu, hatanın satırını ve karakterini işaret ederek düzeltmeyi kolaylaştırır. Benzer katı yapı kuralları YAML'den JSON'a dönüşümde de karşınıza çıkar.

Binlerce satırlık bir JSON dosyasında tek bir eksik virgülü aramak, samanlıkta iğne aramaya benzer. Neyse ki doğru yaklaşım ve doğru araçla bu iş dakikalar sürer.

İlk adım, JSON Biçimlendirici'nin verdiği hata mesajını dikkatle okumaktır. Araç geçersiz girdiyi tespit ettiğinde sorunun konumunu bildirir. Bu konum bilgisi, koca dosyada nereye bakacağınızı söyler. Genellikle asıl hata, bildirilen konumdan hemen önce yer alır; örneğin eksik bir virgül, bir sonraki satırda hata olarak görünebilir.

Hata avında işe yarayan pratik bir yöntem sırası:

1. Konuma gidin: Hata mesajındaki satır ve karakter numarasını editörünüzde bulun.
2. Bir önceki elemana bakın: Eksik virgül veya fazladan virgül çoğunlukla bir satır yukarıdadır.
3. Tırnakları sayın: Kapatılmamış bir çift tırnak, sonraki her şeyi metnin parçası sanmaya yol açar.
4. Parantezleri eşleştirin: Her açılan { ve [ için bir kapanış olmalıdır.

Büyük dosyalarda etkili bir taktik, veriyi parça parça test etmektir. Şüpheli bölümü kopyalayıp ayrı ayrı biçimlendirmeyi deneyin. Sorunlu kısmı böylece izole edersiniz.

Önce veriyi biçimlendirmek de tek başına büyük fark yaratır. Girintili halde, kapanmayan bir parantez veya yanlış hizalanmış bir alan gözünüze hemen çarpar. İç içe yapılarda hizalama bozulmaları en güçlü ipuçlarından biridir.

Unutmayın, ayrıştırıcı katıdır ama tutarlıdır. Aynı kural her zaman geçerlidir, bu yüzden bir kez hataların mantığını kavradığınızda benzer sorunları giderek daha hızlı çözersiniz.

Birçok geliştiricinin ilk şaşkınlığı, JSON'a yorum ekleyememektir. // açıklama veya / not / yazdığınızda ayrıştırıcı hata verir. Bunun nedeni bir eksiklik değil, bilinçli bir tasarım tercihidir.

JSON'un tasarımcısı Douglas Crockford, yorumları standarttan kasten çıkardığını belirtmiştir. Gerekçesi şuydu: insanlar yorumları veriye komut gömmek için kullanmaya başlamış ve bu, farklı ayrıştırıcılar arasında uyumsuzluklar doğurmuştu. Formatı basit ve taşınabilir tutmak için yorum desteği kaldırıldı.

JSON, adının açılımındaki gibi bir veri değişim formatıdır (JavaScript Object Notation), bir yapılandırma dili değil. Amacı veriyi bir sistemden diğerine sade ve belirsizliğe yer bırakmadan taşımaktır. Yorumlar bu amaca hizmet etmez, çünkü makineler için anlamsızdır.

Peki bir JSON dosyasına açıklama eklemek gerçekten gerekiyorsa ne yapılır? Birkaç yaygın çözüm vardır:

• Açıklama alanı ekleyin: "_aciklama": "Bu ayar önbellek süresini saniye cinsinden tutar" gibi normal bir alan kullanabilirsiniz.
• Yorumları destekleyen bir format seçin: Yapılandırma dosyaları için JSON5 veya YAML gibi seçenekler yorum satırına izin verir.
• Dağıtımdan önce temizleyin: Geliştirme sırasında yorumlu bir dosya tutup, kullanmadan önce yorumları silen bir adım ekleyebilirsiniz.

Yapılandırma için yorum desteği arıyorsanız, YAML'den JSON'a dönüştürme iş akışı pratik bir orta yol sunar: yorumlu YAML dosyasında çalışır, sonucu JSON'a çevirirsiniz. JSON Biçimlendirici ise elinizdeki geçerli JSON'u düzenli ve okunur tutmak için doğru araçtır. Yorum yasağını bir kısıtlama değil, formatı sade tutan bir özellik olarak görmek yerinde olur.