Adding Schema Markup

Adding Schema Markup

Overview

Schema is the language Google and LLMs use to understand a page. Crawlers extract entities, relationships, and facts from JSON-LD with much higher confidence than from raw HTML. In 2026 the Google rich-result surface has narrowed sharply (HowTo retired, FAQPage limited to gov/health authority sites) [1][2], but the AI-citation upside has grown: pages with well-formed structured data are cited 2.5–3.2× more often in ChatGPT, Perplexity, and AI Overviews than unstructured pages [3][4].

The job: pick the right type, populate the required + key recommended fields from content that actually exists on the page, validate, ship.

When to Use

• A new content page (article, product, itinerary) is going live
• A page already has bootstrap-level Organization + WebSite schema and now needs page-specific markup
• An audit flagged "no structured data" on important pages
• A page is getting AI-search impressions but few citations — schema gap is a likely cause

Don't use for: thin pages with no real content (Google penalizes schema-for-content-that-isn't-there [1]), legal/disclaimer/utility pages, or pages already covered by a route-level generator.

Schema Type Decision Table

The Flow

1. Identify the page type. Read the file (app/blog/[slug]/page.tsx, pages/products/[id].astro, etc.) and the rendered content. Pick from the table above.
2. Pick the schema type. If unsure between two (Article vs BlogPosting), default to Article — it's a superset.
3. Populate from real content. Pull headline, datePublished, author, image, description from the actual page data — never invent fields. Required fields per type are documented at schema.org and Google Search Central [6][7].
4. Wrap in one block. Use a single <script type="application/ld+json"> containing an @graph when the page has multiple entities that reference each other (Article → Author → Organization) [8]. Use separate blocks only for fully independent entities. Reuse the helper from seo-bootstrap/templates/ so the Organization @id matches site-wide.
5. Validate. Run the offline schema validator scripts/schema-check.js (node scripts/schema-check.js --file <path>) or scripts/schema-quick.py (python scripts/schema-quick.py --file <path>). This instantly checks JSON-LD syntax, catches schema.org casing errors (like Website vs WebSite), and validates Google Rich Result required/recommended fields without browser switching or external pip dependencies. If the schema-validate MCP is installed, it can also be called. Use external tools (Schema Markup Validator and Google Rich Results Test) as secondary browser confirmation [9].
6. Open one PR per page or per route group. Commit message: feat(seo): add <Type> schema to <route>.

Common Mistakes

• @type: "Website" (capital S). schema.org is case-sensitive — it's WebSite. Validators silently drop the wrong casing. Same trap as bootstrap.
• Missing @context: "https://schema.org". No context, no parse.
• JSON-LD inside <noscript> or rendered only client-side after hydration. Most LLM crawlers and many SERP features read the initial HTML — schema must be in SSR output.
• Schema for content that isn't on the page. Inventing FAQ Q&A in JSON-LD that doesn't appear visibly is a Google manual-action target [1].
• Faking AggregateRating. Same — manual action and AI engines downgrade trust.
• Duplicating entities across blocks instead of using @id references inside an @graph [8].
• Forgetting to update dateModified on refreshes — AI engines lean on freshness signals [4].

Quick Reference

// Article (minimum)
{ "@context":"https://schema.org","@type":"Article",
  "headline":"...", "datePublished":"2026-04-26", "author":{"@type":"Person","name":"..."} }

// Product
{ "@context":"https://schema.org","@type":"Product",
  "name":"...", "image":"...", "offers":{"@type":"Offer","price":"29","priceCurrency":"USD","availability":"https://schema.org/InStock"} }

// FAQPage
{ "@context":"https://schema.org","@type":"FAQPage",
  "mainEntity":[{"@type":"Question","name":"...","acceptedAnswer":{"@type":"Answer","text":"..."}}] }

// BreadcrumbList
{ "@context":"https://schema.org","@type":"BreadcrumbList",
  "itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://..."}] }

// TouristTrip
{ "@context":"https://schema.org","@type":"TouristTrip",
  "name":"...", "itinerary":{"@type":"ItemList","itemListElement":[/* TouristAttraction entries */]},
  "provider":{"@id":"https://site.com/#org"} }

Lifecycle

• Bootstrap-time: Organization + WebSite only, in root layout. Handled by seo-bootstrap.
• Growth-time: add page-type schema (Article, Product, TouristTrip) as content ships. This skill.
• Mature / decay: schema.org deprecates types and Google retires rich-result surfaces (HowTo gone, FAQPage display narrowed) [1][2]. Re-audit annually; remove rich-result-only schema that no longer renders, but keep AI-citation-relevant types like FAQPage and HowTo for LLM consumption [4].

What next

Pair with optimizing-on-page for the full per-page polish loop (titles, H1, internal links, schema). Run auditing-technical-seo quarterly to catch schema drift.

Sources

Citations [1]–[9] resolve in SOURCES.md.