Structured Data

Markdown delivery contract

Read markdown-delivery-contract.md for every task. Write a substantive .md document for every material work step and register its direct destination in the work index.md. For public-site work, apply the owner-required Markdown discovery profile across the full eligible inventory; preserve native standards and immutable evidence formats.

Lane outputs: schema-review.md; entity-parity.md (combine small related steps with stable section links). Keep JSON-LD in its supported format and validate eligibility against visible HTML. Record entity/fact parity with Markdown; do not replace schema with .md or invent an AI-specific schema.

Purpose

Audit or draft structured data that accurately represents the visible page and verified entity facts. JSON-LD is a convenient implementation format, but format choice, schema validity, and rich-result eligibility are distinct questions.

Read references/structured-data-review-protocol.md before generating implementation code.

Input gate

Require the rendered page or trusted page source, canonical URL, visible factual content, entity/offer/author/media facts, locale, and intended result or user purpose. For feature eligibility, check current primary search-engine documentation at the time of the work. Do not depend on a static “active/deprecated type” list.

If a fact is unknown—price, availability, rating source, author, date, image, address, certificate, or relationship—leave a clearly marked placeholder or decline the field. Never manufacture missing structured facts.

Workflow

Let <suite-root> mean ${CLAUDE_PLUGIN_ROOT} in Claude Code. In Codex, read .seo-suite-runtime.json beside this SKILL.md when present and use its suite_root value; otherwise use the absolute repository checkout. Before relying on a shipped platform feature state, run python "<suite-root>/scripts/validate_platform_controls.py" validate-registry "<suite-root>/manifests/platform-controls.json" --bundle "<suite-root>/manifests" --as-of <current-UTC-time>. Refresh primary documentation when the registry is stale or the feature is absent.

1. Inventory. Detect JSON-LD, Microdata, and RDFa; identify duplicate, conflicting, malformed, or disconnected entity graphs.
2. Map visible truth. For every proposed property, locate the reader-visible source or an approved authoritative data source. Confirm URLs, dates, locale, entity identity, and nesting match the page.
3. Separate three checks. Validate Schema.org vocabulary/syntax; validate platform-specific feature eligibility and lifecycle (current, preview, deprecated, or removed); then validate rendered visible-content alignment. Passing one is not proof of the others.
4. Check lifecycle freshness. Require a current Platform Controls registry row and primary documentation for the exact feature, market, locale, and surface.
5. Draft the smallest truthful graph. Prefer a coherent entity model over markup volume. Include only supported types/properties and use absolute, canonical URLs where appropriate. Do not add FAQ/HowTo/review/product/organization fields merely as an SEO tactic.
6. Plan safe release. State template/URL scope, owner, test environment, validation method, source-of-truth, rollout, and rollback. Route deployment through seo-action-plan when it changes production templates or data pipelines.
7. Verify. Re-render the page, parse the delivered markup, compare it against visible content, and run the relevant current validator. Record warnings and feature ineligibility honestly.

Guardrails

• Structured data does not guarantee a rich result, AI citation, indexation, ranking, or traffic.
• Do not add “AI schema,” invisible facts, fabricated reviews, self-serving ratings, or non-existent offers.
• Do not convert a page’s hidden/internal data into public markup without authorization and privacy review.
• JavaScript-injected markup should be tested in the actual rendered output; critical metadata must not be assumed visible to a crawler merely because application code contains it.
• Current official docs outrank stale type lists, third-party generators, and historical rollout claims.

Formal evidence handoff

When this work needs a cross-team, approval-ready plan, package evidence-bound findings as an immutable seo-findings.json bundle using the checked-out suite contract. Keep every referenced capture/source below raw/, retain declined claims and limitations, and run python "<suite-root>/scripts/validate_seo_findings.py" validate-findings <bundle>/seo-findings.json --bundle <bundle>. Send only a passing bundle to seo-action-plan; otherwise label the handoff provisional.

Output

Return a detection/validation report, field-to-evidence mapping, precise implementation options, and optional JSON-LD snippet only when the required facts are supplied. Label placeholders and approvals. Include test/rollback steps and never present generated code as already deployed or feature-eligible.