JSON-LD Nedir?

Kısa tanım

JSON-LD (JSON for Linking Data), bağlantılı veriyi JSON sözdizimiyle ifade eden bir W3C standardıdır. Web sitelerinde çoğunlukla application/ld+json türündeki bir script bloğu içinde, schema.org sözlüğüyle yapılandırılmış veri eklemek için kullanılır. @context, @type, @id ve @graph gibi anahtar kelimelerle varlıkları ve aralarındaki ilişkileri, sayfanın görünen HTML'ine dokunmadan tanımlar.

Diğer adları: JSON for Linking Data, application/ld+json, ld+json, JSON-LD işaretlemesi

Yayınlandı 3 Ekim 2026

Sayfaya script etiketiyle eklenen JSON-LD bloğunun tür, ad, tarih ve konum özelliklerine ayrıştırıldığını gösteren diyagram

Sözdiziminin yapı taşları

JSON-LD, sıradan bir JSON nesnesine birkaç ayrılmış anahtar kelime ekleyerek onu bağlantılı veriye dönüştürür. JSON-LD 1.1, 16 Temmuz 2020'de W3C Önerisi (Recommendation) olarak yayımlandı. Web'deki kullanımda en çok şu dört anahtar kelimeyle karşılaşırsınız:

Anahtar kelime	Görevi
`@context`	Kısa özellik adlarının hangi sözlüğe ait olduğunu bildirir. `"@context": "https://schema.org"` yazıldığında `name`, aslında `https://schema.org/name` demektir.
`@type`	Düğümün türünü belirtir: Organization, Article, Product gibi.
`@id`	Düğüme bir IRI ile kalıcı kimlik verir. Başka bir düğüm bu kimliğe başvurarak aynı varlığı işaret edebilir.
`@graph`	Birden fazla üst düzey düğümü tek bir belgede bir liste olarak toplar.

@context olmadan anahtarlar sadece metindir; bir işlemci author kelimesinin schema.org'daki yazar özelliği olduğunu bilemez. Bu yüzden her bağımsız JSON-LD bloğunun bir bağlamı olmalıdır. Hangi türlerin ve özelliklerin kullanılabileceğini JSON-LD değil, Schema.org sözlüğü belirler; JSON-LD yalnızca taşıyıcıdır.

@id ve @graph ile düğümleri birbirine bağlamak

Gerçek bir sayfa tek bir varlıktan ibaret değildir: bir web sitesi, onu yayımlayan kurum, sayfanın kendisi ve sayfanın asıl konusu vardır. Her birini ayrı bir düğüm olarak tanımlayıp @id referanslarıyla bağlamak, aynı bilgiyi her yerde tekrar yazmaktan daha temizdir:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://ornek.com/#kurum",
      "name": "Örnek Yazılım",
      "url": "https://ornek.com/"
    },
    {
      "@type": "WebSite",
      "@id": "https://ornek.com/#site",
      "url": "https://ornek.com/",
      "publisher": { "@id": "https://ornek.com/#kurum" }
    },
    {
      "@type": "WebPage",
      "@id": "https://ornek.com/hakkimizda/#sayfa",
      "url": "https://ornek.com/hakkimizda/",
      "isPartOf": { "@id": "https://ornek.com/#site" },
      "about": { "@id": "https://ornek.com/#kurum" }
    }
  ]
}
</script>

Burada kurum yalnızca bir kez tanımlanır; site ve sayfa ona { "@id": … } nesnesiyle başvurur. #kurum gibi parça tanımlayıcılı (fragment) IRI'ler yaygın bir kalıptır: gerçek bir sayfa adresine dayanır ama sayfanın kendisiyle değil, o sayfada anlatılan varlıkla eşleşir. Aynı @id'yi sitenin her yerinde aynı varlık için kullanmak, birbirinden kopuk düğümler yerine tutarlı bir grafik ortaya çıkarır.

Sayfada nereye ve nasıl konur?

JSON-LD, type="application/ld+json" özniteliğine sahip bir script öğesinin içinde yer alır. Google bu bloğun head veya body içinde olmasını kabul eder; tarayıcı bu bloğu çalıştırmaz, yalnızca veri olarak taşır. Bir sayfada birden fazla blok bulunabilir.

Google, JSON-LD'nin JavaScript ya da CMS eklentileri tarafından sayfaya sonradan eklenebildiğini de belirtir. Yine de bu durumda veriyi okumak sayfanın render edilmesine bağlı kalır; JavaScript çalıştırmayan araçlar ve tarayıcılar onu hiç göremez. Sunucuda üretilen HTML'e yazmak daha az sürpriz çıkarır.

Teknik bir ayrıntı: JSON metni içinde </script> dizisi geçerse tarayıcı bloğu orada kapatır. Kullanıcı girdisi ya da CMS içeriği JSON-LD'ye aktarılıyorsa < karakteri \u003c olarak kaçışlanmalıdır.

Google neden JSON-LD'yi öneriyor?

Google üç biçimi de destekler: JSON-LD, Microdata ve RDFa. JSON-LD'yi önermesinin gerekçesini, site sahiplerinin ölçekli olarak uygulaması ve bakımını yapması en kolay, kullanıcı hatasına en az açık çözüm olmasıyla açıklar. İşaretleme görünen metinden ayrı durduğu için tasarım değişikliği veriyi bozmaz; iç içe yapıları (bir etkinliğin mekânının adresinin ülkesi gibi) ifade etmek de çok daha kolaydır.

Ayrı durması, sayfadan bağımsız olduğu anlamına gelmez. Google'ın yönergelerine göre işaretleme sayfada okura görünen içeriği yansıtmalıdır; görünmeyen bir fiyatı ya da puanı JSON-LD'ye yazmak kural ihlalidir.

Sık görülen JSON-LD hataları

Geçersiz JSON: Fazladan bir virgül ya da CMS'in "akıllı tırnağa" çevirdiği bir çift tırnak, bloğun tamamını okunamaz hâle getirir.
Eksik @context veya @type: Veri ayrıştırılır ama hangi sözlüğe ve türe ait olduğu anlaşılmaz.
Çakışan @id: Aynı kimliğin bir yerde Organization, başka yerde Person olarak tanımlanması.
Boşa düşen referanslar: Hiçbir düğümde tanımlanmamış bir @id'ye başvurmak.
Göreli adresler: url ve @id değerlerinde tam, mutlak adres kullanmak en güvenli yoldur.

SEO Analiz Aracı, sayfadaki JSON-LD bloklarının geçerliliğini, @context ve @type eksiklerini, çakışan @id'leri ve tanımsız referansları kontrol eder.

İlgili terimler

← Sözlüğe dön