TOML vs JSON vs YAML: Hangi Yapılandırma Biçimini Seçmeli?

İşte TOML vs JSON vs YAML karşılaştırmasının kısa hâli: JSON, her dilin ayrıştırdığı, makineler arası değişim için varsayılan biçimdir; YAML, Kubernetes ve CI hatlarını çalıştıran, insan dostu biçimdir; TOML ise Cargo.toml ve pyproject.toml gibi araç ve uygulama yapılandırmaları için tasarlanmış, açık ve türlenmiş biçimdir. Tek bir biçim her yerde kazanmaz. Doğru yapılandırma dosyası biçimi üç şeye bağlıdır: dosyayı kimin düzenlediği, yorumlara ihtiyaç duyup duymadığınız ve türlerin ne kadar katı olması gerektiği.

Pratik bir kural. Dosyayı bir makine yazıp bir makine okuyorsa JSON’a uzanın. Bir insan her gün derinlemesine iç içe geçmiş altyapıyı elle düzenliyorsa YAML karmaşıklığını hak eder. Yanılması zor, açık ve türlenmiş bir yapılandırma istiyorsanız en güvenli seçim TOML’dur. Bu biçimler aslında birbirinin rakibi değildir. Farklı şeritlerde yol alırlar: makineler için JSON, DevOps için YAML, araç yapılandırması için TOML. Aşağıda bunu yan yana örneklerle ve hataya yol açan gerçek farklarla göreceksiniz; en sonda da bir sonraki projenizde kullanabileceğiniz bir karar matrisi var.

30 saniyelik yanıt

Yalnızca yarım dakikanız varsa, aşağıdaki tablo üç biçimi yan yana özetliyor.

	JSON	YAML	TOML
Yorumlar	Yok	Var (#)	Var (#)
Veri türleri	Açık, asgari	Örtük (yapıdan çıkarılır)	Açık, zengin
Yerel tarihler	Yok	Sürüme bağlı	Var (dört tür)
İç içe yapı biçimi	Süslü parantez {}	Girinti	[section] başlıkları
Girintiye duyarlı	Hayır	Evet (sekmeler yasak)	Hayır
Çok satırlı karakter dizileri	Yok (yalnızca \n)	Var (| ve >)	Var (""")
Sondaki virgüller	Yasak	Geçerli değil	Dizilerde izinli
JSON üst kümesi	—	Evet (1.2)	Hayır
En uygun kullanım	API’ler, veri değişimi	K8s, CI, Ansible	Rust/Python araç yapılandırması

Bu tablodan üç tek satırlık sonuç çıkıyor:

• JSON’u seçin, dosya programlar tarafından üretilip tüketildiğinde: API payload’ları, package.json, tsconfig.json, bir sistem sınırını aşan her şey.
• YAML’ı seçin, insanlar derin, iç içe yapılandırmayı elle düzenlediğinde ve ekosistem bunu zaten beklediğinde: Kubernetes manifest’leri, GitHub Actions, Docker Compose, Ansible playbook’ları.
• TOML’u seçin, bir araç ya da uygulama için açık, türlenmiş bir yapılandırma istediğinizde; çoğunlukla düz, birkaç bölümlü, farklı beceri düzeyindeki katkıda bulunanların düzenlediği yapılandırmalar: Cargo.toml, pyproject.toml, Hugo, Netlify.

Peki bu sonuçlar neden böyle? Gerçek hatalar tam da bu gerekçelerin içinde çıkıyor.

Aynı yapılandırma, üç farklı biçimde

Farkı görmenin en hızlı yolu, aynı yapılandırmayı üç kez yazmaktır. İşte küçük bir servis yapılandırması: bir ad ve sürüm, birkaç üst düzey bayrak, bir özellik listesi ve iç içe bir veritabanı bloğu.

JSON:

{
  "name": "acme-api",
  "version": "2.4.0",
  "debug": false,
  "released": "2026-07-02",
  "features": ["auth", "metrics", "tracing"],
  "database": {
    "host": "db.internal",
    "port": 5432,
    "max_connections": 100
  }
}

YAML:

name: acme-api
version: "2.4.0"
debug: false
released: "2026-07-02"
features:
  - auth
  - metrics
  - tracing
database:
  host: db.internal
  port: 5432
  max_connections: 100

TOML:

name = "acme-api"
version = "2.4.0"
debug = false
released = "2026-07-02"
features = ["auth", "metrics", "tracing"]

[database]
host = "db.internal"
port = 5432
max_connections = 100

Üçü de aynı veriyi tanımlar. Gözünüzün nerede takıldığına bakın. En çok noktalama işaretini JSON taşır: her anahtar çift tırnak içindedir, her düzey süslü parantez ekler ve tek bir başıboş sondaki virgül sözdizimi hatasıdır. YAML bunların neredeyse tamamını atar, dolayısıyla yapı yalnızca girintiden gelir; bu da bir sekme araya sızana dek harika okunur. TOML ikisinin arasında durur: tırnaklar yalnızca karakter dizilerinde, key = value çiftleri ve iç içe bloğu eski bir INI dosyasının yapacağı gibi adlandıran bir [database] başlığı. released alanının üçünde de tırnaklı bir karakter dizisi olduğuna dikkat edin; böylece veri burada aynı kalır. Bu bilinçli bir tercih, çünkü tarihler tam da bu biçimlerin anlaşmayı bıraktığı yerdir; sıradaki konu da bu.

JSON — makineler arası değişim için varsayılan

JSON, düşünmeden uzandığınız biçimdir ve genellikle bu içgüdü doğrudur. Her yaygın dil bir ayrıştırıcı sunar, her HTTP API onu konuşur ve dilbilgisi aklınızda tutabileceğiniz kadar küçüktür. Katı ve nettir: bir karakter dizisi karakter dizisidir, 5432 bir sayıdır, true bir mantıksal değerdir ve her birini yazmanın tam olarak tek bir yolu vardır. JSON’u hiç karşılaşmamış sistemler arasında göndermeyi güvenli kılan şey bu katılıktır. Bir Node servisi bir Go servisine JSON gönderdiğinde, ikisi de anlam üzerinde bayt bayt anlaşır.

Aynı katılık, JSON’un kendi sahasına hükmetmesinin nedenidir. package.json, tsconfig.json ve composer.json JSON’dur; çünkü araçlar bunları sürekli üretip yeniden yazar ve makine tarafından yazılan yapılandırma, makineye göre katı bir biçim ister. API payload’ları ve mesaj kuyruklarında başka bir şey seçmenin bir nedeni yok.

JSON’un zayıf yönlerinin tümü, bir insanın onu elle düzenlemesi gereken anda ortaya çıkar. Yorum yoktur. Sondaki virgül yoktur; bu yüzden bir listeyi yeniden sıralamak virgülleri düzeltmek demektir. Çok satırlı karakter dizileri yoktur, yalnızca \n kaçış dizileri vardır. Her anahtarın çift tırnağa ihtiyacı vardır. Ve tarih türü yoktur; bu nedenle 2026-07-02 tırnaklı bir karakter dizisi olarak yaşamak ve teamüle göre ayrıştırılmak zorundadır. Bir insanın baktığı bir yapılandırma dosyası için bu eksiklikler birikerek sürtünmeye dönüşür.

”JSON’da yorum yok” sorunu

En çok istenen tek JSON özelliği, Douglas Crockford’un bilinçli olarak dışarıda bıraktığı şeydir: yorumlar. Gerekçesi, yorumların insanları yapılandırma dosyalarına ayrıştırma yönergeleri kaçırmaya davet ederek birlikte çalışabilirliği bozacağıydı. Bu karar hakkında ne düşünürseniz düşünün, düz bir JSON yapılandırmasına açıklama ekleyemezsiniz ve bu, insanların baktığı her şey için can sıkıcıdır. Pratik çözüm bir üst kümedir. JSON5 yorumlar, sondaki virgüller, tırnaksız anahtarlar ve tek tırnaklar ekler; JSONC (JSON with Comments), VS Code’un ayarları için kullandığı daha hafif çeşittir. İkisi de JSON’u düzenlenebilir kılarken JSON’un biçimini korur. Yorumlara ihtiyacınız varsa ama JSON ailesinde kalmak istiyorsanız, her birinin ne zaman kullanılacağı ve araçları memnun etmenin yolu için JSON5 ve JSONC biçimlendirme rehberimizi okuyun.

YAML — insan dostu DevOps standardı

YAML, klavye başındaki insan için en iyilenmiştir. Yorumları destekler, girinti tabanlı düzeni derinlemesine iç içe yapıları temiz tutar ve çapalar (anchor) bir bloğu bir kez tanımlayıp kopyala-yapıştır yapmak yerine bir takma adla yeniden kullanmanızı sağlar:

defaults: &defaults
  timeout: 30
  retries: 3

staging:
  <<: *defaults
  host: staging.internal

production:
  <<: *defaults
  host: prod.internal

&defaults çapası bir bloğu adlandırır ve <<: *defaults onu her iki ortama da birleştirir; böylece paylaşılan zaman aşımındaki bir değişiklik tek bir yerde olur. Ne JSON’da ne de TOML’da buna benzer bir şey vardır. Bu okunabilirlik, YAML’ın operasyonların ortak dili hâline gelmesinin nedenidir: Kubernetes manifest’leri, GitHub Actions iş akışları, Docker Compose dosyaları ve Ansible playbook’larının tümü YAML’dır. Yapılandırmanız beş düzey derinliğindeyse ve bir insan onu her gün elden geçiriyorsa, YAML’ın az noktalamalı yapısı gerçek bir rahatlamadır.

Bedeli karmaşıklık ve sürprizdir. YAML 1.2 belirtimi büyüktür ve tam uyum nadirdir; bu yüzden farklı ayrıştırıcılar uç durumlarda anlaşmazlığa düşer. Girinti anlamlıdır, sekmeler tamamen yasaktır ve yanlış hizalanmış bir boşluk anlamı değiştirebilir ya da ayrıştırmayı başarısız kılabilir. En keskin köşe örtük türlemedir: YAML tırnaksız bir skalerin türünü yapısından tahmin eder ve bir lakap kazanacak kadar sık yanlış tahmin eder.

Norveç sorunu tek paragrafta

YAML’da country: NO yazın; birçok ayrıştırıcı size "NO" karakter dizisini değil, false mantıksal değerini verir; çünkü çoğu Kubernetes aracının hâlâ izlediği YAML 1.1, NO, YES, ON, OFF, Y ve N değerlerini mantıksal değer olarak ele alır. Norveç’in ülke kodu, hiçbir hata vermeden, sessizce false olur. Aynı örtük türleme 0755’i sekizlik bir sayıya, 1.20’yi de 1.2’ye çevirir. Çözüm sıkıcı ama güvenilirdir: başka bir şeyle karıştırılabilecek karakter dizilerini tırnak içine alın. Bu tuzak, gerçek kesintiler ve YAML 1.1’e karşı 1.2 tarihçesi dahil, YAML Norveç sorunu rehberimizde kendi derinlemesine incelemesini hak edecek kadar ünlüdür. Bu makale için çıkarım basittir: YAML’ın kolaylığı ve tehlikesi aynı özellikten gelir.

İnsanlar her gün derinlemesine iç içe yapılandırmayı düzenlediğinde ve çevredeki ekosistem bunu zaten talep ettiğinde YAML kazanır. Bir Helm chart’ı yazıyorsanız, YAML yazıyorsunuz demektir ve bunda bir sorun yok.

TOML — araçlar için tasarlanmış açık yapılandırma

TOML (Tom’s Obvious, Minimal Language, Tom Preston-Werner tarafından oluşturuldu), YAML kullanıcılarının hep istediği yapılandırma biçimi olacak şekilde tasarlandı: okunabilir ama tahmin yürütmeden. Belirleyici özelliği açıklıktır. Türler nettir; bu yüzden port = 5432 her zaman bir tam sayı, name = "acme" ise her zaman bir karakter dizisidir ve takılıp düşeceğiniz yapı temelli bir çıkarım yoktur. TOML söz dizimi [section] başlığını INI dosyalarından ödünç alır; bu da bir yapılandırmanın en üst düzeyini gözle taranabilir kılar ve girintiye duyarlı değildir; dolayısıyla boşluk hiçbir zaman anlamı değiştirmez. TOML 1.0.0 belirtimi küçük ve kararlıdır; bu bir özelliktir: yanlış hatırlanacak daha az şey vardır.

TOML’un öne çıkan yeteneği, ne JSON’un ne de düz YAML’ın temiz biçimde ele almadığı yerel tarih ve saat türleridir. Bunlardan dört tane vardır: saat dilimli ofsetli tarih-saat (1979-05-27T07:32:00Z), saat dilimsiz yerel tarih-saat, yerel tarih (1979-05-27, yalnızca bir takvim günü) ve yerel saat (07:32:00). Bu, bir dağıtım tarihinin yeniden ayrıştırmanız gereken bir karakter dizisi yerine gerçek bir tarih olarak kalması demektir.

TOML söz diziminin üç parçası işin çoğunu yapar. Bir [section] başlığı bir tablo açar; [tool.ruff] gibi noktalı bir başlık, fazladan girinti olmadan bir tabloyu bir diğerinin içine yerleştirir; ve satır içi tablo { version = "1.0", features = ["derive"] } küçük bir nesneyi tek bir satıra sığdırır. Tekrarlanan bölümler ikiye katlanmış bir başlık, yani tablo dizisini kullanır:

[[servers]]
name = "alpha"
ip = "10.0.0.1"

[[servers]]
name = "beta"
ip = "10.0.0.2"

Bu blok, servers anahtarı altında iki nesneden oluşan bir JSON dizisine dönüşür. Düz bir liste için güzel okunur ve çoğu araç yapılandırmasının ihtiyaç duyduğu şey tam olarak budur.

Zayıf yönleri gerçek ama dardır. TOML’da null türü yoktur; bu yüzden bulunmayan bir değer basitçe atlanmış bir anahtardır. Derin iç içe geçme ayrıntılı hâle gelir; çünkü tekrarlanan iç içe bir yapının her düzeyi tam [[path]] başlığını yineler ve bu, YAML karşılığından daha gürültülü büyür. Ayrıca TOML, JSON ya da YAML’dan daha genç ve daha az evrenseldir; bu nedenle onu her araç konuşmaz. TOML, çoğunlukla düz ve bir avuç etiketli bölümü olan yapılandırmalar için parlar ve bu, araç yapılandırmalarının ezici çoğunluğunu tanımlar.

Neden Rust ve Python için TOML?

TOML’un yükselişi, onu standart olarak benimseyen iki ekosistemi izler. Rust’ın paket yöneticisi Cargo, her crate için Cargo.toml kullanır; bu yüzden her Rust geliştiricisi ilk günden itibaren TOML okur ve yazar. Python bunu izledi: PEP 518, derleme gereksinimlerini bildirmek için pyproject.toml’u getirdi ve PEP 621, proje meta verilerini (ad, sürüm, bağımlılıklar ve [tool.*] bölümleri) aynı dosyada standartlaştırarak dağınık setup.py, setup.cfg ve araca özgü yapılandırmaların yerini aldı. Bu ikisinin ötesinde Hugo, Netlify, Poetry ve Foundry’nin tümü varsayılan olarak TOML kullanır. Ortak nokta, katkıda bulunanların elle düzenlediği ve zekice olmak yerine açık olmaktan yarar sağlayan araç yapılandırmasıdır.

Karşı karşıya — gerçekten canınızı yakan farklar

Özellik tabloları derli topludur. Hatalar değildir. Aşağıda gerçek sorunlara yol açan belirli farklar var; her biri, herhangi bir ayrıştırıcıdan geçirebileceğiniz küçük bir örnekle.

Yorumlar

JSON’da hiçbir yorum söz dizimi yoktur. TOML ve YAML’ın ikisi de satır sonuna kadar # kullanır.

# TOML: a leading comment
port = 5432  # and a trailing one

# YAML: identical comment style
port: 5432   # trailing comment

Katı JSON’a bir // ya da # yapıştırdığınız an ayrıştırma başarısız olur. Bu yüzeysel bir mesele değildir. Yorumsuz bakılan bir yapılandırma, yalnızca birilerinin kafasında yaşayan yazısız bilgi biriktirir.

Veri türleri ve tarihler

JSON’un türleri açık ama seyrektir ve tarih türü yoktur. TOML’un türleri açık ve zengindir. YAML’ınkiler örtüktür ve yukarıda anlatıldığı gibi ara sıra yanlıştır. Tarihler en belirgin ayrımdır. TOML dört türün de tamamını yerel olarak ifade eder:

odt = 1979-05-27T07:32:00Z   # offset date-time (has timezone)
ldt = 1979-05-27T07:32:00    # local date-time (no timezone)
ld  = 1979-05-27             # local date (a calendar day)
lt  = 07:32:00               # local time

Bu TOML’u JSON’a dönüştürün; her değer anlamını koruyan bir karakter dizisine dönüşür: bir yerel tarih, sahte bir gece yarısı zaman damgasına şişirilmek yerine "1979-05-27" olarak kalır. TOML’dan JSON’a dönüştürücümüz bu tarih türünü tam olarak korur; birçok toy dönüştürücü bunu yanlış yapar. YAML ise ayrıştırıcıya ve şema sürümüne bağlı olarak 1979-05-27’yi bir tarih olarak ele alabilir ya da almayabilir ve bu, üretim yapılandırmasında istemeyeceğiniz tam da o belirsizliktir.

İç içe geçme derinliği

Yapılandırmanız ne kadar derin iç içe geçerse, biçimler o kadar ayrışır. Küçük, Docker Compose tarzı bir ağaç alın:

services:
  web:
    build:
      context: .
      args:
        NODE_ENV: production
    ports:
      - "8080:8080"

YAML derinliği saf girintiyle ifade eder ve derli toplu kalır. Aynı yapı TOML’da her başlıkta tam yolu yazmanızı ve skaler değerleri alt tabloların önüne taşımanızı zorunlu kılar:

[services.web]
ports = ["8080:8080"]

[services.web.build]
context = "."

[services.web.build.args]
NODE_ENV = "production"

JSON ağacı iç içe süslü parantezlerle taşır; bu nettir ama noktalama işareti bakımından ağırdır. Sığ yapılandırmalarda üçü de benzer hissettirir; üç ya da dört düzeyi geçince YAML gözle görülür biçimde daha sade, TOML ise gözle görülür biçimde daha tekrarlı olur. Tek bu fark bile Kubernetes’in neden YAML’ı, Cargo’nun neden TOML’u seçtiğini açıklar.

Girintiye duyarlılık

Yalnızca YAML boşluğu önemser. JSON ve TOML’da istediğiniz gibi girinti verebilir ya da hiç vermeyebilirsiniz; anlam aynı kalır. YAML’da girinti yapının ta kendisidir ve sekmeler yasa dışıdır; bu yüzden bir sekme ekleyen bir düzenleyici ya da yanlış derinlikte yapıştırılmış bir blok belgeyi sessizce değiştirir veya yüklenmeyi reddeder. Bir boşluk fazla girintili bir liste öğesi, hiçbir hata vermeden kendini yanlış üst anahtara bağlayabilir ve dosya hâlâ makul göründüğü için bunu gözle yakalamak çıldırtıcı bir hatadır. Katkıda bulunanlarınız karışık düzenleyiciler ve ayarlar kullanıyorsa, bu YAML’ın çıkardığı, diğer ikisinin çıkarmadığı sürekli bir vergidir ve büyük herhangi bir YAML yapılandırmasında CI’da bir linter çalıştırmak için güçlü bir nedendir.

Çok satırlı karakter dizileri

JSON bir karakter dizisi içinde gerçek bir satır sonu tutamaz; onu \n olarak kaçırırsınız. YAML ve TOML’un ikisinde de gerçek çok satırlı karakter dizileri vardır.

{ "note": "line one\nline two" }

note: |
  line one
  line two

note = """
line one
line two
"""

YAML’ın | işareti satır sonlarını korur (bir > bloğu ise onları boşluklara katlar) ve TOML’un """ işareti benzer biçimde davranarak açılış tırnaklarının hemen ardından gelen satır sonunu kırpar. Gömülü betikler, SQL ya da yardım metni için tek başına bu bile biçime karar verdirebilir.

Sondaki virgüller ve katılık

JSON üçünün en katısıdır. Son dizi öğesinden sonra gelen bir sondaki virgül sözdizimi hatasıdır:

# valid TOML — the trailing comma is fine
ports = [
  8001,
  8002,
]

JSON’da 8002’den sonra gelen aynı sondaki virgül ayrıştırılamaz ve bu yüzden bir JSON dizisine bir satır eklemek çoğu zaman üstteki satırdaki virgülü de düzeltmek anlamına gelir. TOML sondaki virgüle izin verir, YAML’ın satır başına tire koyan liste söz dizimi ise soruyu tamamen es geçer. Katılık, makineler arası değişim için bir erdem, elle düzenleme için bir baş belasıdır; bu da öbür taraftan görülen aynı ödünleşmedir. Bu ayrıca JSON5 ve JSONC’nin özellikle JSON için ortadan kaldırmaya giriştiği sürtünmedir.

Büyük tam sayılar ve 2^53 tavanı

Üç biçim de 64 bitlik bir tam sayıyı metin olarak yazabilir. Sorun, o değer JavaScript’ten geçtiğinde başlar; çünkü tarayıcıdaki JSON sayıları IEEE-754 çift duyarlıklı sayılardır ve tam sayıları yalnızca 2^53 − 1’e (9007199254740991) kadar tam olarak temsil edebilir. Bir Snowflake ID’si ya da nanosaniyelik bir zaman damgası bundan büyüktür; bu yüzden JS tabanlı bir araçtan gidiş-dönüş, onu yuvarlar ve değeri bozar:

snowflake = 1420070400000000000   # exact in TOML text

{ "snowflake": "1420070400000000000" }

Her biçimde güvenilir çözüm, bu tür değerleri tırnaklı karakter dizileri olarak saklamaktır; böylece hiçbir sayısal ayrıştırıcı onlara dokunmaz. Bu, herhangi bir biçimin kusuru değildir; dönüştürmeyi yapan çalışma zamanının bir sınırlamasıdır. Dönüştürücülerimiz, bir tam sayı bu sınırı aştığında onu sessizce bozmak yerine sizi uyarır.

Nasıl seçilir — karar matrisi ve akış şeması

Hangi yapılandırma biçimini kullanacağınıza gerçekten karar verirken, soruları sırayla yürüyün ve ilk güçlü evette durun.

1. Dosya çoğunlukla programlar tarafından mı yazılıp okunuyor, ya da ekosistem zaten bir biçimi mi dayatıyor? Evetse JSON kullanın. Bir API payload’ı JSON’dur. package.json’ın yanındaki bir dosya JSON’dur. Araçlara karşı savaşmayın.
2. İnsanlar derin, iç içe yapılandırmayı bunu bekleyen bir yığın (Kubernetes, CI, Ansible) içinde her gün elle mi düzenliyor? Evetse YAML kullanın ve Norveç sorunundan kaçınmak için bir tırnaklama teamülü benimseyin.
3. Bir araç ya da uygulama yapılandırması mı; çoğunlukla düz, birkaç bölümlü, farklı beceri düzeyindeki katkıda bulunanların düzenlediği ve türlenmiş ile açığın kısa ve öze galip geldiği bir yapı mı? Evetse TOML kullanın.

İki yanıt berabere kalırsa, bu eksen haritasıyla eşitliği bozun:

Gereksinim	En uygun	Neden
Dosyada yorumlar	TOML veya YAML	JSON’da hiç yok
Yerel tarih/saat değerleri	TOML	Dört açık tarih türü
Çok derin iç içe geçme	YAML	Girinti derli toplu kalır
Sıfır boşluk sürprizi	JSON veya TOML	Girintiye duyarlı değil
Bir ekosistem dosyasına kilitli	JSON	package.json, tsconfig.json
İnsan düzenlemeleri, az bölüm	TOML	Açık türler, INI benzeri başlıklar
Makineler arası değişim	JSON	Evrensel, katı, hızlı
Tür çıkarımı asla tahmin etmemeli	JSON veya TOML	YAML örtük çıkarım yapar

Çoğu proje sonunda birden fazlasını kullanır. Bir depoda, hiç elle dokunulmayan bir JSON package.json, Python araçları için bir TOML pyproject.toml, .github içinde YAML iş akışları ve bu dilbilgilerinin hiçbirine uymayan, yerel sırlar için bir .env dosyası olabilir. Bu karışım normaldir; her dosya, onu düzenleyene uyan biçimde yaşar. .env katmanı kurulumunuzun bir parçasıysa, .env dosya biçimi rehberimiz bunun JSON yapılandırmasının yanında nereye oturduğunu ve ikisi arasında nasıl dönüştürüleceğini anlatır.

TOML, JSON ve YAML arasında dönüştürme

Bu biçimler arasında beklediğinizden daha sık dönüştürürsünüz. Bir CI işi, elle yazılmış bir pyproject.toml okur ve bir bağımlılık panosunu beslemek için onu JSON olarak ister. Bir taşıma işlemi, daha katı türleme için bir uygulamayı YAML yapılandırmasından TOML’a geçirir. İki dosyanın boşluğa duyarlı orijinallerini değil de JSON biçimini karşılaştırdığınızda bir kod incelemesi daha kolaydır. Her yönün, yapıştırmadan önce bilmeye değer bir tuzağı vardır.

TOML’dan JSON’a. Asıl risk tarihlerdir. 1979-05-27 gibi bir yerel tarih, bir saat ve saat dilimi uyduran gece yarısı UTC zaman damgasına dönüşmemeli, takvim tarihi olarak kalmalıdır. Yorumlar da düşer, çünkü JSON onları tutamaz. TOML’dan JSON’a dönüştürücü her tarih türünü sadakatle korur; böylece gidiş-dönüşler kayıpsız kalır.

JSON’dan TOML’a. TOML yapı konusunda daha katıdır; bu yüzden iki şey bir dönüştürmeyi engelleyebilir. En üst düzey bir nesne olmalıdır, çünkü bir TOML belgesi kökünde her zaman bir tablodur; çıplak bir dizi ya da skalerin gidecek yeri yoktur. Ayrıca TOML’da null yoktur; bu nedenle null bir nesne değeri düşer (hangi anahtarları içerdiğini listeleyen bir uyarıyla), bir dizi içindeki null’ın ise geçerli bir TOML gösterimi hiç yoktur. JSON’dan TOML’a dönüştürücü bozuk çıktı üretmek yerine her iki durumu da açıkça yüzeye çıkarır.

JSON ve YAML, her iki yön. Burada dikkat edilecek şey Norveç sorunudur: tırnaksız bir NO ya da 0755, sınırı aşarken tür değiştirebilir. JSON’dan YAML’a dönüştürücü ve YAML’dan JSON’a dönüştürücü tırnaklamayı halleder; böylece bir karakter dizisi karakter dizisi olarak kalır.

Herhangi bir dönüştürmeden sonra sonucu doğrulamaya değer. Çıktıyı JSON biçimlendiriciden geçirmek, onu işleme almadan ya da ileriye göndermeden önce JSON’un iyi biçimlendirilmiş ve tutarlı girintili olduğunu doğrular. Ve yapılandırma dosyaları sırlar (registry token’ları, veritabanı kimlik bilgileri, dağıtım anahtarları) taşıdığı için, bunların tümü tamamen tarayıcınızda çalışır: hiçbir şey yüklenmez; böylece özel bir registry token’ı olan bir Cargo.toml ya da kimlik bilgileri içeren bir değerler dosyası makinenizden hiç ayrılmaz.

SSS

TOML, YAML’dan daha mı iyi?

Hiçbiri evrensel olarak daha iyi değildir; TOML vs YAML seçimi yapıya iner. Açık türler ve girinti tuzaklarının olmayışı sayesinde TOML’da yanlış yapmak daha zordur; bu yüzden çoğunlukla düz araç yapılandırmalarında kazanır. YAML derin iç içe geçmeyi daha derli toplu ifade eder; bu yüzden Kubernetes gibi büyük, katmanlı altyapılarda kazanır.

Yapılandırma dosyaları için JSON mu YAML mı kullanmalıyım?

Bir insanın düzenlediği yapılandırma için YAML’ı tercih edin: yorumlara izin verir ve temiz okunur, JSON ise okunmaz. Programların üretip tükettiği yapılandırma için JSON’u tercih edin: katı, hızlı ve evrenseldir. Ayrım çizgisi, düzenlemeyi kimin yaptığıdır: insan mı, makine mi.

JSON neden yorumlara izin vermez?

JSON’un yaratıcısı Douglas Crockford, yorumları bilerek kaldırdı. İnsanların onlara ayrıştırma yönergeleri gömüp ayrıştırıcılar arasındaki birlikte çalışabilirliği bozmasından endişe etti. JSON biçimindeki bir dosyada yorumlara ihtiyacınız varsa, çekirdek yapıyı değiştirmeden onları geri ekleyen JSON5 ya da JSONC kullanın.

YAML’daki Norveç sorunu nedir?

YAML 1.1’in belirli tırnaksız sözcükleri mantıksal değer olarak ele almasıdır; böylece country: NO, "NO" karakter dizisi yerine false olur. YES, ON ve OFF de aynı şekilde davranır. Değeri tırnak içine almak bunu önler; tüm hikâye için yukarıda bağlantısı verilen özel rehbere bakın.

TOML yorumları destekler mi?

Evet. TOML, tıpkı YAML gibi, hem kendi satırında hem de bir değerin ardından yorumlar için # kullanır. TOML’u JSON’a dönüştürdüğünüzde yorumların kaybolduğunu unutmayın; çünkü JSON’da onları tutacak bir yorum söz dizimi yoktur.

TOML, JSON’un temsil edebildiği her şeyi temsil edebilir mi?

Neredeyse. JSON vs TOML açığı küçük ama gerçektir: TOML’da null türü yoktur; bu yüzden JSON null’ları dönüştürmede düşer ya da reddedilir ve bir TOML belgesi en üst düzeyde bir tablo olmalıdır; dolayısıyla çıplak bir JSON dizisi ya da skaleri, önce bir anahtar altına sarılmadan dönüştürülemez.

YAML, JSON’un bir üst kümesi mi?

YAML 1.2’den beri evet: geçerli herhangi bir JSON belgesi aynı zamanda geçerli YAML’dır; bu yüzden bir YAML ayrıştırıcısı JSON’u doğrudan okuyabilir. Yararlı bir gerçektir ama bunu bir güvenlik sınırı olarak kullanmayın; çünkü YAML ayrıştırıcıları JSON’da olmayan özellikler (çapalar gibi) ekler.

Hangi yapılandırma biçimi en hızlı ayrıştırılır?

JSON genellikle en hızlısıdır ve her dilde en olgun, en iyilenmiş ayrıştırıcılarla gelir. YAML, büyük belirtimi ve örtük türlemesi nedeniyle ayrıştırması en yavaş ve en karmaşık olanıdır. TOML ortada durur; hızda YAML’dan çok JSON’a yakındır.