---
title: "Schema and Structured Data for GEO — AI Citation Guide"
term: "Schema and Structured Data"
description: "FAQPage JSON-LD yields measurable citation lifts in AI responses (2.7x–3.2x across studies). Implementation guide for FAQPage, HowTo, and DefinedTerm schema in MkDocs Material."
tags:
  - geo
  - workflows
  - tool-agnostic
  - technique
aliases:
  - Schema Markup
  - Structured Data for GEO
  - JSON-LD for AI
last_reviewed: 2026-06-13
maturity: established
---

# 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](https://learn.agentpatterns.ai/geo/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](https://www.frase.io/blog/faq-schema-ai-search-geo-aeo); [DEV Community](https://dev.to/wilow445/schemaorg-is-your-secret-weapon-for-ai-citations-heres-the-data-1if3)) 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](../concepts.md).

## What changed: Google vs AI search

| 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.

```json
{
  "@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.

```json
{
  "@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/`:

```json
{
  "@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>`:

```mermaid
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](topical-authority.md). 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](gsc-search-console-monitoring.md) | Monitors rich result impressions and errors post-deployment | https://search.google.com/search-console |

Run locally:

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

## Sources

- [FAQPage Structured Data — Google Search Central](https://developers.google.com/search/docs/appearance/structured-data/faqpage) — spec and eligibility
- [DefinedTerm — Schema.org](https://schema.org/DefinedTerm) — official spec
- [DefinedTermSet for Industry Terminology — DEV](https://dev.to/mark_mcneece_365i/using-schemaorgs-definedtermset-for-industry-terminology-a-case-study-1mm2) — fragment `@id` and TermSet linking
- [Schema.org Is Your Secret Weapon for AI Citations — DEV](https://dev.to/wilow445/schemaorg-is-your-secret-weapon-for-ai-citations-heres-the-data-1if3) — FAQPage +45%, HowTo +38%
- [FAQ Schema for AI Search, GEO and AEO — Frase.io](https://www.frase.io/blog/faq-schema-ai-search-geo-aeo) — 3.2x AI Overview lift
- [Schema Markup and AI in 2025 — Searchviu](https://www.searchviu.com/en/schema-markup-and-ai-in-2025-what-chatgpt-claude-perplexity-gemini-really-see/) — JSON-LD ignored on live fetch; benefits at indexing
- [Structured Data in MkDocs](https://v-schipka.github.io/posts/schema-in-mkdocs/) — MkDocs Material approach
- [Structured Data for SEO and GEO — Digidop](https://www.digidop.com/blog/structured-data-secret-weapon-seo) — GPT-4 accuracy 16% → 54%

## 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](https://www.frase.io/blog/faq-schema-ai-search-geo-aeo); [DEV Community](https://dev.to/wilow445/schemaorg-is-your-secret-weapon-for-ai-citations-heres-the-data-1if3)), 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](topical-authority.md) 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.

## Related

- [GEO for Technical Docs](geo-for-technical-docs.md) — schema type selection checklist and per-format GEO priorities
- [How AI Engines Cite](how-ai-engines-cite.md) — citation mechanisms schema markup targets
- [Answer-First Writing](answer-first-writing.md) — content structure that complements schema auto-detection
- [SEO vs GEO](seo-vs-geo.md) — how structured data signals differ between traditional SEO and AI citation optimization
- [llms.txt](llms-txt.md) — complementary machine-readable format for AI discoverability
- [AI Crawler Policy](ai-crawler-policy.md) — controlling which crawlers index your structured data
- [Measuring GEO Performance](measuring-geo-performance.md) — tracking schema citation lift
- [What Is GEO](what-is-geo.md) — foundational concepts behind generative engine optimization