FracturedJson

 (github.com/j-brooke)
6 puan yazan GN⁺ 2026-01-03 | 1 yorum | WhatsApp'ta paylaş
  • JSON verilerini insanların kolay okuyabileceği şekilde düzenlerken aynı zamanda sıkı bir yapıda tutan bir biçimlendirme yardımcı araçları koleksiyonu
  • Dizileri ve nesneleri mümkün olduğunca tek satırda ifade eder ve yapı benzer olduğunda tablo biçiminde hizalar
  • Yorum koruma özelliğini destekler; JSON standardında olmasa da pratik kullanım ortamlarında yaygın olan yorumları birlikte korur
  • .NET kütüphanesi, JavaScript/TypeScript paketi, VS Code eklentisi, tarayıcı biçimlendiricisi gibi çeşitli ortamlarda kullanılabilir
  • Mevcut JSON biçimlendiricilerinin okunabilirlik sınırlarını iyileştirerek geliştiricilerin ve veri analistlerinin görsel kavrayışını artıran bir araç

FracturedJson Genel Bakış

  • FracturedJson, insanın okuyabileceği ama yine de görece kompakt bir JSON biçimi üreten bir yardımcı araçlar koleksiyonudur
    • Diziler ve nesneler çok uzun veya karmaşık değilse tek satırda çıktı verir
    • Yapısı benzer birden fazla satırı alanları hizalayarak tablo gibi gösterir
    • Uzun dizileri birden fazla satıra yayar, ancak her satıra birden çok öğe yerleştirir
  • Çıktı biçimi çeşitli ayarlarla kontrol edilebilir ve çoğu durumda varsayılan ayarlar bile hoş görünen sonuçlar üretir
  • Tarayıcı tabanlı biçimlendirici sayfası, .NET kütüphanesi, JavaScript/TypeScript paketi ve VS Code eklentisi olarak sunulur
  • Python için seçenek de ayrıca belirtilmiştir

Motivation

  • Çoğu JSON kütüphanesi yalnızca iki tür biçim sunar
    • Minified JSON: verimlidir ama insanların okuması zordur
    • Beautified/Indented JSON: aşırı genişe yayılır ve hızlıca kavramayı zorlaştırır
  • FracturedJson verileri sanki bir insan doğrudan yazıyormuş gibi biçimlendirir
    • Fazla karmaşık veya uzun olmadığı sürece kapsayıcıları tek satırda tutar
    • Benzer dizileri veya nesneleri tablo biçiminde hizalar

Çalışma Şekli (How It Works)

  • FracturedJson dört biçimlendirme türü kullanır
    1. Inlined: kısa ve basit nesne ya da dizileri tek satırda ifade eder
      • MaxInlineComplexity ayarıyla izin verilen iç içelik seviyesi kontrol edilir
    2. Compact Multiline Array: bir satıra birden çok öğe yerleştirir ama birden fazla satıra bölerek gösterir
      • İç içelik toleransı MaxCompactArrayComplexity ile ayarlanır, -1 ile devre dışı bırakılabilir
    3. Table: yapısı benzer öğeleri sütun hizalı biçimde düzenler
      • İç kapsayıcılar fazla karmaşıksa yalnızca bir kısmı daraltılır
      • MaxTableRowComplexity ve TableCommaPlacement ile kontrol edilebilir
    4. Expanded: yukarıdaki koşullara uymuyorsa, her öğeyi çok satırlı girintili biçimde gösterir

Yorum İşleme

  • JSON standardı yorumlara izin vermez, ancak FracturedJson yorum koruma özelliğini destekler
    • Yorumlar ilgili öğelerle birlikte korunur; çok satırlı yorumlar ve satır içi yorumlar da işlenebilir

Discussions

  • Kullanıcı soruları, geri bildirimler ve öneriler için bir GitHub Discussions alanı sunulur
  • Projeyle ilgili tartışmalar ve iyileştirme önerileri yapılabilir

İlgili okumalar

1 yorum

 
GN⁺ 2026-01-03
Hacker News yorumları

  • Şu anda bu projenin bakımı yapılan iki implementasyonu var
    Biri C# sürümü (FracturedJson .NET Library), diğeri TypeScript/JavaScript sürümü (FracturedJsonJs)
    Eskiden saf bir Python sürümü de vardı ama artık bakımı yapılmıyor; onun yerine C# kodunu saran bir Python wrapper'ı (fractured-json) geldi
    Bu Python sürümünde .NET runtime gerektiği açıkça belirtiliyor; bu da yalnızca pip install ile kurulumun zor olması gibi bir dezavantaj yaratıyor
    Bence bu durum, dilden bağımsız bir conformance suite oluşturmak için iyi bir fırsat — yani farklı implementasyonların aynı şekilde davrandığını doğrulayabilecek veri odaklı bir test seti
    Bu arada, eski Python sürümü zaten böyle bir test biçimini kullanıyordu (compact-json test verileri)

    • Az önce Rust'a port ettim ve bundan sonra bakımını yapmayı planlıyorum
      Bunu ana yoruma da eklemek iyi olabilir
      Ayrıntılar için fracturedjson-rs GitHub ve crates.io paketi sayfalarına bakabilirsiniz
      Konuyla ilgili açıklama yorumu burada
    • Güzel fikir ama test case'lerin ötesine geçip program eşdeğerliği garantisi vermek zor olur diye düşünüyorum
    • Bu neredeyse saf fonksiyon gibi, dolayısıyla test harness yazması çok kolay
    • Veri odaklı testler, bir kütüphaneye güven oluşturmak için çok etkili
      html5lib-tests ya da benim yaptığım xss-bench bunun örnekleri

  • Rust'a port edilmiş bir sürüm yaptım; CLI aracıyla JSON'u bu formatta düzenleyebiliyorsunuz
    fracturedjson-rs ve crates.io paketi üzerinden kurulabiliyor (cargo install fracturedjson)
    Çeşitli seçenekler sunuyor; yorumlama biçimi, girinti stili, satır genişliği sınırı gibi konularda ince ayar yapılabiliyor

    • Port edilmiş sürüm de türetilmiş eser sayıldığı için orijinal yazarın telif hakkı ibaresi korunmalı

  • Bu proje gerçekten harika
    JSON'u daha insan tarafından okunabilir hale getirme yönünü beğendim
    Ben de ters yönde, JSON'u daha makine dostu hale getiren bonjson üzerinde çalışıyorum
    JSON ile tamamen aynı özelliklere ve kısıtlara sahip; okuma ve yazmada 35 kat daha hızlı
    Yeni tipler ya da yeni özellikler yok, yalnızca JSON'un yapabildiği şeyleri aynen yapıyor

    • JSON basit bir gösterim olduğu için bir biçimsel veri modeli gerektiğini düşünüyorum
      Örneğin sayıların bit genişliği ya da tamsayı/kayan nokta ayrımı açıkça belirtilmiyor
      Böyle bir model olursa gösterimler arasında bire bir eşleme mümkün olur
      Bu konuyla ilgili şu yazıyı hazırlıyorum
    • İlginç ama “JSON'un yapabildiği her şeyi yapabiliyor” iddiasına kıyasla güvenlik kısıtları biraz şaşırtıcı
      Örneğin "a\u0000b" gibi bir string geçerli JSON'dur; bunu serialize edemiyorsa bu iddia tam olarak doğru sayılmaz
    • Bunu yapmaya sizi neyin yönelttiğini merak ediyorum
      Ben bir zamanlar JSON ile binary dosyaları ortak arayüzle kaydedip yükleyen bir serializer yapmıştım
      Benim deneyimime göre JSON, kısıtı çok, faydası az bir format oldu
      Bu yüzden virgül, iki nokta üst üste ve tırnak işaretlerini atlamaya izin veren, çok satırlı string'leri ve yorumları kabul eden daha gevşek bir formata geçtim
      JSON'un her zaman “insan dostu” bir formatmış gibi davranılması artık bırakılsa iyi olur
      JSON merkezli olmayan ortamlar için standart bir alternatif lazım
    • Yakın zamanda paylaşılan Lite3 aklıma geldi
    • Sıkıştırma oranı nasıl, merak ettim

  • Şaşırtıcı
    Ben de Python ile yaklaşık 200 satırda benzer bir şey yazmıştım ama böyle bir kütüphane olduğunu bilmiyordum

  • jq gibi pipe input alabilen bir seçeneği var mı, merak ediyorum

    • Depodaki C# CLI koduna bakılırsa standart girdi/çıktı ya da dosya belirtilebiliyor
      JavaScript sürümü ve Python wrapper'ı da aynı CLI aracını sunuyor
    • RCL varsayılan olarak pretty-print yapıyor
      rcl e ile RCL formatını, rcl je ile JSON çıktısını görebilirsiniz
      FracturedJson'daki gibi tablo hizalaması yok ama Philip Wadler'in A Prettier Printer algoritmasına dayandığı için genişliğe göre otomatik satır kırıyor
    • <() process substitution ile geçici dosya oluşturup işlemek de mümkün
    • Çoğu durumda giriş dosyası adı olarak - verirseniz stdin'den okuyabilirsiniz

  • Ben Virtuous adında bir JSON formatter yaptım; bunu görünce kendi formatter'ımı bırakmayı düşünecek kadar etkilendim
    Gerçekten harika bir iş

  • Ben “mommyjson” adında bir Groovy script yazdım
    JSON formatını korumak yerine her öğenin ebeveyn ilişkisini (dizi indeksi, nesne adı vb.) tek satırda gösteriyor; böylece verinin konumunu sezgisel biçimde anlamayı sağlıyor
    Kodu görüntüle
    Groovy pek popüler olmadığı için bir Python portu olsa güzel olurdu

    • Güzel fikir! Böyle araçların birkaç tane olması, insanların buna gerçekten ihtiyaç duyduğunu gösteriyor gibi
      Örneğin gron ve benim yaptığım jstream var
      Örnek çıktı kullanımı eklerseniz anlaşılması daha kolay olabilir
    • Çıktı örneği var mı diye merak ettim

  • JSON'un gerçekten insan tarafından daha okunur hale getirilmesi gereken bir format olup olmadığından emin değilim
    Kullanıcıya veri göstermek için daha iyi birçok yol var ve bence JSON esasen sistemler arası veri aktarımı için kullanılmalı

    • İnsanların bu tür araçları kullanma nedeni genelde açık bir şema veya görselleştirme aracı olmadığında ortaya çıkıyor
      Karmaşık iç içe verileri hızlıca anlamanız gereken debug durumlarında çok faydalı
      Özellikle harici sistemlerle entegrasyon kodu üzerinde çalışırken sık görülüyor
    • Ben de bazen JSON verisini okumak için jq ya da python -m json.tool kullanıyorum
      Böyle bir araç bunlardan daha iyi gösteriyorsa kesinlikle değeri vardır
    • İnsan tarafından okunabilirlik unsurunu çıkarırsanız JSON verimsiz bir encoding haline geliyor
      Sonuçta JSON'un artısı hem insan hem makine tarafından okunabilir olması; bu yüzden debug amaçlı hâlâ anlamlı

  • Bu fikri gerçekten çok beğendim
    Şu anda benimsenmesinin yavaş olmasının nedeni çoğunlukla çoğu dilde ve paket yöneticilerinde (homebrew vb.) destek olmaması
    .NET kütüphanesi C uyumlu paylaşımlı kütüphane olarak derlenirse birçok dilde kolayca kullanılabilir

  • İlginç bir yaklaşım
    Kod formatter'larının da böyle çalışması güzel olurdu
    Şimdikiler fazla katı, bu yüzden yapıyı kavramak zorlaşıyor

    • Ben bir C++ formatter yaptım; yalnızca sekme hizalı tablolar ve tek satırlık bloklar olmak üzere iki tür nesne kullanıyor
      Yorumlar da sağa hizalanarak düzenli yerleştiriliyor
      Bu yapı sayesinde switch-case blokları veya makro tabloları da kolayca 2D olarak hizalanabiliyor
      Temel katmanı bir saatte kodladım; şimdi LSP ve kod gözlemini birleştirerek blokları otomatik algılayacak şekilde tasarlıyorum
    • Geçmişte tabular görünecek şekilde kendi XML formatter'ımı yazmıştım
      İdeal olan XML'i bırakmaktı ama legacy kısıtları yüzünden mecburen uğraşmak zorunda kaldım