/iblai-marketing-schema-markup
Implement schema.org markup that helps search engines understand content and unlocks rich results.
Step 0: Context Check
Read .agents/product-marketing-context.md (or .claude/product-marketing-context.md on older setups) first. Only ask for what isn't there.
Pin down before implementing:
- Page type — what kind of page? Primary content? Possible rich results?
- Current state — any existing schema? Errors? Which rich results already appear?
- Goals — which rich results are you targeting? What's the business value?
Core Principles
- Accuracy first. Schema must accurately represent page content. Don't markup content that doesn't exist. Keep updated when content changes.
- Use JSON-LD. Google recommends JSON-LD. Easier to implement and maintain. Place in
<head> or end of <body>.
- Follow Google's guidelines. Only use markup Google supports. Avoid spam tactics. Review eligibility requirements.
- Validate everything. Test before deploying. Monitor Search Console. Fix errors promptly.
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 |
Complete JSON-LD examples: [references/schema-examples.md](references/schema-examples.md).
Quick Reference
Organization (Company Page)
Required: name, url Recommended: logo, sameAs (social profiles), contactPoint
Article/BlogPosting
Required: headline, image, datePublished, author Recommended: dateModified, publisher, description
Product
Required: name, image, offers (price + availability) Recommended: sku, brand, aggregateRating, review
FAQPage
Required: mainEntity (array of Question/Answer pairs)
BreadcrumbList
Required: itemListElement (array with position, name, item)
Multiple Schema Types
Combine multiple 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 docs 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 → structured data
Output Format
Schema Implementation
// Full JSON-LD code block
{
"@context": "https://schema.org",
"@type": "...",
// Complete markup
}
Testing Checklist
Task-Specific Questions
- What type of page is this?
- Which rich results are you targeting?
- What data is available to populate the schema?
- Existing schema on the page?
- Tech stack?
Related Skills
- iblai-marketing-seo-audit: Overall SEO including schema review
- iblai-marketing-ai-seo: AI search optimization (schema helps AI understand content)
- iblai-marketing-programmatic-seo: Templated schema at scale
- iblai-marketing-site-architecture: Breadcrumb structure and navigation schema planning
