/seo-schema

name: seo-schema
description: Detect, validate, and generate Schema.org structured data as JSON-LD. Extracts every ld+json block from HTML, validates nested values (offers, return policies, shipping, ratings) and value rules (ISO dates, absolute URLs, numeric price, ISO 4217 currency) against September 2026 rich-results rules, flags retired displays (FAQ, HowTo, the 2025 set) as info, scores the result, graph-checks @id references across pages, and emits a linked Organization/WebSite/WebPage starter graph. Trigger when the user says "schema", "structured data", "rich results", "JSON-LD", "schema markup", "validate schema", "schema graph", or "rich results eligibility".

seo-schema

**Family:** seo **Status:** Stable

Purpose

Full Schema.org JSON-LD lifecycle: extract what's on the page, validate it (nested values included), generate the right markup, and prove the site reads as **one entity graph** — the part of structured data that keeps paying off for ranking systems and AI answer engines even after a rich-result display is retired. JSON-LD is the only format Google recommends.

Encodes the September 2026 status (dated in `references/shared/search-landscape-2026.md` §5): active rich results include Product / merchant listings, Review snippets, Breadcrumb, Article, Video, Event, Recipe, LocalBusiness, Organization, ProfilePage, DiscussionForumPosting and JobPosting; **FAQ rich results ended on 2026-05-07**, HowTo and the sitelinks search box are gone, and the 2025-retired set (Course Info, Claim Review, Estimated Salary, Learning Video, Special Announcement, Vehicle Listing) plus practice problems are flagged as *info* — valid markup, no visual, never an error. Rules, `@id` conventions and scoring: `references/seo-schema/entity-graph.md`; type vocabulary: `references/shared/schema-catalog.md`.

Triggers

• "schema" / "structured data" / "rich results"
• "json-ld" / "markup"
• "validate schema" / "add schema" / "schema graph"

Inputs

• Page HTML file(s) or URL content saved locally (detect/validate/graph), inline or

file JSON-LD (validate), a page type + facts (generate), or brand + page facts (site starter)

• Mode: detect | validate | generate | graph-check | site-starter

Steps

1. **List supported types** (required, one-of groups, recommended, rich status):

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/seo/schema_gen.py" --list

2. **Detect + validate straight from HTML** — every `application/ld+json` block, `@graph` flattened, nested values (Offer, MerchantReturnPolicy, shipping, ratings, reviews) checked against their own spec, plus value rules (ISO 8601 dates, absolute URLs, numeric price, ISO 4217 currency, schema.org enums, rating bounds, breadcrumb order):

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/seo/schema_gen.py" --html page.html --human

(`--validate file.json` does the same for raw JSON-LD.) The JSON carries `detected`, `deprecations`, per-node `issues` `{type, severity, property, finding, fix}`, and a 0-100 `score`. 3. **Graph-check across pages** — pass the home page plus the pages under review:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/seo/schema_gen.py" --graph home.html product.html about.html --human

Flags dangling `@id` references, one `@id` with conflicting types, a split Organization entity, and missing Organization/WebSite hubs. The check sees only the files passed — say which pages were in scope. 4. **Generate** — a single node, auto-validated:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/seo/schema_gen.py" --type Product --data '{"name":"...","image":"https://...","offers":{"@type":"Offer","price":"49.00","priceCurrency":"USD","availability":"https://schema.org/InStock"}}'

or the linked site skeleton (Organization → WebSite → WebPage → BreadcrumbList with `#fragment` ids), validated and graph-checked in one pass:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/seo/schema_gen.py" --site '{"name":"...","url":"https://site","logo":"https://site/logo.png","page":{"url":"https://site/p","name":"...","breadcrumb":[["Home","https://site/"],["Page"]]}}' --human

Only mark up facts visible on the page (prices, ratings, reviews). 5. **Deliver** ready-to-drop `<script type="application/ld+json">` blocks, the validation + graph summary with scores, and the fix list — never promising a retired rich result.

Outputs

• Inventory of detected types + deprecations, per-node validation with fixes, score
• Generated, pre-validated JSON-LD (single node or linked site `@graph`)
• Cross-page `@id` entity-graph report (dangling / conflicting / split / missing hubs)

Dependencies

• `scripts/seo/schema_gen.py` (required) — Python 3.10+, standard library only
• `references/seo-schema/entity-graph.md` (required) — @id conventions, value rules, scoring
• `references/shared/schema-catalog.md` (required) — type vocabulary
• `references/shared/search-landscape-2026.md` (required) — which rich results are live

Notes

Cross-page `@id` graph linking is frequently missed — most tools validate per-page only. A hub for the SEO family (`seo-page`, `seo-technical`, `seo-local-unified`, `seo-ecommerce` lean on it).