seo-schema-structured-data（SEO schema structured 数据）

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

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.

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.

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.

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.

LocalBusiness (and Subtypes)

Triggers: local knowledge panel, map pack eligibility data.

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

Organization

Triggers: knowledge panel data, logo in search results.

BreadcrumbList

Triggers: breadcrumb trail in search results replacing the URL.

WebSite (with SearchAction for Sitelinks Search Box)

Triggers: sitelinks search box on branded queries.

{
  "@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.

Recipe

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

VideoObject

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

Course

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

SoftwareApplication

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

Review

Triggers: review snippet with star rating.

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:

1. Map CMS fields to schema properties in a template or plugin.
2. Ensure price, availability, and rating data are pulled from the live data source.
3. 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

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

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.