schema-markup

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

<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