Schema Markup
Implement, audit, and validate structured data on any website.
$skillfish add ~skills/schema-markup Real Conversations
See how the Schema Markup skill responds to actual requests. These are representative examples of what your AI agent will produce.
We have a blog post 'How to Run Sprint Planning Meetings' that ranks #5 for our target keyword. I've heard FAQ schema can get us rich results and bump CTR. How do I implement it for this post, and what questions should I include?
FAQ schema on a ranking post is a reliable CTR boost — expect +1–2 percentage points when Google displays the rich result. Here's the implementation:
Step 1: Choose your FAQ questions
Pick 3–4 questions that:
- Appear in the "People Also Ask" box for your keyword in Google
- Have concise answers (40–60 words each — Google truncates longer ones)
- Don't repeat what your H1 already answers
Recommended questions for "sprint planning meetings":
- How long should a sprint planning meeting be?
- What is the sprint planning meeting agenda?
- Who should attend sprint planning?
- What's the difference between sprint planning and sprint review?
Step 2: JSON-LD implementation
Add to <head> or bottom of <body>:
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "How long should a sprint planning meeting be?",
"acceptedAnswer": {
"@type": "Answer",
"text": "For a 2-week sprint, planning should take 2–4 hours for a team of 5–10. The Scrum Guide recommends a maximum of 8 hours for a 1-month sprint, scaled down proportionally for shorter sprints."
}
}
]
}
In WordPress/Yoast: Yoast Premium has a FAQ block — use it instead of hand-coding.
Step 3: Validate before publishing Run through Google's Rich Results Test (search.google.com/test/rich-results) — check for errors before the page gets recrawled.
Expected timeline: Rich results appear within 1–4 weeks. CTR uplift shows in GSC within 30 days.
Want the full JSON-LD for all 4 questions?
Get Started
How to install and use this skill in your preferred environment.
Skills are designed for AI coding agents (Claude Code, Cursor, Windsurf) and IDE-based workflows where the agent can read files, run scripts, and act on your codebase. Web-based AI can use the knowledge and frameworks, but won't have tool access.
Models & Context
Which AI models and context windows work best with this skill.
Recommended Models
Larger models produce more detailed, production-ready outputs.
Context Window
This skill's SKILL.md is typically 3–10 KB — fits in any modern context window.
All current frontier models (Claude, GPT, Gemini) support 100K+ context. Use the full window for complex multi-service work.
Pro tips for best results
Be specific
Include numbers — users, budget, RPS — so the skill can size the architecture.
Share constraints
Compliance needs, team size, and existing stack all improve the output.
Iterate
Start with a high-level design, then ask follow-ups for IaC, cost analysis, or security review.
Combine skills
Pair with companion skills below for end-to-end coverage.
Good to Know
Advanced guide and reference material for Schema Markup. Background, edge cases, and patterns worth understanding.
Contents
Schema Types That Drive Rich Results
Not all Schema types produce rich results in Google Search — many are valid Schema.org vocabulary but Google does not render them as enhanced SERP features. Focus implementation effort on types Google actively supports:
| Schema type | Google rich result | Notes |
|---|---|---|
| FAQPage | FAQ accordion below listing | High-value CTR boost; watch for overuse policy |
| Product | Price, availability, rating stars | Requires offers and ideally AggregateRating |
| Article / NewsArticle | Top Stories carousel eligibility | NewsArticle for news publishers; Article for evergreen |
| HowTo | Step-by-step rich result with images | Displayed on desktop; mobile display limited |
| Recipe | Image, rating, cook time, calories | High competition niche; full required fields needed |
| Event | Date, location, ticket link in results | Requires startDate, location, name at minimum |
| LocalBusiness | Knowledge panel, map pack data | Critical for local SEO; sync with GBP |
| SoftwareApplication | Star rating, price, OS | Requires real third-party review backing for AggregateRating |
Schema.org defines hundreds of additional types. They have semantic value for entity understanding but do not produce visual rich results.
JSON-LD vs Microdata vs RDFa
| Format | Placement | Maintainability | Google recommendation |
|---|---|---|---|
| JSON-LD | <script> tag in <head> or <body> |
High — separate from HTML | Preferred |
| Microdata | Inline HTML attributes (itemscope, itemprop) |
Low — tightly coupled to markup | Supported but not preferred |
| RDFa | Inline HTML attributes | Low — verbose, complex | Supported for specific use cases |
Why JSON-LD is preferred: The markup is decoupled from the page's visual HTML, making it easier to update independently, generate dynamically, and validate in isolation. It does not break if the visual template changes.
When Microdata makes sense: Microdata is useful when your CMS or template system cannot inject arbitrary <script> blocks but does allow custom attributes on HTML elements. Some older WordPress page builders fall into this category.
Validation Workflow
Run validation in this order — each tool catches different error categories:
1. Google Rich Results Test (search.google.com/test/rich-results)
Tests only for rich-result-eligible types. Run this first to confirm Google can parse the markup and that required fields are present. Errors here mean no rich result.
2. Schema.org Validator (validator.schema.org)
Validates structural correctness against the Schema.org specification. Catches property name typos, wrong nesting, and non-standard values that the Rich Results Test may not flag.
3. Google Search Console Enhancement Reports Located under Search Console > Enhancements. Shows at-scale validation errors across your full site after indexation. Useful for catching issues introduced by CMS updates or template changes that affect hundreds of pages simultaneously.
Do not skip step 1 and go directly to GSC — Enhancement reports have a 1–2 week lag; catching errors before publishing saves crawl cycles.
Common Markup Errors
Missing required fields: Each rich result type has documented required vs recommended properties. Product without name and offers will not generate a rich result. Check the Google developer documentation for the exact required set per type — it differs from Schema.org's specification.
Wrong @type nesting: AggregateRating must be nested inside the parent entity (Product, LocalBusiness, SoftwareApplication) — not declared as a top-level entity. A standalone AggregateRating block will not associate with anything.
String vs number type mismatches: ratingValue and reviewCount must be numbers, not strings. "ratingValue": "4.5" (string) will fail validation in strict parsers; "ratingValue": 4.5 (number) is correct.
AggregateRating without reviewCount: Google requires both ratingValue and reviewCount (or ratingCount). A rating without a review count is unverifiable and will be rejected for display.
Mismatched content: Schema markup must accurately describe visible page content. If your page shows "Starting at $49/month" but your Product markup says "price": "0", this is a policy violation.
Penalty Risk and Policy Violations
Schema spamming: Adding rich-result-eligible markup to pages where it does not reflect actual page content — e.g., FAQPage markup on a product page that has no FAQ section, or HowTo markup on a blog post. Google has manual and algorithmic actions for this.
"Not supported" vs "against guidelines": These are different outcomes. "Not supported" means Google parses the markup but does not display a rich result — no penalty, no benefit. "Against guidelines" means the markup misrepresents content or is used manipulatively — risks a Search Console manual action against the Enhancement type.
Mismatched visible content: The most common cause of manual actions for schema. The rule: every claim in your structured data must be visibly verifiable on the page. Ratings displayed in markup must appear as visible ratings. Prices in markup must match displayed prices. Google's quality raters check this manually; the algorithm also catches systematic mismatches at scale.
Ready to try Schema Markup?
Install the skill and start getting expert-level guidance in your workflow — any agent, any IDE.
$skillfish add ~skills/schema-markup