| name | schema-markup |
| description | Structured data implementation, validation, and optimization. Covers JSON-LD patterns for 20+ schema types, rich snippet eligibility, AI search visibility, Knowledge Graph optimization, and CMS-specific deployment guides.
|
| license | MIT + Commons Clause |
| metadata | {"version":"1.0.0","author":"borghei","category":"marketing-growth","updated":"2026-03-31T00:00:00.000Z","tags":["seo","schema","structured-data","json-ld","rich-snippets","knowledge-graph"]} |
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
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 |
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
python scripts/schema_validator.py --file schema.json --json
python scripts/schema_validator.py --html page.html --verbose
python scripts/schema_generator.py --type Article --title "My Post" --author "Jane" --json
