Společnost

Automatizovaná validace schema.org v CI/CD prostředí

Jankoš 0

Proč automaticky validovat schema v CI/CD

Strukturovaná data (Schema.org, JSON-LD, Microdata) představují infrastrukturu pro vyhledávače, LLM a interní aplikace. Bez automatizované validace se v produkci rychle objeví chyby: neplatné typy, chybějící povinná pole, kolize klíčů či neaktuální taxonomie. Automatizace validace v CI/CD snižuje riziko regresí o desítky procent, zkracuje time-to-fix a umožňuje programatické SEO škálovat bez ručních kontrol.

Cíle a milníky: co má přinést pipeline

  • Bezpečnost změn: každý pull/merge request musí projít syntaktickou i sémantickou validací.
  • Monitorování kvality: trendová metrika chyb per URL/template, rozdělená podle závažnosti.
  • Rychlá diagnostika: reporty s přesnou cestou k chybě (JSON Pointer/XPath, název šablony, release).
  • Odolnost vůči změnám standardu: pravidelné „drift“ testy vůči novým verzím slovníků a vyhledávacích doporučení.

Vícevrstvý model validace: od syntaxe po business pravidla

  1. Syntaktická validace: JSON parse, správné kódování, velikost polí, unikátnost klíčů.
  2. Sémantická validace: typy a povinné vlastnosti podle Schema.org (např. Article → headline, datePublished).
  3. Doménová pravidla: firemní konvence (např. priceCurrency vždy „EUR“, brand.name z SSOT).
  4. Search-engine specifika: pravidla pro rich results (např. BreadcrumbList, Product s offers).
  5. Produkční observabilita: zda se markup skutečně nasazuje na správné URL a v jakém poměru.

Techniky a nástroje: co kombinovat

  • JSON Schema pro syntakticko-strukturální pravidla (typy, required, patterny, enumy).
  • SHACL/ShEx pro grafové a sémantické závislosti (RDF/JSON-LD kontexty, shape pravidla).
  • Schema.org slovníky jako referenční ontologie (zdroj pravdy pro rangeIncludes, domainIncludes).
  • Vlastní validátory v jazyce buildu (Node/Python/Go) na business logiku, křížové kontroly s SSOT.
  • Headless prohlížeč (např. Playwright) pro extrakci a validaci JSON-LD přímo z renderu stránky.

Architektura dat: Single Source of Truth (SSOT)

Programmatic SEO vyžaduje jeden konzistentní zdroj dat pro entity (produkty, místa, články). Pipeline SSOT vynucuje:

  • Konzistence NAP (Name-Address-Phone) a geodat pro LocalBusiness.
  • Referenční ID (SKU, ORCID, ISSN, GTIN) mapované na pole @id, identifier.
  • Taxonomie (kategorie, značky) s pravidly mapování na additionalType nebo about.

Pipeline v CI/CD: kontrolní brány

  1. Pre-commit hook: rychlá syntaktická kontrola JSON/JSON-LD a linters (názvy klíčů, diakritika, prázdná pole).
  2. PR/merge gate: sémantická validace vůči JSON Schema + SHACL; snapshot porovnání vůči poslednímu good build.
  3. Build stage: generování artefaktů (minifikovaný JSON-LD, mapování šablon → URL), podpis verze.
  4. Canary release: nasazení na malou vzorku URL; online validace (syntetický crawl) a zpětná metrika.
  5. Production monitor: kontinuální audit vybrané vzorky URL, alerting při poklesu pokrytí nebo nových chybách.

Šablony validace: co testovat na úrovni šablon

  • Přítomnost povinných vlastností podle typu (např. Product vyžaduje name, offers.price a priceCurrency).
  • Regulární výrazy pro data (ISO 8601), měny (ISO 4217), telefony (E.164).
  • Křížové závislosti (pokud availability = OutOfStock, pak priceValidUntil může chybět).
  • Lokální pravidla (pokud inLanguage = „sk-SK“, pak headline musí být ve slovenštině).

Testování generátorů: unit, property-based, snapshot

  • Unit testy: deterministická kontrola malých transformací (např. mapa SSOT → brand objekt).
  • Property-based testy: generovat náhodné entity a kontrolovat invarianty (žádná prázdná pole, správné rozsahy).
  • Snapshot testy: porovnat produkovaný JSON-LD s poslední akceptovanou verzí, s whitelistem povolených změn.

Minimalistický JSON Schema příklad (výřez bez <pre>)

{
"$schema":"https://json-schema.org/draft/2020-12/schema",
"title":"Product (výřez)",
"type":"object",
"required":["@context","@type","name","offers"],
"properties":{
"@context":{"const":"https://schema.org"},
"@type":{"const":"Product"},
"name":{"type":"string","minLength":3},
"sku":{"type":"string"},
"brand":{"oneOf":[{"type":"string"},{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}]},
"offers":{"type":"object","required":["@type","price","priceCurrency","availability"],"properties":{
"@type":{"const":"Offer"},
"price":{"type":"number","minimum":0},
"priceCurrency":{"type":"string","pattern":"^[A-Z]{3}$"},
"availability":{"type":"string","pattern":"^https://schema.org/(InStock|OutOfStock|PreOrder)$"}
}}
}}
}

SHACL shape (výřez JSON-LD → RDF) bez <pre>

@prefix schema: <https://schema.org/> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

schema:ProductShape a sh:NodeShape ;
sh:targetClass schema:Product ;
sh:property [ sh:path schema:name ; sh:minCount 1 ; sh:datatype xsd:string ] ;
sh:property [ sh:path schema:offers ; sh:minCount 1 ] .

Git workflow: pravidla pro změny ve schématech

  • Versioning: semver pro vlastní schémata (1.4.0), CHANGELOG s dopady na šablony.
  • Branch protection: PR musí projít validací, snapshot diffem a minimálně jednou lidskou revizí.
  • Schema registry: zveřejněné URL schémat (CDN), s hlavičkou Cache-Control a podpisy.

Příklad CI jobu (GitHub Actions) bez <pre>

name: schema-validate
on: [pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm ci
- run: npm run build:schema
- run: node tools/validate-jsonld.js --input dist/jsonld --schema schemas/product.schema.json
- run: node tools/render-and-validate.js --urls test/fixtures.txt --headless

Render-time validace: co se testuje v headless prohlížeči

  • Přítomnost a počet skriptů application/ld+json po renderu (SSR/CSR).
  • Konzistence mezi statickou verzí a runtime (hydratační změny nesmí odstranit povinná pole).
  • Kanálové variace (A/B, geolokalizace): zda všechny varianty obsahují povinné schémy.

Detekce driftu: když se mění svět kolem

  • Kontrola nových vlastností v Schema.org a doporučeních vyhledávačů; porovnání vůči našim schématům.
  • Automatizované PR s návrhem aktualizace schémat (bot), včetně migračních poznámek.
  • Bezpečné fallbacky (ignorovat neznámá pole, ale logovat změny pro analýzu).

Metodika závažnosti chyb a politika nasazení

Úroveň Popis Příklad Akce v CI
BLOCKER Porušení povinného pole/typu Product bez name Fail build
MAJOR Chybný formát/enum priceCurrency ≠ ISO 4217 Fail PR
MINOR Doporučená pole chybí Article bez image Warn + tiket
INFO Nová vlastnost detekována Podpora knowsAbout Log + návrh

Produkční observabilita: od pokrytí po rich-result výstupy

  • Coverage KPI: podíl URL s validním JSON-LD podle typu (Product, Article, LocalBusiness).
  • Error budget: povolený počet MINOR chyb za týden; překročení → zpomalit release.
  • Event logy: strukturované záznamy validace s trace-id a verzí schématu/release.

Programmatic SEO: generování ve velkém bez ztráty kvality

  • Šablony pro entity (produkt, pobočka, článek) s dědičností sdílených vlastností.
  • Feed-driven generování (např. z katalogů), kontrola nulových a default hodnot.
  • Anti-duplicitní pravidla (@id stabilní, kanonické URL, relace isPartOf/hasPart).

Příklady doménových pravidel (ilustrace)

  • Pokud offers.price < 1, označit jako chybu MAJOR (pravděpodobně testovací cena).
  • Pokud datePublished > dnešní datum, zablokovat release (budoucí datum je neplatné).
  • Pro LocalBusiness musí address.addressCountry být „SK“ nebo „CZ“ podle domény.

Governance: odpovědnosti a rituály

  1. Schema Owner: správa JSON Schema/SHACL, dokumentace změn.
  2. SEO/Content: definice doporučených polí a priorit typů.
  3. Data Engineering: SSOT, mapování identifikátorů, kvalita feedů.
  4. QA/DevOps: pipeline, alerting, canary, rollbacks.
  5. Release Council (týdně): revize driftu, chyb a plán úprav.

Checklist před merge a před release

  • Prošly všechny vrstvy validace (syntax, sémantika, business)?
  • Snapshot dify pouze v povolených polích?
  • Canary sample bez regresí a s dostatečným pokrytím?
  • Aktualizovaný changelog schémat a dokumentace?

Antivzory: čemu se vyhnout

  • „Best effort“ validace pouze na stagingu bez PR brány.
  • Manuální opravy JSON-LD přímo v šablonách bez zdrojového SSOT.
  • Spojené typy (jedna šablona produkuje jednou Product, jindy Service podle nálady).
  • Ignorování produkce: validace pouze offline, bez render-time kontroly.

Validace jako konkurenční výhoda

Automatizovaná validace schémat v CI/CD je více než technická pojistka. Je to základní mechanizmus důvěry pro vyhledávače, LLM a interní datové toky. Vícevrstvé testy, drift detekce a produkční observabilita umožňují nasazovat programmatic SEO rychle a bezpečně – s předvídatelnou kvalitou a měřitelným dopadem na viditelnost a konverze.

Jankoš

Website:

Related Story