Schema.org Structured Data & JSON-LD

JSON-LD Fundamentals

JSON-LD (JavaScript Object Notation for Linked Data) is Google's recommended format for structured data. It is injected via a <script> tag in the <head> or <body> of an HTML page.

Basic Syntax

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "How to Implement Structured Data",
  "author": {
    "@type": "Person",
    "name": "Jane Smith"
  }
}
</script>

Core Keywords

Keyword	Purpose	Example
`@context`	Declares the vocabulary (always `https://schema.org`)	`"@context": "https://schema.org"`
`@type`	Specifies the entity type	`"@type": "Article"`
`@id`	Unique identifier for an entity (enables cross-referencing)	`"@id": "https://example.com/#organization"`
`@graph`	Contains multiple entities in a single JSON-LD block	`"@graph": [{ ... }, { ... }]`

Nesting Entities

Entities can be nested directly or referenced by @id:

{
  "@context": "https://schema.org",
  "@type": "Article",
  "author": {
    "@type": "Person",
    "name": "Jane Smith",
    "@id": "https://example.com/#jane"
  },
  "publisher": {
    "@id": "https://example.com/#organization"
  }
}

Arrays

Use arrays when a property has multiple values:

{
  "@type": "Article",
  "author": [
    { "@type": "Person", "name": "Jane Smith" },
    { "@type": "Person", "name": "John Doe" }
  ]
}

The @graph Pattern (Multi-Entity Pages)

Use @graph to describe multiple entities on a single page (e.g., Organization + WebPage + BreadcrumbList):

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Example Corp",
      "url": "https://example.com"
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/about/#webpage",
      "url": "https://example.com/about/",
      "name": "About Us",
      "isPartOf": { "@id": "https://example.com/#website" }
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
        { "@type": "ListItem", "position": 2, "name": "About" }
      ]
    }
  ]
}

Google-Supported Schema Types

The following types are recognized by Google and can trigger rich results. Each section lists required (R) and recommended (Rec) properties.

Article (NewsArticle, BlogPosting)

Triggers: article rich result with headline, image, date in search.

Property	Status	Notes
`headline`	R	Max 110 characters
`image`	R	At least 696px wide; multiple images recommended
`datePublished`	R	ISO 8601 format
`dateModified`	Rec	ISO 8601 format
`author`	R	Person or Organization with `name` and `url`
`publisher`	Rec	Organization with `name` and `logo`
`description`	Rec	Short summary of the article
`mainEntityOfPage`	Rec	URL of the page

MCP Tool: Use extract_schema on any article URL to see its current structured data, then generate_schema with type Article to produce compliant markup.

Product (with Offer, AggregateRating)

Triggers: product rich result with price, availability, rating stars.

Property	Status	Notes
`name`	R	Product name
`image`	R	At least one image
`description`	Rec	Product description
`sku`	Rec	Stock-keeping unit
`brand`	Rec	Brand name
`offers`	R	Offer or AggregateOffer
`offers.price`	R	Numeric price
`offers.priceCurrency`	R	ISO 4217 currency code
`offers.availability`	R	ItemAvailability enum (e.g., `https://schema.org/InStock`)
`offers.url`	Rec	URL to buy
`aggregateRating`	Rec	AggregateRating with `ratingValue` and `reviewCount`
`review`	Rec	Individual Review objects

Nesting pattern: AggregateRating and Offer nest inside Product:

{
  "@type": "Product",
  "name": "Widget",
  "offers": {
    "@type": "Offer",
    "price": "29.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.5",
    "reviewCount": "120"
  }
}

FAQPage (with Question / Answer)

Triggers: expandable FAQ accordion in search results.

Property	Status	Notes
`mainEntity`	R	Array of Question objects
`Question.name`	R	The question text
`Question.acceptedAnswer`	R	Answer object
`Answer.text`	R	The answer text (HTML allowed)

Rules:

Only use FAQPage for pages where the primary content is a list of questions and answers.
Each question and answer must be visible on the page.
Do not use for forums or single-question pages (use QAPage instead).

HowTo (with HowToStep)

Triggers: step-by-step rich result or carousel.

Property	Status	Notes
`name`	R	Title of the how-to
`step`	R	Array of HowToStep objects
`step.name`	R	Step title
`step.text`	R	Step instructions
`step.image`	Rec	Image for each step
`step.url`	Rec	URL anchor to step on page
`totalTime`	Rec	ISO 8601 duration (e.g., `PT30M`)
`estimatedCost`	Rec	MonetaryAmount object
`supply`	Rec	HowToSupply items needed
`tool`	Rec	HowToTool items needed

LocalBusiness (and Subtypes)

Triggers: local knowledge panel, map pack eligibility data.

Subtypes: Restaurant, Dentist, LegalService, RealEstateAgent, MedicalBusiness, etc.

Property	Status	Notes
`name`	R	Business name
`address`	R	PostalAddress object
`telephone`	Rec	Phone number
`openingHoursSpecification`	Rec	Array of hours
`geo`	Rec	GeoCoordinates (lat/long)
`url`	Rec	Website URL
`image`	Rec	Business photo
`priceRange`	Rec	e.g., `$$` or `$10-50`
`servesCuisine`	Rec	For Restaurant subtype
`aggregateRating`	Rec	AggregateRating
`review`	Rec	Review objects

Organization

Triggers: knowledge panel data, logo in search results.

Property	Status	Notes
`name`	R	Organization name
`url`	R	Website URL
`logo`	R	ImageObject or URL (min 112x112px, square preferred)
`sameAs`	Rec	Array of social profile URLs
`contactPoint`	Rec	ContactPoint object
`address`	Rec	PostalAddress
`description`	Rec	Short description
`foundingDate`	Rec	ISO 8601 date

BreadcrumbList

Triggers: breadcrumb trail in search results replacing the URL.

Property	Status	Notes
`itemListElement`	R	Array of ListItem objects
`ListItem.position`	R	Integer (1-indexed)
`ListItem.name`	R	Breadcrumb label
`ListItem.item`	R*	URL (*omit on last item)

WebSite (with SearchAction for Sitelinks Search Box)

Triggers: sitelinks search box on branded queries.

Property	Status	Notes
`url`	R	Homepage URL
`name`	Rec	Site name
`potentialAction`	R	SearchAction object
`SearchAction.target`	R	URL template with `{search_term_string}`
`SearchAction.query-input`	R	`"required name=search_term_string"`

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

Event

Triggers: event rich result with date, location, ticket info.

Property	Status	Notes
`name`	R	Event name
`startDate`	R	ISO 8601 datetime
`location`	R	Place or VirtualLocation
`location.name`	R	Venue name
`location.address`	R	PostalAddress
`endDate`	Rec	ISO 8601 datetime
`description`	Rec	Event description
`image`	Rec	Event image
`offers`	Rec	Offer with price/url/availability
`performer`	Rec	Person or Organization
`organizer`	Rec	Person or Organization
`eventStatus`	Rec	EventScheduled, EventCancelled, EventPostponed, etc.
`eventAttendanceMode`	Rec	OfflineEventAttendanceMode, OnlineEventAttendanceMode, MixedEventAttendanceMode

Recipe

Triggers: recipe rich result with image, rating, cook time.

Property	Status	Notes
`name`	R	Recipe name
`image`	R	Multiple images at different aspect ratios
`author`	R	Person or Organization
`datePublished`	Rec	ISO 8601
`description`	Rec	Short description
`prepTime`	Rec	ISO 8601 duration
`cookTime`	Rec	ISO 8601 duration
`totalTime`	Rec	ISO 8601 duration
`recipeYield`	Rec	e.g., `"4 servings"`
`recipeIngredient`	Rec	Array of strings
`recipeInstructions`	R	Array of HowToStep objects
`nutrition`	Rec	NutritionInformation (calories)
`aggregateRating`	Rec	AggregateRating
`video`	Rec	VideoObject

VideoObject

Triggers: video rich result with thumbnail, duration, upload date.

Property	Status	Notes
`name`	R	Video title
`description`	R	Video description
`thumbnailUrl`	R	Thumbnail image URL
`uploadDate`	R	ISO 8601 date
`contentUrl`	Rec	Direct URL to video file
`embedUrl`	Rec	Embed URL
`duration`	Rec	ISO 8601 duration
`interactionStatistic`	Rec	View count

Course

Triggers: course rich result in search and Google for Education.

Property	Status	Notes
`name`	R	Course title
`description`	R	Course description
`provider`	R	Organization offering the course
`offers`	Rec	Offer with price
`courseCode`	Rec	Identifier
`hasCourseInstance`	Rec	CourseInstance with schedule

SoftwareApplication

Triggers: software rich result with rating, price, OS.

Property	Status	Notes
`name`	R	App name
`operatingSystem`	Rec	e.g., `"Windows 10"`, `"Android"`
`applicationCategory`	Rec	e.g., `"GameApplication"`, `"BusinessApplication"`
`offers`	R	Offer with price (use `"0"` for free)
`aggregateRating`	Rec	AggregateRating
`review`	Rec	Review objects

Review

Triggers: review snippet with star rating.

Property	Status	Notes
`itemReviewed`	R	The entity being reviewed (Product, LocalBusiness, etc.)
`author`	R	Person who wrote the review
`reviewRating`	R	Rating object with `ratingValue`
`reviewRating.bestRating`	Rec	Maximum rating value
`reviewRating.worstRating`	Rec	Minimum rating value
`datePublished`	Rec	ISO 8601 date
`reviewBody`	Rec	Full text of the review

Dynamic Schema Generation Patterns

When building pages programmatically, generate schema from your data models:

Server-Side Rendering (Next.js example)

export default function ProductPage({ product }) {
  const schema = {
    "@context": "https://schema.org",
    "@type": "Product",
    "name": product.title,
    "image": product.images,
    "description": product.description,
    "sku": product.sku,
    "brand": { "@type": "Brand", "name": product.brand },
    "offers": {
      "@type": "Offer",
      "price": product.price,
      "priceCurrency": "USD",
      "availability": product.inStock
        ? "https://schema.org/InStock"
        : "https://schema.org/OutOfStock"
    }
  };

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
      />
      {/* Page content */}
    </>
  );
}

CMS Integration Pattern

For WordPress, Shopify, or headless CMS:

Map CMS fields to schema properties in a template or plugin.
Ensure price, availability, and rating data are pulled from the live data source.
Use conditional logic to only output properties that have values.

Validation Approach

Step 1: Rich Results Test (Google)

URL: https://search.google.com/test/rich-results
Tests if your markup qualifies for rich results.
Reports errors and warnings per schema type.

Step 2: Schema Markup Validator (Schema.org)

URL: https://validator.schema.org/
Validates against the full Schema.org vocabulary (broader than Google).

Step 3: Google Search Console

Check Enhancements section for structured data reports.
Monitor errors, warnings, and valid item counts.
Review indexing of pages with structured data.

MCP Tool: Use extract_schema on any URL to pull all JSON-LD, Microdata, and RDFa. Use generate_schema with a target type to produce valid markup from page content.

Common Pitfalls

Pitfall	Problem	Fix
Invisible content	Schema describes content not visible to users	Ensure every structured data property matches visible page content
Missing required fields	Google ignores incomplete markup	Always include all required properties per type
Wrong `@type`	Using a type Google does not support for rich results	Use only Google-documented types
Fake reviews	Schema includes fabricated ratings or reviews	Only mark up genuine, real user reviews
Outdated prices	Product schema shows old price	Dynamically generate schema from live data
Multiple conflicting types	Two Product schemas on one page with different data	Use one canonical schema per entity
Self-referencing issues	`@id` references that point nowhere	Ensure every `@id` reference has a matching definition
Incorrect date format	Using `MM/DD/YYYY` instead of ISO 8601	Always use `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS+00:00`
HTTP image URLs	Images referenced over HTTP not HTTPS	Use HTTPS URLs for all images
Spam policy violations	Marking up content solely for SEO manipulation	Follow Google's structured data spam policies

Related Skills

seo-on-page-optimization -- for content and meta tag optimization
seo-technical-audit -- for crawlability and indexing issues
seo-mcp-tools-expert -- for detailed MCP tool usage

Key MCP Tools for Structured Data

Tool	Use For
`extract_schema`	Extract existing structured data from any URL
`generate_schema`	Generate valid JSON-LD markup for a given page and type

See SCHEMA_TEMPLATES.md for ready-to-use JSON-LD templates. See VALIDATION_RULES.md for Google's validation requirements. See RICH_RESULTS_GUIDE.md for which types trigger which rich results.

seo-schema-structured-data