schema-markup

What this skill does

# Schema Markup Implementation

Production-grade structured data implementation covering 20+ schema types, rich result eligibility rules, AI search optimization, and CMS-specific deployment patterns. Handles auditing existing markup, implementing new schema, and fixing validation errors.

---

## Table of Contents

- [Operating Modes](#operating-modes)
- [Schema Type Selection Matrix](#schema-type-selection-matrix)
- [Implementation Patterns](#implementation-patterns)
- [Rich Result Eligibility Rules](#rich-result-eligibility-rules)
- [AI Search Optimization](#ai-search-optimization)
- [Knowledge Graph Strategy](#knowledge-graph-strategy)
- [CMS Deployment Guide](#cms-deployment-guide)
- [Validation and Testing](#validation-and-testing)
- [Common Errors and Fixes](#common-errors-and-fixes)
- [Audit Framework](#audit-framework)
- [Output Artifacts](#output-artifacts)
- [Related Skills](#related-skills)

---

## Operating Modes

### Mode 1: Audit Existing Markup
1. Extract all JSON-LD blocks from the page source
2. Validate required vs recommended fields per schema type
3. Cross-reference with Google's current rich result requirements
4. Score completeness 0-100 per schema block
5. Deliver prioritized fix list with corrected JSON-LD

### Mode 2: Implement New Schema
1. Identify page type and matching schema types
2. Select primary + supporting schema combination
3. Generate complete, copy-paste-ready JSON-LD populated with page content
4. Advise on placement method (inline head, CMS plugin, server-side rendering)
5. Test before deployment

### Mode 3: Fix Validation Errors
1. Map Google Search Console errors to specific fields
2. Identify root cause (missing field, wrong format, content mismatch)
3. Deliver corrected JSON-LD with change log
4. Explain the fix to prevent recurrence

---

## Schema Type Selection Matrix

### Primary Schema by Page Type

| Page Type | Primary Schema | Supporting Schema | Rich Result Type |
|-----------|---------------|-------------------|-----------------|
| Homepage | Organization | WebSite + SearchAction | Sitelinks search box |
| Blog post | Article | BreadcrumbList, Person (author), ImageObject | Article card |
| How-to guide | HowTo | Article, BreadcrumbList, ImageObject | How-to steps |
| FAQ page | FAQPage | BreadcrumbList | FAQ dropdowns |
| Product page | Product | Offer, AggregateRating, Review, BreadcrumbList | Product card |
| Local business | LocalBusiness | OpeningHoursSpecification, GeoCoordinates, PostalAddress | Local pack |
| Video page | VideoObject | Article (if embedded) | Video card |
| Category page | CollectionPage | BreadcrumbList, ItemList | -- |
| Event page | Event | Organization, Place, Offer | Event listing |
| Recipe | Recipe | NutritionInformation, AggregateRating | Recipe card |
| Course | Course | Organization, Offer | Course listing |
| Software/App | SoftwareApplication | Offer, AggregateRating | Software card |
| Job posting | JobPosting | Organization, Place | Job listing |
| Review page | Review | Product or LocalBusiness, Rating | Review snippet |
| Podcast episode | PodcastEpisode | PodcastSeries, Person | Podcast card |
| Author page | Person | sameAs links | Knowledge Panel |
| Company page | Organization | sameAs links, ContactPoint | Knowledge Panel |
| Breadcrumb trail | BreadcrumbList | -- | Breadcrumb rich result |
| Site navigation | SiteNavigationElement | -- | -- |
| Dataset | Dataset | DataCatalog | Dataset search |

### Stacking Rules

**Always add:**
- BreadcrumbList to any non-homepage if breadcrumbs exist on the page
- Organization to the homepage (site-wide identity)

**Common valid stacks:**
- Article + BreadcrumbList + Person + ImageObject (blog posts)
- Product + Offer + AggregateRating + BreadcrumbList (product pages)
- LocalBusiness + OpeningHoursSpecification + GeoCoordinates + Review (local pages)
- HowTo + Article + BreadcrumbList + ImageObject (guides)

**Never combine:**
- Product on a page that does not sell a product (Google penalizes misuse)
- Multiple Organization blocks for the same entity (combine into one)
- FAQPage on pages where the Q&A is not visible to users

---

## Implementation Patterns

### JSON-LD Format (Always Use This)

JSON-LD is the only format worth implementing. Google recommends it, it lives in the `<head>`, and it does not touch your HTML markup. Microdata and RDFa are legacy -- do not use them for new implementations.

### Placement

```html
<head>
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "Your Article Title",
    "author": {
      "@type": "Person",
      "name": "Author Name",
      "url": "https://example.com/authors/name",
      "sameAs": ["https://linkedin.com/in/name", "https://twitter.com/name"]
    },
    "datePublished": "2026-01-15",
    "dateModified": "2026-03-01",
    "image": "https://example.com/images/article-hero.jpg",
    "publisher": {
      "@type": "Organization",
      "name": "Company Name",
      "logo": {
        "@type": "ImageObject",
        "url": "https://example.com/logo.png"
      }
    }
  }
  </script>
</head>
```

Multiple `<script type="application/ld+json">` blocks per page are valid. Use separate blocks for unrelated schema types. Nest related types within one block.

### Scope Rules

| Scope | Schema | Placement |
|-------|--------|-----------|
| Site-wide | Organization, WebSite + SearchAction | Homepage template header |
| Per-page | Article, Product, HowTo, FAQPage | Page-specific head injection |
| Per-element | BreadcrumbList | Every non-homepage |
| Conditional | Event, JobPosting | Only on pages with that content type |

---

## Rich Result Eligibility Rules

Google does not give rich results for all valid schema. These are the current requirements (as of 2026):

### Article Rich Result

| Field | Required | Notes |
|-------|----------|-------|
| headline | Yes | Must match visible page title |
| image | Yes | Must be crawlable, min 1200px wide |
| datePublished | Yes | ISO 8601 format |
| dateModified | Recommended | Must be >= datePublished |
| author.name | Yes | Must match a real person or organization |
| author.url | Recommended | Links to author page |
| publisher.name | Yes | |
| publisher.logo | Yes | Max 600x60px |

### Product Rich Result

| Field | Required | Notes |
|-------|----------|-------|
| name | Yes | Product name |
| image | Yes | Product photo |
| offers.price | Yes | Numeric value |
| offers.priceCurrency | Yes | ISO 4217 code |
| offers.availability | Recommended | Use schema.org/InStock etc. |
| aggregateRating.ratingValue | Recommended | Numeric |
| aggregateRating.reviewCount | Recommended | Integer |
| review | Recommended | At least 1 review |

### FAQPage Rich Result

| Field | Required | Notes |
|-------|----------|-------|
| mainEntity | Yes | Array of Question items |
| Question.name | Yes | The question text |
| Question.acceptedAnswer.text | Yes | The answer text |
| Visible on page | Yes | Q&A must be visible to users, not hidden |

### HowTo Rich Result

| Field | Required | Notes |
|-------|----------|-------|
| name | Yes | Title of the how-to |
| step | Yes | Array of HowToStep items |
| step.name | Yes | Step title |
| step.text | Yes | Step description |
| image | Recommended | Per-step or overall |
| totalTime | Recommended | ISO 8601 duration |

---

## AI Search Optimization

AI search systems (Google AI Overviews, Perplexity, ChatGPT Search, Bing Copilot) use structured data for content understanding, citation decisions, and entity recognition.

### Why Schema Matters for AI Search

1. **Content type classification** -- AI systems use `@type` to determine if content is a how-to, product listing, FAQ, or opinion piece
2. **Citation eligibility** -- FAQPage and HowTo schema increase citation likelihood because AI systems can extract structured Q&A and step-by-step content directly
3. **Freshness signals** -- `datePublished` and `dateModified` help AI systems fi