Validácia schema v CI/CD

Prečo validovať schema automaticky v CI/CD

Štruktúrované dáta (Schema.org, JSON-LD, Microdata) sú infraštruktúra pre vyhľadávače, LLM a interné aplikácie. Bez automatizovanej validácie sa v produkcii rýchlo objavia chyby: neplatné typy, chýbajúce povinné polia, kolízia kľúčov, či neaktuálne taxonómie. Automatizácia validácie v CI/CD znižuje riziko regrese o rádovo desiatky percent, skracuje time-to-fix a umožňuje programmatic SEO škálovať bez ručných kontrol.

Ciele a míľniky: čo má priniesť pipeline

• Bezpečnosť zmien: každý pull/merge request musí prejsť syntaktickou a sémantickou validáciou.
• Monitorovanie kvality: trendová metrika chýb per URL/template, rozdelená podľa závažnosti.
• Rýchla diagnostika: reporty s presnou cestou k chybe (JSON Pointer/XPath, názov šablóny, release).
• Odolnosť voči zmenám štandardu: pravidelné „drift“ testy voči novým verziám slovníkov a vyhľadávacích odporúčaní.

Vrstevnatý model validácie: od syntaxe po biznis pravidlá

1. Syntaktická validácia: JSON parse, správne kódovanie, veľkosť polí, unikátnosť kľúčov.
2. Sémantická validácia: typy a povinné vlastnosti podľa Schema.org (napr. Article → headline, datePublished).
3. Doménové pravidlá: firemné konvencie (napr. priceCurrency vždy „EUR“, brand.name z SSOT).
4. Search-engine špecifiká: pravidlá pre rich results (napr. BreadcrumbList, Product s offers).
5. Produkčná observabilita: či sa markup reálne nasadzuje na správne URL, a v akom pomere.

Techniky a nástroje: čo kombinovať

• JSON Schema pre syntakticko-štruktúrne pravidlá (typy, required, patterny, enumy).
• SHACL/ShEx pre grafové a sémantické závislosti (RDF/JSON-LD kontexty, shape pravidlá).
• Schema.org slovníky ako referenčná ontológia (zdroj pravdy pre rangeIncludes, domainIncludes).
• Vlastné validátory v jazyku buildu (Node/Python/Go) na biznis logiku, krížové kontroly s SSOT.
• Headless prehliadač (napr. Playwright) na extrakciu a validáciu JSON-LD priamo z renderu stránky.

Architektúra dát: Single Source of Truth (SSOT)

Programmatic SEO vyžaduje jeden konsistentný zdroj dát pre entity (produkty, miesta, články). Pipeline si SSOT vynucuje:

• Konzistencia NAP (Name-Address-Phone) a geodát pre LocalBusiness.
• Referenčné ID (SKU, ORCID, ISSN, GTIN) mapované na polia @id, identifier.
• Taxonómie (kategórie, značky) s pravidlami mapovania na additionalType alebo about.

Pipeline v CI/CD: kontrolné brány

1. Pre-commit hook: rýchla syntaktická kontrola JSON/JSON-LD a linters (názvy kľúčov, diakritika, prázdne polia).
2. PR/merge gate: sémantická validácia voči JSON Schema + SHACL; snapshot porovnanie voči poslednému good build.
3. Build stage: generovanie artefaktov (minifikovaný JSON-LD, mapovanie šablón → URL), podpis verzie.
4. Canary release: nasadiť na malú vzorku URL; online validácia (syntetický crawl) a spätná metrika.
5. Production monitor: kontinuálny audit vybranej vzorky URL, alerting pri poklese pokrytia alebo nových chybách.

Šablóny validácie: čo testovať na úrovni šablón

• Prítomnosť povinných vlastností podľa typu (napr. Product vyžaduje name, offers.price a priceCurrency).
• Regulárne výrazy na dátumy (ISO 8601), meny (ISO 4217), telefóny (E.164).
• Krížové závislosti (ak availability = OutOfStock, potom priceValidUntil môže chýbať).
• Lokálne pravidlá (ak inLanguage = „sk-SK“, potom headline musí byť v slovenčine).

Testovanie generátorov: unit, property-based, snapshot

• Unit testy: deterministická kontrola malých transformácií (napr. mapa SSOT → brand objekt).
• Property-based testy: generovať náhodné entity a kontrolovať invarianti (žiadne prázdne polia, správne rozsahy).
• Snapshot testy: porovnať produkovaný JSON-LD s poslednou akceptovanou verziou, s whitelistom povolených zmien.

Minimalistický JSON Schema príklad (výrez bez <pre>)

{
  "$schema":"https://json-schema.org/draft/2020-12/schema",
  "title":"Product (výrez)",
  "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ýrez 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: pravidlá pre zmeny v schémach

• Versioning: semver pre vlastné schémy (1.4.0), CHANGELOG s dopadmi na šablóny.
• Branch protection: PR musí prejsť validáciou, snapshot diffom a minimálne jednou ľudskou revíziou.
• Schema registry: zverejnené URL schém (CDN), s hlavičkou Cache-Control a podpismi.

Prí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 validácia: čo sa testuje v headless prehliadači

• Prítomnosť a počet skriptov application/ld+json po renderi (SSR/CSR).
• Konzistentnosť medzi statickou verziou a runtime (hydratačné zmeny nesmú odstrániť povinné polia).
• Kanálové variácie (A/B, geolokalizácia): či všetky varianty obsahujú povinné schémy.

Drift detekcia: keď sa mení svet okolo

• Kontrola nových vlastností v Schema.org a odporúčaní vyhľadávačov; porovnanie voči našim schémam.
• Automatizované PR s návrhom aktualizácie schém (bot), vrátane migračných poznámok.
• Bezpečné fallbacky (ignorovať neznáme polia, ale logovať zmeny pre analýzu).

Metodika závažnosti chýb a politika nasadenia

Produkčná observabilita: od pokrytia po rich-result výstupy

• Coverage KPI: podiel URL s validným JSON-LD podľa typu (Product, Article, LocalBusiness).
• Error budget: povolený počet MINOR za týždeň; prekročenie → znížiť rýchlosť release.
• Event logy: štruktúrované záznamy validácie s trace-id a verziou schémy/release.

Programmatic SEO: generovanie vo veľkom bez straty kvality

• Templaty pre entity (produkt, pobočka, článok) s dedičnosťou spoločných vlastností.
• Feed-driven generovanie (napr. z katalógov), kontrola nulových a default hodnôt.
• Anti-duplicitné pravidlá (@id stabilné, kanonické URL, relácie isPartOf/hasPart).

Príklady doménových pravidiel (ilustrácia)

• Ak offers.price < 1, označiť ako chyba MAJOR (pravdepodobne testovacia cena).
• Ak datePublished > dnešný dátum, zablokovať release (budúci dátum je neplatný).
• Pre LocalBusiness musí address.addressCountry byť „SK“ alebo „CZ“ podľa domény.

Governance: zodpovednosti a rituály

1. Schema Owner: správa JSON Schema/SHACL, dokumentácia zmien.
2. SEO/Content: definícia odporúčaných polí a priority typov.
3. Data Engineering: SSOT, mapovanie identifikátorov, kvalita feedov.
4. QA/DevOps: pipeline, alerting, kanárik, rollbacks.
5. Release Council (týždenne): review driftu, chýb a plán úprav.

Checklist pred merge a pred release

• Prešli všetky vrstvy validácie (syntax, sémantika, biznis)?
• Snapshot dify len v povolených poliach?
• Canary sample bez regresií a s dostatočným pokrytím?
• Aktualizovaný changelog schém a dokumentácia?

Antivzory: čomu sa vyhnúť

• „Best effort“ validácia len na stagingu bez PR brány.
• Manuálne opravy JSON-LD priamo v šablónach bez zdrojového SSOT.
• Zlúčené typy (jedna šablóna produkuje raz Product, raz Service podľa nálady).
• Ignorovanie produkcie: validácia len offline, bez render-time kontroly.

Validácia ako konkurenčná výhoda

Automatizovaná validácia schém v CI/CD je viac než technická poistka. Je to základný mechanizmus dôvery pre vyhľadávače, LLM a interné dátové toky. Vrstevnaté testy, drift detekcia a produkčná observabilita umožňujú nasadzovať programmatic SEO rýchlo a bezpečne – s predvídateľnou kvalitou a merateľným dopadom na viditeľnosť a konverzie.