JSON, YAML, TOML: Hangi Yapılandırma Formatını Seçmelisiniz?

JSON, YAML ve TOML arasındaki farklar nelerdir? Her formatın güçlü ve zayıf yönleri, ne zaman hangisini seçmeniz gerektiği ve sık karşılaşılan tuzaklar pratik örneklerle anlatılıyor.

#json#yaml#toml#yapılandırma#veri formatı

JSON, YAML, TOML: Hangi Yapılandırma Formatını Seçmelisiniz?

Bir uygulamanın ayar dosyasını yazarken, bir API yanıtı tasarlarken ya da bir CI/CD hattı tanımlarken hep aynı soruyla karşılaşırsınız: Hangi formatı kullanmalıyım? JSON, YAML ve TOML; bu üç formatın her biri belirli işler için doğmuştur ve birini diğerinin yerine zorla kullanmak çoğu zaman baş ağrısı yaratır. Bu yazıda üçünü yan yana koyup güçlü ve zayıf yönlerini, klasik tuzaklarını ve hangi durumda hangisini seçmeniz gerektiğini netleştiriyoruz.

Aynı Yapılandırma, Üç Format

En iyi karşılaştırma, aynı veriyi üç formatta da görmektir. Basit bir sunucu yapılandırmasını ele alalım.

JSON:

{
  "uygulama": {
    "ad": "MagmaNex",
    "surum": "2.1.0",
    "hata_ayikla": false
  },
  "sunucu": {
    "host": "127.0.0.1",
    "port": 8080,
    "izinli_kokenler": ["https://magmanex.com", "https://app.magmanex.com"]
  }
}

YAML:

uygulama:
  ad: MagmaNex
  surum: "2.1.0"
  hata_ayikla: false

sunucu:
  host: 127.0.0.1
  port: 8080
  izinli_kokenler:
    - https://magmanex.com
    - https://app.magmanex.com

TOML:

[uygulama]
ad = "MagmaNex"
surum = "2.1.0"
hata_ayikla = false

[sunucu]
host = "127.0.0.1"
port = 8080
izinli_kokenler = ["https://magmanex.com", "https://app.magmanex.com"]

Aynı bilgi, üç farklı görsel ağırlık. Şimdi her birini tek tek inceleyelim.

JSON: Her Yerde, Ama Katı

JSON (JavaScript Object Notation) makineler arası veri değişiminin ortak dilidir. Neredeyse her programlama dili onu kutudan çıktığı gibi ayrıştırabilir.

Güçlü yönleri:

Her yerde desteklenir. Tarayıcılardan veritabanlarına kadar evrensel.
Net ve kesin sözdizimi. Belirsizliğe yer yoktur; bir JSON ya geçerlidir ya değildir.
Hızlı ayrıştırma. Makineler için ideal.

Zayıf yönleri:

Yorum satırı yok. Bir ayarın neden orada olduğunu açıklayamazsınız.
Sondaki virgül (trailing comma) hatası. {"a": 1,} geçersizdir ve bu, en sık yapılan hatalardan biridir.
Çift tırnak zorunlu. Tek tırnak (') kabul edilmez, her anahtar tırnak içinde olmalıdır.
İnsan eli için yorucu. Uzun bir ayar dosyasını elle yazmak ve okumak külfetlidir.

JSON, API yanıtları ve programlar arası veri taşıma için mükemmeldir. İnsanların elle düzenlediği ayar dosyaları için ise en konforlu seçenek değildir.

YAML: İnsan Dostu, Ama Tuzaklarla Dolu

YAML (YAML Ain't Markup Language), okunabilirliği ön plana koyar. Süslü parantezler yerine girintiyle hiyerarşi kurar; bu sayede Kubernetes, Docker Compose ve GitHub Actions gibi araçların gözde formatı olmuştur.

Güçlü yönleri:

Çok okunabilir. Görsel gürültü minimumdur.
Yorum desteği. # ile satır eklenebilir.
Çapalar ve referanslar. Tekrar eden blokları yeniden kullanabilirsiniz.

Zayıf yönleri:

Boşluğa duyarlıdır. Yanlış bir girinti tüm dosyayı bozar ve hatayı bulmak zordur. Tab karakteri kullanmak çoğu ayrıştırıcıda yasaktır.
Tip zorlaması (type coercion). YAML değerleri "akıllıca" tahmin etmeye çalışır ve bu beklenmedik sonuçlar doğurur.

YAML'ın "Norveç Problemi"

En ünlü tuzak budur. Bir ülke kodu listesi düşünün:

ulkeler:
  - GB
  - US
  - NO

Buradaki NO, Norveç'in kodudur. Ancak eski YAML 1.1 ayrıştırıcıları bunu boolean false olarak yorumlar. Benzer şekilde yes, on değerleri true; version: 1.0 ise string yerine bir ondalık sayı olur. Çözüm basit ama akılda tutulmalı: belirsiz değerleri tırnak içine alın ("NO", "1.0").

YAML, insanların sık düzenlediği yapılandırma dosyaları için harikadır; ancak makine üretimi ve kesinlik gereken yerlerde tuzaklarına dikkat etmek gerekir.

TOML: Yapılandırma İçin Tasarlandı

TOML (Tom's Obvious, Minimal Language) tam olarak yapılandırma dosyaları için doğmuştur. Rust'ın Cargo.toml'u ve Python'ın pyproject.toml'u bu formatı popülerleştirdi.

Güçlü yönleri:

Açık ve okunabilir. INI dosyalarına benzer, sezgiseldir.
Boşluğa duyarlı değildir. Girinti hatası diye bir derdiniz olmaz.
Belirsiz tipleme yok. NO her zaman bir string'dir, sürpriz olmaz.
Tarih/saat yerleşik olarak desteklenir.

Zayıf yönleri:

Derin iç içe yapılarda hantallaşır. Çok katmanlı veriler için tablo sözdizimi yorucu olabilir.
Daha az evrensel. JSON kadar her dilde hazır kütüphanesi yoktur.

TOML, düz veya az katmanlı uygulama ayarları için ideal sıcak noktadır.

Hangisini, Ne Zaman?

Pratik bir karar rehberi:

API yanıtları, programlar arası iletişim → JSON. Evrensel ve hızlı.
Kubernetes, CI/CD, çok katmanlı ayar dosyaları → YAML. Okunabilir ve esnek (tuzaklarına dikkat).
Uygulama/araç yapılandırması (Cargo, pyproject) → TOML. Net ve güvenli.
Yorum satırına ihtiyaç var → YAML veya TOML (JSON değil).
Mutlak kesinlik ve makine üretimi → JSON.

Sık Karşılaşılan Tuzaklar ve Dönüştürme İpuçları

JSON'da sondaki virgül: Listenin son elemanından sonra virgül bırakmayın.
YAML'da tip belirsizliği: Şüpheli her değeri tırnağa alın; Açık, Kapalı, NO, sürüm numaraları en riskli adaylardır.
TOML'da bölüm tekrarı: Aynı [tablo] başlığını iki kez tanımlayamazsınız.

Dönüştürme yaparken sıfırdan elle yazmak yerine araç kullanın. Önce JSON'unuzu temizleyip doğrulamak için JSON Biçimlendirici aracını kullanın; ardından formatlar arası geçiş için JSON → YAML Dönüştürücü, YAML → JSON Dönüştürücü ve TOML → JSON Dönüştürücü araçlarından yararlanabilirsiniz. Yapılandırmanız için tip güvenli arayüzler üretmek isterseniz JSON → TypeScript Dönüştürücü işinizi görür.

Sonuç

Tek bir "en iyi" format yoktur; doğru seçim işin bağlamına bağlıdır. JSON makineler için, YAML karmaşık ve insan tarafından düzenlenen yapılandırmalar için, TOML ise sade ve net araç ayarları için parlar. Üçünün de tuzaklarını bildiğinizde, hangisini seçerseniz seçin başınız ağrımaz.