Plain HTML tells AI agents what's on the page. Schema.org JSON-LD tells them what it means. The difference shows up in citation rates: pages with proper JSON-LD get cited 4-7× more often by Perplexity, ChatGPT browse, and Google AI Overviews than pages without.
This guide gives you the three blocks every site needs in 2026: Organization, WebSite, and FAQPage. Copy-paste, replace placeholders, ship.
Why JSON-LD specifically
Schema.org supports three syntaxes: microdata, RDFa, and JSON-LD. Google has recommended JSON-LD since 2015, and AI agents follow suit because:
- Separable from markup. JSON-LD sits in a
<script>tag — agents parse it without walking your DOM. - Order-independent. Microdata requires the markup order to mirror semantics. JSON-LD doesn't.
- Easier to validate. Tools like Google's Rich Results Test eat JSON-LD natively.
Block 1: Organization
Goes in <head> on every page (or at least on home, about, and contact). Declares who you are.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Your Brand",
"url": "https://yoursite.com",
"logo": "https://yoursite.com/logo.png",
"description": "One-sentence pitch.",
"sameAs": [
"https://twitter.com/yourhandle",
"https://github.com/yourorg",
"https://www.linkedin.com/company/yourorg"
],
"contactPoint": {
"@type": "ContactPoint",
"contactType": "customer service",
"email": "[email protected]",
"availableLanguage": "English"
}
}
</script>Three things to get right:
sameAsis your social-graph anchor. Include canonical profiles only — agents use this to dedupe across the web.descriptionis your elevator pitch. Match what you'd want quoted in an AI answer.logoshould be a PNG with a transparent background, ideally 512×512.
Block 2: WebSite + SearchAction
This unlocks the "sitelinks search box" — agents (and Google) can offer in-line search across your site.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "WebSite",
"name": "Your Brand",
"url": "https://yoursite.com",
"potentialAction": {
"@type": "SearchAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": "https://yoursite.com/search?q={search_term_string}"
},
"query-input": "required name=search_term_string"
}
}
</script>Replace the urlTemplate with your real search URL. If you don't have on-site search, skip this block — declaring it without a working endpoint hurts trust.
Block 3: FAQPage
This is the highest-leverage block for AI citations. Agents lift FAQ answers verbatim into responses.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "How long does shipping take?",
"acceptedAnswer": {
"@type": "Answer",
"text": "2-5 business days within the US; 7-14 days international. Tracking included on every order."
}
},
{
"@type": "Question",
"name": "Do you accept returns?",
"acceptedAnswer": {
"@type": "Answer",
"text": "30-day window for unused items. Email [email protected] to start; we cover return shipping for US orders."
}
},
{
"@type": "Question",
"name": "Is this hand-made or factory-produced?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Hand-finished in our Portland workshop. The base components are produced by our partner factory in Vermont."
}
}
]
}
</script>Three rules:
- Match the visible page. The FAQ in your JSON-LD must appear as readable content elsewhere on the page. Google penalises invisible structured data.
- Direct answers. Write the
textas a self-contained answer — assume an agent will quote it without context. - 10–25 questions sweet spot. Below 10 looks thin; above 25 dilutes the strongest answers.
The @graph pattern (combine multiple blocks cleanly)
If you ship Organization + WebSite + Article on the same page, use @graph to keep them in one script tag:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@graph": [
{ "@type": "Organization", "@id": "https://yoursite.com/#org", "name": "Your Brand", "url": "https://yoursite.com" },
{ "@type": "WebSite", "@id": "https://yoursite.com/#site", "url": "https://yoursite.com", "publisher": { "@id": "https://yoursite.com/#org" } },
{ "@type": "Article", "headline": "Your post title", "author": { "@id": "https://yoursite.com/#org" } }
]
}
</script>Use @id to cross-link entities. Our scanner parses this pattern correctly; many older SEO plugins do not.
Where to put it on common stacks
- WordPress (no plugin): theme's
header.phpinside<head>, before</head>. - WordPress + Yoast/Rank Math: these emit Organization + WebSite for you. Add FAQPage manually via WPCode or a custom block.
- Next.js: use
generateMetadataand the<Script>component, or inline viadangerouslySetInnerHTML. - Webflow: Project Settings → Custom Code → Head Code.
- Shopify: theme.liquid before
</head>. - Tilda: Site Settings → More → HTML Code in HEAD.
Validate before shipping
- Google Rich Results Test — flags JSON-LD syntax errors and missing required fields.
- Schema.org Validator — strict against the official schema definition.
npx agentfix-mini-scanner yoursite.com— checks Organization, WebSite, FAQ presence and JSON-LD parseability.
Want all three blocks generated from your real content?
The AgentFix Pack crawls your site, extracts your real name, description, FAQs, social links, and emits ready-to-paste JSON-LD blocks. It also generates /llms.txt, /llms-full.txt, A2A agent-card.json, and MCP server-card.json. From $1 one-time.