JSON mu YAML mı: Farklar Açıklandı

Bazı projelerin config için .json dosyaları kullandığını, bazılarının ise .yaml veya .yml kullandığını fark etmişsindir. Her iki format da yapılandırılmış veriyi temsil ediyor. Her ikisi de insan tarafından okunabilir. Peki gerçek fark nedir ve ne zaman hangisini seçmelisin?

İkisini de yoğun şekilde kullandım — JSON, API'ler ve veri alışverişi için günlük sürücüm, YAML ise Kubernetes manifest'leri, GitHub Actions ve Docker Compose için tercihim. Benzer sorunları çözüyorlar ama çok farklı karakterlere sahipler.

Yan Yana: Aynı Config Her İki Formatta

JSON olarak yazılmış bir veritabanı config object'i:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp",
    "ssl": true,
    "pool": {
      "min": 2,
      "max": 10
    },
    "replicas": ["replica1.db", "replica2.db"]
  }
}

Aynı config'in YAML hali:

database:
  host: localhost
  port: 5432
  name: myapp
  ssl: true
  pool:
    min: 2
    max: 10
  replicas:
    - replica1.db
    - replica2.db

YAML görsel olarak daha temiz. Çoğu string'in etrafında tırnak yok, süslü parantez yok, virgül yok. Düzenli olarak insan tarafından düzenlenen bir config dosyası için bu netlik birikir. Ama YAML bunu, altta oldukça daha karmaşık olarak başarıyor.

YAML'ın Parladığı Yerler

• İnsan tarafından düzenlenen config dosyaları. CI/CD pipeline'ları (GitHub Actions, GitLab CI), Kubernetes manifest'leri, Docker Compose, Ansible playbook'ları. Hepsi YAML. Tesadüf değil — bunlar insanların elle yazdığı dosyalar.
• Yorumlar. YAML, # ile yorumları destekliyor. Bir ayarın neden o şekilde olduğunu açıklamak istediğin config dosyaları için bu çok önemli. JSON hiç yorum desteklemiyor.
• Çok satırlı string'ler. YAML, doğal okunabilen çok satırlı içerik için block scalar'lar sunuyor. JSON, \n escape dizileri gerektiriyor.
• Daha az görsel gürültü. Çoğu string'i tırnak içine almak zorunlu değil, kapanış süslü parantezi yok, takip eden virgül derdi yok.
• Anchor'lar ve alias'lar. YAML, bir değeri bir kez tanımlayıp başka yerlerde &anchor ve *alias ile referans vermenizi sağlıyor — DRY config dosyaları için kullanışlı.

JSON'un Kazandığı Yerler

• Katılık. JSON, herhangi bir veri yapısı için tek geçerli temsile sahip. YAML'da aynı şeyi yazmanın bir düzine yolu var, bu da ekipler arasında tutarsızlık yaratıyor.
• Girinti tuzağı yok. JSON süslü parantez ve köşeli parantez kullanır. YAML girinti kullanır, yani yanlış yerleştirilmiş tek bir boşluk tüm config'ini sessizce bozabilir.
• Parse performansı. JSON parser'ları hızlı ve basit. YAML parser'ları karmaşık — YAML 1.1'in notoriously hileli implicit type coercion kuralları var.
• Evrensel kütüphane desteği. Her dilde battle-tested, zero-dependency JSON parser'ı var. YAML kütüphaneleri kalite ve spec uyumluluğu açısından değişiklik gösteriyor.
• Tooling. Linter'lar, formatter'lar, şema validator'ları — JSON tooling'i daha olgun ve yaygın olarak mevcut.
• API payload'ları. JSON, web API'lerinin evrensel dili. HTTP üzerinden YAML göndermek alışılmışın dışında olur ve sürtüşme yaratır.

Seni Yakacak YAML Tuzakları

YAML'ın gerçek üretim olaylarına neden olmuş bazı gerçekten şaşırtıcı davranışları var. Bunların çoğu, YAML 1.1'deki implicit type kurallarından geliyor, bunları YAML 1.2 sıkılaştırdı. Kritik bir şey için YAML'a güvenmeden önce bunları bil:

# YAML 1.1 implicit type coercion — all of these become booleans:
enabled: yes   # → true
disabled: no   # → false
country: NO    # → false (!)  ← the Norway Problem

# Safe practice: quote strings that look like booleans
country: "NO"
enabled: "yes"

• Octal integer'lar. YAML 1.1'de 010, 10 değil 8 (octal) olarak parse edilir. Dosya izinleri gibi şeyler için geçerli.
• Tab'lar vs boşluklar. YAML, girinti için tab'ları yasaklar. Bir kod editöründen bir tab sızarsa, dosyan sessizce kırılır ya da şifreli bir hata fırlatır.
• Implicit null'lar. YAML'da boş bir değer null olur. Elle düzenlerken gözden kaçırmak kolay.
• String vs sayı belirsizliği. port: 8080 sana bir integer verir. version: 1.0 bir float verebilir. Bazen "1.0" string'ini istiyorsun. Önemli olduğunda her zaman tırnak kullan.

Pratik Karar Rehberi

YAML'ı tercih et:

• İnsanların doğrudan düzenlediği config dosyaları yazarken: CI/CD, Kubernetes, Docker Compose, Ansible
• Dosyada ayarları açıklayan yorumlar olacaksa
• Çok satırlı string değerleri yaygınsa
• Çalıştığın ekosistem zaten YAML kullanıyorsa (konvansiyonla savaşma)

JSON'ı tercih et:

• Bir API üzerinden veri gönderip alırken
• Veri programatik olarak üretilip tüketiliyorsa (insan düzenlemesi yok)
• Farklı araçlar ve diller arasında garantili parse tutarlılığına ihtiyaç varsa
• JSON'u standartlaştıran bir ekosistemde çalışırken: npm (package.json), VS Code (settings.json), Angular, TypeScript

İkisi Arasında Dönüştürme

YAML'ı anlamayan bir araç için YAML config'ini JSON'a dönüştürmen mi gerekiyor? YAML'dan JSON'a dönüştürücü'yü kullan. Tersine mi gideceksin? JSON'dan YAML'a dönüştürücü halleder. YAML Formatter, hizası bozulmuş YAML yapıştırdığında da işe yarıyor. YAML'ın parse edilmiyorsa, YAML Validator tam olarak nerede sorun olduğunu söyler.

Sonuç

JSON ve YAML rekabet halinde değil, birbirini tamamlar nitelikte. Veri alışverişi için JSON kullan — API'ler, programatik veri depolama, serileştirme. İnsanların okuduğu ve düzenlediği config dosyaları için YAML kullan. Olgun projelerin çoğu ikisini de kullanır: bağımlılıklar için package.json, CI için .github/workflows/*.yml. Her formatın ne için optimize edildiğini kavradıktan sonra seçim kendiliğinden netleşir.