JSON ve YAML: Doğru Yapılandırma Formatını Seçmek

JSON ve YAML, ikisinden birinde binlerce satırlık bir yapılandırma dosyasını korumayı deneyene kadar farklı kostümlerdeki aynı şey gibi görünür. Farklar önemlidir ve çoğu sözdizimi hakkında değil — her formatın biraz yanlış olduğunuzda ne yaptığına dair.

Her ikisinde aynı örnek

Farkı hissetmenin en kısa yolu aynı veriyi yan yana okumaktır.

JSON

{
  "name": "convertitive",
  "version": "1.4.0",
  "ports": [80, 443],
  "features": {
    "darkMode": true,
    "telemetry": false
  },
  "owners": ["[email protected]", "[email protected]"]
}

YAML

name: convertitive
version: 1.4.0
ports:
  - 80
  - 443
features:
  darkMode: true
  telemetry: false
owners:
  - [email protected]
  - [email protected]

YAML yaklaşık %30 daha kısa ve her ikisini de daha önce hiç görmemiş bir insan tarafından argüman olarak daha okunabilir. JSON makine için belirsizdir, ayrıştırıcı dostudur ve herhangi bir işletim sistemindeki herhangi bir metin düzenleyicisinde görünmez karakter hasarı olmadan kopyala-yapıştır yoluyla hayatta kalır.

YAML’ın üstün olduğu durumlar

Yorumlar

YAML her yerde # satır yorumları’nı destekler. JSON desteklemez — RFC 8259 bunları kasıtlı olarak hariç tutar. Bir bayrağın neden kapalı olduğunu veya bir ayarın gerçekte hangi değer aralığını kabul ettiğini belgelemek için yorumlar güzel-olsa-da-olur değil; nasıl yapıldığını belgeleyen şeydir.

# pin to a specific patch release; do not auto-update
version: 1.4.0

ports:
  - 80
  # 443 is here so the LB health check works; do not remove
  - 443

Çok satırlı dizeler

YAML’ın çok satırlı dizeler için iki blok-skaler stili vardır. | yeni satırları korur, > onları boşluklara katlar.

Çıpalar ve takma adlar

YAML bir düğümü & ile etiketlemenize ve başka bir yerde* ile başvurmanıza izin verir. Birleştirme anahtarları (<<) bir eşleştirmeyi diğeriyle genişletir. Sonuç, bir yapılandırma dosyasında gerçek DRY:

defaults: &defaults
  retries: 3
  timeout_ms: 5000

production:
  <<: *defaults
  endpoint: api.example.com

JSON’un eşdeğeri yoktur. Geçici çözüm şablonlama (Jinja, Helm) veya yükleme zamanında işlem sonrası, her ikisi de JSON yerel yapılandırmaların önlediği mekanizmalar ekler.

Görsel taranabilirlik

Girinti-olarak-yapı, ekiplerin YAML’ı seçmesinin en büyük tek nedenidir. Her Kubernetes manifestosu YAML ve her Ansible oyun kitabının YAML olmasının nedeni budur.

JSON’un üstün olduğu durumlar

Belirsiz ayrıştırma

JSON beş sayfalık bir gramere sahiptir. İki doğru ayrıştırıcı her belge üzerinde mutabık kalacak. YAML, ayrıştırıcı sürümüne bağlı olarak aynı belgenin birden fazla geçerli yorumuyla doksan sayfalık bir gramere sahiptir. JSON’un katılığı özelliktir.

Araç yaygınlığı

Her dil standart kütüphanesinde JSON ayrıştırıcısıyla birlikte gelir. YAML çoğu ortamda üçüncü taraf bağımlılığı gerektirir.

Herhangi bir metin kanalından geçişler

JSON’un önemli boşluğu yoktur. Bir sohbet istemcisine, e-postaya, kabuk istemine yapıştırabilirsiniz; küçültebilirsiniz. YAML önemli boşlukludur ve tek bir sekme-boşluk hatası belgeyi bozar.

Norveç sorunu — gerçekten

En ünlü YAML tuzağı: YAML 1.1’de NO dizesi boolean falseolarak ayrıştırılır. Norveç’in ISO kodunu (NO) içeren ülke listeleri tırnak içine alınmadıkça [false, ...] olur. YAML 1.2 yalnızca küçük harfli true ve falseyi boolean olarak ele alarak bunu düzeltir — ancak şaşırtıcı miktarda araç 2026’da hâlâ 1.1 varsayılanına sahip.

Güvenlik varsayılanları

YAML’ın spesifikasyonu, bir belgenin ayrıştırıcının rastgele sınıflar örneklemesini sağlayan tür etiketleri içerir. Birkaç dil bağlantısı bunu yıllarca varsayılan olarak onurlandırdı. Düzeltme “güvenli” yükleyici kullanmaktır (yaml.safe_load Python’da, YAML.safe_loadRuby’de).

Ortak tuzaklar

JSON sayı hassasiyeti

JSON’un spesifikasyonu sayıların keyfi büyüklük ve hassasiyette olabileceğini söylüyor. Ancak JavaScript’in JSON.parse’ı ve çoğu JS dışı uygulama bunları IEEE 754 double’a seri dışı bırakır; bu da 2^53 - 1’e (yaklaşık 9,007 × 10^15) kadar tam sayıları tam olarak temsil edebilir. Twitter snowflake ID, Stripe charge ID veya bu sınırın üzerindeki 19 haneli tam sayı sessizce yuvarlanacak. Düzeltme: büyük tam sayıları string olarak kodlayın veya BigInt destekli ayrıştırıcı kullanın.

YAML sürüm kayması

YAML 1.1 (2005) ve YAML 1.2 (2009), bu ikisi gerçek dünyadadır. 1.2, JSON’un katı bir üst kümesidir, Norveç sorununu düzeltti ve spesifikasyonu önemli ölçüde sıkılaştırdı. Birçok ayrıştırıcı hâlâ sessizce 1.1’e varsayılan.

Karar ağacı

Tüketiciye hakim olduğunuz yeni projeler için:

1. Makineden makineye tel formatı mı? JSON kullanın.
2. 100 satırın altında insan tarafından düzenlenen yapılandırma mı? Tüketici YAML bekliyorsa YAML, aksi takdirde TOML kullanın.
3. 100 satırın üzerinde, derinlemesine iç içe insan tarafından düzenlenen yapılandırma mı? YAML’ın çıpaları ve blok skalerleri bu boyutta işe yaramaya başlar. YAML 1.2’yi belgede sabitleyin.
4. Güvenilmez giriş mi? JSON varsayılan olarak daha güvenlidir.
5. Tüketici sabit mi (Kubernetes, npm)? Tüketiciye uyun. Ekosistemin mantığına karşı savaşmayın.

Aralarında dönüştürme

Dönüşüm mekanik çünkü YAML 1.2 bir JSON üst kümesidir. JSON girişi, YAML çıkışı her zaman kayıpsızdır. YAML girişi, JSON çıkışı yalnızca YAML ilkel türler kullanıyor ve genişletme gerektiren çıpa/takma ad yoksa kayıpsızdır.

JSON ↔ YAML dönüştürücümüz tarayıcıda her iki yönü de işler. Salt JSON çalışması için — güzel yazdırma, doğrulama, küçültme — JSON biçimlendirici daha keskin bir araçtır.

Dürüst çıkarım

JSON, iki programın mutabık kalması gereken her şey için doğru varsayılandır. YAML, bir insanın uzun süre düzenleyeceği her şey için doğru varsayılandır. Çoğu üretim sistemi her ikisiyle biter: insan sınırında YAML (Helm grafikleri, GitHub Actions iş akışları, uygulama yapılandırması), tel üzerinde ve veritabanlarında bekleyen JSON.