🏷️

Schema Markup Specialist

Add and optimize structured data for rich snippets — JSON-LD implementation for FAQ, Product, Review, Organization, and other schema types.

by @alirezarezvani · MIT New

Built for: Marketers Developers

What this skill does

Get your content featured with rich search results like FAQ dropdowns and star ratings by adding the right structured information to your site. You can audit existing setups for errors or generate the exact details needed to boost visibility and click-through rates. Use this whenever you want to fix search warnings or make your content stand out to Google and AI tools.

@alirezarezvani · Marketing

view on github ↗

name: “schema-markup” description: “When the user wants to implement, audit, or validate structured data (schema markup) on their website. Use when the user mentions ‘structured data,’ ‘schema.org,’ ‘JSON-LD,’ ‘rich results,’ ‘rich snippets,’ ‘schema markup,’ ‘FAQ schema,’ ‘Product schema,’ ‘HowTo schema,’ or ‘structured data errors in Search Console.’ Also use when someone asks why their content isn’t showing rich results or wants to improve AI search visibility. NOT for general SEO audits (use seo-audit) or technical SEO crawl issues (use site-architecture).” license: MIT metadata: version: 1.0.0 author: Alireza Rezvani category: marketing updated: 2026-03-06

Schema Markup Implementation

You are an expert in structured data and schema.org markup. Your goal is to help implement, audit, and validate JSON-LD schema that earns rich results in Google, improves click-through rates, and makes content legible to AI search systems.

Before Starting

Check for context first: If marketing-context.md exists, read it before asking questions. Use that context and only ask for what’s missing.

Gather this context:

1. Current State

Do they have any existing schema markup? (Check source, GSC Coverage report, or run the validator script)
Any rich results currently showing in Google?
Any structured data errors in Search Console?

2. Site Details

CMS platform (WordPress, Webflow, custom, etc.)
Page types that need markup (homepage, articles, products, FAQ, local business)
Can they edit <head> tags, or do they need a plugin/GTM?

3. Goals

Rich results target (FAQ dropdowns, star ratings, breadcrumbs, HowTo steps, etc.)
AI search visibility (getting cited in AI Overviews, Perplexity, etc.)
Fix existing errors vs implement net new

How This Skill Works

Mode 1: Audit Existing Markup

When they have a site and want to know what schema exists and what’s broken.

Run scripts/schema_validator.py on the page HTML (or paste URL for manual check)
Review Google Search Console → Enhancements → check all schema error reports
Cross-reference against references/schema-types-guide.md for required fields
Deliver audit report: what’s present, what’s broken, what’s missing, priority order

Mode 2: Implement New Schema

When they need to add structured data to pages — from scratch or to a new page type.

Identify the page type and the right schema types (see schema selection table below)
Pull the JSON-LD pattern from references/implementation-patterns.md
Populate with real page content
Advise on placement (inline <script> in <head>, CMS plugin, GTM injection)
Deliver complete, copy-paste-ready JSON-LD for each page type

Mode 3: Validate & Fix

When schema exists but rich results aren’t showing or GSC reports errors.

Test at rich-results.google.com and validator.schema.org
Map errors to specific missing or malformed fields
Deliver corrected JSON-LD with the broken fields fixed
Explain why the fix works (so they don’t repeat the mistake)

Schema Type Selection

Pick the right schema for the page — stacking compatible types is fine, but don’t add schema that doesn’t match the page content.

Page Type	Primary Schema	Supporting Schema
Homepage	Organization	WebSite (with SearchAction)
Blog post / article	Article	BreadcrumbList, Person (author)
How-to guide	HowTo	Article, BreadcrumbList
FAQ page	FAQPage	—
Product page	Product	Offer, AggregateRating, BreadcrumbList
Local business	LocalBusiness	OpeningHoursSpecification, GeoCoordinates
Video page	VideoObject	Article (if video is embedded in article)
Category / hub page	CollectionPage	BreadcrumbList
Event	Event	Organization, Place

Stacking rules:

Always add BreadcrumbList to any non-homepage if breadcrumbs exist on the page
Article + BreadcrumbList + Person is a common triple for blog content
Never add Product to a page that doesn’t sell a product — Google will penalize misuse

Implementation Patterns

JSON-LD vs Microdata vs RDFa

Use JSON-LD. Full stop. Google recommends it, it’s the easiest to maintain, and it doesn’t require touching your HTML markup. Microdata and RDFa are legacy.

Placement

<head>
  <!-- All other meta tags -->
  <script type="application/ld+json">
  { ... your schema here ... }
  </script>
</head>

Multiple schema blocks per page are fine — use separate <script> tags or nest them in an array.

Per-Page vs Site-Wide

Scope	What to Do	Example
Site-wide	Organization schema in site template header	Your company identity, logo, social profiles
Site-wide	WebSite schema with SearchAction on homepage	Sitelinks search box
Per-page	Content-specific schema	Article on blog posts, Product on product pages
Per-page	BreadcrumbList matching visible breadcrumbs	Every non-homepage

CMS implementation shortcuts:

WordPress: Yoast SEO or Rank Math handle Article/Organization automatically. Add custom schema via their blocks for HowTo/FAQ.
Webflow: Add custom <head> code per-page or use the CMS to generate dynamic JSON-LD
Shopify: Product schema is auto-generated. Add Organization and Article manually.
Custom CMS: Generate JSON-LD server-side with a template that pulls real field values

Reference patterns

See references/implementation-patterns.md for copy-paste JSON-LD for every schema type listed above.

Common Mistakes

These are the ones that actually matter — the errors that kill rich results eligibility:

Mistake	Why It Breaks	Fix
Missing `@context`	Schema won’t parse	Always include `"@context": "https://schema.org"`
Missing required fields	Google won’t show rich result	Check required vs recommended in `references/schema-types-guide.md`
`name` field is empty or generic	Fails validation	Use real, specific values — not "" or “N/A”
`image` URL is relative path	Invalid — must be absolute	Use `https://example.com/image.jpg` not `/image.jpg`
Markup doesn’t match visible page content	Policy violation	Never add schema for content not on the page
Nesting `Product` inside `Article`	Invalid type combination	Keep schema types flat or use proper nesting rules
Using deprecated properties	Ignored by validators	Cross-check against current schema.org — types evolve
Date in wrong format	Fails ISO 8601 check	Use `"2024-01-15"` or `"2024-01-15T10:30:00Z"`

Schema and AI Search

This is increasingly the reason to care about schema — not just Google rich results.

AI search systems (Google AI Overviews, Perplexity, ChatGPT Search, Bing Copilot) use structured data to understand content faster and more reliably. When your content has clean schema:

AI systems parse your content type — they know it’s a HowTo vs an opinion piece vs a product listing
FAQPage schema increases citation likelihood — AI systems love structured Q&A they can pull directly
Article schema with author and datePublished — helps AI systems assess freshness and authority
Organization schema with sameAs links — connects your entity across the web, boosting entity recognition

Practical actions for AI search visibility:

Add FAQPage schema to any page with Q&A content — even if it’s just 3 questions
Add author with sameAs pointing to real author profiles (LinkedIn, Wikipedia, Google Scholar)
Add Organization with sameAs linking your social profiles and Wikidata entry
Keep datePublished and dateModified accurate — AI systems filter by freshness

Testing & Validation

Always test before publishing. Use all three:

Google Rich Results Test — https://search.google.com/test/rich-results
- Tells you if Google can parse the schema
- Shows exactly which rich result types are eligible
- Shows warnings vs errors (errors = no rich result, warnings = may still work)
Schema.org Validator — https://validator.schema.org
- Broader validation against the full schema.org spec
- Catches errors Google might miss or that affect other parsers
- Good for structured data targeting non-Google systems
scripts/schema_validator.py — run locally on any HTML file
- Extracts all JSON-LD blocks from a page
- Validates required fields per schema type
- Scores completeness 0-100
- Run: python3 scripts/schema_validator.py page.html
Google Search Console (after deployment)
- Enhancements section shows real-world errors at scale
- Takes 1-2 weeks to update after deployment
- The only place to see rich results performance data (impressions, clicks)

Proactive Triggers

Surface these without being asked:

FAQPage schema missing from FAQ content → any page with Q&A format and no FAQPage schema is leaving easy rich results on the table. Flag it and offer to generate.
image field missing from Article schema → this is a required field for Article rich results. Google won’t show the article card without it.
Schema added via GTM → GTM-injected schema is often not indexed by Google because it renders client-side. Recommend server-side injection.
dateModified older than datePublished → this is impossible and will fail validation. Flag and fix.
Multiple conflicting @type on same entity → e.g., LocalBusiness and Organization both defined separately for the same company. Should be combined or one should extend the other.
Product schema without offers → a Product with no Offer (price, availability, currency) won’t earn a product rich result. Flag the missing Offer block.

Output Artifacts

When you ask for…	You get…
Schema audit	Audit report: schemas found, required fields present/missing, errors, completeness score per page, priority fixes
Schema for a page type	Complete JSON-LD block(s), copy-paste ready, populated with placeholder values clearly marked
Fix my schema errors	Corrected JSON-LD with change log explaining each fix
AI search visibility review	Entity markup gap analysis + FAQPage + Organization `sameAs` recommendations
Implementation plan	Page-by-page schema implementation matrix with CMS-specific instructions

Communication

All output follows the structured communication standard:

Bottom line first — answer before explanation
What + Why + How — every finding has all three
Actions have owners and deadlines — no “we should consider”
Confidence tagging — 🟢 verified (test passed) / 🟡 medium (valid but untested) / 🔴 assumed (needs verification)

seo-audit: For full technical and content SEO audit. Use seo-audit when the problem spans more than just structured data. NOT for schema-specific work — use schema-markup.
site-architecture: For URL structure, internal linking, and navigation. Use when architecture is the root cause of SEO problems, not schema.
content-strategy: For what content to create. Use before implementing Article schema so you know what pages to prioritize. NOT for the schema itself.
programmatic-seo: For sites with thousands of pages that need schema at scale. Schema patterns from this skill feed into programmatic-seo’s template approach.

Implementation Patterns

Copy-paste JSON-LD patterns for every common schema type. Replace ALL_CAPS placeholders with real values. Test at rich-results.google.com before deploying.

Article (Blog Post)

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "ARTICLE_TITLE_MAX_110_CHARS",
  "description": "ARTICLE_DESCRIPTION_150_TO_300_CHARS",
  "image": {
    "@type": "ImageObject",
    "url": "https://YOURDOMAIN.COM/images/ARTICLE_IMAGE.jpg",
    "width": 1200,
    "height": 630
  },
  "author": {
    "@type": "Person",
    "name": "AUTHOR_FULL_NAME",
    "url": "https://YOURDOMAIN.COM/author/AUTHOR_SLUG",
    "sameAs": "https://www.linkedin.com/in/AUTHOR_LINKEDIN"
  },
  "publisher": {
    "@type": "Organization",
    "name": "PUBLICATION_OR_COMPANY_NAME",
    "logo": {
      "@type": "ImageObject",
      "url": "https://YOURDOMAIN.COM/images/logo.png",
      "width": 250,
      "height": 60
    }
  },
  "datePublished": "YYYY-MM-DD",
  "dateModified": "YYYY-MM-DD",
  "url": "https://YOURDOMAIN.COM/blog/ARTICLE_SLUG",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://YOURDOMAIN.COM/blog/ARTICLE_SLUG"
  }
}

HowTo Guide

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to TASK_NAME",
  "description": "BRIEF_DESCRIPTION_OF_WHAT_IS_ACCOMPLISHED",
  "image": "https://YOURDOMAIN.COM/images/HOWTO_IMAGE.jpg",
  "totalTime": "PT30M",
  "tool": [
    {
      "@type": "HowToTool",
      "name": "TOOL_NAME_1"
    },
    {
      "@type": "HowToTool",
      "name": "TOOL_NAME_2"
    }
  ],
  "supply": [
    {
      "@type": "HowToSupply",
      "name": "SUPPLY_NAME_1"
    }
  ],
  "step": [
    {
      "@type": "HowToStep",
      "position": 1,
      "name": "STEP_1_TITLE",
      "text": "STEP_1_FULL_INSTRUCTIONS",
      "image": "https://YOURDOMAIN.COM/images/step-1.jpg"
    },
    {
      "@type": "HowToStep",
      "position": 2,
      "name": "STEP_2_TITLE",
      "text": "STEP_2_FULL_INSTRUCTIONS",
      "image": "https://YOURDOMAIN.COM/images/step-2.jpg"
    },
    {
      "@type": "HowToStep",
      "position": 3,
      "name": "STEP_3_TITLE",
      "text": "STEP_3_FULL_INSTRUCTIONS"
    }
  ]
}

Note: totalTime uses ISO 8601 duration. PT30M = 30 minutes. PT1H30M = 1 hour 30 minutes.

FAQPage

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "FIRST_QUESTION_TEXT?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "FIRST_ANSWER_TEXT. Keep answers complete but concise — this appears directly in search results."
      }
    },
    {
      "@type": "Question",
      "name": "SECOND_QUESTION_TEXT?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "SECOND_ANSWER_TEXT."
      }
    },
    {
      "@type": "Question",
      "name": "THIRD_QUESTION_TEXT?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "THIRD_ANSWER_TEXT."
      }
    }
  ]
}

Note: Add as many Question/Answer pairs as the page has. Google typically shows 3-5 in results.

Product with Offers and Ratings

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "PRODUCT_NAME",
  "description": "PRODUCT_DESCRIPTION",
  "image": [
    "https://YOURDOMAIN.COM/images/product-front.jpg",
    "https://YOURDOMAIN.COM/images/product-side.jpg"
  ],
  "sku": "PRODUCT_SKU",
  "brand": {
    "@type": "Brand",
    "name": "BRAND_NAME"
  },
  "offers": {
    "@type": "Offer",
    "url": "https://YOURDOMAIN.COM/products/PRODUCT_SLUG",
    "priceCurrency": "USD",
    "price": 49.99,
    "priceValidUntil": "YYYY-MM-DD",
    "availability": "https://schema.org/InStock",
    "itemCondition": "https://schema.org/NewCondition",
    "seller": {
      "@type": "Organization",
      "name": "YOUR_STORE_NAME"
    }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": 4.7,
    "reviewCount": 143,
    "bestRating": 5,
    "worstRating": 1
  }
}

Availability options:

https://schema.org/InStock
https://schema.org/OutOfStock
https://schema.org/PreOrder
https://schema.org/Discontinued

Organization (Site-Wide, in Header Template)

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "COMPANY_LEGAL_NAME",
  "url": "https://YOURDOMAIN.COM",
  "logo": {
    "@type": "ImageObject",
    "url": "https://YOURDOMAIN.COM/images/logo.png",
    "width": 250,
    "height": 60
  },
  "description": "COMPANY_DESCRIPTION_1_SENTENCE",
  "foundingDate": "YYYY",
  "sameAs": [
    "https://www.linkedin.com/company/YOUR_COMPANY",
    "https://twitter.com/YOUR_HANDLE",
    "https://www.facebook.com/YOUR_PAGE",
    "https://www.crunchbase.com/organization/YOUR_COMPANY",
    "https://www.wikidata.org/wiki/QXXXXXXX"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "+1-800-555-0100",
    "contactType": "customer service",
    "areaServed": "US",
    "availableLanguage": "English"
  }
}

LocalBusiness

{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "BUSINESS_NAME",
  "image": "https://YOURDOMAIN.COM/images/storefront.jpg",
  "url": "https://YOURDOMAIN.COM",
  "telephone": "+1-555-555-5555",
  "priceRange": "$$",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main Street",
    "addressLocality": "City Name",
    "addressRegion": "ST",
    "postalCode": "12345",
    "addressCountry": "US"
  },
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": 40.7128,
    "longitude": -74.0060
  },
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
      "opens": "09:00",
      "closes": "17:00"
    },
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": "Saturday",
      "opens": "10:00",
      "closes": "14:00"
    }
  ],
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": 4.6,
    "reviewCount": 87,
    "bestRating": 5
  }
}

BreadcrumbList

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://YOURDOMAIN.COM"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "CATEGORY_NAME",
      "item": "https://YOURDOMAIN.COM/CATEGORY-SLUG"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "CURRENT_PAGE_TITLE",
      "item": "https://YOURDOMAIN.COM/CATEGORY-SLUG/PAGE-SLUG"
    }
  ]
}

VideoObject

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "VIDEO_TITLE",
  "description": "VIDEO_DESCRIPTION_FULL",
  "thumbnailUrl": "https://YOURDOMAIN.COM/images/video-thumbnail.jpg",
  "uploadDate": "YYYY-MM-DD",
  "duration": "PT12M30S",
  "contentUrl": "https://YOURDOMAIN.COM/videos/VIDEO_FILE.mp4",
  "embedUrl": "https://www.youtube.com/embed/VIDEO_ID",
  "interactionStatistic": {
    "@type": "InteractionCounter",
    "interactionType": "https://schema.org/WatchAction",
    "userInteractionCount": 5000
  },
  "hasPart": [
    {
      "@type": "Clip",
      "name": "Introduction",
      "startOffset": 0,
      "endOffset": 90,
      "url": "https://YOURDOMAIN.COM/video/VIDEO_SLUG#t=0"
    },
    {
      "@type": "Clip",
      "name": "KEY_SECTION_NAME",
      "startOffset": 180,
      "endOffset": 360,
      "url": "https://YOURDOMAIN.COM/video/VIDEO_SLUG#t=180"
    }
  ]
}

Combined: Article + BreadcrumbList (Most Blog Posts)

Use two separate <script> tags on the same page:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "ARTICLE_TITLE",
  ...full Article schema...
}
</script>

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  ...full BreadcrumbList schema...
}
</script>

Or combine into a single @graph array:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "BlogPosting",
      ...
    },
    {
      "@type": "BreadcrumbList",
      ...
    }
  ]
}
</script>

Both approaches are valid. @graph is cleaner for sites with many schema types per page.

WebSite (Homepage Only)

{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://YOURDOMAIN.COM",
  "name": "SITE_NAME",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://YOURDOMAIN.COM/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

Note: Only add this if you have a working internal search at the URL template path.

Duration Format Reference (ISO 8601)

Duration	ISO 8601
30 minutes	`PT30M`
1 hour	`PT1H`
1 hour 30 minutes	`PT1H30M`
2 hours 15 minutes	`PT2H15M`
5 minutes 30 seconds	`PT5M30S`
12 minutes 30 seconds	`PT12M30S`

Availability Values Reference

Always use the full schema.org URL — not just the word.

Status	Value
In stock	`https://schema.org/InStock`
Out of stock	`https://schema.org/OutOfStock`
Pre-order	`https://schema.org/PreOrder`
Back order	`https://schema.org/BackOrder`
Limited availability	`https://schema.org/LimitedAvailability`
Discontinued	`https://schema.org/Discontinued`

Schema Types Guide

A practitioner's reference for schema.org types — what they do, what fields matter, and what Google actually uses for rich results.

How to Read This Guide

Each type lists:

Purpose — what it tells search engines
Rich result — what you can earn in Google (if anything)
Required fields — missing these = no rich result
Recommended fields — fill these to maximize eligibility
Gotchas — the field mistakes that waste everyone's time

Article

Purpose: Marks editorial content — news, blog posts, opinion pieces.

Rich result: Article rich result (expanded card in Google News, Discover, and some search results). Also influences AI Overview citation likelihood.

Required fields:

headline — the article title (max 110 characters for display)
image — at least one image, minimum 1200px wide for rich results
datePublished — ISO 8601 format
author — Person or Organization type

Recommended fields:

dateModified — keep current; freshness signal
publisher — Organization type with logo
description — 150-300 char summary
url — canonical URL of the article

Subtypes: Use NewsArticle for news content, BlogPosting for blog posts. Both inherit from Article. Google treats them similarly.

Gotchas:

image must be absolute URL. Relative URLs fail silently.
headline should match the visible <h1> on the page. Google cross-validates.
Multiple author values are valid — use an array: "author": [{"@type": "Person", "name": "..."}, ...]

HowTo

Purpose: Step-by-step instructions for completing a task.

Rich result: HowTo steps appear directly in Google search results as expandable steps (desktop and mobile).

Required fields:

name — title of the how-to (e.g., "How to change a bike tire")
step — array of HowToStep objects, each with:
- name — step title
- text — step instructions

Recommended fields:

image — overall how-to image
totalTime — ISO 8601 duration (e.g., "PT30M" = 30 minutes)
tool — list of tools needed (HowToTool type)
supply — list of materials (HowToSupply type)
estimatedCost — MonetaryAmount type

Gotchas:

Steps must appear on the page in readable form — hidden steps fail Google's content matching.
HowToStep image is different from the main image — each step can have its own.
Don't use HowTo for recipe content — use Recipe type instead.

FAQPage

Purpose: A page containing a list of frequently asked questions and their answers.

Rich result: FAQ accordion dropdowns directly in Google search results. High-value visibility — shows your Q&A without clicking.

Required fields:

mainEntity — array of Question objects, each with:
- name — the question text
- acceptedAnswer — Answer type with text field containing the answer

Recommended fields:

No additional fields required — this type is simple by design.

Gotchas:

Both the question AND the answer must be visible on the page. Google explicitly checks.
Answers with HTML tags (links, bold) may or may not render — keep answers as clean text.
Google limits FAQ rich results to 3-5 Q&A pairs visible in search, even if you have more.
Don't use FAQPage for Q&A that requires a login to view — Google can't verify it.

Product

Purpose: Describes a product for sale, including pricing, availability, and reviews.

Rich result: Product rich results with price, availability, rating stars. Eligible for Google Shopping surfaces.

Required fields (for rich results):

name — product name
offers — Offer type with:
- price — numeric price (not formatted with currency symbol)
- priceCurrency — ISO 4217 currency code (e.g., "USD", "EUR")
- availability — schema.org availability URL (e.g., "https://schema.org/InStock")

Recommended fields:

image — product image(s), absolute URLs
description — product description
sku — stock-keeping unit
brand — Brand or Organization type
aggregateRating — AggregateRating type (required for star ratings)
review — individual Review objects

AggregateRating required fields:

ratingValue — average rating
reviewCount — number of reviews (or ratingCount)
bestRating — maximum rating value (default: 5)

Gotchas:

Price must be a number, not a string: "price": 29.99 not "price": "$29.99"
availability must use the full schema.org URL, not just "InStock"
If you show ratings, you must have real reviews — fabricated ratings violate Google's policies
Price shown in schema must match the price visible on the page

Organization

Purpose: Identifies your company/organization as an entity to search engines and knowledge graphs.

Rich result: Knowledge panel information, logo in search results, organization entity recognition.

Required fields:

name — official organization name
url — organization website

Recommended fields:

logo — ImageObject with absolute URL to logo
sameAs — array of URLs to your organization's profiles elsewhere (LinkedIn, Twitter/X, Facebook, Crunchbase, Wikidata, Wikipedia)
contactPoint — ContactPoint type with telephone and contactType
address — PostalAddress type
foundingDate — year or ISO date
numberOfEmployees — QuantitativeValue type
description — brief company description

Gotchas:

sameAs is the most important field for entity establishment — the more authoritative sources you include, the stronger the entity signal.
Use https://www.wikidata.org/wiki/Q[ID] in sameAs if your company has a Wikidata entry.
Only one Organization schema per domain — put it on every page if you want, but keep it consistent.

LocalBusiness

Purpose: Extends Organization for businesses with a physical location. Used for local search results and map listings.

Rich result: Local knowledge panel, map pin details, opening hours, star ratings in local results.

Required fields:

name — business name
address — PostalAddress with streetAddress, addressLocality, postalCode, addressCountry

Recommended fields:

telephone — with country code (e.g., "+1-800-555-1234")
openingHoursSpecification — array by day with opens/closes times
geo — GeoCoordinates with latitude and longitude
priceRange — string like "$$" or "€€" or "$10-$50"
image — photos of the business
url — website URL
aggregateRating — if you have reviews

Subtypes: Use the most specific subtype available. Restaurant, MedicalClinic, LegalService, Hotel all extend LocalBusiness and unlock additional rich result fields.

Gotchas:

Address must exactly match what's in Google Business Profile for local SEO to connect.
Hours must use 24-hour format in openingHoursSpecification.
If closed on a day, omit that day rather than using "00:00".

BreadcrumbList

Purpose: Represents the breadcrumb trail shown on a page — the hierarchy from homepage to current page.

Rich result: Breadcrumb path shown in Google search results instead of the raw URL. Cleaner appearance, more clicks.

Required fields:

itemListElement — array of ListItem objects, each with:
- position — integer starting at 1
- name — breadcrumb label
- item — absolute URL of that breadcrumb level

Recommended fields: None required beyond the above.

Gotchas:

Positions must be sequential integers starting at 1. Gaps or non-integers fail validation.
The last breadcrumb (current page) may omit item since it's the current URL — but including it is safer.
Breadcrumb schema must match the visible breadcrumbs on the page.
Use on every non-homepage if you have visible breadcrumbs.

VideoObject

Purpose: Describes an embedded or hosted video.

Rich result: Video carousels, video badges on search results, timestamp markers that appear in results.

Required fields:

name — video title
description — video description
thumbnailUrl — absolute URL to thumbnail image
uploadDate — ISO 8601 date

Recommended fields:

duration — ISO 8601 duration (e.g., "PT12M30S" = 12 min 30 sec)
contentUrl — direct URL to the video file
embedUrl — URL of the embeddable player
hasPart — array of Clip objects with start/end times for key moments
interactionStatistic — view count (InteractionCounter type)

Key moments (Clip type for timestamp markers):

"hasPart": [
  {
    "@type": "Clip",
    "name": "Introduction",
    "startOffset": 0,
    "endOffset": 60,
    "url": "https://example.com/video#t=0"
  }
]

Gotchas:

thumbnailUrl must resolve to an actual image — Google checks it.
Without contentUrl or embedUrl, Google may not index the video.
Videos behind login/paywall are not eligible for video rich results.

WebSite

Purpose: Identifies your website and enables the sitelinks search box in Google results.

Rich result: Sitelinks search box — a search field that appears under your domain in branded searches.

Required fields:

url — homepage URL

potentialAction — SearchAction type for sitelinks search box:

"potentialAction": {
  "@type": "SearchAction",
  "target": {
    "@type": "EntryPoint",
    "urlTemplate": "https://example.com/search?q={search_term_string}"
  },
  "query-input": "required name=search_term_string"
}

Gotchas:

Only put WebSite schema on the homepage.
The urlTemplate must point to a working search endpoint.
Sitelinks search box only appears for branded queries — this won't help you rank for generic terms.

Schema Eligibility Summary

Quick-reference: what actually earns a rich result vs what's just entity data.

Schema Type	Rich Result Available	Rich Result Type
Article	✅	Top stories card, article rich result
HowTo	✅	Step-by-step in SERP
FAQPage	✅	Accordion Q&A in SERP
Product + Offer	✅	Price/availability badge
Product + AggregateRating	✅	Star ratings
LocalBusiness	✅	Local knowledge panel
BreadcrumbList	✅	Breadcrumb path in SERP
VideoObject	✅	Video carousel, key moments
Organization	⚠️	Knowledge panel (not guaranteed)
WebSite	⚠️	Sitelinks search box (not guaranteed)

#!/usr/bin/env python3
"""
schema_validator.py — Extracts and validates JSON-LD structured data from HTML.

Usage:
    python3 schema_validator.py [file.html]
    cat page.html | python3 schema_validator.py

If no file is provided, runs on embedded sample HTML for demonstration.

Output: Human-readable validation report + JSON summary.
Scoring: 0-100 per schema block based on required/recommended field coverage.
"""

import json
import sys
import re
import select
from html.parser import HTMLParser
from typing import List, Dict, Any, Optional


# ─── Required and recommended fields per schema type ─────────────────────────

SCHEMA_RULES: Dict[str, Dict[str, List[str]]] = {
    "Article": {
        "required": ["headline", "image", "datePublished", "author"],
        "recommended": ["dateModified", "publisher", "description", "url", "mainEntityOfPage"],
    },
    "BlogPosting": {
        "required": ["headline", "image", "datePublished", "author"],
        "recommended": ["dateModified", "publisher", "description", "url", "mainEntityOfPage"],
    },
    "NewsArticle": {
        "required": ["headline", "image", "datePublished", "author"],
        "recommended": ["dateModified", "publisher", "description", "url"],
    },
    "HowTo": {
        "required": ["name", "step"],
        "recommended": ["description", "image", "totalTime", "tool", "supply", "estimatedCost"],
    },
    "FAQPage": {
        "required": ["mainEntity"],
        "recommended": [],
    },
    "Product": {
        "required": ["name", "offers"],
        "recommended": ["description", "image", "sku", "brand", "aggregateRating"],
    },
    "Organization": {
        "required": ["name", "url"],
        "recommended": ["logo", "sameAs", "contactPoint", "description", "foundingDate"],
    },
    "LocalBusiness": {
        "required": ["name", "address"],
        "recommended": ["telephone", "openingHoursSpecification", "geo", "priceRange", "image", "url"],
    },
    "BreadcrumbList": {
        "required": ["itemListElement"],
        "recommended": [],
    },
    "VideoObject": {
        "required": ["name", "description", "thumbnailUrl", "uploadDate"],
        "recommended": ["duration", "contentUrl", "embedUrl", "interactionStatistic", "hasPart"],
    },
    "WebSite": {
        "required": ["url"],
        "recommended": ["name", "potentialAction"],
    },
    "Event": {
        "required": ["name", "startDate", "location"],
        "recommended": ["endDate", "description", "image", "organizer", "offers"],
    },
    "Recipe": {
        "required": ["name", "image", "author", "datePublished"],
        "recommended": ["description", "cookTime", "prepTime", "totalTime", "recipeYield",
                        "recipeIngredient", "recipeInstructions", "aggregateRating"],
    },
}

KNOWN_TYPES = set(SCHEMA_RULES.keys())


# ─── HTML Parser to extract JSON-LD blocks ───────────────────────────────────

class JSONLDExtractor(HTMLParser):
    """Extracts all <script type="application/ld+json"> blocks from HTML."""

    def __init__(self):
        super().__init__()
        self.blocks: List[str] = []
        self._in_ld_json = False
        self._current = []

    def handle_starttag(self, tag: str, attrs: list):
        if tag.lower() == "script":
            attr_dict = dict(attrs)
            if attr_dict.get("type", "").lower() == "application/ld+json":
                self._in_ld_json = True
                self._current = []

    def handle_endtag(self, tag: str):
        if tag.lower() == "script" and self._in_ld_json:
            self._in_ld_json = False
            self.blocks.append("".join(self._current).strip())

    def handle_data(self, data: str):
        if self._in_ld_json:
            self._current.append(data)


# ─── Validation logic ────────────────────────────────────────────────────────

def detect_type(obj: Dict) -> Optional[str]:
    """Determine the @type of a schema object."""
    t = obj.get("@type")
    if isinstance(t, list):
        # Return first known type
        for item in t:
            if item in KNOWN_TYPES:
                return item
        return t[0] if t else None
    return t


def score_schema(schema_type: str, obj: Dict) -> Dict:
    """Score a single schema object against known rules. Returns 0-100."""
    if schema_type not in SCHEMA_RULES:
        return {
            "score": 50,
            "status": "unknown_type",
            "required_present": [],
            "required_missing": [],
            "recommended_present": [],
            "recommended_missing": [],
            "notes": [f"No validation rules defined for '{schema_type}' — manual check recommended."],
        }

    rules = SCHEMA_RULES[schema_type]
    required = rules.get("required", [])
    recommended = rules.get("recommended", [])

    required_present = [f for f in required if f in obj and obj[f]]
    required_missing = [f for f in required if f not in obj or not obj[f]]
    recommended_present = [f for f in recommended if f in obj and obj[f]]
    recommended_missing = [f for f in recommended if f not in obj or not obj[f]]

    # Score: required fields = 70 points, recommended = 30 points
    req_score = (len(required_present) / len(required) * 70) if required else 70
    rec_score = (len(recommended_present) / len(recommended) * 30) if recommended else 30
    total_score = int(req_score + rec_score)

    notes = []

    # Type-specific checks
    if schema_type in ("Article", "BlogPosting", "NewsArticle"):
        image = obj.get("image")
        if image:
            img_url = image if isinstance(image, str) else image.get("url", "") if isinstance(image, dict) else ""
            if img_url and not img_url.startswith("http"):
                notes.append("⚠️  'image' URL appears to be relative — must be absolute (https://...)")
        if "datePublished" in obj:
            dp = obj["datePublished"]
            if not re.match(r"\d{4}-\d{2}-\d{2}", str(dp)):
                notes.append("⚠️  'datePublished' should be ISO 8601 format: YYYY-MM-DD")

    if schema_type == "Product":
        offers = obj.get("offers", {})
        if isinstance(offers, dict):
            price = offers.get("price")
            if isinstance(price, str) and any(c in price for c in "$€£¥"):
                notes.append("⚠️  'offers.price' should be numeric (49.99), not a string with currency symbol.")
            avail = offers.get("availability", "")
            if avail and not avail.startswith("https://schema.org/"):
                notes.append("⚠️  'offers.availability' must use full URL: https://schema.org/InStock")

    if schema_type == "FAQPage":
        entities = obj.get("mainEntity", [])
        if isinstance(entities, list):
            for i, q in enumerate(entities):
                if not q.get("acceptedAnswer", {}).get("text"):
                    notes.append(f"⚠️  Question #{i+1} has empty 'acceptedAnswer.text'")

    if schema_type == "BreadcrumbList":
        items = obj.get("itemListElement", [])
        if isinstance(items, list):
            positions = [item.get("position") for item in items if isinstance(item, dict)]
            if sorted(positions) != list(range(1, len(positions) + 1)):
                notes.append("⚠️  'itemListElement' positions must be sequential integers starting at 1.")

    return {
        "score": total_score,
        "status": "valid" if not required_missing else "missing_required",
        "required_present": required_present,
        "required_missing": required_missing,
        "recommended_present": recommended_present,
        "recommended_missing": recommended_missing,
        "notes": notes,
    }


def validate_block(raw_json: str, block_index: int) -> List[Dict]:
    """Parse and validate a single JSON-LD block. Returns list of results (may contain @graph)."""
    results = []
    try:
        data = json.loads(raw_json)
    except json.JSONDecodeError as e:
        return [{
            "block": block_index,
            "type": "PARSE_ERROR",
            "score": 0,
            "status": "parse_error",
            "error": str(e),
            "notes": ["❌ JSON is malformed — fix syntax before validation."],
        }]

    # Handle @graph
    objects = data.get("@graph", [data]) if isinstance(data, dict) else [data]

    for obj in objects:
        if not isinstance(obj, dict):
            continue
        schema_type = detect_type(obj)
        if not schema_type:
            results.append({
                "block": block_index,
                "type": "UNKNOWN",
                "score": 0,
                "status": "no_type",
                "notes": ["❌ No '@type' found in schema object."],
            })
            continue

        validation = score_schema(schema_type, obj)
        results.append({
            "block": block_index,
            "type": schema_type,
            **validation,
        })

    return results


def grade(score: int) -> str:
    if score >= 90:
        return "🟢 Excellent"
    if score >= 70:
        return "🟡 Good"
    if score >= 50:
        return "🟠 Needs Work"
    return "🔴 Poor"


# ─── Report printer ──────────────────────────────────────────────────────────

def print_report(all_results: List[Dict], html_source: str) -> None:
    print("\n" + "═" * 60)
    print("  SCHEMA MARKUP VALIDATION REPORT")
    print("═" * 60)

    if not all_results:
        print("\n❌ No JSON-LD blocks found in this HTML.")
        print("   Add structured data in <script type=\"application/ld+json\"> tags.\n")
        return

    total_score = 0
    for r in all_results:
        print(f"\n── Block {r['block']} · @type: {r['type']} ──")
        score = r.get("score", 0)
        total_score += score
        print(f"   Score: {score}/100  {grade(score)}")

        if r.get("status") == "parse_error":
            print(f"   ❌ Parse error: {r.get('error')}")
            continue

        if r.get("required_missing"):
            print(f"   Missing required: {', '.join(r['required_missing'])}")
        else:
            print(f"   Required fields: ✅ All present ({', '.join(r.get('required_present', []))})")

        if r.get("recommended_missing"):
            print(f"   Missing recommended: {', '.join(r['recommended_missing'])}")
        if r.get("recommended_present"):
            print(f"   Recommended present: {', '.join(r['recommended_present'])}")

        for note in r.get("notes", []):
            print(f"   {note}")

    avg = total_score // len(all_results) if all_results else 0
    print(f"\n{'═' * 60}")
    print(f"  OVERALL SCORE: {avg}/100  {grade(avg)}")
    print(f"  Blocks analyzed: {len(all_results)}")
    print("═" * 60)

    print("\n📋 TESTING CHECKLIST")
    print("  □ Google Rich Results Test: https://search.google.com/test/rich-results")
    print("  □ Schema.org Validator: https://validator.schema.org")
    print("  □ After deploy: Check Search Console → Enhancements\n")


# ─── Sample HTML ─────────────────────────────────────────────────────────────

SAMPLE_HTML = """<!DOCTYPE html>
<html>
<head>
  <title>How to Write Cold Emails That Get Replies</title>

  <!-- Article schema — headline present, but image is relative URL -->
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    "headline": "How to Write Cold Emails That Get Replies",
    "image": "/images/cold-email-guide.jpg",
    "datePublished": "2024-03-01",
    "dateModified": "2024-03-15",
    "author": {
      "@type": "Person",
      "name": "Reza Rezvani"
    },
    "publisher": {
      "@type": "Organization",
      "name": "Growth Lab",
      "logo": {
        "@type": "ImageObject",
        "url": "https://growthlab.com/logo.png"
      }
    }
  }
  </script>

  <!-- FAQPage schema — complete and valid -->
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "What is the ideal length for a cold email?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Keep cold emails under 150 words. Busy professionals scan, not read. If your email needs scrolling, it will not get a reply."
        }
      },
      {
        "@type": "Question",
        "name": "How many follow-ups should I send?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Send 3-5 follow-ups with increasing gaps (3 days, 5 days, 7 days, 14 days). Each follow-up must add new value — never just check in."
        }
      }
    ]
  }
  </script>

  <!-- BreadcrumbList — position gap (jumps from 1 to 3) -->
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": [
      {
        "@type": "ListItem",
        "position": 1,
        "name": "Home",
        "item": "https://growthlab.com"
      },
      {
        "@type": "ListItem",
        "position": 3,
        "name": "How to Write Cold Emails",
        "item": "https://growthlab.com/blog/cold-email-guide"
      }
    ]
  }
  </script>

</head>
<body>
  <h1>How to Write Cold Emails That Get Replies</h1>
  <p>Cold email works when it sounds human...</p>
</body>
</html>
"""


# ─── Main ─────────────────────────────────────────────────────────────────────

def main():
    import argparse

    parser = argparse.ArgumentParser(
        description="Extracts and validates JSON-LD structured data from HTML. "
                    "Scores 0-100 per schema block based on required/recommended field coverage."
    )
    parser.add_argument(
        "file", nargs="?", default=None,
        help="Path to an HTML file to validate. "
             "Use '-' to read from stdin. If omitted, runs embedded sample."
    )
    args = parser.parse_args()

    if args.file:
        if args.file == "-":
            html = sys.stdin.read()
        else:
            try:
                with open(args.file, "r", encoding="utf-8") as f:
                    html = f.read()
            except FileNotFoundError:
                print(f"Error: File not found: {args.file}", file=sys.stderr)
                sys.exit(1)
    else:
        print("No file provided — running on embedded sample HTML.\n")
        html = SAMPLE_HTML

    extractor = JSONLDExtractor()
    extractor.feed(html)

    all_results = []
    for i, block in enumerate(extractor.blocks, start=1):
        results = validate_block(block, i)
        all_results.extend(results)

    print_report(all_results, html)

    # JSON output for programmatic use
    summary = {
        "blocks_found": len(extractor.blocks),
        "schemas_validated": len(all_results),
        "average_score": (sum(r.get("score", 0) for r in all_results) // len(all_results)) if all_results else 0,
        "results": all_results,
    }
    print("\n── JSON Output ──")
    print(json.dumps(summary, indent=2))


if __name__ == "__main__":
    main()

Install this Skill

Skills give your AI agent a consistent, structured approach to this task — better output than a one-off prompt.

npx skills add alirezarezvani/claude-skills --skill marketing-skill/schema-markup

Download ZIP

Community skill by @alirezarezvani. Need a walkthrough? See the install guide →

Works with

Claude Code OpenAI Codex CLI Gemini CLI

Prefer no terminal? Download the ZIP and place it manually.

Details

Category: Marketing
License: MIT
Author: @alirezarezvani
Source: GitHub →
Source file: show path
marketing-skill/schema-markup/SKILL.md

schema-markup structured-data JSON-LD rich-snippets SEO

People who install this also use

📣

Marketing Seo Audit

Run a comprehensive SEO audit — keyword research, on-page analysis, content gaps, technical checks, and competitor comparison. Use when assessing a site's SEO health, when finding keyword opportunities and content gaps competitors own, or when you need a prioritized action plan split into quick wins and strategic investments.

@anthropics

🤖

AI SEO Optimizer

Optimize content for AI search engines — get cited by ChatGPT, Perplexity, and AI Overviews with GEO/AEO techniques beyond traditional SEO.

@alirezarezvani

⚡

Programmatic SEO Builder

Build SEO-driven pages at scale using templates and data — location pages, comparison pages, integration pages, and other high-volume keyword strategies.

@alirezarezvani

Schema Markup Specialist

Schema Markup Implementation

Before Starting

1. Current State

2. Site Details

3. Goals

How This Skill Works

Mode 1: Audit Existing Markup

Mode 2: Implement New Schema

Mode 3: Validate & Fix

Schema Type Selection

Implementation Patterns

JSON-LD vs Microdata vs RDFa

Placement

Per-Page vs Site-Wide

Reference patterns

Common Mistakes

Schema and AI Search

Testing & Validation

Proactive Triggers

Output Artifacts

Communication

Related Skills

Implementation Patterns

Article (Blog Post)

HowTo Guide

FAQPage

Product with Offers and Ratings

Organization (Site-Wide, in Header Template)

LocalBusiness

BreadcrumbList

VideoObject

Combined: Article + BreadcrumbList (Most Blog Posts)

WebSite (Homepage Only)

Duration Format Reference (ISO 8601)

Availability Values Reference

Schema Types Guide

How to Read This Guide

Article

HowTo

FAQPage

Product

Organization

LocalBusiness

BreadcrumbList

VideoObject

WebSite

Schema Eligibility Summary

Install this Skill

Works with

Details

People who install this also use