JSON'dan YAML'a Dönüştürücü

JSON YAML Dönüştürücü, JSON biçimindeki veriyi YAML biçimine çevirerek daha okunabilir, düzenlenebilir ve yapılandırma dosyalarına uygun hâle getiren bir araçtır. JSON, API yanıtlarında, web uygulamalarında ve veri alışverişinde çok yaygın kullanılır. YAML ise özellikle Docker Compose, Kubernetes, GitHub Actions ve CI/CD dosyalarında tercih edilir çünkü girinti temelli yapısı insan gözüyle daha rahat izlenir.

Bir belediyenin açık veri API’sinden mahalle bazlı otopark doluluk bilgisi aldığınızı düşünün. API büyük olasılıkla JSON döndürür. Bu veriyi bir test ortamında yapılandırma dosyası olarak kullanmak istediğinizde YAML daha pratik olabilir. JSON’daki süslü parantezler, köşeli parantezler ve virgüller yerine YAML’da anahtarlar, değerler ve girintiler öne çıkar.

JSON YAML Dönüştürücü özellikle hazır JSON çıktısını elle yeniden yazmadan YAML’a aktarmak isteyen geliştiriciler için zaman kazandırır. Dönüştürmeden önce JSON’un geçerli olup olmadığını görmek istiyorsanız JSON düzenleme aracı ile biçimi kontrol etmek iyi bir adımdır. Ters yönde çalışmanız gerektiğinde ise YAML’dan JSON’a dönüşüm iş akışını tamamlayabilir.

JSON ve YAML aynı tür bilgileri temsil edebilir: nesneler, listeler, metinler, sayılar, mantıksal değerler ve boş değerler. Fark, bu bilgilerin yazılış biçimindedir. JSON daha katı bir söz dizimine sahiptir. Anahtarlar çift tırnak içinde yazılır, nesneler süslü parantezle, diziler köşeli parantezle gösterilir. Virgül kullanımı zorunludur ve küçük bir yazım hatası tüm yapıyı geçersiz kılabilir.

YAML ise girintiye dayalıdır. Bu nedenle yapılandırma dosyalarında daha doğal okunur. Örneğin bir Kubernetes manifest dosyasında servis adı, imaj adı, port bilgisi ve ortam değişkenleri alt alta düzenli biçimde görülebilir. Türkiye’deki bir e-ticaret ekibinin ödeme, kargo ve kampanya servislerini ayrı ayrı yapılandırdığı bir projede YAML, operasyon ekibinin ayarları hızlıca gözden geçirmesini kolaylaştırır.

Buna karşılık YAML’da girinti önemlidir. Yanlış boşluk kullanımı anlamı değiştirebilir. JSON’da yapı sembollerle belirgin olduğu için makine tarafından işlenmesi daha doğrudandır. JSON YAML Dönüştürücü bu iki yaklaşım arasında köprü kurar: JSON’un makine dostu yapısını alır, YAML’ın insan dostu düzenine dönüştürür. Dönüşüm sırasında anahtar sırası, liste yapısı ve veri türleri mümkün olduğunca korunur.

JSON YAML Dönüştürücü önce girilen JSON metnini ayrıştırır. Bu aşamada aracın beklediği şey geçerli bir JSON yapısıdır. Örneğin anahtarların tırnak içinde olması, dizilerde elemanların doğru virgüllerle ayrılması ve süslü parantezlerin dengeli kapanması gerekir. JSON geçerli değilse sağlıklı bir YAML çıktısı üretilemez çünkü araç önce verinin anlamlı bir ağaç yapısına dönüşmesine ihtiyaç duyar.

Ayrıştırma tamamlandıktan sonra JSON nesneleri YAML eşlemelerine, JSON dizileri YAML listelerine çevrilir. {"sehir":"İzmir","aktif":true} gibi bir yapı YAML’da sehir: İzmir ve aktif: true satırlarıyla temsil edilir. İç içe nesnelerde girinti kullanılır. Örneğin ilçe, mahalle ve teslimat bölgesi gibi bilgiler alt seviyelere taşınır.

Araç bazı özel durumları da dikkate alır. Boş değerler, çok satırlı metinler, Türkçe karakterler, tırnak gerektiren ifadeler ve sayı gibi görünen metinler dönüşümde önemlidir. "0342" gibi bir alan telefon koduysa metin olarak kalması gerekebilir. JSON YAML Dönüştürücü bu tür ayrıntıları korumaya çalışır, ancak kritik yapılandırmalarda çıktıyı kullanmadan önce gözden geçirmek her zaman doğru yaklaşımdır.

JSON YAML Dönüştürücü en çok API yanıtlarını yapılandırma dosyalarına yaklaştırmak isteyen ekiplerin işine yarar. Bir kargo firmasının şube listesi, bir ödeme sağlayıcısının işlem yanıtı veya bir kamu verisi servisinden gelen JSON çıktısı doğrudan uygulama içinde kullanılabilir. Ancak aynı veriyi test senaryosu, örnek konfigürasyon ya da dokümantasyon içinde göstermek istediğinizde YAML daha okunaklı olabilir.

DevOps ekipleri için kullanım alanı daha da belirgindir. Docker Compose dosyaları, Kubernetes kaynakları ve GitHub Actions akışları çoğunlukla YAML ile yazılır. JSON formatında hazırlanmış ortam değişkenlerini, servis tanımlarını veya izin listelerini YAML’a çevirmek, elle düzenleme hatalarını azaltır. Örneğin İstanbul, Ankara ve Bursa bölgelerine göre ayrılmış dağıtım servislerini tek tek yazmak yerine JSON kaynağını dönüştürüp YAML dosyasına uyarlamak daha hızlıdır.

Veri mühendisleri de farklı sistemler arasında biçim uyumu sağlamak için bu aracı kullanabilir. Bazı araçlar JSON isterken bazıları YAML tercih eder. Yapılandırma dışında TOML kullanan sistemlerle çalışıyorsanız JSON’dan TOML’a dönüşüm de benzer bir ihtiyaç için değerlendirilebilir. Önemli olan, hedef sistemin beklediği veri türlerini ve girinti kurallarını son kontrolde doğrulamaktır.

Gerçek projelerde JSON çoğu zaman basit birkaç alandan ibaret değildir. Kullanıcı bilgileri, adresler, ürün seçenekleri, kampanya koşulları ve izinler iç içe nesneler ve diziler hâlinde gelir. JSON YAML Dönüştürücü bu yapıları YAML’da girintilerle gösterir. Bir müşterinin adres alanı içinde il, ilçe, mahalle ve posta kodu varsa YAML çıktısında bu bilgiler aynı hiyerarşiyle alt alta yer alır.

Dikkat edilmesi gereken ilk konu girintidir. YAML’da girinti yalnızca görsel düzen değil, aynı zamanda yapının anlamıdır. Bir liste elemanının yanlış seviyeye yerleşmesi, teslimat seçeneklerinin farklı bir alana bağlanmasına neden olabilir. Bu yüzden özellikle Kubernetes veya CI/CD dosyalarında dönüştürülen çıktıyı çalıştırmadan önce kontrol etmek gerekir.

Özel karakterler de önemlidir. Türkçe karakterler, iki nokta üst üste, yüzde işareti, kare işareti ve tırnak içeren metinler YAML’da farklı yorumlanabilir. Örneğin kampanya: "2 al 1 öde" gibi bir ifade metin olarak korunmalıdır. Çok satırlı açıklamalar, sözleşme metinleri veya hata mesajları YAML’da özel blok biçimleriyle gösterilebilir. JSON YAML Dönüştürücü bu durumları yönetmeye yardımcı olur, ancak üretim ortamına alınacak dosyalarda anlam kayması olup olmadığını gözle denetlemek gerekir.

JSON’dan YAML’a dönüşüm çoğu standart veri yapısında kayıpsıza yakın sonuç verir. Nesneler, diziler, metinler, sayılar, true, false ve null gibi değerler genellikle aynı anlamı korur. Yine de biçimler arasında bire bir eşleşmeyen ayrıntılar olabilir. JSON’da bulunmayan bazı YAML özellikleri ya da YAML’ın metinleri yorumlama biçimi, dikkat edilmezse beklenmeyen sonuçlara yol açabilir.

En sık kontrol edilmesi gereken alanlar sayıya benzeyen metinlerdir. Telefon kodu, barkod, vergi kimlik numarası veya başında sıfır bulunan değerler metin olarak kalmalıdır. Örneğin bir mağaza kodu "0601" ise bunun sayı gibi algılanması istenmez. Tarih benzeri ifadeler de benzer şekilde kontrol edilmelidir. Bir alanın gerçekten tarih mi, yoksa sadece metin mi olduğu hedef sistem açısından önemlidir.

Pratik kontrol için önce JSON’un geçerli olduğundan emin olun, sonra JSON YAML Dönüştürücü ile çıktıyı üretin. Ardından YAML dosyasını kullanacağınız araçta doğrulayın. Kubernetes için manifest doğrulaması, Docker Compose için yapılandırma kontrolü, CI/CD için deneme çalıştırması yapılabilir. Büyük dosyalarda rastgele değil, kritik alanları bilinçli seçerek kontrol etmek daha güvenlidir: kimlik alanları, bağlantı bilgileri, gizli değişken adları, liste sıraları ve iç içe izin kuralları ilk bakılması gereken yerlerdir.