Comprehensive Guide to JSON-LD for SEO and Web Data Structuring

What is JSON-LD?

JSON-LD (JavaScript Object Notation for Linked Data) is a lightweight, JSON-based format designed to embed machine-readable metadata into web pages. It enables search engines and applications to better understand your page content by providing semantic markup using the widely adopted Schema.org vocabulary. This enhanced understanding boosts SEO performance, supports rich results (like ratings, pricing, and events), and facilitates technologies such as voice search and AI assistants.

Core Features of JSON-LD

• JSON Syntax: Simple and human-readable.
• Semantic Markup: Uses Schema.org vocabularies to clearly define content meaning.
• Flexibility: Supports nested objects, arrays, and multilingual text.
• Wide Application: Applicable for SEO, voice search, data integration, and more.

Search engines primarily parse HTML and text but cannot inherently grasp the meaning of content. JSON-LD bridges this gap by explicitly labeling content types such as Product, Person, FAQPage, which helps engines better match user queries and display rich snippets.

Basic Syntax of JSON-LD

A typical JSON-LD block includes:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Example Product",
  "description": "A description of the example product."
}
</script>

• @context: Defines the vocabulary (usually Schema.org).
• @type: Specifies the data type (e.g., Product, Event).
• Properties such as name, description provide details.

This data is embedded in your webpage’s HTML but not visible to users. It informs search engines about the page content semantics.

Important JSON-LD Keywords

Common JSON-LD Types

Core Types

• Thing: Base type for all entities.
• CreativeWork: Articles, books, movies, music.
• Event: Concerts, conferences, sports.
• Organization: Companies, schools, nonprofits.
• Person: Individuals.
• Place: Locations, businesses.
• Product: Items or services.
• Action: User actions like purchases or reviews.

Frequently Used Subtypes

Choosing Correct @type

• Blog post → BlogPosting
• News article → NewsArticle
• Product → Product
• FAQ page → FAQPage
• Local business → LocalBusiness
• Event → Event
• Review → Review
• Website → WebSite
• Web page → WebPage

You can combine multiple entities using @graph for complex pages.

Nested Structures & Arrays

JSON-LD supports nested objects and arrays for complex relationships:

Nested example: Product with offer

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Example Product",
  "offers": {
    "@type": "Offer",
    "price": "99.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  }
}

Array example: FAQ with multiple questions

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is SEO?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "SEO optimizes site content and structure for better search rankings."
      }
    },
    {
      "@type": "Question",
      "name": "How to improve SEO?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Improve site speed, content quality, keyword use, and backlinks."
      }
    }
  ]
}

Multilingual Support

You can specify language for text fields:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": {
    "@value": "示例产品",
    "@language": "zh"
  },
  "description": {
    "@value": "这是一个示例产品的描述。",
    "@language": "zh"
  }
}

This enables simultaneous descriptions in multiple languages.

The @graph Keyword

@graph lets you bundle multiple related entities in one JSON-LD block, enhancing clarity and efficiency.

Example combining product and review:

{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "@graph": [
    {
      "@type": "Product",
      "name": "High-Performance Wireless Headphones",
      "price": "299.00",
      "currency": "CNY"
    },
    {
      "@type": "Review",
      "reviewRating": {
        "@type": "Rating",
        "ratingValue": "4",
        "bestRating": "5"
      },
      "author": {
        "@type": "Person",
        "name": "Li Si"
      },
      "reviewBody": "Great sound quality and comfortable fit.",
      "itemReviewed": {
        "@type": "Product",
        "name": "High-Performance Wireless Headphones"
      }
    }
  ]
}

Best Practices for JSON-LD

• Ensure relevance: Data must match visible page content.
• Avoid duplication: Keep consistent structured data.
• Follow search engine guidelines: Use formats compliant with Google and others.
• Validate regularly: Use tools like Google Rich Results Test and JSON-LD Playground.

FAQs

Can I add multiple JSON-LD blocks per page? Yes, either via multiple <script> tags or combined with @graph.

Where should JSON-LD be placed? Anywhere on pages with relevant content — homepage, products, blogs.

How to validate JSON-LD? Use:

• Google Rich Results Test
• JSON-LD Playground

Difference between FAQPage and QAPage? FAQPage is static Q&A; QAPage supports dynamic user-generated Q&A.

Practical JSON-LD Examples

Blog Post

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "SEO Optimization Strategies for 2025",
  "author": {"@type": "Person", "name": "Zhang San"},
  "datePublished": "2025-03-01T10:00:00+08:00",
  "publisher": {
    "@type": "Organization",
    "name": "YouZhan SEO",
    "logo": {"@type": "ImageObject", "url": "https://example.com/logo.png"}
  },
  "image": "https://example.com/blog-image.jpg",
  "description": "Best practices to boost your SEO in 2025."
}

Product

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Wireless Headphones",
  "brand": {"@type": "Brand", "name": "SoundMaster"},
  "offers": {
    "@type": "Offer",
    "priceCurrency": "CNY",
    "price": "299.00",
    "availability": "https://schema.org/InStock"
  }
}

Event

{
  "@context": "https://schema.org",
  "@type": "Event",
  "name": "2025 International Coding Conference",
  "startDate": "2025-05-15T09:00:00+08:00",
  "location": {
    "@type": "Place",
    "name": "Shanghai International Expo Center",
    "address": {
      "@type": "PostalAddress",
      "streetAddress": "888 Century Avenue",
      "addressLocality": "Shanghai",
      "postalCode": "200000",
      "addressCountry": "CN"
    }
  }
}

References

• Schema.org Official Documentation
• Google Structured Data Guidelines
• JSON-LD Official Site