Schema Markup
Implement schema.org markup that helps search engines understand content and enables rich results.
What to establish about the page
If .claude/product-marketing-context.md exists, read first. Only ask for what's not covered.
- Page Type - what kind of page, primary content, what rich results are possible
- Current State - existing schema, implementation errors, rich results already appearing
- Goals - which rich results are targeted, business value
- Data & Stack - what data is available to populate the schema, tech stack (static, React/Next.js, CMS)
Core Principles
1. Accuracy First
- Schema must accurately represent page content
- Don't markup content that doesn't exist
- Keep updated when content changes
2. Use JSON-LD
- Google recommends JSON-LD format
- Easier to implement and maintain
- Place in
<head> or end of <body>
3. Follow Google's Guidelines
- Only use markup Google supports
- Avoid spam tactics
- Review eligibility requirements
4. Validate Everything
- Test before deploying
- Monitor Search Console
- Fix errors promptly
5. Its effect on AI citations is contested, so do not sell it as one
SE Ranking measured a 30-40% AI Overviews lift for pages carrying Article, FAQPage, HowTo or
Product schema; Ahrefs found no confirmed link and treats schema as general hygiene. Both readings
agree it does not hurt, and Perplexity does favour FAQ pages because they hand it an
already-extracted question and answer. Justify a schema backlog on rich-result eligibility, which
is measurable, and take any AI-visibility gain as a bonus. The evidence on both sides is owned by
programmatic-seo, in its references/geo-signals.md.
Common Schema Types
| Type |
Use For |
Required Properties |
| Organization |
Company homepage/about |
name, url |
| WebSite |
Homepage (search box) |
name, url |
| Article |
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 |
For complete JSON-LD examples: See references/schema-examples.md
Recommended Properties
Beyond the required properties in the table above:
| Type |
Recommended |
| Organization |
logo, sameAs (social profiles), contactPoint |
| Article/BlogPosting |
dateModified, publisher, description |
| Product |
sku, brand, aggregateRating, review |
Multiple Schema Types
You can combine multiple schema types on one page using @graph:
{
"@context": "https://schema.org",
"@graph": [
{ "@type": "Organization", ... },
{ "@type": "WebSite", ... },
{ "@type": "BreadcrumbList", ... }
]
}
Validation and Testing
Tools
Common Errors
Missing required properties - Check Google's documentation for required fields
Invalid values - Dates must be ISO 8601, URLs fully qualified, enumerations exact
Mismatch with page content - Schema doesn't match visible content
Implementation
Static Sites
- Add JSON-LD directly in HTML template
- Use includes/partials for reusable schema
Dynamic Sites (React, Next.js)
- Component that renders schema
- Server-side rendered for SEO
- Serialize data to JSON-LD
CMS / WordPress
- Plugins (Yoast, Rank Math, Schema Pro)
- Theme modifications
- Custom fields to structured data
Output Format
Schema Implementation
// Full JSON-LD code block
{
"@context": "https://schema.org",
"@type": "..."
// Complete markup
}
Testing Checklist
Related Skills
- programmatic-seo: For templated schema at scale
1---2name: seo-schema-markup3description: 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," or "breadcrumb schema."4---56# Schema Markup78Implement schema.org markup that helps search engines understand content and enables rich results.910## What to establish about the page11If `.claude/product-marketing-context.md` exists, read first. Only ask for what's not covered.12131. **Page Type** - what kind of page, primary content, what rich results are possible142. **Current State** - existing schema, implementation errors, rich results already appearing153. **Goals** - which rich results are targeted, business value164. **Data & Stack** - what data is available to populate the schema, tech stack (static, React/Next.js, CMS)1718---1920## Core Principles2122### 1. Accuracy First2324- Schema must accurately represent page content25- Don't markup content that doesn't exist26- Keep updated when content changes2728### 2. Use JSON-LD2930- Google recommends JSON-LD format31- Easier to implement and maintain32- Place in `<head>` or end of `<body>`3334### 3. Follow Google's Guidelines3536- Only use markup Google supports37- Avoid spam tactics38- Review eligibility requirements3940### 4. Validate Everything4142- Test before deploying43- Monitor Search Console44- Fix errors promptly4546### 5. Its effect on AI citations is contested, so do not sell it as one4748SE Ranking measured a 30-40% AI Overviews lift for pages carrying Article, FAQPage, HowTo or49Product schema; Ahrefs found no confirmed link and treats schema as general hygiene. Both readings50agree it does not hurt, and Perplexity does favour FAQ pages because they hand it an51already-extracted question and answer. Justify a schema backlog on rich-result eligibility, which52is measurable, and take any AI-visibility gain as a bonus. The evidence on both sides is owned by53`programmatic-seo`, in its `references/geo-signals.md`.5455---5657## Common Schema Types5859| Type | Use For | Required Properties |60| ------------------- | ------------------------- | -------------------------------------- |61| Organization | Company homepage/about | name, url |62| WebSite | Homepage (search box) | name, url |63| Article | Blog posts, news | headline, image, datePublished, author |64| Product | Product pages | name, image, offers |65| SoftwareApplication | SaaS/app pages | name, offers |66| FAQPage | FAQ content | mainEntity (Q&A array) |67| HowTo | Tutorials | name, step |68| BreadcrumbList | Any page with breadcrumbs | itemListElement |69| LocalBusiness | Local business pages | name, address |70| Event | Events, webinars | name, startDate, location |7172**For complete JSON-LD examples**: See [references/schema-examples.md](references/schema-examples.md)7374---7576## Recommended Properties7778Beyond the required properties in the table above:7980| Type | Recommended |81| --- | --- |82| Organization | logo, sameAs (social profiles), contactPoint |83| Article/BlogPosting | dateModified, publisher, description |84| Product | sku, brand, aggregateRating, review |8586---8788## Multiple Schema Types8990You can combine multiple schema types on one page using `@graph`:9192```json93{94 "@context": "https://schema.org",95 "@graph": [96 { "@type": "Organization", ... },97 { "@type": "WebSite", ... },98 { "@type": "BreadcrumbList", ... }99 ]100}101```102103---104105## Validation and Testing106107### Tools108109- **Google Rich Results Test**: https://search.google.com/test/rich-results110- **Schema.org Validator**: https://validator.schema.org/111- **Search Console**: Enhancements reports112113### Common Errors114115**Missing required properties** - Check Google's documentation for required fields116117**Invalid values** - Dates must be ISO 8601, URLs fully qualified, enumerations exact118119**Mismatch with page content** - Schema doesn't match visible content120121---122123## Implementation124125### Static Sites126127- Add JSON-LD directly in HTML template128- Use includes/partials for reusable schema129130### Dynamic Sites (React, Next.js)131132- Component that renders schema133- Server-side rendered for SEO134- Serialize data to JSON-LD135136### CMS / WordPress137138- Plugins (Yoast, Rank Math, Schema Pro)139- Theme modifications140- Custom fields to structured data141142---143144## Output Format145146### Schema Implementation147148```json149// Full JSON-LD code block150{151 "@context": "https://schema.org",152 "@type": "..."153 // Complete markup154}155```156157### Testing Checklist158159- [ ] Validates in Rich Results Test160- [ ] No errors or warnings161- [ ] Matches page content162- [ ] All required properties included163164---165166## Related Skills167168- **programmatic-seo**: For templated schema at scale
heyramzi