Skip to content

Schema and Structured Data for GEO

Structured data lifts AI citation rates by pre-packaging content in the Q&A and step formats engines reuse — studies report 2.7x–3.2x FAQPage gains.

Related lesson: Machine-Readable Corpora — this concept features in a hands-on lesson with quizzes.

Independent studies report FAQPage citation improvements of 2.7x to 3.2x (Frase.io; DEV Community) because structured data reduces extraction effort during indexing. Schema's primary value has shifted from SEO to AI citation — ChatGPT, Perplexity, Gemini, and Claude process it at indexing time. This site auto-injects Article, FAQPage, HowTo, DefinedTerm, and BreadcrumbList schemas via hooks/structured_data.py, plus a site-wide DefinedTermSet on the concepts glossary.

Channel FAQPage / HowTo rich results Schema citation value
Google Search (classic) Restricted to government/health sites since Aug 2023 Low for most dev docs
Google AI Overviews Processed at index time High — 3.2x appearance lift (Frase.io)
ChatGPT Not rendered live; indexed content used High — favors Q&A format
Perplexity Indexed schema aids entity disambiguation High — citation footnotes
Gemini Renders JavaScript; processes schema High

Chatbots do not read JSON-LD on live fetch. The benefit accrues at indexing and training.

The three schema types

FAQPage

Structures Q&A blocks for direct AI extraction. Keep answers 40–80 words — standalone, citable length.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "What is an agent harness?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "An agent harness is scaffolding that surrounds an AI agent loop — managing context, tool calls, error recovery, and output formatting. It separates infrastructure concerns from reasoning logic."
    }
  }]
}

The hook detects ## FAQ or ## Frequently Asked Questions followed by **Question** / answer pairs and emits this schema automatically.

HowTo

Converts numbered step lists into extractable blocks — each step is a quotable unit.

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to configure prompt caching",
  "step": [
    { "@type": "HowToStep", "position": 1, "text": "Enable the caching header in your API request." },
    { "@type": "HowToStep", "position": 2, "text": "Place stable content at the top of the context window." }
  ]
}

Auto-detection triggers on ordered lists (<ol>) with 3+ items, restricted to patterns/ and techniques/ paths. Extend _HOWTO_PATHS in hooks/structured_data.py to widen coverage.

DefinedTerm

Machine-readable definitions for named concepts — useful where terms like "agent" are ambiguous across tools. Every coined-concept leaf page emits one DefinedTerm, anchored to a single DefinedTermSet on /concepts/:

{
  "@context": "https://schema.org",
  "@type": "DefinedTerm",
  "name": "Harness Engineering",
  "description": "The discipline of designing agent environments so agents reliably produce correct results.",
  "alternateName": ["agent environment design", "environment design for agents"],
  "url": "https://agentpatterns.ai/agent-design/harness-engineering/",
  "inDefinedTermSet": "https://agentpatterns.ai/concepts/"
}

The hook maps frontmatter to schema fields automatically:

DefinedTerm field Source
name term: frontmatter — the clean moniker — falling back to title: (SEO-shaped)
description description: frontmatter (the page's one-line definition)
alternateName aliases: frontmatter — the page's strongest vocabulary-ownership signal
url / inDefinedTermSet canonical page URL / the /concepts/ glossary

Gated to coined-concept sections (_DEFINED_TERM_PATHS) plus _DEFINED_TERM_ALLOW exceptions; articles/, tools/, and training/ are excluded — they describe terms rather than coin them.

How this site generates schema

The hook runs at on_post_page and injects JSON-LD into every page's <head>:

graph LR
    A[MkDocs builds page] --> B[on_post_page hook fires]
    B --> C[Organization schema]
    B --> D{Is homepage?}
    D -- yes --> E[WebSite schema]
    B --> F[Article schema]
    B --> G[BreadcrumbList schema]
    B --> H{FAQ heading detected?}
    H -- yes --> I[FAQPage schema]
    B --> J{Ordered list 3+ steps and patterns/ or techniques/ path?}
    J -- yes --> K[HowTo schema]
    B --> M{Coined-concept section?}
    M -- yes --> N[DefinedTerm schema]
    C & E & F & G & I & K & N --> L[Inject before head close]

No per-page config — add an FAQ section and schema appears; a coined-concept page emits a DefinedTerm with no config at all (and a cleaner one if you set term:).

Writing for schema auto-detection

To trigger each schema type, write in the shape the hook detects:

  • FAQPage — a ## FAQ (or ## Frequently Asked Questions) heading with **Question?** lines followed by paragraph answers. Keep answers 40–80 words and standalone.
  • HowTo — an ordered list of 3+ steps under patterns/ or techniques/. Write each step as a self-contained sentence, since the hook extracts it as a standalone HowToStep.text.
  • DefinedTerm — nothing in the body. Set term: to the bare moniker when title: is a headline (otherwise name falls back to the SEO title), keep description: a one-line definition, and list every searchable alternate name under aliases:.

When this backfires

Schema lifts citation rates in aggregate, but fails under specific conditions:

  • Stale schema after edits — if body text drifts from the auto-generated schema (for example, FAQ answers edited outside the **Question** / answer format), engines see contradictory signals and may deprioritize the page.
  • Thin or low-authority domains — lift is relative to baseline authority. Schema accelerates the existing topical-authority signal. It does not manufacture credibility.
  • Wrong type for content shape — HowTo on conceptual explanations, or FAQPage on unrelated Q&A, causes schema–content mismatch that validators flag and engines may penalize.
  • Indexing pipeline changes — benefit accrues at indexing time. If a provider downweights structured data, pages relying on the lift lose it with no on-page change.

Testing schema

Tool Purpose URL
Google Rich Results Test Validates Google-supported rich results (Article, BreadcrumbList) https://search.google.com/test/rich-results
Schema Markup Validator Validates all schema.org types without Google restrictions https://validator.schema.org/
Google Search Console Monitors rich result impressions and errors post-deployment https://search.google.com/search-console

Run locally:

mkdocs build --strict
# Paste a built page's <head> into the Schema Markup Validator

Sources

FAQ

How much do independent studies say FAQPage schema improves AI citation rates?

Independent studies report FAQPage schema lifting AI citation appearances by 2.7x to 3.2x compared to unstructured pages (Frase.io; DEV Community), because structured data reduces extraction effort during indexing. Schema's primary value has shifted from Google rich results to this AI-citation effect — cited by ChatGPT, Perplexity, Gemini, and Claude at indexing time, not on live fetch.

Does ChatGPT or Perplexity read a page's JSON-LD when they visit it live?

No. ChatGPT, Perplexity, and most AI engines do not parse a page's JSON-LD during a live fetch — the hook-injected schema is processed at indexing and training time instead, not the moment they visit the page. Gemini is the exception: it renders JavaScript and processes schema in real time, unlike the others.

What exact heading and format triggers automatic FAQPage schema on this site?

Write a ## FAQ (or ## Frequently Asked Questions) heading followed by bold-paragraph questions and plain-text answer paragraphs — the same **Question** / answer pattern this page uses. The hooks/structured_data.py hook scans for that exact shape at build time and emits a FAQPage JSON-LD block automatically; no frontmatter flag or manual schema authoring is required.

Why does adding schema markup not fix citation problems on a low-authority page?

Schema markup amplifies an existing signal rather than creating one — its citation lift is relative to a page's baseline authority. On a thin or low-authority page, adding FAQPage or HowTo JSON-LD accelerates whatever topical authority the page already has, but it does not manufacture credibility the page lacks.

Key Takeaways

  • Schema's payoff is now AI citation, not Google rich results — benefit accrues at indexing time, not on live fetch.
  • This site auto-injects FAQPage, HowTo, and DefinedTerm schema from page structure and frontmatter — no per-page config.
  • Match the schema type to content shape; mismatched types (HowTo on prose, stale FAQ answers) can deprioritize a page.
Established — multiple independent sources Last reviewed: 2026-06-13