Yapılandırılmış Veri (JSON-LD) Rehberi ve Doğrulama

Bir sayfanın kaynak koduna baktığınızda gördüğünüz bir veri bloğu, sitenizin arama motorlarına kendini nasıl anlattığını gösterir. Peki bu bloğu kim yazıyor, neyi içermeli ve hata yaptığınızda ne olur? Bu rehber, yapılandırılmış veri konusunu üç yaygın tür üzerinden pratik biçimde ele alır: Organization, BreadcrumbList ve Article.

Amaç şablon başına tek bir doğru kaynak kurmak, işaretlemeyi sayfada görünen içerikle eşleştirmek ve üç aracı sırayla kullanarak doğrulamaktır. Hiçbir adım zengin sonuç vaadi taşımaz; yalnız belgelenmiş gereksinimleri uygulamayı anlatır. Sondaki tek kontrol tablosunu kendi şablonlarınıza uyarlayabilirsiniz.

Yapılandırılmış Veri ve JSON-LD Nedir

Yapılandırılmış veri, bir sayfadaki bilgiyi makinelerin tutarlı biçimde okuyabileceği bir sözlükle etiketlemektir. Sayfa "bu bir makale, yazarı şu, yayın tarihi bu" der; arama motoru bunu metinden tahmin etmek zorunda kalmaz. Kullanılan sözlük çoğunlukla schema.org'dur ve Google'ın yapılandırılmış veriye giriş belgesi (yeni sekmede açılır) bu verinin hangi sonuç görünümlerine uygunluk sağlayabileceğini anlatır.

JSON-LD, bu etiketleri sayfanın içine ayrı bir veri bloğu olarak koyan biçimdir. HTML etiketlerinin arasına özellik eklemek yerine tek bir yerde toplanır; bu yüzden şablondan üretmek ve bakımını yapmak kolaydır. Google, siteniz uygunsa JSON-LD'yi önerir. Microdata ve RDFa da desteklenir ve işaretleme geçerli olduğu sürece üçü Google için eşit kabul edilir. Yani biçim seçimi bir sıralama meselesi değil, bakım meselesidir.

Kapsamı baştan netleştirin. Bu yazı genel yaklaşımı ve üç yaygın türü anlatır. Makale ve SSS işaretlemesinin ayrıntısı ayrı bir yazıda, ürün işaretlemesi ve breadcrumb mimarisi de kendi yazılarında ele alınır; burada onları yeniden anlatmayacağız, yalnız bağlayacağız. Yapılandırılmış veri bir sıralama düğmesi değildir. Belgeler "uygunluk" der, kesin sonuç vaat etmez; biz de bu dili koruyoruz.

• Ne yapar: sayfanın türünü ve temel özelliklerini makineye açıkça bildirir.
• Ne yapmaz: sıralamayı tek başına yükseltmez, zengin sonuç sözü vermez.
• Kime lazım: marka sitesi, blog, kategori ve ürün şablonu yöneten herkes.

JSON-LD'nin Yapısı: Context, Type ve Property

Bir JSON-LD bloğunun iskeleti üç kavrama dayanır. İlki bağlamdır: bloğa hangi sözlüğün kullanıldığını söyleyen alan, yani @context. Schema.org kullanıyorsanız bu alan o sözlüğün adresini gösterir. İkincisi tür: @type, sayfadaki varlığın ne olduğunu belirtir; Organization, BreadcrumbList veya Article gibi. Üçüncüsü özelliklerdir: türe ait ad, adres, tarih, yazar gibi alanlar.

Özellikler değer olarak düz metin, sayı ya da başka bir iç içe varlık taşıyabilir. Örneğin bir Article'ın yazarı kendi başına bir Person varlığıdır; adı ve adresi o iç varlığın özellikleridir. Bu iç içe yapı, aynı bilginin tek yerde tanımlanıp başka yerden başvurulmasını sağlar ve hata riskini düşürür.

Okurken şu sırayı izleyin: önce bloğun türünü bulun, sonra o türün Google belgesindeki özellik listesine bakın, sonra sizin sayfanızdaki karşılığını eşleştirin. Dikkat edilecek bir nokta: bazı türlerin zorunlu özelliği vardır, bazılarının yoktur. Organization ve Article belgelerinde zorunlu özellik bulunmaz, hepsi önerilendir. BreadcrumbList'te ise liste ve her öğenin konumu gibi alanlar gereklidir. Belgeyi okumadan alan uydurmayın; belgede olmayan bir özelliği "olmalı" diye eklemek hiçbir şey kazandırmaz.

Bu yazıda kod örneği vermiyoruz; yapıyı liste ve tablo ile anlatıyoruz. Gerçek bloğu şablonunuzda yazarken Google belgesindeki örnekleri ve schema.org tür sayfalarını referans alın.

1. Sayfa için hangi türün uygun olduğuna karar verin.
2. Google belgesindeki zorunlu ve önerilen özellikleri not edin.
3. Her özelliğin sayfada görünen bir karşılığı olup olmadığını işaretleyin.
4. Karşılığı olmayan özelliği bloğa eklemeyin.

Organization İşaretlemesi: Marka Bilgisini Netleştirmek

Organization işaretlemesi, sitenin arkasındaki kurumu tanıtır: adı, adres ve iletişim bilgisi, logosu ve resmi profilleri. Google'ın Organization belgesinde zorunlu özellik yoktur; ad, alternatif ad, açıklama, URL, logo, sameAs, adres ve iletişim noktası gibi alanlar önerilen özellikler olarak sıralanır. Önemli olan dolu olması değil, doğru ve görünen bilgiyle tutarlı olmasıdır.

Yerleşim konusunda belge nettir: bu bilgiyi ana sayfaya veya hakkımızda gibi tek bir kurumsal sayfaya koymanız yeterlidir, her sayfaya eklemeniz gerekmez. Mümkünse en özel schema.org alt türünü seçin; çevrimiçi bir mağaza için genel bir tür yerine ona uygun alt tür gibi. Yerel bir işletme ise ilgili yerel işletme türleri tercih edilir.

Logo için belgede bazı koşullar vardır: en az 112x112 piksel, taranabilir ve indekslenebilir bir adres, Google Görseller'in desteklediği bir biçim ve beyaz zeminde düzgün görünmesi. Bu koşulları sayfanızdaki gerçek logoya karşı kontrol edin, başka bir görsel göstermeyin.

Marka bilgisinin netliği, Google'ın sizi bir varlık olarak anlamasının yalnız bir parçasıdır. Markanın hangi konularla ilişkilendiğini ve tutarlı bir adlandırmayı nasıl kuracağınızı varlık tabanlı SEO rehberinde bulabilirsiniz. Orada markanın tüm kanallardaki adı ve tanımı birbirini tamamlıyor olmalıdır; Organization bloğu bu çalışmanın makine tarafıdır.

• Resmi adı, görünen marka adıyla aynı yazın.
• Adres ve telefonu yalnız sayfada gerçekten yayımladığınız biçimde girin.
• sameAs alanına yalnız markanın sahibi olduğu profilleri koyun.

BreadcrumbList: Gezinti Yolunu Tanımlamak

BreadcrumbList, bir sayfanın site hiyerarşisindeki yolunu tanımlar. Google'ın belgesine göre liste en az iki öğe taşır; her öğe için konum bir tam sayıdır ve ilk öğe 1'dir. Öğenin görünen adı ve adresi de belirtilir. Son öğede adres atlanabilir; bu durumda Google içeren sayfanın adresini kullanır. Ana alan adının ve içinde bulunulan sayfanın ayrı bir öğe olması gerekmez.

Belgedeki kritik ilke, breadcrumb'ın tipik bir kullanıcı yoluna dayanmasıdır; URL yapısını olduğu gibi kopyalamak zorunlu değildir. Bir ürün hem iki kategoride hem de bir kampanyada görünüyorsa, kullanıcıya gösterdiğiniz yol hangisiyse işaretlemede de o olmalıdır. Sayfadaki görünür gezinti ile işaretleme birbirini yalanlamamalıdır.

Gezinti yolunu bir mimari karar olarak nasıl kuracağınızı, kategori derinliğini ve iç bağlantıyı site mimarisi ve breadcrumb yazısında ele aldık. Bu yazıda yalnız işaretleme tarafı var: yol önce tasarlanır, sonra işaretlenir; sıra tersine çevrilmez.

Kontrol edilecek noktalar

• Öğe sayısı iki veya daha fazla mı?
• Konum numaraları 1'den başlayıp sırayla artıyor mu?
• Görünür breadcrumb ile işaretlenen yol aynı mı?
• Eski data-vocabulary.org işaretlemesi kalmadı mı? Google belgesine göre bu eski işaretleme zengin sonuç için uygun değildir.

Article İşaretlemesi: Yazı, Yazar ve Tarih Bilgisi

Article işaretlemesi bir haber, blog yazısı veya makaleyi tanımlar. Google'ın Article belgesinde zorunlu özellik yoktur; uygulananları eklemeniz istenir. Belgelenen önerilen özellikler şunlardır: yazar, ilk yayın tarihi, son değişiklik tarihi, başlık ve görsel.

Yazar için belgenin ince ayrıntıları önemlidir. Sayfada görünen her yazarı ayrı bir yazar girdisi olarak ekleyin; birden fazla adı tek alanda birleştirmeyin. Kişi için Person, kurum için Organization türünü kullanın. Yazar adı alanına yalnız ad girin; unvan, "tarafından yazıldı" gibi ifadeler veya yayıncı adı orada yer almasın. Yazarın kimliğini tanıtan bir adres de eklenir.

Tarihler ISO 8601 biçimindedir ve saat dilimi bilgisi eklemeniz önerilir; eklemezseniz Google, Googlebot'un kullandığı saat dilimini varsayar. Başlık kısa olmalıdır, çünkü uzun başlıklar bazı cihazlarda kesilebilir. Görsel, makaleyi temsil eden ve taranabilir bir adresten sunulan bir görsel olmalıdır; logo ya da altyazı değildir.

Makale türüne ve FAQ işaretlemesinin durumuna özel derinlik için Article ve FAQ işaretlemesi yazısına bakın. Orada anlatılanı tekrar etmiyoruz; bu bölümün amacı, genel bir şablon için Article'ın hangi alanlarının güvenle doldurulabileceğini göstermektir.

İşaretlemenin Sayfada Görünen İçerikle Eşleşmesi

Google'ın yapılandırılmış veri belgesindeki en sık yanlış anlaşılan kural şudur: sayfada kullanıcıya görünmeyen bilgiyi, doğru olsa bile işaretlemeyin. İşaretleme, görünen içeriğin makine okunur özetidir; görünmeyen bir iddiayı sisteme taşımanın aracı değildir.

Pratikte bu, her özelliği sayfadaki bir parçayla eşlemek demektir. Makalenin yazarı sayfada adıyla görünüyorsa işaretlemede olabilir. Yayın tarihi sayfada yoksa, tarihi yalnız işaretlemede göstermek eşleşmeyi bozar. Aynı şekilde, sayfa üzerinde hiç bulunmayan bir telefon numarasını Organization bloğuna eklemek de uygunsuzdur.

Yazarlık bilgisinde bu eşleşme özellikle önemlidir. Yazar bloğu ile sayfadaki yazar kutusu aynı kişiyi aynı adla göstermelidir. Güvenilir bir yazar sayfasının nasıl kurulacağını, yazar kimliğini hangi kanıtlarla destekleyeceğinizi yazar sayfası ve E-E-A-T yazısında bulabilirsiniz. Orada kurduğunuz yapı burada işaretlenir; işaretleme güvenilirliği yaratmaz, yalnızca var olanı bildirir.

Eşleştirme sorusunu şu sırayla sorun: bu özellik sayfada bir kullanıcıya görünüyor mu, görünüyorsa aynı değerle mi? Cevap hayırsa özelliği bloktan çıkarın ya da önce sayfayı düzeltin. Kurgu bir örnek: bir blog şablonunda yazar adı başlığın altında görünüyor, yayın tarihi ise yalnız kaynak kodda var. Doğru çözüm tarihi sayfaya görünür biçimde eklemek ya da işaretlemeden çıkarmaktır; üçüncü bir yol yoktur.

• Görünür ve eşleşen: işaretlenir.
• Görünür ama değeri farklı: önce tutarlı hale getirilir.
• Hiç görünmeyen: işaretlenmez.

JSON-LD'yi Sayfaya Eklemek: Elle, Şablon ve Eklenti

JSON-LD'yi sayfaya eklemenin üç yolu vardır ve her birinin bakım maliyeti farklıdır. Elle yazım, tek bir sayfa için hızlıdır ama çoğaldığında tutarsızlık doğurur. Şablon üzerinden üretim, bilgiyi sistemin tek kaynağından alır: kurum bilgisi ayar sayfasından, yazar ve tarih içerik kaydından, breadcrumb ise gezinti verisinden gelir. Eklenti ise kurulum süresini kısaltır ama çıktısını sizin doğrulamanız gerekir.

Şablon yaklaşımında temel ilke "tek kaynak"tır. Aynı kurum adı üç yerde elle yazılırsa, biri değiştiğinde diğerleri eskir. Bunun yerine sayfanın görünen verisini üreten aynı değişkenden işaretlemeyi de üretin. Böylece görünen içerikle işaretleme otomatik olarak aynı kalır.

Yapılandırılmış verinin sayfa türüne göre nasıl dağıtılacağı, özellikle e-ticarette farklı bir iştir. Ürün sayfaları için özellik seçimi ve fiyat bilgisi gibi konular ürün işaretlemesi rehberinde ayrıca anlatılır; bu yazıdaki iş akışı oraya da uyarlanabilir.

Hangi yöntemi ne zaman seçmeli

• Tek sayfalık, nadir değişen içerik: elle yazım ve sonrasında doğrulama.
• Çok sayıda benzer sayfa: şablon üretimi, tek kaynak.
• Hızlı başlangıç gerekiyor: eklenti, ardından çıktıyı sayfa başına kontrol.

Hangi yolu seçerseniz seçin, eklenen bloğun sayfanın kaynağında gerçekten göründüğünü kontrol edin. Bazı kurulumlarda işaretleme ancak betik çalışınca oluşur; bu durumda tarayıcının oluşturduğu sürümü de test edin.

Doğrulama: Zengin Sonuçlar Testi, Schema Doğrulayıcı ve Search Console

Doğrulama üç araçla, belirli sırayla yapılır. Birincisi Zengin Sonuçlar Testi'dir: Google'ın belgesi onu yapılandırılmış veriyi doğrulamak için kolay ve yararlı bir araç olarak tanıtır. Bir URL ya da kod parçası verirsiniz, araç algıladığı türleri ve hataları gösterir. İkincisi Schema Markup Validator (yeni sekmede açılır)'dır; bu araç Google'ın zengin sonuç gereksinimlerinden bağımsız olarak schema.org söz dizimine göre bakar. İkisi aynı şeyi ölçmez: biri Google görünümüne uygunluğu, diğeri sözlüğe uyumu denetler.

Üçüncü araç Search Console'dur. URL Denetleme aracı, Google'ın sayfayı görüp yapılandırılmış veriyi bulduğunu teyit eder. Yayından sonra ilgili durum raporları geçersiz öğeleri toplu gösterir. BreadcrumbList belgesi bu sırayı açıkça önerir: önce testle kritik hataları düzeltin, yayından sonra URL Denetleme ile sayfanın robots.txt, noindex veya giriş gereksinimiyle engellenmediğini görün, site haritası gönderin ve indekslendikten sonra raporu izleyin.

Raporu okumayı ve sayfa bazında düşüşleri yorumlamayı Search Console performans raporu yazısında ayrıntılı bulabilirsiniz. Dikkat: Test araçlarının yeşil görünmesi sıralama ya da zengin sonuç sözü değildir; yalnız teknik geçerliliği gösterir.

1. Taslakta Zengin Sonuçlar Testi ile kritik hataları temizleyin.
2. Schema Markup Validator ile söz dizimini ayrıca kontrol edin.
3. Yayından sonra URL Denetleme ile Google'ın görünümünü doğrulayın.
4. Durum raporunu düzenli aralıklarla izleyin.

Sık Yapılan Hatalar ve Spam Sayılabilecek Kullanımlar

En yaygın hata, işaretlemeyi sayfadan koparmaktır: sayfada olmayan puan, görünmeyen SSS ya da gerçekte bulunmayan bir adres. Bunlar yalnız teknik değil, aldatıcı sayılabilecek kullanımlardır. Google'ın belgeleri yönergelerin dışında görülen işaretlemenin manuel işleme yol açabileceğini söylediğinden, "nasıl olsa işe yarar" düşüncesiyle yapılan eklemeler gereksiz bir risk taşır.

İkinci grup hata teknik niteliktedir: zorunlu bir özelliğin eksik olması, konum numaralarının bozuk sıralanması, tarihin geçersiz biçimde yazılması, logo adresinin taranamaması, aynı sayfada çakışan iki farklı Organization bloğu. Bunlar test araçlarında yakalanır ve kolayca düzeltilir.

Üçüncü grup sürdürme hatalarıdır: şablon değişti, sayfadaki alan kaldırıldı ama işaretleme eski değeri taşımaya devam ediyor. Bu tür tutarsızlıklar aylar sonra fark edilir.

Spam sayılabilecek kullanımlar

• Sayfada görünmeyen müşteri puanı ya da yorum işaretlemek.
• Başka bir kuruma ait bilgiyi kendi Organization bloğunda göstermek.
• Sayfa içeriğiyle ilgisiz bir tür seçmek.
• Her sayfaya aynı bloğu gerekçesiz kopyalamak.

Hata bulduğunuzda önce nedenini sorun: şablon mu, veri mi, eklenti mi? Kaynağı düzeltmeden tek tek sayfaları elle onarmak aynı hatayı yeniden üretir.

Bakım: Şablon Değişikliğinde Yeniden Doğrulama

Yapılandırılmış veri bir kez yazılıp unutulacak bir iş değildir. Şablon her değiştiğinde, ayrı bir yayın notu gibi, işaretlemenin de yeniden kontrol edilmesi gerekir. Tema güncellemesi, eklenti sürümü, çok dilli yapıya geçiş, gezinti yeniden düzenlemesi, hepsi bloğun çıktısını değiştirebilir.

Basit bir bakım rutini kurun. Her şablon değişikliğinde temsilci bir sayfa türü, yani bir makale, bir kategori ve ana sayfa, doğrulayıcıya verilir. Fark varsa yayından önce düzeltilir. Daha geniş teknik denetimin bir parçası olarak da işaretleme kontrolünü eklemek mantıklıdır; bunun için teknik SEO denetimi kontrol listesi ve önceliklendirme yazısını çatı olarak kullanabilirsiniz.

Çok dilli sitelerde her dil sürümü kendi görünen metnine uygun olmalıdır. Türkçe sayfanın işaretlemesi Türkçe başlığı, İngilizce sayfanınki İngilizce başlığı taşır; çevrilmemiş bir alan, görünen içerikle eşleşmeyi bozar.

• Şablon değişikliği sonrası üç temsilci sayfayı yeniden doğrulayın.
• Durum raporunda ani artan geçersiz öğe sayısını inceleyin.
• Kurum bilgisi (ad, adres, logo) değiştiğinde ayar sayfasını güncelleyin.
• Ayrılan ya da eklenen yazarların bilgisini düzenli gözden geçirin.

Örnek Şablon: JSON-LD Uygulama ve Doğrulama Kontrol Tablosu

Aşağıdaki tablo, kurgu bir kurumsal blog şablonu için uygulama ve doğrulama adımlarını bir arada gösterir. Örnek değerler yalnız anlatım içindir; kendi sitenizin sayfalarına göre uyarlayın.

Tabloyu sırayla uygulayın ve her satırın "görünen karşılık" sütununu gerçek sayfada elle kontrol edin. Boş kalan bir görünen karşılık, o özelliğin bloğa girmeyeceği anlamına gelir.

Kurgu senaryo: küçük bir şirket blogu kurum adını hem ayar sayfasında hem de şablonda elle yazmış, logosu yeni sürümde değişmiş. Tabloya göre düzeltme önce ayar sayfasının tek kaynak olması, ardından ana sayfanın yeniden doğrulanmasıdır. Aynı mantık yazar ve tarih alanları için de geçerlidir.

Sıkça Sorulan Sorular

JSON-LD nedir ve neden tercih edilir?

JSON-LD, yapılandırılmış veriyi sayfaya bir veri bloğu olarak ekleyen biçimdir; görünen HTML'yi karıştırmadan sayfanın ne hakkında olduğunu makinelere bildirir. Google, siteniz uygunsa JSON-LD'yi önerir ve uygulaması ile bakımı en kolay biçim olarak sunar. Microdata ve RDFa de desteklenir, geçerli oldukları sürece eşit kabul edilir.

Yapılandırılmış veri sıralamayı yükseltir mi?

Hayır, yapılandırılmış veri tek başına sıralamayı yükseltmez. Google belgelerine göre işaretleme, sayfanın içeriğini anlamasına yardım eder ve uygun koşullarda zengin sonuçlara uygunluk sağlayabilir. Bu uygunluk bir vaat değildir. Sıralama için içerik kalitesi ve genel sayfa deneyimi belirleyici olmaya devam eder.

Organization işaretlemesi her sayfada mı olmalı?

Hayır. Google'ın Organization belgesi bu bilgiyi her sayfaya eklemenizi gerektirmediğini söyler; ana sayfa ya da tek bir kurumsal sayfa, örneğin hakkımızda, yeterli bir yerdir. Belgede zorunlu özellik de yoktur, hepsi önerilen özelliklerdir. Sayfada görünen bilgiyle tutarlı olmaları yeter.

BreadcrumbList işaretlemesi nasıl doğrulanır?

Önce Zengin Sonuçlar Testi veya Schema Markup Validator'a URL ya da kod verip kritik hataları temizleyin. Yayından sonra URL Denetleme aracıyla Google'ın sayfayı görebildiğini, robots.txt, noindex ya da girişle engellenmediğini kontrol edin. İndekslendikten sonra Search Console'daki ilgili durum raporunu izleyin.

JSON-LD'yi elle mi eklemeliyim yoksa eklentiyle mi?

Ekip ve şablon yapısına bağlıdır. Şablonda tek kaynaktan üretilen kod, sayfa bilgisi değiştiğinde bozulma riskini azaltır. Eklenti hızlı kurulum sağlar ama çıktısını yine doğrulamanız gerekir. Elle yazım yalnız tek seferlik, nadir değişen sayfalarda mantıklıdır; çoğaltılan sayfalarda hata birikir.

Yapılandırılmış veri hataları sitemi cezalandırır mı?

Otomatik bir ceza uygulanmaz, ancak kurallara aykırı işaretleme zengin sonuç uygunluğunu kaybettirebilir. Google'ın BreadcrumbList belgesi, yönergelerin dışında görülen işaretlemenin manuel işlem tetikleyebileceğini belirtir. Görünmeyen veya yanıltıcı bilgi işaretlemekten kaçının, teknik hataları ise düzeltin.

Sonuç ve Sonraki Adım

Karar noktanız şu: işaretleme sayfanın gerçek ve görünen bilgisini mi taşıyor, yoksa görünmeyen bir iddiayı mı? İlki küçük bir bakım işidir, ikincisi düzeltilmesi gereken bir risk. Bu rehberdeki sırayı izleyerek tür seçimini yapın, her özelliği sayfadaki karşılığıyla eşleyin, üç aracla doğrulayın ve şablon değişince yeniden kontrol edin.

Yapılandırılmış verinin yanında içerik üretiminin de düzenli akması gerekir. Marka bilgisi, yazar profili ve breadcrumb düzgünse sıradaki iş, okuyucunun gerçekten işine yarayan makaleleri yayımlamaktır. Bu yükü paylaşmak isterseniz makale yazımı sayfasındaki sipariş akışına göz atın: hizmeti seçer, sepete ekler, ödemeyi tamamlar, satıcı onayını ve teslimat bildirimini takip eder, gerekirse itiraz yolunu kullanırsınız.