İki biçim, iki farklı yaklaşım
XML (Extensible Markup Language), W3C'nin XML 1.0 önerisiyle tanımlanan, açılış ve kapanış etiketleriyle çalışan bir işaretleme dilidir. Türkiye'de en sık e-Fatura ve e-Arşiv belgelerinin UBL-TR yapısında karşımıza çıkar; SOAP servisleri, RSS beslemeleri, Maven'ın pom.xml dosyası ve .NET proje dosyaları da XML'dir. Ad alanları (namespace), öznitelikler ve XSD şemalarıyla güçlü bir doğrulama altyapısı sunar, ama ayrıntılıdır.
YAML ise yapıyı girintiyle kurar, parantez ve etiket kullanmaz, # ile yorum yazmaya izin verir. Docker Compose, Kubernetes manifestleri, GitHub Actions iş akışları ve Ansible görevleri YAML ile yazılır. Güncel belirtim YAML 1.2.2'dir ve 1 Ekim 2021 tarihlidir. Belirtime göre 2009'da yayımlanan 1.2 sürümünün ana hedefi YAML'ı JSON'un katı bir üst kümesi yapmaktı.
İkisi de ağaç yapısında veri taşır, ancak modelleri aynı değildir. XML'de bir bilgi öznitelik olarak da alt öğe olarak da yazılabilir ve metinle etiketler iç içe geçebilir. YAML'ın modeli ise JSON'a yakındır: eşlemeler, listeler ve tekil değerler.
XML'de iyi biçimlilik ve sık hatalar
Bir XML belgesinin 'iyi biçimli' (well-formed) sayılması için birkaç kurala uyması gerekir: tek bir kök öğe olmalı, açılan her etiket kapanmalı, etiketler doğru sırayla iç içe geçmeli, öznitelik değerleri tırnak içinde yazılmalıdır. Etiket adları büyük-küçük harfe duyarlıdır; <Fatura> ile </fatura> eşleşmez. Metin içindeki & ve < karakterleri & ve < olarak yazılmalıdır. Elle düzenlenen dosyalarda en sık görülen hata, 'Yılmaz & Oğulları' gibi bir firma adında kaçışlanmamış & işaretidir.
İyi biçimli olmak 'geçerli' (valid) olmakla aynı şey değildir. Geçerlilik, belgenin bir DTD veya XSD şemasına uymasıdır. Örneğin e-Fatura belgeleri UBL-TR şemasına ve GİB'in ek kurallarına uymak zorundadır; iyi biçimli ama şemaya uymayan bir fatura reddedilebilir. XML görüntüleyici yalnızca iyi biçimliliği tarayıcının kendi XML ayrıştırıcısıyla denetler; şema doğrulaması yapmaz, elektronik imzanın geçerliliği hakkında da bir sonuç üretmez.
Kodlama sorunları da sık görülür. Dosyanın ilk satırındaki bildirim başka, gerçek kodlaması başka olduğunda Türkçe karakterler bozulur. Araç dosyayı önce UTF-8 olarak okur, çok sayıda bozuk karakter görürse Windows-1254'e geçer; bayt sırası işareti (BOM) varsa ona uyar.
e-Fatura gibi belgelerde sık görülen cbc: ve cac: önekleri ad alanlarını gösterir. Önek yalnızca bir kısaltmadır; asıl kimlik, belgenin başındaki xmlns bildirimindeki adrestir. Aynı ad alanına farklı öneklerle başvuran iki belge teknik olarak eşdeğerdir. Biçimlendirilmiş görünümde yorumlar ve CDATA blokları korunur.
YAML'de girinti, sekme ve tür tuzakları
YAML 1.2.2 belirtimi sekme karakterinin girintide kullanılmasını açıkça yasaklar, çünkü farklı sistemler sekmeyi farklı genişlikte yorumlar. Editörünüz sekme ekliyorsa görüntüleyicide 'tab characters must not be used in indentation' benzeri bir hata görürsünüz. Aynı seviyedeki öğelerin girintisi bir boşluk bile kaydığında 'bad indentation' hatası alınır ya da daha kötüsü, dosya hata vermeden farklı bir yapıya dönüşür.
Tür tuzakları sürüm farkından doğar. YAML 1.1'in boolean tanımı y, yes, no, on, off gibi değerleri de true/false kabul eder; ülke kodu NO'nun false'a dönüşmesi bu yüzden bilinen bir sorundur. YAML 1.2'nin çekirdek şemasında yalnızca true ve false boolean'dır. Sitedeki görüntüleyici YAML 1.2 kurallarını izleyen js-yaml kütüphanesini kullanır; yes, on ve NO değerleri burada metin olarak görünür. Dosyanızı okuyan program YAML 1.1 tabanlıysa aynı değer boolean olabilir. En sağlam çözüm bu tür değerleri tırnak içine almaktır.
Sayılar da şaşırtabilir. 3.10 biçimindeki bir sürüm numarası ondalık sayı olarak okunur ve 3.1'e dönüşür; 010 değeri YAML 1.2'de on, bazı YAML 1.1 ayrıştırıcılarında sekizlik tabanda sekiz olarak yorumlanır. Aynı eşlemede bir anahtarın iki kez yazılması ise görüntüleyicide 'duplicated mapping key' hatası verir; belirtim anahtarların benzersiz olmasını ister.
Çok satırlı metinlerde | ve > işaretleri farklı davranır. | satır sonlarını olduğu gibi korur ve betik ya da sertifika gibi içerikler için uygundur. > ise satırları tek bir paragrafta boşlukla birleştirir. Bir CI dosyasındaki komutların beklenmedik biçimde tek satıra dönüşmesinin nedeni çoğu zaman bu iki işaretin karıştırılmasıdır; ağaç görünümünde değerin gerçekte nasıl okunduğunu görebilirsiniz. Satır sonundaki fazladan boşluklar ve dosyanın son satırının boş olup olmaması da bu bloklarda sonucu değiştirebilir; |- ve |+ biçimleri son satır sonunun atılıp atılmayacağını açıkça belirler.
Görüntüleyiciler ne yapar, ne yapmaz?
XML görüntüleyici, belge iyi biçimliyse her öğeyi 2 boşluk girintiyle ayrı satıra yerleştirip satır numaralı gösterir. Belge bozuksa ayrıştırıcının ilk hata satırı sarı bir uyarıda yazar ve içerik ham hâliyle açılır. 2 milyon karakteri aşan dosyalar tarayıcıyı yormamak için biçimlendirilmeden gösterilir. Biçimlendirme metin düğümlerinin başındaki ve sonundaki boşlukları kırptığından ekrandaki görünüm okumak içindir. İndir, düzenleme yapmadıysanız dosyanın orijinal metnini verir.
YAML görüntüleyici dosyayı ayrıştırıp üstte yeşil 'Geçerli YAML' ya da kırmızı 'Geçersiz YAML' etiketi gösterir. Hata mesajında satır ve sütun bilgisi yer alır. Geçerli dosyalar JSON görüntüleyicinin ağaç yapısında açılır, 'Ham YAML' düğmesi özgün metne döner. Ağaç görünümü veriyi gösterdiği için yorumlar orada yer almaz; &anchor ve *alias ile tekrar kullanılan bloklar ise açılmış hâlde görünür.
Bilinmesi gereken önemli bir sınır var: araç tek belgeli YAML bekler. Kubernetes dosyalarında sık görülen, belgeleri --- satırlarıyla ayıran çok belgeli dosyalar 'expected a single document' hatasıyla geçersiz görünür. Bu durumda dosya hatalı değildir; belgeleri ayrı dosyalara bölüp tek tek açabilirsiniz. Araç ayrıca Kubernetes veya Compose şemasını bilmez, yanlış yazılmış bir alan adını hata olarak göstermez.
Pratik bir çalışma sırası önerelim: önce dosyanın geçerli olup olmadığına bakın, sonra ağaç görünümünde beklediğiniz anahtarların doğru seviyede durduğunu kontrol edin, en son değerlerin türüne bakın. Girinti hatası çoğu zaman bir anahtarın bir üst ya da alt seviyeye kaymasıyla kendini gösterir ve bu kayma ağaçta metinden çok daha kolay fark edilir.
Bu rehberdeki araçlar
Anlatılan işlemleri hemen tarayıcınızda, dosyanız sunucuya yüklenmeden yapın:
Sık sorulan sorular
Kubernetes manifestim çalışıyor ama görüntüleyici 'Geçersiz YAML' diyor. Neden?
Dosyada --- ile ayrılmış birden fazla belge varsa araç bunu tek belge olarak ayrıştıramaz. Belgeleri ayrı dosyalara bölerek her birini açabilirsiniz.
YAML'deki yorumlarım neden ağaç görünümünde yok?
Ağaç görünümü dosyanın veri modelini gösterir; yorumlar veri değildir. Yorumlarla birlikte okumak için 'Ham YAML' görünümüne geçin.
XML görüntüleyici e-Faturanın GİB kurallarına uyduğunu denetler mi?
Hayır. Yalnızca XML'in iyi biçimli olup olmadığına bakar. Fatura alanlarını okunur düzende görmek için sitedeki e-Fatura XML görüntüleyici daha uygundur; resmî geçerlilik için GİB sistemleri esastır.
Sürüm numarası 3.10 neden 3.1 olarak görünüyor?
Tırnaksız 3.10 değeri YAML'da ondalık sayı olarak okunur ve sondaki sıfır düşer. Değeri "3.10" biçiminde tırnak içine alırsanız metin olarak korunur.