Schema Markup Implementation Skill

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.

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

Extract all JSON-LD blocks from the page source
Validate required vs recommended fields per schema type
Cross-reference with Google's current rich result requirements
Score completeness 0-100 per schema block
Deliver prioritized fix list with corrected JSON-LD

Mode 2: Implement New Schema

Identify page type and matching schema types
Select primary + supporting schema combination
Generate complete, copy-paste-ready JSON-LD populated with page content
Advise on placement method (inline head, CMS plugin, server-side rendering)
Test before deployment

Mode 3: Fix Validation Errors

Map Google Search Console errors to specific fields
Identify root cause (missing field, wrong format, content mismatch)
Deliver corrected JSON-LD with change log
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

Content type classification -- AI systems use @type to determine if content is a how-to, product listing, FAQ, or opinion piece
Citation eligibility -- FAQPage and HowTo schema increase citation likelihood because AI systems can extract structured Q&A and step-by-step content directly
Freshness signals -- datePublished and dateModified help AI systems filter by recency
Authority signals -- author with sameAs links to known profiles boosts entity recognition
Entity connection -- Organization with sameAs links to Wikidata, LinkedIn, and social profiles strengthens entity resolution

AI Search Schema Playbook

| Action | Priority | Impact | |--------|----------|--------| | Add FAQPage schema to any page with Q&A content (even 3 questions) | High | Direct citation in AI answers | | 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 | | Add HowTo schema to process/tutorial content | Medium | Step-by-step citation | | 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

Wikidata entry -- Create or claim your entity on Wikidata.org
Wikipedia presence -- A Wikipedia article dramatically increases KG entry probability
Consistent NAP -- Name, Address, Phone must be identical across all citations
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:

Wikidata (strongest entity signal)
Wikipedia
LinkedIn
Official social profiles
Industry directories (Crunchbase, G2, Capterra)

CMS Deployment Guide

WordPress

Yoast SEO / Rank Math: Auto-generate Article, Organization, BreadcrumbList. Add custom schema via their blocks for HowTo and FAQPage.
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

Pre-deployment: Rich Results Test + Schema.org Validator on the rendered HTML
Post-deployment (day 1): Check page is crawled via URL Inspection tool in GSC
Post-deployment (week 2-4): Check Enhancements section in GSC for errors at scale
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, FAQPage opportunities, sameAs gaps | | 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 | Questions not visible to users on the page, or site lacks sufficient authority | Ensure Q&A content is visible in page HTML, not hidden behind tabs or JS toggles | | 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 citation impact: FAQPage and HowTo schema present on all informational content pages to maximize AI 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 rich results were restricted in 2023)
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

Agent Skills: Schema Markup Implementation

Install this agent skill to your local

Skill Files