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
• Schema Type Selection Matrix
• Implementation Patterns
• Rich Result Eligibility Rules
• AI Search Optimization
• Knowledge Graph Strategy
• CMS Deployment Guide
• Validation and Testing
• Common Errors and Fixes
• Audit Framework
• Output Artifacts
• Related Skills

---

Clarify First

Before generating the schema, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• Page type & operating mode — audit existing, implement new, or fix errors; and on what page type (Article, Product, FAQPage, LocalBusiness…) — selects the schema type and workflow
• Target rich result or AI-search goal — which rich result or citation you want to win — sets the required-field checklist and eligibility rules
• CMS / deployment platform — WordPress, Webflow, Shopify, Next.js, or static — drives the deployment method and known warnings (e.g. GTM injection)
• Source page content — the real headline/author/price/Q&A to populate — schema must match visible content or Google penalizes it

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

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 (site name)	Site name, logo / knowledge panel signals (sitelinks search box retired Nov 2024)
Blog post	Article	BreadcrumbList, Person (author), ImageObject	Article card
How-to guide	Article	BreadcrumbList, ImageObject (HowTo optional)	Article (HowTo rich results removed Sept 2023)
FAQ page	WebPage / Article	BreadcrumbList (FAQPage optional)	-- (FAQ rich results removed May 2026)
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)
• Article + BreadcrumbList + ImageObject (guides; HowTo markup optional, no rich result)

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	Homepage template header
Per-page	Article, Product, VideoObject, Event	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 September 2026). Check the live Search Gallery before promising a rich result — types get retired.

Retired Google rich results (markup is still valid schema.org, but produces no Google search feature):

Feature	Status	Source
HowTo rich results	Restricted Aug 2023; no longer shown on any device from Sept 13, 2023	Search Central blog
FAQ rich results	Restricted to authoritative government/health sites Aug 2023; removed from Google Search May 7, 2026	FAQPage docs changelog
Sitelinks search box (WebSite + SearchAction)	Removed Nov 21, 2024; leaving the markup in place causes no issues	Search Central blog

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 and HowTo (no Google rich result)

If you still emit FAQPage or HowTo for other consumers, keep it valid and honest: mainEntity as an array of Question items with acceptedAnswer.text (FAQPage), step as an array of HowToStep items (HowTo), and every Q&A pair or step visible on the page. Do not report these as rich-result wins.

---

AI Search Optimization

AI search systems (Google AI Overviews, Perplexity, ChatGPT Search, Bing Copilot) may use structured data for content understanding and entity recognition. Google states that no special schema.org markup is required to appear in AI Overviews or AI Mode (AI features and your website, as of September 2026) — schema supports understanding; it is not an AI-citation switch.

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. Extractable structure lives on the page -- AI systems extract visible Q&A and step-by-step content; FAQPage/HowTo markup is optional and has no demonstrated citation lift from Google's side
3. Freshness signals -- datePublished and dateModified help AI systems filter by recency
4. Authority signals -- author with sameAs links to known profiles boosts entity recognition
5. Entity connection -- Organization with sameAs links to Wikidata, LinkedIn, and social profiles strengthens entity resolution

AI Search Schema Playbook

Action	Priority	Impact
Add author Person schema with sameAs to LinkedIn, Twitter, Google Scholar	High	Author entity recognition
Add Organization with sameAs to Wikidata, LinkedIn, Crunchbase	High	Brand entity recognition
Keep dateModified accurate on every content update	Medium	Freshness filtering
Keep Article, Product, BreadcrumbList schema accurate and matching visible content	Medium	Rich results + content-type clarity
FAQPage / HowTo markup on Q&A or tutorial content	Low	Optional; no Google rich result, no special AI-feature treatment
Add SoftwareApplication schema to tool/product pages	Medium	Product recognition in AI answers

---

Knowledge Graph Strategy

Getting into Google's Knowledge Graph means your entity (person, company, product) is recognized and displayed in panels, AI answers, and cross-referenced searches.

Knowledge Graph Entry Requirements

1. Wikidata entry -- Create or claim your entity on Wikidata.org
2. Wikipedia presence -- A Wikipedia article dramatically increases KG entry probability
3. Consistent NAP -- Name, Address, Phone must be identical across all citations
4. sameAs network -- Organization schema must link to all official profiles

sameAs Best Practices

{
  "@type": "Organization",
  "name": "Your Company",
  "url": "https://yourcompany.com",
  "sameAs": [
    "https://www.wikidata.org/wiki/Q12345678",
    "https://en.wikipedia.org/wiki/Your_Company",
    "https://www.linkedin.com/company/yourcompany",
    "https://twitter.com/yourcompany",
    "https://www.crunchbase.com/organization/yourcompany",
    "https://github.com/yourcompany"
  ]
}

Order of importance for sameAs links:

1. Wikidata (strongest entity signal)
2. Wikipedia
3. LinkedIn
4. Official social profiles
5. Industry directories (Crunchbase, G2, Capterra)

---

CMS Deployment Guide

WordPress

• Yoast SEO / Rank Math: Auto-generate Article, Organization, BreadcrumbList. Their FAQ/HowTo blocks still emit markup, but it no longer yields Google rich results.
• Custom schema: Add via wp_head action hook or a custom plugin.
• Avoid: Plugins that inject schema via JavaScript (Google may not render it).

Webflow

• Per-page: Add custom code in page settings > Custom Code > Head
• CMS-driven: Use Webflow CMS to generate dynamic JSON-LD via embedded code blocks with CMS field references
• Site-wide: Add Organization schema in Project Settings > Custom Code > Head

Shopify

• Product schema: Auto-generated by most themes. Verify it includes Offer and AggregateRating.
• Article/Blog schema: Usually missing -- add manually via theme.liquid or a schema app.
• Organization: Add to theme.liquid <head> section.

Next.js / Custom React

• Server-side rendering: Generate JSON-LD in the page component and render in <Head>.
• next-seo library: Provides schema components for common types.
• Dynamic pages: Generate schema from your data layer, not hardcoded.

Static sites (Hugo, Jekyll, Gatsby)

• Template-level: Add JSON-LD to layout templates using template variables.
• Per-page: Use frontmatter data to populate schema fields dynamically.

Google Tag Manager (GTM)

• Warning: GTM-injected schema is often NOT indexed by Google because it renders client-side after JavaScript execution.
• Use only when: No other option exists (no CMS access, no dev resources).
• Better alternative: Server-side injection via CMS or template engine.

---

Validation and Testing

Three-Layer Validation

Test every schema implementation with all three tools before deployment:

Tool	URL	What It Checks
Google Rich Results Test	search.google.com/test/rich-results	Google's parser, rich result eligibility
Schema.org Validator	validator.schema.org	Full spec compliance (broader than Google)
Google Search Console	Enhancements section	Real-world errors at scale, post-deployment

Validation Workflow

1. Pre-deployment: Rich Results Test + Schema.org Validator on the rendered HTML
2. Post-deployment (day 1): Check page is crawled via URL Inspection tool in GSC
3. Post-deployment (week 2-4): Check Enhancements section in GSC for errors at scale
4. Ongoing (monthly): Monitor GSC Enhancements for new errors from content updates

---

Common Errors and Fixes

Error	Root Cause	Fix
Missing @context	Schema block has no context declaration	Add "@context": "https://schema.org"
Missing required field	A required property is absent	Add the field with real content from the page
image URL is relative	/image.jpg instead of absolute URL	Use https://example.com/image.jpg
dateModified < datePublished	Impossible date relationship	Ensure dateModified >= datePublished
Markup does not match page content	Schema claims content not visible to users	Only add schema for content actually on the page
Deprecated property	Using old schema.org property names	Check current spec at schema.org
Nested type conflict	Product inside Article incorrectly	Keep types flat or use proper @graph nesting
Date format wrong	Not ISO 8601	Use "2026-01-15" or "2026-01-15T10:30:00Z"
Empty string values	"name": "" passes syntax but fails semantics	Use real values, never empty strings
Array expected, single value given	mainEntity needs array for FAQPage	Wrap in [] array brackets
Logo too large	Publisher logo exceeds 600x60px	Resize or use a different logo format
GTM injection not indexed	Client-side rendering	Move to server-side <head> injection

---

Audit Framework

Audit Scorecard (0-100)

Dimension	Weight	Scoring
Required fields present	40%	-10 per missing required field
Recommended fields present	15%	-3 per missing recommended field
Rich result eligibility	20%	Binary: eligible or not
Content-markup match	15%	-5 per mismatch between schema and visible content
sameAs and entity signals	10%	-5 per missing major platform link

Priority Classification

Priority	Criteria	Action
P0 Critical	Required field missing, blocks rich result	Fix immediately
P1 High	Recommended field missing, reduces eligibility	Fix this week
P2 Medium	Content mismatch, deprecated property	Fix this month
P3 Low	Missing sameAs link, optional enhancement	Add when convenient

---

Output Artifacts

Artifact	Format	Description
Schema Audit Report	Scored table	Per-page schema inventory, completeness score, priority fixes
JSON-LD Implementation	Copy-paste code blocks	Complete schema for each page type, populated with placeholder values marked clearly
Error Fix Log	Before/after JSON-LD	Each fix explained with root cause and prevention
AI Search Gap Analysis	Recommendation table	Missing entity markup, sameAs gaps, content-type mismatches
CMS Implementation Guide	Step-by-step instructions	Platform-specific deployment instructions
Rich Result Eligibility Matrix	Page type x schema x eligibility	Which pages qualify for which rich result types

---

Related Skills

• seo-audit -- For full technical and content SEO audits spanning beyond structured data. Use when the problem is broader than schema.
• site-architecture -- For URL structure and navigation. Use when architecture is the root cause, not schema.
• programmatic-seo -- For sites with thousands of pages that need schema at scale. Schema patterns feed into pSEO template design.
• content-creator -- For content creation. Use before implementing Article schema to ensure content quality.

---

Troubleshooting

Problem	Likely Cause	Fix
Schema passes validation but no rich results appear	Missing required fields for rich result eligibility, or Google has not recrawled	Verify against Google Rich Results Test (not just schema.org validator); request reindexing via GSC
FAQPage schema not generating FAQ dropdowns	FAQ rich results were removed from Google Search in May 2026 (HowTo in Sept 2023)	Expected behavior — nothing to fix; keep the markup valid or remove it, and stop tracking it as a rich-result KPI
Product schema shows "missing field" warnings in GSC	Required fields (price, availability, review) absent or malformed	Add all required Product + Offer fields; use ISO 4217 for currency, schema.org/InStock for availability
GTM-injected schema not being indexed	Client-side rendering — Google may not execute GTM JavaScript for schema	Move schema from GTM to server-side <head> injection; GTM schema is unreliable for indexing
dateModified older than datePublished	Data entry error or CMS auto-populating incorrectly	Ensure dateModified >= datePublished; audit CMS date field logic
Multiple conflicting Organization blocks	Different plugins or templates injecting separate Organization schema	Consolidate into a single Organization block on the homepage; remove duplicates
Schema validated but Google shows "content mismatch"	Schema claims content not actually visible to users on the page	Only add schema for content physically present on the page — never fake or hidden content

---

Success Criteria

• Rich result eligibility: 100% of content pages with appropriate schema types eligible for rich results per Google Rich Results Test
• Validation pass rate: Zero errors in Google Search Console Enhancements reports across all schema types
• Rich result CTR boost: Structured data pages achieving 20-35% higher CTR than non-structured pages (2026 benchmark from SearchPilot testing)
• AI readiness: Entity markup (Organization, Person with sameAs) and accurate Article dates on all informational pages; answers visible in the HTML for extraction
• Entity recognition: Organization schema with 5+ sameAs links deployed site-wide; brand appearing in Knowledge Graph
• Coverage breadth: Schema implemented on 95%+ of indexable pages (BreadcrumbList minimum, content-specific types on relevant pages)
• Freshness accuracy: dateModified updated within 24 hours of every content change across all Article schema

---

Scope & Limitations

In scope:

• Schema type selection and JSON-LD implementation for 20+ schema types
• Rich result eligibility verification and optimization
• AI search visibility through structured data
• Knowledge Graph entity optimization
• Schema validation, testing, and error resolution
• CMS-specific deployment guidance (WordPress, Webflow, Shopify, Next.js)

Out of scope:

• Content creation for schema-eligible pages (use Content Production)
• Technical SEO beyond structured data (use SEO Audit)
• Microdata or RDFa implementations (JSON-LD only — Google's recommendation)
• Custom schema.org extensions or vocabulary proposals
• Server-side rendering implementation
• CMS plugin development

Known limitations:

• Google does not guarantee rich results even with valid schema — authority and content quality also factor in
• GTM-injected schema is frequently not indexed — server-side deployment is required for reliability
• Schema.org spec updates faster than Google's support — not all valid types generate rich results
• Rich result types can be deprecated with minimal notice (e.g., HowTo removed in 2023, sitelinks search box in 2024, FAQ in 2026)
• Structured data CTR impact varies by industry and SERP features present

---

Scripts

# Validate JSON-LD schema from a file or URL
python scripts/schema_validator.py --file schema.json --json

# Audit a page for schema coverage and completeness
python scripts/schema_validator.py --html page.html --verbose

# Generate JSON-LD templates for common page types
python scripts/schema_generator.py --type Article --title "My Post" --author "Jane" --json