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
• 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