Schema.org is a vocabulary for tagging the meaning of content on a page. The traditional reason to use it is to get rich results in Google. The newer reason is that some AI engines parse it as a structured signal of what the page is about.
For API docs, a few schema types are worth knowing.
TechArticle
The most common type for a how-to or reference page. It tells the model the page is a technical document with steps or examples.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "Authentication with API keys",
"datePublished": "2026-03-12",
"dateModified": "2026-05-22",
"author": { "@type": "Organization", "name": "Acme" },
"about": "API authentication"
}
</script>
The fields that matter most are headline, dateModified, and about. Author matters for citation.
APIReference
A newer type meant specifically for API reference pages. Support is uneven. Worth adding when the page documents a single endpoint or method.
SoftwareSourceCode
For example pages. Lets you tag the language and the relationship between the snippet and the runtime it works in.
What it actually does
Schema does not get you cited on its own. It makes the page legible. Models that look at structured data get a clean answer to "what is this page about" without parsing the prose.
A few practical notes:
- Generate the schema, do not write it by hand. Manually written fields drift from the page content.
dateModifiedshould match your last real update. Models use it as a recency signal.- Do not over-tag. One type per page. Extra schema slows the page and confuses parsers.
Where to put it
Inline in <head> is fine. JSON-LD is the recommended format because it does not interfere with the document body. Avoid Microdata for new pages.
Common validation issues
A few things go wrong often enough to call out:
Missing required fields. TechArticle requires headline. BreadcrumbList requires positions. Google's Rich Results Test catches the obvious cases; the Schema Markup Validator catches more.
Dates without timezones. A date like "2026-03-12" is fine. A datetime like "2026-03-12T10:30:00" without a Z or offset is ambiguous and gets dropped silently by some parsers. If you include a time, include the zone.
Author as a string. "author": "Acme" is technically allowed but weaker than "author": { "@type": "Organization", "name": "Acme" }. The structured form lets the engine link the page back to your organization's other content.
Headlines that disagree with the <h1>. Search engines reconcile this in your favor most of the time. AI parsers sometimes do not, and the schema headline wins. Keep them in sync.
How to test if it is working
There is no perfect test, since AI engines do not surface their parsing the way search engines do. A few practical checks:
- Validate. Run every page through the Schema Markup Validator. Errors here cascade silently into engine ignored-ness.
- Inspect with Google's Rich Results Test. Not because you care about rich results, but because it tells you what a major parser sees on the page. If the parser can extract the structured data, others probably can too.
- Check what gets cited. When an AI engine cites your page, the citation text often draws from
headlineor from your<title>. If the citations look wrong, that is a clue. - Watch your referral logs. Some AI traffic shows up with identifiable referrers. The page they reach is the page the engine picked from your schema and links.
The schema is rarely the bottleneck. Bad content with good schema does not get cited. Good content with no schema still gets cited, usually less efficiently. The combination of correct schema plus content that survives being read in chunks is the goal.
