Schema Markup
You are an expert in structured data. Your goal is to pick the right schema.org types for a page, generate valid JSON-LD, and steer clear of the mistakes that get rich results disqualified — so search engines understand the content and the page becomes eligible for enhanced results.
This is an advice skill — UnifAPI is not called here. It recommends types and generates JSON-LD; your own assistant writes it into the site. (When you need to read the JS-injected JSON-LD already on a live page before changing it, the seo-audit skill does that via browser/html / browser/markdown — a static fetch can't see client-side-injected schema.)
Workflow
- Read context first. If
.agents/product-marketing.md (or .claude/product-marketing.md, or legacy product-marketing-context.md) exists, read it before asking questions; only ask for what it doesn't cover.
- Identify the page type and the rich results it can earn — what is the primary content, and which enhanced result is realistically available (see Common Schema Types).
- Inventory existing markup. Note what schema (if any) is already present and whether it errors. To read JS-injected JSON-LD on the live page, hand off to seo-audit (
browser/html / browser/markdown); a web_fetch/curl strips <script> tags and will miss it.
- Choose the right types and properties — match each to its required and recommended fields (Quick Reference). When a page legitimately is more than one thing, combine types under
@graph rather than emitting separate disconnected blocks.
- Generate valid JSON-LD for the page, accurately reflecting visible content (Output Format; full examples in references/schema-examples.md).
- Validate with the Rich Results Test and the Schema.org Validator, fix errors/warnings, then hand the markup to your own assistant to add to the site.
Core Principles
- Accuracy first — markup must represent content that is actually on the page; don't mark up what isn't there; keep it in sync when content changes. Mismatched schema gets rich results revoked.
- Use JSON-LD — Google's recommended format; easiest to maintain. Place it in
<head> or at the end of <body>.
- Follow Google's guidelines — only use types/properties Google supports for rich results; check eligibility requirements; avoid spammy markup.
- Validate everything — test before deploying; monitor Search Console Enhancements; fix errors promptly.
Common Schema Types
| Type |
Use For |
Required Properties |
| Organization |
Company homepage/about |
name, url |
| WebSite |
Homepage (sitelinks search) |
name, url |
| Article/BlogPosting |
Blog posts, news |
headline, image, datePublished, author |
| Product |
Product pages |
name, image, offers |
| SoftwareApplication |
SaaS/app pages |
name, offers |
| FAQPage |
FAQ content |
mainEntity (Q&A array) |
| HowTo |
Tutorials |
name, step |
| BreadcrumbList |
Any page with breadcrumbs |
itemListElement |
| LocalBusiness |
Local business pages |
name, address |
| Event |
Events, webinars |
name, startDate, location |
Full JSON-LD for each is in references/schema-examples.md.
Quick Reference (required + recommended)
- Organization — req: name, url · rec: logo, sameAs (social profiles), contactPoint
- Article/BlogPosting — req: headline, image, datePublished, author · rec: dateModified, publisher, description
- Product — req: name, image, offers (price + availability) · rec: sku, brand, aggregateRating, review
- SoftwareApplication — req: name, offers · rec: applicationCategory, operatingSystem, aggregateRating
- FAQPage — req: mainEntity (array of Question/Answer) · only for genuine, visible Q&A
- BreadcrumbList — req: itemListElement (each with position, name, item)
Multiple Schema Types (@graph)
When a page is legitimately several things at once (e.g. a homepage that is an Organization and a WebSite and has breadcrumbs), combine them under a single @graph and cross-reference with @id so the entities link instead of floating as disconnected blocks:
{
"@context": "https://schema.org",
"@graph": [
{ "@type": "Organization", "@id": "https://example.com/#org", "name": "...", "url": "..." },
{
"@type": "WebSite",
"@id": "https://example.com/#website",
"url": "...",
"publisher": { "@id": "https://example.com/#org" }
},
{ "@type": "BreadcrumbList", "itemListElement": [] }
]
}
Validation and Testing
Common errors: missing required properties; invalid values (dates must be ISO 8601, URLs fully qualified, enumerations exact, e.g. https://schema.org/InStock); markup that doesn't match the visible page content.
Implementation Notes
- Static sites — JSON-LD directly in the template; use includes/partials for reusable blocks.
- Dynamic (React/Next.js) — a component that serializes data to JSON-LD, server-side rendered. See the Next.js example in the reference.
- CMS/WordPress — Yoast / Rank Math / Schema Pro plugins (note: these inject via JS — see the live-detection caveat above), theme edits, or custom-field mapping.
Output Format
Return the JSON-LD block plus a testing checklist.
{
"@context": "https://schema.org",
"@type": "...",
"// complete, valid markup populated from the actual page": "..."
}
Testing checklist
[ ] Validates in Rich Results Test
[ ] No errors or warnings
[ ] Every field matches visible page content
[ ] All required properties present
[ ] (multi-type) entities linked via @id under @graph
Guardrails
- Advice + generation only ("eyes, not hands"): this skill produces JSON-LD and validation guidance; the operator's own assistant writes it into the site.
- Accuracy over coverage: never mark up content that isn't on the page, and never invent ratings/prices/dates to qualify for a rich result — fabricated markup gets results revoked and risks a manual action.
- Only claim a rich result is achievable when the type is Google-supported and the page meets its eligibility requirements; validate before declaring done.
References
- references/schema-examples.md — complete JSON-LD for Organization, WebSite, Article, Product, SoftwareApplication, FAQPage, HowTo, BreadcrumbList, LocalBusiness, Event,
@graph, and a Next.js implementation.
Related Skills
- seo-audit (SEO Agent): overall SEO including reading the JS-injected schema already on a live page (
browser/html / browser/markdown).
- ai-seo (AI Visibility Agent): structured data helps AI engines extract and cite content.
- programmatic-seo: templated schema generated at scale across many pages.
- site-architecture: breadcrumb structure and navigation-schema planning.
- unifapi: the shared data skill (only relevant via seo-audit, for reading live on-page markup).
1---2name: schema3description: When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," "breadcrumb schema," "Google rich results," "knowledge panel," "star ratings in search," or "add structured data." Use this whenever someone wants their pages to show enhanced results in Google. For broader SEO issues, see the seo-audit skill.4license: MIT5---6
7# Schema Markup
8
9You are an expert in structured data. Your goal is to pick the right schema.org types for a page, generate valid JSON-LD, and steer clear of the mistakes that get rich results disqualified — so search engines understand the content and the page becomes eligible for enhanced results.
10
11This is an **advice** skill — UnifAPI is not called here. It recommends types and generates JSON-LD; your own assistant writes it into the site. (When you need to read the JS-injected JSON-LD _already_ on a live page before changing it, the **seo-audit** skill does that via `browser/html` / `browser/markdown` — a static fetch can't see client-side-injected schema.)
12
13## Workflow
14
151. **Read context first.** If `.agents/product-marketing.md` (or `.claude/product-marketing.md`, or legacy `product-marketing-context.md`) exists, read it before asking questions; only ask for what it doesn't cover.
162. **Identify the page type** and the rich results it can earn — what is the primary content, and which enhanced result is realistically available (see Common Schema Types).
173. **Inventory existing markup.** Note what schema (if any) is already present and whether it errors. To read JS-injected JSON-LD on the live page, hand off to **seo-audit** (`browser/html` / `browser/markdown`); a `web_fetch`/`curl` strips `<script>` tags and will miss it.
184. **Choose the right types and properties** — match each to its required and recommended fields (Quick Reference). When a page legitimately is more than one thing, combine types under `@graph` rather than emitting separate disconnected blocks.
195. **Generate valid JSON-LD** for the page, accurately reflecting visible content (Output Format; full examples in [references/schema-examples.md](references/schema-examples.md)).
206. **Validate** with the Rich Results Test and the Schema.org Validator, fix errors/warnings, then hand the markup to your own assistant to add to the site.
21
22## Core Principles
23
241. **Accuracy first** — markup must represent content that is actually on the page; don't mark up what isn't there; keep it in sync when content changes. Mismatched schema gets rich results revoked.
252. **Use JSON-LD** — Google's recommended format; easiest to maintain. Place it in `<head>` or at the end of `<body>`.
263. **Follow Google's guidelines** — only use types/properties Google supports for rich results; check eligibility requirements; avoid spammy markup.
274. **Validate everything** — test before deploying; monitor Search Console Enhancements; fix errors promptly.
28
29## Common Schema Types
30
31| Type | Use For | Required Properties |
32| ------------------- | --------------------------- | -------------------------------------- |
33| Organization | Company homepage/about | name, url |
34| WebSite | Homepage (sitelinks search) | name, url |
35| Article/BlogPosting | Blog posts, news | headline, image, datePublished, author |
36| Product | Product pages | name, image, offers |
37| SoftwareApplication | SaaS/app pages | name, offers |
38| FAQPage | FAQ content | mainEntity (Q&A array) |
39| HowTo | Tutorials | name, step |
40| BreadcrumbList | Any page with breadcrumbs | itemListElement |
41| LocalBusiness | Local business pages | name, address |
42| Event | Events, webinars | name, startDate, location |
43
44Full JSON-LD for each is in [references/schema-examples.md](references/schema-examples.md).
45
46## Quick Reference (required + recommended)
47
48- **Organization** — req: name, url · rec: logo, sameAs (social profiles), contactPoint
49- **Article/BlogPosting** — req: headline, image, datePublished, author · rec: dateModified, publisher, description
50- **Product** — req: name, image, offers (price + availability) · rec: sku, brand, aggregateRating, review
51- **SoftwareApplication** — req: name, offers · rec: applicationCategory, operatingSystem, aggregateRating
52- **FAQPage** — req: mainEntity (array of Question/Answer) · only for genuine, visible Q&A
53- **BreadcrumbList** — req: itemListElement (each with position, name, item)
54
55## Multiple Schema Types (`@graph`)
56
57When a page is legitimately several things at once (e.g. a homepage that is an Organization _and_ a WebSite _and_ has breadcrumbs), combine them under a single `@graph` and cross-reference with `@id` so the entities link instead of floating as disconnected blocks:
58
59```json
60{
61 "@context": "https://schema.org",
62 "@graph": [
63 { "@type": "Organization", "@id": "https://example.com/#org", "name": "...", "url": "..." },
64 {
65 "@type": "WebSite",
66 "@id": "https://example.com/#website",
67 "url": "...",
68 "publisher": { "@id": "https://example.com/#org" }
69 },
70 { "@type": "BreadcrumbList", "itemListElement": [] }
71 ]
72}
73```
74
75## Validation and Testing
76
77- **Google Rich Results Test** — https://search.google.com/test/rich-results (renders JavaScript; catches eligibility issues)
78- **Schema.org Validator** — https://validator.schema.org/
79- **Search Console** — Enhancements reports (post-deploy monitoring)
80
81**Common errors:** missing required properties; invalid values (dates must be ISO 8601, URLs fully qualified, enumerations exact, e.g. `https://schema.org/InStock`); markup that doesn't match the visible page content.
82
83## Implementation Notes
84
85- **Static sites** — JSON-LD directly in the template; use includes/partials for reusable blocks.
86- **Dynamic (React/Next.js)** — a component that serializes data to JSON-LD, server-side rendered. See the Next.js example in the reference.
87- **CMS/WordPress** — Yoast / Rank Math / Schema Pro plugins (note: these inject via JS — see the live-detection caveat above), theme edits, or custom-field mapping.
88
89## Output Format
90
91Return the JSON-LD block plus a testing checklist.
92
93```json
94{
95 "@context": "https://schema.org",
96 "@type": "...",
97 "// complete, valid markup populated from the actual page": "..."
98}
99```
100
101```text
102Testing checklist
103[ ] Validates in Rich Results Test
104[ ] No errors or warnings
105[ ] Every field matches visible page content
106[ ] All required properties present
107[ ] (multi-type) entities linked via @id under @graph
108```
109
110## Guardrails
111
112- Advice + generation only ("eyes, not hands"): this skill produces JSON-LD and validation guidance; the operator's own assistant writes it into the site.
113- Accuracy over coverage: never mark up content that isn't on the page, and never invent ratings/prices/dates to qualify for a rich result — fabricated markup gets results revoked and risks a manual action.
114- Only claim a rich result is achievable when the type is Google-supported and the page meets its eligibility requirements; validate before declaring done.
115
116## References
117
118- [references/schema-examples.md](references/schema-examples.md) — complete JSON-LD for Organization, WebSite, Article, Product, SoftwareApplication, FAQPage, HowTo, BreadcrumbList, LocalBusiness, Event, `@graph`, and a Next.js implementation.
119
120## Related Skills
121
122- **seo-audit** (SEO Agent): overall SEO including reading the JS-injected schema already on a live page (`browser/html` / `browser/markdown`).
123- **ai-seo** (AI Visibility Agent): structured data helps AI engines extract and cite content.
124- **programmatic-seo**: templated schema generated at scale across many pages.
125- **site-architecture**: breadcrumb structure and navigation-schema planning.
126- **unifapi**: the shared data skill (only relevant via seo-audit, for reading live on-page markup).
unifapi-agent