JSON-LD best practices

JSON-LD best practices: moduly a deduplikácia

JSON-LD je preferovaný formát pre štruktúrované dáta na webe, pretože oddelí dátovú vrstvu od prezentácie, znižuje krehkosť HTML a uľahčuje správu. Pri škálovaní na desiatky typov stránok a stovky atribútov však rýchlo narazíte na problémy s duplicito u entít, nekonzistentnými identifikátormi a „rozpletenými“ skriptami. Tento článok ponúka praktický rámec, ako navrhovať modulárnu architektúru JSON-LD a ako spoľahlivo riešiť deduplikáciu naprieč komponentmi, šablónami a celým webom.

Základné princípy: entity, graf a identita

• Entita je akýkoľvek „vecný“ objekt (produkt, článok, organizácia, obchod, udalosť), ktorý by mal mať @id a @type.
• Graf (@graph) je kolekcia prepojených entít v jednom skripte. Umožňuje vypublikovať viacero typov naraz bez prebytočných skriptov.
• Identita sa opiera o stabilné, kanonické @id URI (často URL). Rovnaké @id = tá istá entita, nech už ju publikuje ktorýkoľvek modul.

Modulárna architektúra: od „monolitu“ k stavebnici

Monolitický skript rýchlo rastie a stáva sa neudržateľným. Lepší prístup je rozdeliť dáta do modulov podľa typu entity a zodpovednosti:

• Core moduly: Organization, WebSite, WebPage – prítomné takmer všade.
• Doménové moduly: Product, Article, BreadcrumbList, FAQPage, Offer, AggregateRating, Event, atď.
• Kontextové moduly: LocalBusiness (na pobočkách), PostalAddress, OpeningHoursSpecification, ImageObject, VideoObject.

Každý modul generuje svoju entitu/entit y s @id a odkazuje na iné entity pomocou ich @id. Na stránke potom tieto moduly komponujeme do jedného @graph.

Riadenie @context a verzovanie schém

• Preferujte "@context": "https://schema.org" na úrovni celého skriptu (@graph), nie v každej entite osobitne.
• Nezamieňajte http a https v @context; používajte konzistentne https.
• Pri prechode na nové vlastnosti udržiavajte spätnú kompatibilitu a testujte, či validačné nástroje nevyhadzujú warningy.

Stabilné identifikátory: základ deduplikácie

Najčastejšia príčina duplikátov je nekonzistentný alebo chýbajúci @id. Odporúčania:

• Každá entita musí mať stály @id (ideálne kanonická URL), napr. "@id": "https://www.example.com/#organization".
• Produkty a články používajú svoje kanonické URL: https://www.example.com/produkt/sku-123/, doplnené o fragment pre jednoznačnosť: #product, #article, #image.
• Opakované použitie tej istej entity (logo, org, vydavateľ) vždy odkazom cez "@id": "…#organization", nie opätovným zápisom celej entity.

Kanonikalizácia a konzistencia URL

• Kanonická stránka = zdroj pravdy pre @id danej entity (napr. detail produktu, detail článku).
• Vyhnite sa zámene http vs. https, trailing slash vs. bez, subdomény vs. hlavná doména – drobné rozdiely vytvárajú „nové“ entity.
• Pri jazykových mutáciách používajte jazyk špecifické kanonické URL pre obsahové entity (článok, produkt) a pre globálne entity (Organization) používajte jazykovo agnostické @id (napr. root domény s #organization).

Jeden skript, viac entít: prečo používať @graph

Namiesto viacerých <script type="application/ld+json"> roztrúsených po stránke je robustnejšie pripraviť jeden skript s @graph, ktorý agreguje všetky moduly. Minimalizujete riziko konfliktov, zrýchlite parsing a máte centrálnu kontrolu deduplikácie.

Kompozícia modulov v praxi

Typická zostava pre produktový detail agregovaná do jedného skriptu:

• Organization (globálny modul) s @id https://www.example.com/#organization
• WebSite s @id https://www.example.com/#website
• WebPage pre konkrétnu URL stránky
• BreadcrumbList
• Product + Offer + AggregateRating (ak relevantné)
• Prípadné FAQPage, ImageObject, VideoObject

Modul „Organization“: single source of truth

Udržujte iba jeden autoritatívny popis organizácie. Všetky ostatné moduly referencujú "publisher": {"@id": "https://www.example.com/#organization"} alebo "brand": {"@id": "…#organization"}. Logo, social profily (sameAs) aj kontaktné dáta patria sem.

Modul „WebSite“ a interné vyhľadávanie

Pre WebSite používajte "potentialAction": {"@type":"SearchAction"…} iba raz. Neopakovane vkladať rovnaký SearchAction z viacerých modulov spôsobuje duplicitu. Referencujte ho cez @id, ak ho potrebujete použiť inde.

Modul „WebPage“: kontext pre ostatné entity

• Každá stránka má svoju entitu WebPage s @id rovnou kanonickej URL + #webpage.
• Prepojte WebPage na hlavnú entitu cez "mainEntity": {"@id": "…#product"} resp. #article.
• Uveďte inLanguage, datePublished/dateModified, breadcrumb cez @id na BreadcrumbList.

Produkt, ponuky a varianty: eliminácia duplicitných entít

Najčastejšia deduplikácia sa týka produktov:

• Rovnaký produkt, viac variantov (farba/veľkosť): modelujte jeden Product s Offer pre dostupné varianty, alebo používajte hasVariant s vlastnými @id pre varianty len vtedy, ak majú vlastné kanonické URL.
• SKU vs. parent: ak parent nemá URL, nepoužívajte ho ako samostatnú entitu; udržiavajte konzistentný sku, gtin, mpn a brand.
• Price a availability: aktualizujte cez server alebo trusted feed; zamedzíte divergencii medzi modulmi.

BreadcrumbList, FAQPage a ďalšie „sekundárne“ moduly

• BreadcrumbList: iba jeden na stránke; ak vzniká z viacerých komponentov, agregujte položky do jedného objektu s deterministickým position.
• FAQPage: každú otázku (Question) identifikujte @id (napr. #faq-q1) a odpovede (Answer) #faq-a1. Opätovné otázky odkazujte cez @id, nie duplikovaním textu.
• ImageObject/VideoObject: obrázky/videá s vlastným @id používajte naprieč modulmi cez referenciu.

Agregácia do jedného skriptu: recommended pattern

Z hľadiska deduplikácie je ideálne skladať moduly v aplikačnej vrstve a na stránku vypisovať jediný skript s @graph. Príklad (schematicky):

Deduplikácia: pravidlá a kontrolné body

1. Jeden @id = jedna entita: ak modul potrebuje entitu, ktorá už existuje, používa jej @id – nikdy nevytvára kópiu s rovnakými vlastnosťami.
2. Deterministické generovanie @id: tvorba identifikátora musí byť čistá funkcia (z URL, SKU, slug); žiadne náhodné hash-e v produkcii.
3. Eliminácia duplicitných skriptov: namiesto mnohých skriptov z komponentov vytvorte jeden agregovaný skript v šablóne.
4. Normalizácia URL: jednotná schéma (https), trailing slash politika, lowercase host, kanonické cesty.
5. Referencovanie multimédií: obrázky a videá majú vlastné @id a sú referencované, nie kopírované.
6. „Parent vs. child“ model: pri variantoch používajte hasVariant alebo Offer podľa URL modelu, vyhnite sa paralelným popisom tých istých SKU.

Server-side render (SSR) vs. client-side inject (CSR/GTM)

• Preferujte SSR alebo build-time generovanie (SSG). Minimalizujete oneskorenie a riziko, že validátory neuvidia dáta.
• Ak používate GTM, majte dedikovanú dátovú vrstvu s jednoznačnými kľúčmi; na jednej stránke spúšťajte iba jeden JSON-LD inject.
• Vyhnite sa súbežnému SSR + GTM generovaniu tých istých entít – vznikajú duplicity a konflikty.

Riadenie verzií a migrácie schém

• Pri pridávaní nových vlastností najprv nasadzujte na malú vzorku, monitorujte warningy a vplyv na zobrazenie (napr. bohaté výsledky).
• Pri odstraňovaní legacy vlastností najprv zabezpečte, aby ich žiadny modul už nereferencoval.
• Verzujte generátory modulov (napr. product@2.1.0) a udržiavajte changelog.

Validácia, monitoring a alerting

• Automatizujte validáciu počas CI/CD (linting JSON, kontrola @id kolízií, prítomnosť @graph).
• Logujte a dashboardujte počty entít na URL, rozdelené podľa @type; náhly nárast signalizuje duplicitu.
• Pravidelne kontrolujte bohaté výsledky a ich volatilitu – náhle straty často súvisia s chybami v JSON-LD.

Deterministická skladba: „merge“ pravidlá

Ak moduly vznikajú v rôznych vrstvách (CMS, API, microfrontend), potrebujete deterministický „merge“ algoritmus:

1. Indexujte entity podľa @id.
2. Pri kolízii rovnakého @id vykonajte hlboký merge s prioritou zdrojov (napr. server > CMS > klient).
3. Polia (sameAs, itemListElement) zlučujte bez duplicitných prvkov (set-like merge).
4. Hodnoty null/empty nepovažujte za prepis – nechávajte ich bez efektu, aby kvalitnejší zdroj nebol „zmazaný“ prázdnotou.

sameAs a prepojenia: posilnenie autority bez duplikácie

sameAs prepojí entitu na jej oficiálne profily (Wikidata, sociálne siete). Dodržujte:

• Uvedené URL musia byť konzistentné a aktívne; zlomené odkazy znižujú dôveryhodnosť.
• Neuvádzajte duplicity v sameAs (http vs. https, trailing slash).
• Nepoužívajte sameAs na interné technické stránky; patrí sem len relevantná externá identita.

Časté anti-patterny a ako sa im vyhnúť

1. Viac skriptov s rovnakými Organization údajmi – majte iba jeden globálny a inde referencujte @id.
2. Rozdielne @id pre ten istý produkt – viažte @id na kanonickú URL, nie na kontext (kategória vs. hľadanie).
3. Duplikované breadcrumb entity pri kombinovaní komponentov – skladanie do jedného BreadcrumbList.
4. Neurčité alebo relatívne @id – vždy používajte absolútne URL.
5. Dvojitý inject cez GTM a šablónu – zjednoťte generovanie do jednej vrstvy.

Internacionalizácia a hreflang vs. JSON-LD

• Obsahové entity (Article, Product) majú jazykovo špecifické @id viazané na kanonickú URL mutácie.
• Globálne entity (Organization, WebSite) majú jedno @id naprieč jazykmi, pričom textové polia (name) môžu byť v lokálnom jazyku podľa potreby.
• Prepojenia medzi mutáciami môžete doplniť cez vlastný kľúč (napr. inLanguage) – hreflang ostáva v HTML; v JSON-LD nezdvojujte tú istú informáciu, pokiaľ to neprináša pridanú hodnotu.

Lokálne pobočky a sieť prevádzok

Pri LocalBusiness definujte @id každ ej pobočky (napr. https://www.example.com/pobocky/bratislava/#place). Nereplikujte jednu generickú pobočku na všetkých miestnych stránkach – vždy unikátna entita pre konkrétne miesto.

Výkonnostné hľadisko a bezpečnosť

• Komp aktné skripty (žiadne zbytočné whitespace) skracujú prenos a zrýchľujú render.
• Nevkladajte dynamicky nedôveryhodné hodnoty (user input) bez sanitácie – JSON-LD je síce neexekvovateľný, ale môže narušiť HTML.
• Pri veľkých zoznamoch (napr. ItemList s desiatkami položiek) zvažujte publikovať iba top N položiek a zvyšok načítať cez API pre vlastné účely (validátory aj tak vzorkujú).

Checklist pre moduly a deduplikáciu

• Každá entita má stabilný, absolútny @id odvodený z kanonickej URL.
• Na stránke publikujete jeden skript s @graph – žiadne kvalitativne rovnaké duplikáty.
• Globálne entity (Organization, WebSite) existujú len raz a všade sa referencujú.
• Breadcrumb je jeden zjednotený objekt; pozície sú deterministické.
• Produkty: jasný model parent/variant, žiadne paralelné popisy tých istých SKU.
• Obrázky/videá majú vlastné @id a sú referencované, nie kopírované.
• Automatizovaná validácia v CI/CD a alerting na anomálie počtu entít.

Modulárny JSON-LD s dôslednou deduplikáciou stojí na stabilných @id, centralizovanom @graph a deterministickom skladaní entít. Takýto prístup znižuje technický dlh, eliminuje rozpory medzi modulmi, uľahčuje údržbu a prináša konzistentné signály pre vyhľadávače. Investícia do kvalitnej identitnej vrstvy a „merge“ pravidiel sa vráti v spoľahlivých bohatých výsledkoch, lepšej dátovej hygiene a rýchlejšom nasadzovaní nových typov štruktúrovaných dát.