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.