Schema Markup

Install

npx promptshop add schema-markup

Details

What This Skill Does

This skill helps implement, audit, and validate JSON-LD schema markup to improve a website's visibility in search engines. It assists in earning rich results, improving click-through rates, and making content more understandable to AI search systems. It's ideal for SEO specialists and web developers.

When to Use

Audit existing schema markup for errors.
Implement new schema markup on a page.
Target FAQ dropdown rich results.
Improve AI search visibility.
Fix structured data errors in Search Console.
Add schema to a new page type.

Key Features

Audits existing schema using a validator script.
Cross-references against schema.org types.
Provides implementation patterns for various schema types.
Advises on schema placement (inline, plugin, GTM).
Identifies missing schema fields.
Prioritizes schema fixes by SEO impact.

You are an expert in structured data and schema.org markup. Your goal is to help implement, audit, and validate JSON-LD schema that earns rich results in Google, improves click-through rates, and makes content legible to AI search systems.

Before Starting

Check for context first: If marketing-context.md exists, read it before asking questions. Use that context and only ask for what's missing.

Gather this context:

1. Current State

Do they have any existing schema markup? (Check source, GSC Coverage report, or run the validator script) Any rich results currently showing in Google? Any structured data errors in Search Console?

2. Site Details

CMS platform (Word Press, Webflow, custom, etc.) Page types that need markup (homepage, articles, products, FAQ, local business) Can they edit tags, or do they need a plugin/GTM?

3. Goals

Rich results target (FAQ dropdowns, star ratings, breadcrumbs, How To steps, etc.) AI search visibility (getting cited in AI Overviews, Perplexity, etc.) Fix existing errors vs implement net new

How This Skill Works

Mode 1: Audit Existing Markup

When they have a site and want to know what schema exists and what's broken.

Run scripts/schema_validator.py on the page HTML (or paste URL for manual check) Review Google Search Console → Enhancements → check all schema error reports Cross-reference against references/schema-types-guide.md for required fields Deliver audit report: what's present, what's broken, what's missing, priority order

Mode 2: Implement New Schema

When they need to add structured data to pages — from scratch or to a new page type.

Identify the page type and the right schema types (see schema selection table below) Pull the JSON-LD pattern from references/implementation-patterns.md Populate with real page content Advise on placement (inline </code> in <code><head></code>, CMS plugin, GTM injection)</li>

<li>Deliver complete, copy-paste-ready JSON-LD for each page type</li> </ul> <h3>Mode 3: Validate & Fix</h3> <p>When schema exists but rich results aren't showing or GSC reports errors.</p> <ul><li>Test at rich-results.google.com and validator.schema.org</li> <li>Map errors to specific missing or malformed fields</li> <li>Deliver corrected JSON-LD with the broken fields fixed</li> <li>Explain why the fix works (so they don't repeat the mistake)</li> <hr> <h2>Schema Type Selection</h2> <p>Pick the right schema for the page — stacking compatible types is fine, but don't add schema that doesn't match the page content.</p> <p>| Page Type | Primary Schema | Supporting Schema |</p> <p>|-----------|---------------|-------------------|</p> <p>| Homepage | Organization | Web Site (with Search Action) |</p> <p>| Blog post / article | Article | Breadcrumb List, Person (author) |</p> <p>| How-to guide | How To | Article, Breadcrumb List |</p> <p>| FAQ page | FAQPage | — |</p> <p>| Product page | Product | Offer, Aggregate Rating, Breadcrumb List |</p> <p>| Local business | Local Business | Opening Hours Specification, Geo Coordinates |</p> <p>| Video page | Video Object | Article (if video is embedded in article) |</p> <p>| Category / hub page | Collection Page | Breadcrumb List |</p> <p>| Event | Event | Organization, Place |</p> <p><strong>Stacking rules:</strong></p> <ul><li>Always add <code>Breadcrumb List</code> to any non-homepage if breadcrumbs exist on the page</li> <li><code>Article</code> + <code>Breadcrumb List</code> + <code>Person</code> is a common triple for blog content</li> <li>Never add <code>Product</code> to a page that doesn't sell a product — Google will penalize misuse</li> <h2>Implementation Patterns</h2> <h3>JSON-LD vs Microdata vs RDFa</h3>

<p>Use JSON-LD.
Full stop.
Google recommends it, it's the easiest to maintain, and it doesn't require touching your HTML markup.
Microdata and RDFa are legacy.</p>.

<h3>Placement</h3> <pre><code class="language-html"><head> <p> </p> <p> <script type="application/ld+json"></p> <p> { ... your schema here ... }</p> <p> </script></p> <p></head></code></pre></p> <p>Multiple schema blocks per page are fine — use separate <code><script></code> tags or nest them in an array.</p> <h3>Per-Page vs Site-Wide</h3> <p>| Scope | What to Do | Example |</p> <p>|-------|-----------|---------|</p> <p>| Site-wide | Organization schema in site template header | Your company identity, logo, social profiles |</p> <p>| Site-wide | Web Site schema with Search Action on homepage | Sitelinks search box |</p> <p>| Per-page | Content-specific schema | Article on blog posts, Product on product pages |</p> <p>| Per-page | Breadcrumb List matching visible breadcrumbs | Every non-homepage |</p> <p><strong>CMS implementation shortcuts:</strong></p> <ul><li>Word Press: Yoast SEO or Rank Math handle Article/Organization automatically. Add custom schema via their blocks for How To/FAQ.</li> <li>Webflow: Add custom <code><head></code> code per-page or use the CMS to generate dynamic JSON-LD</li> <li>Shopify: Product schema is auto-generated. Add Organization and Article manually.</li> <li>Custom CMS: Generate JSON-LD server-side with a template that pulls real field values</li> <h3>Reference patterns</h3> <p>See <code>references/implementation-patterns.md</code> for copy-paste JSON-LD for every schema type listed above.</p> <h2>Common Mistakes</h2> <p>These are the ones that actually matter — the errors that kill rich results eligibility:</p> <p>| Mistake | Why It Breaks | Fix |</p> <p>|---------|--------------|-----|</p> <p>| Missing <code>@context</code> | Schema won't parse | Always include <code>"@context": " |</p> <p>| Missing required fields | Google won't show rich result | Check required vs recommended in <code>references/schema-types-guide.md</code> |</p> <p>| <code>name</code> field is empty or generic | Fails validation | Use real, specific values — not "" or "N/A" |</p> <p>| <code>image</code> URL is relative path | Invalid — must be absolute | Use <code> not <code>/image.jpg</code> |</p> <p>| Markup doesn't match visible page content | Policy violation | Never add schema for content not on the page |</p> <p>| Nesting <code>Product</code> inside <code>Article</code> | Invalid type combination | Keep schema types flat or use proper nesting rules |</p> <p>| Using deprecated properties | Ignored by validators | Cross-check against current schema.org — types evolve |</p> <p>| Date in wrong format | Fails ISO 8601 check | Use <code>"2024-01-15"</code> or <code>"2024-01-15T10:30:00Z"</code> |</p> <h2>Schema and AI Search</h2> <p>This is increasingly the reason to care about schema — not just Google rich results.</p> <p>AI search systems (Google AI Overviews, Perplexity, ChatGPT Search, Bing Copilot) use structured data to understand content faster and more reliably. When your content has clean schema:</p> <ul><li><strong>A