The Complete Guide to JSON-LD: From Beginner to Master

From basic syntax to advanced applications, gain a comprehensive understanding of JSON-LD structured data implementation. This article details JSON-LD’s core features, multilingual support, SEO optimization techniques, and best practices to help developers improve their webpages’ search visibility and user experience. Whether you’re a beginner or an experienced developer, you’ll find practical knowledge and solutions for JSON-LD here.

JSON-LD (JSON for Linked Data) is a structured data markup language based on the JSON format that helps search engines and other applications better understand web content. Its core function is to add machine-readable metadata to web content through semantic markup, thereby improving search engine understanding, boosting SEO performance, optimizing the display of search results, and supporting technologies such as voice search and AI assistants.

What is JSON-LD?

JSON-LD is a JSON-based format for embedding machine-readable data in web pages. Its core goal is to help search engines and other applications better understand web content through semantic markup. JSON-LD’s key features include:

Based on JSON : Simple syntax, easy to read and write.
Semantic markup : Use Schema.org’s vocabulary to clearly describe the meaning of the data.
Flexibility : Supports complex data structures such as nested, array, and multi-language.
Wide application : Applicable to various scenarios such as SEO, voice search, and data integration.

When search engines crawl webpages using their crawlers, they only see text and HTML tags but cannot directly understand their meaning. JSON-LD uses clear semantic markup (such as “Product,” “Person,” and “FAQPage”) to inform search engines of the content type and structure of a page, enabling more accurate matching of user search intent. JSON-LD also enables search engines to display richer information (called “rich snippets”) in search results, such as ratings, prices, inventory, and event times. These rich snippets are not only more engaging but also directly answer users’ questions, reducing the number of clicks required.

Basic syntax of JSON-LD

JSON-LD is a format designed to help machines understand web content. It uses JSON syntax but adds some special tags and structures to express the meaning of the data. To help you understand, let’s take a look at a simple JSON-LD example:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": " 示例产品 ",
  "description": " 这是一个示例产品的描述。"
}
</script>

The above code can be embedded in a web page.

Specific instructions:

<script type="application/ld+json">Tags : This line tells the browser that this part of the content is JSON-LD data, usually placed <head>in the tag of the web page or other appropriate places.
@context: This keyword tells JSON-LD what standard or rules you are using. Here we are using Schema.org, which is a widely recognized vocabulary for describing various types of web content.
@type: This keyword tells search engines what type of content you are describing. In this example, we are defining a “Product”.
nameand description: These are specific attributes that describe the name and description of the product.

JSON-LD is essentially a data format embedded in a web page. It is not the “visible content” of the web page, but “extra information” that helps search engines understand the content of the web page. You can think of it as a “background tag” that tells search engines what the page is about.

A typical JSON-LD structure usually contains the following parts:

@context: Points to the standard or vocabulary library used by the data.
@type: Define the type of data (such as Product, Event, Person, etc.).
Attributes (such as name,, priceetc. address) : fill in specific content according to the data type.

Core keywords of JSON-LD

JSON-LD defines some core keywords ( @starting with ) that describe the structure and semantics of data:

Keywords	effect
`@context`	Tells JSON-LD which standard to use (e.g. Schema.org).
`@type`	Define the type of data (such as product, event, person, etc.).
`@id`	Provide a unique identifier for the data (optional).
`@value`	Defines the specific value of the attribute.
`@language`	Defines the language of the text (e.g. `en`for English).

Core features of JSON-LD

1. JSON-LD data types and properties

JSON-LD structured data is based on the Schema.org vocabulary and supports a large number @typeof types. The following are the main categories and subcategories that are commonly seen:

Main core types

type( `@type`)	describe
`Thing`	The base class for all types (all types inherit from `Thing`)
`CreativeWork`	Any creative work, such as articles, books, movies, music, etc.
`Event`	Events such as concerts, competitions, conferences, etc.
`Intangible`	Non-physical things, such as brands, currencies, ratings, etc.
`Organization`	Organizations, such as companies, non-profit organizations, schools, etc.
`Person`	Individual or public figure
`Place`	Places, such as cities, stores, attractions, etc.
`Product`	Products or Services
`Action`	User behavior, such as purchases, views, comments, etc.

Subcategory: Articles & News

type( `@type`)	describe
`Article`	Article, general type
`BlogPosting`	Blog Posts (for blog sites)
`NewsArticle`	News articles (for news sites)
`ScholarlyArticle`	academic papers
`TechArticle`	Technical articles, such as API documentation
`Report`	Reports and research reports

Subcategory: Organizations & Companies

type( `@type`)	describe
`Organization`	Organization (generic type)
`Corporation`	company
`NGO`	Non-governmental organizations
`GovernmentOrganization`	government agencies
`EducationalOrganization`	Educational institutions (schools, universities)
`LocalBusiness`	Local businesses (good for local SEO)
`MedicalOrganization`	medical institutions

Subcategory: Places & Local Businesses

type( `@type`)	describe
`Place`	Location (generic type)
`LocalBusiness`	Local businesses, such as restaurants and shops
`LandmarksOrHistoricalBuildings`	Landmarks or historical buildings
`TouristAttraction`	tourist attractions
`Restaurant`	Dining room
`Hotel`	hotel

Subcategory: Media & Entertainment

type( `@type`)	describe
`CreativeWork`	Creative Works (General Type)
`Movie`	Movie
`TVSeries`	TV drama
`MusicAlbum`	Music albums
`MusicRecording`	Music recording (single)
`VideoGame`	video games
`PodcastEpisode`	Podcast

Subcategory: Products & E-commerce

type( `@type`)	describe
`Product`	Products (for e-commerce)
`Offer`	Product Quote
`AggregateOffer`	Aggregation of multiple quotes
`Review`	User Reviews
`Brand`	brand
`Service`	Serve
`MerchantReturnPolicy`	return policy

Subcategory: Events

type( `@type`)	describe
`Event`	Event (generic type)
`Festival`	Festivals and carnivals
`SportsEvent`	sports events
`BusinessEvent`	Commercial Activities
`MusicEvent`	concert
`TheaterEvent`	drama performances
`EducationEvent`	Educational activities

Subcategory: Structured Data & Search Optimization

type( `@type`)	describe
`BreadcrumbList`	Breadcrumbs (important for SEO)
`FAQPage`	FAQ page (improve Google results)
`HowTo`	Guidelines (as in “how to do something”)
`QAPage`	Question and Answer Page (for forums)
`Rating`	Ratings (such as product ratings)
`AggregateRating`	Comprehensive rating (ratings from multiple users)

Other subcategories

type( `@type`)	describe
`WebSite`	Website (used to define the entire site)
`WebPage`	Webpage (for a specific page)
`SearchAction`	Search operation (for site search)
`EducationalOccupationalProgram`	Education and vocational training programs
`JobPosting`	Recruitment Information

How to choose the right JSON-LD @type?

Blog Post →BlogPosting
News Article →NewsArticle
E-commerce products →Product
FAQ page →FAQPage
Service-oriented website →Service
Local Businesses →LocalBusiness
Breadcrumb navigation →BreadcrumbList
Event Page →Event
Product Reviews →Review
Website Introduction →WebSite
Website Introduction →WebPage

If your JSON-LD needs to support multiple data types, you can @graphcombine multiple types.

2. Nested Data Structure in JSON-LD

JSON-LD supports nested data structures, which can be used to describe complex relationships. For example, a property Productcan be nested and itself be an object.offersoffers

Example: Nested Structures

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": " 示例产品 ",
  "description": " 这是一个示例产品的描述。",
  "offers": {
    "@type": "Offer",
    "price": "99.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  }
}
</script>

3. Using JSON-LD Arrays

JSON-LD supports arrays, which can be used to describe multiple values or objects. For example, a field FAQPagecan contain multiple questions and answers.

Example: Array

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": " 示例问题 1",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": " 这是示例问题 1 的答案。"
      }
    },
    {
      "@type": "Question",
      "name": " 示例问题 2",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": " 这是示例问题 2 的答案。"
      }
    }
  ]
}
</script>

4. JSON-LD Multilingual Support

Keywords @languageallow you to specify a language for the text.

Example: Multilingual support

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": {
    "@value": " 示例产品 ",
    "@language": "zh"
  },
  "description": {
    "@value": " 这是一个示例产品的描述。",
    "@language": "zh"
  }
}
</script>

For more details on the usage and details of JSON-LD multilingual support, please read the article: JSON-LD multilingual support detailed: how to describe multiple languages at the same time

JSON-LD in Action

To better understand the application of JSON-LD, we’ll show you several practical examples below, covering different data types, keywords, nested structures, and multilingual support. These examples will help you gain a deeper understanding of how JSON-LD is used in practice.

1. BlogPosting Example

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://example.com/my-awesome-blog-post"
  },
  "headline": " 如何优化你的 SEO 策略：2025 年最佳实践 ",
  "description": " 本文将介绍一些 SEO 优化的最佳实践，帮助提升网站排名。",
  "datePublished": "2025-03-01T10:00:00+08:00",
  "dateModified": "2025-03-01T12:00:00+08:00",
  "author": {
    "@type": "Person",
    "name": " 张三 "
  },
  "publisher": {
    "@type": "Organization",
    "name": " 优站 SEO",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  },
  "image": "https://example.com/blog-post-image.jpg",
  "url": "https://example.com/my-awesome-blog-post",
  "articleSection": "SEO",
  "keywords": "SEO, 网站优化, 搜索引擎 "
}
</script>

2. Product Example

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": " 高效无线耳机 ",
  "image": "https://example.com/product-image.jpg",
  "description": " 这款无线耳机提供卓越音质和舒适佩戴感。",
  "sku": "12345",
  "brand": {
    "@type": "Brand",
    "name": " 音响大师 "
  },
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/product-page",
    "priceCurrency": "CNY",
    "price": "299.00",
    "priceValidUntil": "2025-12-31",
    "itemCondition": "https://schema.org/NewCondition",
    "availability": "https://schema.org/InStock"
  }
}
</script>

3. Event Example

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Event",
  "name": "2025 国际编程大会 ",
  "startDate": "2025-05-15T09:00:00+08:00",
  "endDate": "2025-05-17T18:00:00+08:00",
  "location": {
    "@type": "Place",
    "name": " 上海国际会展中心 ",
    "address": {
      "@type": "PostalAddress",
      "streetAddress": " 上海市浦东新区世纪大道 888 号 ",
      "addressLocality": " 上海 ",
      "addressRegion": " 上海市 ",
      "postalCode": "200000",
      "addressCountry": "CN"
    }
  },
  "description": " 国际编程大会，汇集全球顶级程序员，分享技术趋势与未来展望。",
  "url": "https://example.com/event/2025-international-programming-conference",
  "image": "https://example.com/event-image.jpg",
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/event-tickets",
    "priceCurrency": "CNY",
    "price": "999.00",
    "availability": "https://schema.org/InStock",
    "validFrom": "2025-02-01T09:00:00+08:00"
  }
}
</script>

4. Organization Example

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": " 创新科技有限公司 ",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "+86-400-123-4567",
    "contactType": "Customer Service",
    "areaServed": "CN",
    "availableLanguage": "Chinese"
  },
  "sameAs": [
    "https://www.facebook.com/innovationtech",
    "https://twitter.com/innovation_tech"
  ]
}
</script>

5. LocalBusiness Example

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": " 星光咖啡馆 ",
  "image": "https://example.com/cafe-image.jpg",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": " 北京市朝阳区星光路 123 号 ",
    "addressLocality": " 北京 ",
    "addressRegion": " 北京市 ",
    "postalCode": "100000",
    "addressCountry": "CN"
  },
  "openingHours": "Mo-Su 08:00-22:00",
  "telephone": "+86-10-12345678",
  "url": "https://example.com/star-cafe",
  "priceRange": "￥￥"
}
</script>

6. FAQPage Example

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": " 什么是 SEO？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "SEO（搜索引擎优化）是指通过优化网站内容、结构和外部链接等手段，提升在搜索引擎中的排名，从而增加网站的流量。"
      }
    },
    {
      "@type": "Question",
      "name": " 如何提高网站的 SEO 排名？",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": " 提高 SEO 排名的方法包括优化网站速度、内容质量、关键词使用、外链建设等。"
      }
    }
  ]
}
</script>

7. Review Example

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Review",
  "reviewRating": {
    "@type": "Rating",
    "ratingValue": "4",
    "bestRating": "5"
  },
  "author": {
    "@type": "Person",
    "name": " 李四 "
  },
  "reviewBody": " 这款耳机音质不错，佩戴舒适，性价比高。",
  "itemReviewed": {
    "@type": "Product",
    "name": " 高效无线耳机 "
  }
}
</script>

8. WebSite Example

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": " 创新科技官网 ",
  "url": "https://example.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://example.com/search?q={search_term}",
    "query-input": "required name=search_term"
  }
}
</script>

9. WebPage Example

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "name": " 产品页面 - 高效无线耳机 ",
  "url": "https://example.com/product/high-performance-wireless-headphones",
  "description": " 购买高效无线耳机，享受卓越音质和舒适佩戴。",
  "mainEntityOfPage": "https://example.com/product/high-performance-wireless-headphones"
}
</script>

For more specific examples of using JSON-LD types, please refer to the article: JSON-LD Type Example Reference Manual

`@graph`Usage in JSON-LD

What is in JSON-LD @graph?

@graphIt is a keyword in JSON-LD that allows you scriptto include multiple entities (such as multiple products, events, or organizations) within a single tag. Its role is to group multiple related data items together in a structured way, which helps search engines better understand and process this data.

@graphWhat’s the difference between this and writing multiple scriptblocks directly? :

1. Multiple scriptblocks :

Each scripttag typically represents a separate structured data entity.
If you use multiple tags in a page script, the content between them is independent and search engines will parse each scripttag separately.
In some complex scenarios, multiple scripttags may result in duplicate structured data, especially when there are associations between data items.

2. Use@graph :

@graphAllows you to declare relationships between multiple entities (such as organizations, products, reviews, etc.) within the same JSON-LD data block.
It can effectively reduce scriptthe use of multiple tags in the page and improve the efficiency of structured data management of the page.
When multiple entities have relationships between them, using @graphcan make them more clearly grouped together rather than treated separately.

For example : If you have a page that contains both product information and reviews about that product, you can @graphcombine both entities into the same JSON-LD data block instead of writing a separate scripttag for each entity.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "@graph": [
    {
      "@type": "Product",
      "name": " 高效无线耳机 ",
      "price": "299.00",
      "currency": "CNY"
    },
    {
      "@type": "Review",
      "reviewRating": {
        "@type": "Rating",
        "ratingValue": "4",
        "bestRating": "5"
      },
      "author": {
        "@type": "Person",
        "name": " 李四 "
      },
      "reviewBody": " 这款耳机音质不错，佩戴舒适，性价比高。",
      "itemReviewed": {
        "@type": "Product",
        "name": " 高效无线耳机 "
      }
    }
  ]
}
</script>

JSON-LD Best Practices

Ensure content relevance : JSON-LD data should be highly relevant to the page content.
Avoid duplicate data : If multiple JSON-LD data blocks contain the same information, ensure that the data is consistent.
Follow search engine guidelines : Make sure your structured data complies with search engine guidelines like Google.
Test and validate : Use Google’s Rich Results Testing Tool to verify that JSON-LD is implemented correctly.

JSON-LD FAQ

1. Can I place multiple JSON-LDs on a page?

Yes, you can place multiple JSON-LD data blocks on a page. This can be <script>achieved by using multiple tags or by merging the JSON-LD data.

2. Does JSON-LD need to be placed on a dedicated page?

Not necessarily. JSON-LD can be placed on any page with relevant content, such as your homepage, product pages, blog posts, etc.

3. How to verify the correctness of JSON-LD?

JSON-LD can be validated using the following tools:

Google Rich Results Testing Tool : https://search.google.com/test/rich-results
JSON-LD Playground : https://json-ld.org/playground/

4. How to use multiple language descriptions in JSON-LD

When implementing multilingual support in JSON-LD, you can describe content in multiple languages at the same time in a variety of ways. For more information, please refer to the article: How to use multiple languages in JSON-LD

5. What is the difference between FAQPage and QAPage?

The main difference between the two lies in the way the page content is generated and its interactivity. FAQPage is more static and formal, while QAPage is more interactive and real-time. The FAQPage type is used to represent “Frequently Asked Questions” pages. These pages typically list a set of predefined, topic-related Frequently Asked Questions (FAQs) and their corresponding answers. The QAPage type is used to represent question-and-answer pages, which often include user-generated content. Unlike FAQPage, QAPage emphasizes an open-ended question-and-answer environment where questions and answers may be generated dynamically, allowing users to ask questions and receive answers.

Summarize

JSON-LD is a powerful structured data markup language suitable for a variety of scenarios, including SEO optimization, voice search, and data integration. Proper use of JSON-LD can significantly improve web page search visibility and user experience. This article helps readers fully grasp the use of JSON-LD and solve practical application problems.

appendix :