İkisi de yapılandırılmış veri taşır ve birbirine çevrilebilir. Ama farklı amaçlarla tasarlandılar: JSON makineler arası veri alışverişi için, YAML insanların yazıp okuyacağı yapılandırma dosyaları için.
JSON: katı ve öngörülebilir
JSON’ın söz dizimi küçüktür: nesneler, diziler, dizeler, sayılar, mantıksal değerler ve null. Fazlası yoktur.
Bu katılık bir özelliktir. Ayrıştırıcılar arasında davranış farkı neredeyse yoktur; bir JSON dosyası her yerde aynı okunur.
Bedeli okunabilirliktir: yorum satırı yoktur, tırnak zorunludur, son ögeden sonra virgül konulamaz ve derin yapılar süslü parantez yığınına dönüşür.
Bu yüzden JSON asıl olarak API yanıtlarında ve makine ürettiği çıktılarda kullanılır — insanın elle yazacağı yerlerde değil. API tarafındaki kullanımı API ve REST nedir yazısında.
YAML: okunabilir ama esnek
YAML girintiyle çalışır, tırnak çoğu zaman gerekmez ve yorum yazılabilir. Aynı yapı JSON’a göre belirgin biçimde kısa ve okunur görünür.
Kubernetes manifestleri, Compose dosyaları, CI boru hattı tanımları ve Ansible playbook’ları bu yüzden YAML’dır.
Ama esneklik bedelsiz değildir. YAML’ın söz dizimi geniştir ve ayrıştırıcılar arasında davranış farkları vardır. Aşağıdaki tuzakların hepsi bu genişlikten doğar.
Girinti: sekme kabul edilmez
YAML girintiyi yapının kendisi olarak kullanır ve sekme karakterini kabul etmez. Yalnızca boşluk geçerlidir.
Editörünüz sekme ekliyorsa dosya, gözle bakıldığında doğru görünür ama ayrıştırıcı hata verir. Hata mesajı da çoğu zaman gerçek satırı göstermez.
İkinci girinti tuzağı, aynı düzeydeki ögelerin tutarlı girintilenmesi zorunluluğudur. Bir satırda iki boşluk, diğerinde üç kullanmak sessiz bir yapı değişikliği üretebilir.
Örtük tür dönüşümü
En sinsi tuzak budur. YAML, tırnaksız yazılan değerlerin türünü tahmin eder.
5432 sayıya dönüşür. true mantıksal değere. 2026-08-25 tarihe. Bunlar genelde istenen davranıştır.
Sorun beklenmedik dönüşümlerde çıkar. Eski YAML sürümünde yes, no, on, off de mantıksal değer sayılır. Bir yapılandırmada secenek: no yazmak, dize değil false üretir.
Bunun en bilinen örneği Norveç sorunudur: ülke kodu listesine yazılan NO, ülke kodu değil false olarak okunur.
Çözüm basittir: dize olması gereken her değeri tırnak içine alın. Özellikle sürüm numaraları, ülke kodları ve on/off gibi kelimeler için.
Bu ve benzeri sorunları taramak için YAML doğrulayıcı aracı var.
Sayı gibi görünen dizeler
08 yazmak bazı ayrıştırıcılarda sekizlik sayı denemesine yol açar ve 8 geçersiz sekizlik basamak olduğu için hata verir ya da beklenmedik değer üretir.
Sürüm numaraları da benzer sorun çıkarır: 1.10 bir sayıdır ve 1.1 olarak yorumlanabilir — sürüm anlamı kaybolur.
Aynı şekilde 1:30 gibi değerler bazı sürümlerde altmışlık sayı olarak okunur.
Kural yine aynıdır: anlamı metin olan her şeyi tırnakla.
Aynı anahtarın iki kez yazılması
Bir YAML haritasında aynı anahtar iki kez geçerse çoğu ayrıştırıcı hata vermez; sonuncuyu alır ve öncekini sessizce atar.
Uzun dosyalarda bu kolayca olur — özellikle kopyala-yapıştır ile bölüm çoğaltıldığında. Belirti nettir: yaptığınız ayar uygulanmıyordur, çünkü aşağıda aynı anahtar tekrar tanımlanmıştır.
Benzer bir davranış SSH yapılandırmasında da vardır ama ters yönde çalışır — orada ilk değer kazanır. Ayrıntısı SSH sertleştirme aracında.
Çok satırlı metin
YAML’da uzun metin iki işaretle yazılır ve aralarındaki fark sık karıştırılır.
| satır sonlarını korur — betikler ve çok satırlı yapılandırma blokları için doğru olan budur.
> satır sonlarını boşluğa çevirir — uzun bir paragrafı kaynakta bölmek için kullanılır.
Bir kabuk betiğini > ile yazmak, tüm satırları tek satıra birleştirir ve betik çalışmaz. Bu, CI tanımlarında sık rastlanan bir hatadır.
Hangisini seçmeli
Kural pratikte basittir.
İnsan yazacaksa YAML. Yapılandırma dosyaları, manifestler, boru hattı tanımları.
Makine üretip makine okuyacaksa JSON. API yanıtları, günlük kayıtları, veri alışverişi.
JSON aynı zamanda geçerli bir YAML’dır — yani bir YAML ayrıştırıcısı JSON’u da okur. Tersi doğru değildir.
Bir JSON örneğinden şema ya da tür tanımı çıkarmak için JSON şema üreteci, biçimlendirme ve hata bulma için JSON biçimlendirici aracı var.
Şema doğrulaması
Her iki biçimde de asıl güvence şemadır: hangi alanların zorunlu olduğu, türlerinin ne olması gerektiği.
Şema doğrulaması boru hattına konduğunda, bozuk bir yapılandırma üretime çıkmadan yakalanır. Kubernetes manifestleri için bu yerleşiktir; kendi dosyalarınız için ayrıca kurulması gerekir.
Manifest yazarken atlanan alanları görmek için Kubernetes manifest üreteci aracına bakabilirsiniz.
Kısaca
JSON katıdır ve her yerde aynı davranır; YAML okunurdur ama tür tahmini yapar.
YAML yazarken üç kural sorunların çoğunu keser: sekme kullanmayın, dize olması gereken her şeyi tırnaklayın, çok satırlı bloklarda | ile > farkını bilin.