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

YAML ve JSON aynı veri modelini paylaşır: ikisi de eşlemeler, diziler ve skaler değerlerden oluşan bir ağaç tanımlar. Fark, bu ağacın yazıya dökülüş biçimindedir.

JSON yapıyı noktalama ile kurar: nesneler süslü parantezle açılır, anahtarlar çift tırnağa alınır, öğeler virgülle ayrılır. YAML ise yapıyı girintiyle anlatır; tırnak çoğu zaman gerekmez, satır başındaki boşluklar hiyerarşiyi belirler.

YAML'ın rahat sözdizimi yapılandırma dosyalarında elle yazmayı kolaylaştırır; bu yüzden Docker Compose, Kubernetes ve CI tanımları YAML ile yazılır. JSON'un katı kuralları ise makineler arası veri alışverişinde belirsizliği ortadan kaldırır; API'lerin ortak dili bu yüzden JSON'dur.

YAML'dan JSON'a Dönüştürücü bu iki dünya arasındaki köprüdür: elle yazdığınız YAML'ı, programların ve servislerin beklediği katı JSON biçimine çevirir. Aradaki eşleme bire bir olduğu için veri kaybı yaşamadan yapıyı taşırsınız; yalnızca yorumlar gibi JSON'un temsil edemediği ayrıntılar geride kalır.

Dönüşüm iki aşamada gerçekleşir: önce YAML metni ayrıştırılır, sonra ortaya çıkan veri ağacı JSON olarak yazılır.

Ayrıştırma sırasında araç girintileri izleyerek hiyerarşiyi kurar, her değerin türünü belirler ve YAML'a özgü yapıları çözer. Çapalar ve takma adlar bu adımda genişletilir: &varsayilan ile işaretlediğiniz bir blok, *varsayilan ile başvurulan her yerde içeriğiyle çoğaltılır. Katlanmış ve blok biçimli çok satırlı metinler tek bir JSON dizesine indirgenir, satır sonları kurallarına göre korunur veya boşluğa çevrilir.

Yazma aşamasında her eşleme bir JSON nesnesine, her dizi bir JSON dizisine dönüşür. Anahtarlar çift tırnağa alınır, özel karakterler kaçışlanır, çıktı isteğe göre girintili veya tek satır olarak üretilir.

Dikkat isteyen birkaç durum vardır:

• Tırnaksız değerler türlerine göre yorumlanır: evet yazan bir metin dize kalırken true mantıksal değere, 3.14 sayıya dönüşür.
• Aynı çapaya yapılan çok sayıda başvuru, JSON çıktısında verinin fiziksel olarak tekrarlanması demektir; dosya boyutu büyüyebilir.
• YAML birden çok belgeyi tek dosyada barındırabilir; JSON tarafında bunlar ayrı çıktılar veya bir dizi olarak ele alınır.

Tüm işlem tarayıcınızda gerçekleştiği için yapılandırma dosyalarınız cihazınızdan çıkmaz; hassas değerler içeren dosyaları da gönül rahatlığıyla çevirebilirsiniz.

En sık karşılaşılan senaryo, elle bakımı yapılan bir YAML yapılandırmasını JSON bekleyen bir sisteme vermektir. Birçok API, komut satırı aracı ve eski kütüphane yalnızca JSON kabul eder; YAML dosyanızı bu araçlara geçirmeden önce çevirmeniz gerekir.

İkinci yaygın kullanım hata ayıklamadır. Girinti kaynaklı YAML hataları gözle zor yakalanır; bir öğenin yanlış seviyede durması dosyayı geçersiz kılmaz ama anlamını değiştirir. Dosyayı JSON'a çevirip parantezli yapıya bakmak, hangi anahtarın hangi bloğa bağlandığını netleştirir. Çıktıyı JSON biçimlendirici ile girintileyerek yapıyı daha da okunaklı hale getirebilirsiniz.

Üçüncü senaryo biçim geçişleridir. Bir projenin yapılandırmasını YAML'dan JSON'a taşırken dosyaları tek tek elle çevirmek hem yavaş hem hataya açıktır; dönüştürücü aynı yapıyı birebir üretir. Rust ve Python ekosistemlerinde yaygınlaşan TOML dosyalarıyla çalışıyorsanız TOML'dan JSON'a dönüştürücü aynı işi o biçim için yapar.

Ters yönde bir ihtiyacınız varsa, yani JSON verinizi daha okunaklı bir yapılandırmaya çevirmek istiyorsanız JSON'dan YAML'a dönüştürücü kullanılır. İki araç birlikte, biçimler arasında kayıpsız gidiş geliş sağlar.

Son olarak öğrenme amacı da küçümsenmemeli: aynı verinin iki biçimde nasıl göründüğünü yan yana incelemek, YAML'ın girinti mantığını kavramanın en hızlı yoludur.

YAML'ın esnek tür çıkarımı, dönüşümde en çok sürprize yol açan konudur. Tırnaksız yazılmış bazı değerler beklediğinizden farklı türe çevrilebilir.

Klasik örnek, eski YAML sürümlerinde no sözcüğünün mantıksal false olarak yorumlanmasıdır; ülke kodu olarak Norveç'i yazdığınızı düşünürken çıktıda false bulursunuz. Benzer biçimde 1.10 gibi bir sürüm numarası sayıya çevrilip 1.1 olabilir, öndeki sıfırıyla anlamlı olan 007 gibi bir kod sayısal değere inebilir. Bu tür değerleri YAML tarafında tırnak içine almak sorunu kökten çözer; dönüştürücü tırnaklı değeri her zaman dize olarak korur.

İkinci konu yorum satırlarıdır. JSON yorum desteklemez; YAML dosyanızdaki açıklamalar çıktıya taşınmaz. Yorumlar sizin için önemliyse özgün YAML dosyasını silmeyin, JSON çıktısını türetilmiş bir kopya olarak kullanın.

Üçüncüsü anahtar türleridir. YAML sayısal veya mantıksal anahtarlara izin verir; JSON'da tüm anahtarlar dizedir. 2024: gibi bir anahtar çıktıda "2024" olur. Çoğu uygulamada fark yaratmaz ama anahtarları sayı olarak okuyan kod varsa bilmekte yarar var.

Son olarak tarih benzeri değerler: YAML 2024-12-12 yazımını tarih olarak tanıyabilir; JSON'da doğal tarih türü olmadığından bu değerler dizeye çevrilir. Tarihleri işleyen kodunuz varsa çıktıdaki dize biçimini doğrulamanız yeterlidir.

Dönüştürücü geçersiz YAML ile karşılaştığında hatanın yerini bildirir; en sık karşılaşacağınız sorunları önceden bilmek düzeltmeyi hızlandırır.

1. Sekme kullanımı: YAML girintide sekme karakterine izin vermez, yalnızca boşluk geçerlidir. Kod editörünüz sekmeyi otomatik boşluğa çevirmiyorsa dosya daha ilk satırlarda ayrıştırma hatası verir.
2. Tutarsız girinti: Aynı seviyedeki öğelerin aynı sütunda başlaması gerekir. Bir liste öğesini iki, diğerini üç boşlukla girintilemek yapıyı bozar veya öğeyi beklenmedik bir bloğa bağlar.
3. İki nokta sonrası eksik boşluk: anahtar:deger yazımı geçersizdir; iki noktadan sonra boşluk gerekir: anahtar: deger.
4. Kaçışsız özel karakterler: İki nokta veya diyez içeren değerler tırnaksız yazıldığında yorum ya da yeni anahtar sanılabilir. mesaj: "saat: 14:30" gibi tırnaklı yazım güvenlidir.
5. Karışık liste yazımı: Aynı diziyi hem tireli satırlarla hem satır içi köşeli parantezle tanımlamaya çalışmak ayrıştırıcıyı şaşırtır; tek bir stile bağlı kalın.

Hata mesajı çoğu zaman sorunun bir satır altını gösterir; ayrıştırıcı, beklenmeyen girintiyi ancak bir sonraki öğeye geçerken fark eder. Bildirilen satırda hata göremiyorsanız bir üst satıra ve o bloğun girinti düzenine bakın. Dosya temizlendikten sonra dönüşüm tek denemede tamamlanır.