Osvědčené postupy pro JSON-LD: modulární přístup a deduplikace strukturovaných dat

Technické SEO a strukturovaná data
Eva Senková
JSON-LD best practices: Modulárny prístup a deduplikácia štruktúrovaných dát

Osvědčené postupy pro JSON-LD: moduly a deduplikace

JSON-LD je preferovaný formát pro strukturovaná data na webu, protože odděluje datovou vrstvu od prezentace, snižuje křehkost HTML a usnadňuje správu. Při škálování na desítky typů stránek a stovky atributů však rychle narazíte na problémy s duplicitami entit, nekonzistentními identifikátory a „roztříštěnými“ skripty. Tento článek nabízí praktický rámec pro návrh modulární architektury JSON-LD a spolehlivé řešení deduplikace napříč komponentami, šablonami i celým webem.

Základní principy: entity, graf a identita

  • Entita je jakýkoli „věcný“ objekt (produkt, článek, organizace, obchod, událost), který by měl mít @id a @type.
  • Graf (@graph) je kolekce propojených entit v jednom skriptu. Umožňuje publikovat více typů najednou bez zbytečných skriptů.
  • Identita se opírá o stabilní, kanonické URI @id (často URL). Stejné @id = stejná entita bez ohledu na to, který modul ji publikuje.

Modulární architektura: od „monolitu“ ke stavebnici

Monolitický skript rychle narůstá a stává se neudržitelným. Lepším přístupem je rozdělit data do modulů podle typu entity a odpovědnosti:

  • Základní moduly: Organization, WebSite, WebPage – jsou přítomny téměř všude.
  • Doménové moduly: Product, Article, BreadcrumbList, FAQPage, Offer, AggregateRating, Event atd.
  • Kontextové moduly: LocalBusiness (pro pobočky), PostalAddress, OpeningHoursSpecification, ImageObject, VideoObject.

Každý modul generuje svou entitu či entity s @id a odkazuje na jiné entity pomocí jejich @id. Na stránce pak tyto moduly skládáme do jednoho @graph.

Správa @context a verzování schémat

  • Preferujte "@context": "https://schema.org" na úrovni celého skriptu (@graph), nikoli v každé entitě zvlášť.
  • Nezaměňujte http a https v @context; používejte důsledně https.
  • Při přechodu na nové vlastnosti zachovávejte zpětnou kompatibilitu a testujte, zda validační nástroje nevypisují varování.

Stabilní identifikátory: základ deduplikace

Nejčastější příčinou duplicit je nekonzistentní nebo chybějící @id. Doporučení:

  • Každá entita musí mít stálé @id (ideálně kanonickou URL), např. "@id": "https://www.example.com/#organization".
  • Produkty a články používají své kanonické URL: https://www.example.com/produkt/sku-123/, doplněné o fragment pro jednoznačnou identifikaci: #product, #article, #image.
  • Opakovaně použitou entitu (logo, organizaci, vydavatele) vždy odkazujte pomocí "@id": "…#organization", místo abyste znovu zapisovali celou entitu.

Kanonizace a konzistence URL

  • Kanonická stránka = zdroj pravdy pro @id dané entity (např. detail produktu, detail článku).
  • Vyhněte se záměně http a https, varianty s koncovým lomítkem a bez něj nebo subdomény a hlavní domény – drobné rozdíly vytvářejí „nové“ entity.
  • U jazykových mutací používejte pro obsahové entity (článek, produkt) kanonické URL specifické pro daný jazyk a pro globální entity (Organization) používejte jazykově nezávislé @id (např. kořen domény s #organization).

Jeden skript, více entit: proč používat @graph

Místo několika prvků <script type="application/ld+json"> roztroušených po stránce je robustnější připravit jeden skript s @graph, který agreguje všechny moduly. Minimalizujete riziko konfliktů, zrychlíte parsování a získáte centrální kontrolu nad deduplikací.

Kompozice modulů v praxi

Typická sestava pro detail produktu agregovaná do jednoho skriptu:

  • Organization (globální modul) s @id https://www.example.com/#organization
  • WebSite s @id https://www.example.com/#website
  • WebPage pro konkrétní URL stránky
  • BreadcrumbList
  • Product + Offer + AggregateRating (pokud je to relevantní)
  • Případně FAQPage, ImageObject, VideoObject

Modul „Organization“: jediný zdroj pravdy

Udržujte pouze jeden autoritativní popis organizace. Všechny ostatní moduly odkazují na "publisher": {"@id": "https://www.example.com/#organization"} nebo "brand": {"@id": "…#organization"}. Patří sem logo, profily na sociálních sítích (sameAs) i kontaktní údaje.

Modul „WebSite“ a interní vyhledávání

U WebSite použijte "potentialAction": {"@type":"SearchAction"…} pouze jednou. Opakované vkládání stejného SearchAction z více modulů způsobuje duplicity. Pokud jej potřebujete použít jinde, odkazujte na něj pomocí @id.

Modul „WebPage“: kontext pro ostatní entity

  • Každá stránka má vlastní entitu WebPage s @id odpovídajícím kanonické URL + #webpage.
  • Propojte WebPage s hlavní entitou pomocí "mainEntity": {"@id": "…#product"}, respektive #article.
  • Uveďte inLanguage, datePublished/dateModified a breadcrumb pomocí @id odkazujícího na BreadcrumbList.

Produkt, nabídky a varianty: eliminace duplicitních entit

Nejčastěji se deduplikace týká produktů:

  • Stejný produkt, více variant (barva/velikost): modelujte jeden Product s položkou Offer pro dostupné varianty, nebo použijte hasVariant s vlastními @id pro varianty pouze tehdy, pokud mají vlastní kanonické URL.
  • SKU vs. nadřazený produkt: pokud nadřazený produkt nemá URL, nepoužívejte jej jako samostatnou entitu; udržujte konzistentní hodnoty sku, gtin, mpn a brand.
  • Cena a dostupnost: aktualizujte je prostřednictvím serveru nebo důvěryhodného feedu; předejdete tak rozporům mezi moduly.

BreadcrumbList, FAQPage a další „sekundární“ moduly

  • BreadcrumbList: pouze jeden na stránku; pokud vzniká z více komponent, agregujte položky do jednoho objektu s deterministickými hodnotami position.
  • FAQPage: každou otázku (Question) identifikujte pomocí @id (např. #faq-q1) a odpověď (Answer) pomocí #faq-a1. Opakované otázky odkazujte přes @id, místo abyste duplikovali jejich text.
  • ImageObject/VideoObject: obrázky/videa s vlastním @id používejte napříč moduly prostřednictvím odkazu.

Agregace do jednoho skriptu: doporučený vzor

Z hlediska deduplikace je ideální skládat moduly v aplikační vrstvě a na stránku vypisovat jediný skript s @graph. Příklad (schematicky):

Deduplikace: pravidla a kontrolní body

  1. Jedno @id = jedna entita: pokud modul potřebuje entitu, která už existuje, použije její @id – nikdy nevytváří kopii se stejnými vlastnostmi.
  2. Deterministické generování @id: tvorba identifikátoru musí být čistou funkcí (z URL, SKU, slugu); v produkci nepoužívejte náhodné hashe.
  3. Eliminace duplicitních skriptů: místo mnoha skriptů z jednotlivých komponent vytvořte jeden agregovaný skript v šabloně.
  4. Normalizace URL: jednotné schéma (https), pravidla pro koncové lomítko, hostitel malými písmeny, kanonické cesty.
  5. Odkazování na multimédia: obrázky a videa mají vlastní @id a odkazuje se na ně, nekopírují se.
  6. Model „nadřazený vs. podřízený“: u variant použijte hasVariant nebo Offer podle modelu URL; vyhněte se paralelním popisům stejných SKU.

Server-side renderování (SSR) vs. vkládání na straně klienta (CSR/GTM)

  • Preferujte SSR nebo generování při sestavení (SSG). Minimalizujete zpoždění a riziko, že validátory data neuvidí.
  • Pokud používáte GTM, mějte vyhrazenou datovou vrstvu s jednoznačnými klíči; na jedné stránce spouštějte pouze jedno vložení JSON-LD.
  • Vyhněte se souběžnému generování stejných entit pomocí SSR a GTM – vznikají duplicity a konflikty.

Správa verzí a migrace schémat

  • Při přidávání nových vlastností je nejprve nasaďte na malém vzorku, sledujte varování a vliv na zobrazení (např. ve výsledcích s rozšířenými funkcemi).
  • Při odstraňování zastaralých vlastností nejprve zajistěte, aby na ně už žádný modul neodkazoval.
  • Verzujte generátory modulů (např. product@2.1.0) a udržujte changelog.

Validace, monitoring a upozornění

  • Automatizujte validaci během CI/CD (lintování JSON, kontrola kolizí @id, přítomnost @graph).
  • Zaznamenávejte a zobrazujte na dashboardu počty entit na URL, rozdělené podle @type; náhlý nárůst signalizuje duplicity.
  • Pravidelně kontrolujte výsledky s rozšířenými funkcemi a jejich proměnlivost – náhlé ztráty často souvisejí s chybami v JSON-LD.

Deterministické skládání: pravidla slučování

Pokud moduly vznikají v různých vrstvách (CMS, API, mikrofrotend), potřebujete deterministický algoritmus slučování:

  1. Indexujte entity podle @id.
  2. Při kolizi stejného @id proveďte hluboké sloučení s prioritou zdrojů (např. server > CMS > klient).
  3. Pole (sameAs, itemListElement) slučujte bez duplicitních položek (slučování podobné množině).
  4. Hodnoty null/empty nepovažujte za přepsání – nechte je bez účinku, aby kvalitnější zdroj nebyl „vymazán“ prázdnou hodnotou.

sameAs a propojení: posílení autority bez duplicit

sameAs propojuje entitu s jejími oficiálními profily (Wikidata, sociální sítě). Dodržujte následující pravidla:

  • Uvedené URL musí být konzistentní a aktivní; nefunkční odkazy snižují důvěryhodnost.
  • V sameAs neuvádějte duplicity (http vs. https, koncové lomítko).
  • Nepoužívejte sameAs pro interní technické stránky; patří sem pouze relevantní externí identita.

Časté anti-patterny a jak se jim vyhnout

  1. Více skriptů se stejnými údaji o Organization – mějte pouze jeden globální a jinde odkazujte na @id.
  2. Různá @id pro stejný produkt – navazujte @id na kanonickou URL, nikoli na kontext (kategorie vs. vyhledávání).
  3. Duplicitní entity breadcrumbů při kombinování komponent – skládejte je do jednoho BreadcrumbList.
  4. Nejednoznačné nebo relativní @id – vždy používejte absolutní URL.
  5. Dvojí vložení přes GTM a šablonu – sjednoťte generování do jedné vrstvy.

Internacionalizace a hreflang vs. JSON-LD

  • Obsahové entity (Article, Product) mají jazykově specifické @id navázané na kanonickou URL dané mutace.
  • Globální entity (Organization, WebSite) mají jedno @id napříč jazyky, přičemž textová pole (name) mohou být podle potřeby v místním jazyce.
  • Propojení mezi mutacemi můžete doplnit pomocí vlastního klíče (např. inLanguage) – hreflang zůstává v HTML; v JSON-LD nezdvojujte stejné informace, pokud to nepřináší přidanou hodnotu.

Místní pobočky a síť provozoven

U LocalBusiness definujte @id každé pobočky (např. https://www.example.com/pobocky/bratislava/#place). Nekopírujte jednu obecnou pobočku na všechny místní stránky – pro každé konkrétní místo vždy vytvořte jedinečnou entitu.

Výkonnost a bezpečnost

  • Kompaktní skripty (bez zbytečných mezer) zkracují přenos a zrychlují vykreslování.
  • Nevkládejte dynamicky nedůvěryhodné hodnoty (uživatelský vstup) bez sanitizace – JSON-LD sice není spustitelný, může však narušit HTML.
  • U rozsáhlých seznamů (např. ItemList s desítkami položek) zvažte publikování pouze prvních N položek a načítání zbytku přes API pro vlastní potřebu (validátory stejně pracují se vzorky).

Kontrolní seznam pro moduly a deduplikaci

  • Každá entita má stabilní, absolutní @id odvozené z kanonické URL.
  • Na stránce publikujete jeden skript s @graph – žádné duplicitní entity se stejnými vlastnostmi.
  • Globální entity (Organization, WebSite) existují pouze jednou a všude se na ně odkazuje.
  • Breadcrumb je jeden sjednocený objekt; pozice jsou deterministické.
  • Produkty: jasný model nadřazeného produktu a variant, žádné paralelní popisy stejných SKU.
  • Obrázky/videa mají vlastní @id a odkazuje se na ně, nekopírují se.
  • Automatizovaná validace v CI/CD a upozornění na anomálie v počtu entit.

Modulární JSON-LD s důslednou deduplikací stojí na stabilních @id, centralizovaném @graph a deterministickém skládání entit. Tento přístup snižuje technický dluh, eliminuje rozpory mezi moduly, usnadňuje údržbu a poskytuje konzistentní signály vyhledávačům. Investice do kvalitní vrstvy identity a pravidel slučování se vrátí v podobě spolehlivých výsledků s rozšířenými funkcemi, lepší datové hygieny a rychlejšího nasazování nových typů strukturovaných dat.