JSON'dan TOML'ye Dönüştürücü

JSON TOML Dönüştürücü, JSON biçimindeki veriyi TOML biçimine çevirerek özellikle yapılandırma dosyası hazırlayan geliştiricilerin işini kolaylaştırır. JSON, API yanıtlarında ve veri alışverişinde çok yaygındır. TOML ise okunabilir yapılandırma dosyaları için tercih edilir. Rust ekosistemindeki Cargo dosyaları, Python projelerindeki pyproject.toml yapısı ve Hugo gibi statik site araçları bu biçimi sık kullanır.

Dönüşüme genellikle elinizde hazır bir JSON çıktısı varken ihtiyaç duyarsınız. Örneğin bir belediye açık veri API’sinden gelen ayarları, İstanbul’daki bir yazılım ekibinin kullandığı TOML tabanlı servis yapılandırmasına aktarması gerekebilir. JSON makine tarafından kolay işlenir, TOML ise insan tarafından daha rahat okunur. Bu yüzden dönüşüm sadece biçim değiştirmek değil, bakım yapılabilir bir yapılandırma dosyası üretmek anlamına da gelir.

JSON ile TOML arasındaki temel fark sözdizimindedir. JSON süslü parantezler, köşeli parantezler ve virgüllerle çalışır. TOML ise bölümleri tablolarla, değerleri daha okunur satırlarla ifade eder. JSON içindeki { "sunucu": { "port": 8080 } } yapısı TOML’de [sunucu] ve port = 8080 şeklinde temsil edilebilir. Benzer biçimleri karşılaştırmak isteyen kullanıcılar için JSON YAML dönüşümü de yapılandırma dosyaları açısından yararlı bir karşılaştırma noktasıdır.

JSON ve TOML aynı veriyi taşıyabilir, ancak veriyi ifade etme biçimleri farklıdır. JSON, nesne ve dizi kavramları üzerine kuruludur. Anahtarlar çift tırnakla yazılır, metin değerleri yine çift tırnak içindedir, her alan virgülle ayrılır. TOML ise yapılandırma dosyası gibi okunmak üzere tasarlandığı için tablolar, alt tablolar ve açık anahtar değer satırları kullanır.

Basit bir kullanıcı ayarı düşünelim: il Ankara, dil tr, bildirim true. JSON’da bu yapı tek satırda veya girintili olarak yazılabilir. TOML’de ise il = "Ankara", dil = "tr", bildirim = true şeklinde daha düz bir görünüm alır. İç içe nesnelerde fark daha belirginleşir. JSON’da veritabani.host gibi mantıksal bir alan süslü parantezler içinde yer alırken, TOML’de [veritabani] başlığı altında toplanır.

Diziler de dikkat gerektirir. JSON’da ürün listesi nesneler dizisi olarak tutulabilir. TOML’de bu yapı çoğu zaman tablo dizileriyle gösterilir. Örneğin bir e ticaret uygulamasında KDV oranı, stok durumu ve kategori bilgileri ürün bazında tekrarlanıyorsa, JSON TOML Dönüştürücü bu nesne dizilerini TOML’in [[urunler]] biçimine eşleyebilir. Biçimlendirilmiş ve okunabilir JSON ile çalışmak isterseniz önce JSON düzenleme aracından yararlanmak dönüşüm öncesinde hataları görmeyi kolaylaştırır.

JSON TOML Dönüştürücü önce girilen JSON metnini ayrıştırır. Bu aşamada süslü parantezlerin dengesi, virgüllerin doğru yerde olup olmadığı, metinlerin çift tırnakla kapatılıp kapatılmadığı ve değer türleri kontrol edilir. Geçerli olmayan JSON doğrudan TOML’e çevrilemez, çünkü araç önce verinin ağaç yapısını anlamak zorundadır.

Ayrıştırmadan sonra JSON nesneleri TOML tablolarına, basit alanlar anahtar değer satırlarına, diziler ise TOML dizilerine veya tablo dizilerine dönüştürülür. Örneğin {"api":{"adres":"https://ornek.test","zaman_asimi":30}} yapısı TOML’de [api], adres = "https://ornek.test", zaman_asimi = 30 olarak yazılabilir. Buradaki amaç yalnızca karakterleri değiştirmek değil, anlamı koruyarak TOML’in beklediği söz dizimine uygun çıktı üretmektir.

Araç, özel karakterler ve tarih benzeri değerlerde de dikkatli davranmalıdır. JSON’da tarih çoğunlukla metin olarak taşınır. TOML ise tarih ve saat için yerleşik türlere sahiptir. Bu nedenle "2025-05-19T09:30:00+03:00" gibi bir değer, bağlama göre metin olarak korunabilir veya TOML tarih saat değerine uygun biçimde yazılabilir. Türkçe karakterler içeren "açıklama":"İzmir şubesi" gibi alanlarda karakter kodlamasının korunması önemlidir. Dönüşümden sonra ters yönde işlem yapmak gerekirse TOML JSON dönüşümü ile sonuç kontrol edilebilir.

JSON TOML Dönüştürücü kullanırken en çok dikkat edilmesi gereken alanlar iç içe nesneler, karma diziler, boş değerler ve özel karakterlerdir. JSON esnek bir veri taşıma biçimidir. TOML ise yapılandırma okunabilirliğini korumak için bazı konularda daha katı davranır. Bu fark, özellikle API yanıtlarını doğrudan yapılandırma dosyasına dönüştürürken ortaya çıkar.

İç içe nesneler çoğunlukla TOML tablolarına çevrilir. uygulama.veritabani.host gibi bir yapı, TOML’de [uygulama.veritabani] tablosu altında gösterilebilir. Ancak çok derin yapıların okunabilirliği azalabilir. Bu durumda dönüşümden önce JSON’daki gereksiz alanları temizlemek daha sağlıklı sonuç verir. Bir lojistik uygulamasında il, ilçe, depo ve raf bilgisi çok katmanlı tutuluyorsa, TOML çıktısında bölümleri açık adlandırmak bakım kolaylığı sağlar.

Dizilerdeki değer türleri de önemlidir. TOML dizileri genellikle aynı türde değerler bekler. JSON’da aynı dizide sayı, metin ve nesne bulunabiliyorsa, bu yapı TOML’e bire bir ve temiz biçimde aktarılamayabilir. Boş değerler de benzer bir konudur. JSON’da null yaygındır, TOML’de ise doğrudan karşılığı yoktur. Araç bu durumda alanı atlama, boş metne çevirme veya kullanıcıya uyarı verme yaklaşımı izleyebilir. Türkçe karakterler, tırnak işaretleri ve satır sonları korunmalı, özellikle İ, ı, ğ, ş gibi karakterler bozulmamalıdır.

JSON TOML Dönüştürücü, yalnızca biçim değiştiren basit bir yardımcı araç olarak görülmemelidir. Geliştirme süreçlerinde zaman kazandıran, hata riskini azaltan ve ekip içi standardizasyonu destekleyen pratik bir çözümdür. Özellikle API tüketen uygulamalarda, servislerden gelen JSON verisinin bir kısmı yapılandırma dosyasına taşınacaksa elle dönüştürme hem yavaş hem de hataya açıktır.

Bir Rust projesinde deneme ortamı ayarları JSON olarak tutuluyorsa, bu ayarların Cargo ve ilgili araçlarla uyumlu TOML dosyalarına taşınması gerekebilir. Benzer şekilde Python tarafında pyproject.toml kullanan ekipler, eski betiklerden veya kurum içi panellerden gelen JSON ayarlarını TOML’e dönüştürerek daha düzenli proje yapılandırması elde edebilir. Türkiye’deki ekiplerde sık görülen geliştirme, test ve canlı ortam ayrımı da TOML tablolarıyla okunur biçimde ayrılabilir.

Hugo ile statik site hazırlayan içerik ekipleri için de dönüşüm değerlidir. Örneğin bir haber sitesi, kategori ve menü ayarlarını JSON olarak dışa aktarıp TOML yapılandırmasına çevirebilir. Veri mühendisleri ise farklı sistemler arasında ara biçim olarak JSON kullanıp, uygulama tarafında TOML bekleyen servisler için dönüştürme yapabilir. Eğer veri önce okunabilir hâle getirilecekse JSON biçimlendirme aşaması, ardından JSON TOML Dönüştürücü kullanımı daha güvenli bir akış sağlar.

JSON’dan TOML’e dönüşüm çoğu basit yapı için anlamını korur, ancak her zaman tamamen kayıpsız kabul edilmemelidir. Basit metinler, sayılar, mantıksal değerler, nesneler ve düzenli diziler genellikle sorunsuz çevrilir. Sorun daha çok JSON’un izin verdiği fakat TOML’in doğrudan temsil etmediği yapılarda ortaya çıkar. null değerler, karışık türlerden oluşan diziler ve tarih olarak yorumlanabilecek metinler bu gruba girer.

Sonucu kontrol ederken ilk adım, TOML çıktısının sözdizimi açısından geçerli olduğundan emin olmaktır. Tablolar doğru açılmış mı, aynı anahtar iki kez yazılmış mı, diziler tutarlı mı, metinlerde tırnaklar korunmuş mu gibi noktalar incelenmelidir. İkinci adım anlam kontrolüdür. Örneğin kargo_ucreti = 49.90 gibi bir alanın sayı olarak mı, metin olarak mı kalması gerektiği uygulamanın beklentisine göre değerlendirilmelidir. Para, tarih ve ölçü birimi gibi alanlarda geliştirici kararları önem kazanır.

Pratik bir kontrol yöntemi, dönüştürülen TOML’i tekrar JSON’a çevirip ilk veriyle karşılaştırmaktır. Bunun için ters dönüşüm kullanılabilir. Tam bire bir metin eşleşmesi beklenmeyebilir, çünkü alan sırası veya biçim değişebilir. Önemli olan anahtarların, değerlerin ve hiyerarşinin aynı kalmasıdır. Kritik üretim ayarlarında dönüşümden sonra küçük bir test ortamında uygulamayı çalıştırmak en güvenli yaklaşımdır.