Automatizace validace Schema.org (CI/CD)

Proč automaticky validovat schema v CI/CD

Strukturovaná data (Schema.org, JSON-LD, Microdata) jsou infrastrukturou 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íčů nebo zastaralé taxonomie. Automatizace validace v CI/CD snižuje riziko regrese o řádově desítky procent, zkracuje time-to-fix a umožňuje škálovat programmatic SEO bez ručních kontrol.

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

• Bezpečnost změn: každý pull/merge request musí projít syntaktickou a 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 standardů: pravidelné testy „driftu“ vůči novým verzím slovníků a doporučením vyhledávačů.

Vrstvený model validace: od syntaxe po obchodní pravidla

1. Syntaktická validace: parsování JSON, správné kódování, velikost polí, jedinečnost 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 ze SSOT).
4. Specifika vyhledávačů: pravidla pro rich results (např. BreadcrumbList, Product s offers).
5. Observabilita v produkci: 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 syntaktická a strukturální pravidla (typy, required, vzory, výčtové hodnoty).
• SHACL/ShEx pro grafové a sémantické závislosti (kontexty RDF/JSON-LD, pravidla shape).
• Slovníky Schema.org jako referenční ontologie (zdroj pravdy pro rangeIncludes, domainIncludes).
• Vlastní validátory v jazyce použitém při sestavení (Node/Python/Go) pro obchodní logiku a křížové kontroly se SSOT.
• Bezhlavý prohlížeč (např. Playwright) pro extrakci a validaci JSON-LD přímo z vykreslené stránky.

Datová architektura: Single Source of Truth (SSOT)

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

• 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; porovnání snapshotu s posledním good build.
3. Build stage: generování artefaktů (minifikovaný JSON-LD, mapování šablon → URL), podepsání verze.
4. Canary release: nasazení na malý vzorek URL; online validace (syntetický crawl) a zpětná metrika.
5. Production monitor: průběžný audit vybraného vzorku URL, upozornění při poklesu pokrytí nebo výskytu nových chyb.

Validační šablony: 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), telefonní čísla (E.164).
• Křížové závislosti (pokud availability = OutOfStock, může chybět priceValidUntil).
• Místní pravidla (pokud inLanguage = „sk-SK“, musí být headline ve slovenštině).

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

• Unit testy: deterministická kontrola malých transformací (např. mapování SSOT → objekt brand).
• Property-based testy: generování náhodných entit a kontrola invariantů (žádná prázdná pole, správné rozsahy).
• Snapshot testy: porovnání vytvořeného JSON-LD s poslední akceptovanou verzí, s whitelistem povolených změn.

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

{
"$schema":"https://json-schema.org/draft/2020-12/schema",
"title":"Product (výňatek)",
"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ýňatek 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 ] .

Pracovní postup v Gitu: pravidla pro změny schémat

• Správa verzí: semver pro vlastní schémata (1.4.0), CHANGELOG s dopady na šablony.
• Ochrana větví: PR musí projít validací, porovnáním snapshotu a alespoň jednou lidskou revizí.
• Registr schémat: zveřejněné URL schém (CDN) s hlavičkou Cache-Control a podpisy.

Příklad úlohy CI (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

Validace při vykreslení: co se testuje v bezhlavém prohlížeči

• Přítomnost a počet skriptů application/ld+json po vykreslení (SSR/CSR).
• Konzistence mezi statickou verzí a verzí za běhu (změny při hydrataci nesmějí odstranit povinná pole).
• Varianty kanálů (A/B, geolokace): zda všechny varianty obsahují povinná schémata.

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

• Kontrola nových vlastností ve Schema.org a doporučeních vyhledávačů; porovnání s našimi schématy.
• Automatizované PR s návrhem aktualizace schémat (bot), včetně poznámek k migraci.
• Bezpečné náhradní postupy (ignorování neznámých polí, ale zaznamenávání změn pro analýzu).

Metodika závažnosti chyb a pravidla nasazování

Observabilita v produkci: od pokrytí po výstupy rich results

• KPI pokrytí: podíl URL s platným JSON-LD podle typu (Product, Article, LocalBusiness).
• Error budget: povolený počet chyb MINOR za týden; při překročení zpomalit tempo vydávání verzí.
• Protokoly událostí: strukturované záznamy validace s trace-id a verzí schématu/release.

Programmatic SEO: rozsáhlé generování bez ztráty kvality

• Šablony pro entity (produkt, pobočka, článek) se zděděním společných vlastností.
• Generování řízené feedem (např. z katalogů), kontrola nulových a výchozích hodnot.
• Pravidla proti duplicitám (stabilní @id, kanonické URL, vazby isPartOf/hasPart).

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

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

Správa: odpovědnosti a pravidelné činnosti

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, upozorňování, canary, rollbacky.
5. Release Council (týdně): revize driftu, chyb a plánu úprav.

Kontrolní seznam před sloučením a před vydáním

• Prošly všechny vrstvy validace (syntax, sémantika, obchodní pravidla)?
• Jsou rozdíly ve snapshotech jen v povolených polích?
• Je vzorek pro canary bez regresí a s dostatečným pokrytím?
• Jsou aktualizovány changelog schémat a dokumentace?

Antivzory: čemu se vyhnout

• Validace „best effort“ pouze na stagingu, bez kontroly v rámci PR.
• Ruční opravy JSON-LD přímo v šablonách bez zdrojového SSOT.
• Sloučené typy (jedna šablona jednou vytváří Product, jindy Service podle nálady).
• Ignorování produkce: validace pouze offline, bez kontroly při vykreslení.

Validace jako konkurenční výhoda

Automatizovaná validace schémat v CI/CD je víc než jen technická pojistka. Je základním mechanismem budování důvěry u vyhledávačů, LLM a interních datových toků. Vrstvené testy, detekce driftu a observabilita v produkci umožňují nasazovat programmatic SEO rychle a bezpečně – s předvídatelnou kvalitou a měřitelným dopadem na viditelnost a konverze.