« Back to front page


Structured data is becoming ever more important for search engine optimization. Search engines such as Google can read this data and use it to enrich search engine results (rich snippets) or for special results, such as the Knowledge Graph.

To take advantage of this, you should tag your content with mark-ups. JSON-LD offers an opportunity to mark structured data simply. In this tutorial, you will learn what you need to optimally prepare your web content for Google & Co.

What is the Difference between JSON and JSON-LD?

The abbreviation JSON stands for "JavaScript Object Notation." This is a special data format derived from JavaScript that allows the exchange of text-based information. This format can be easily read and processed by people and machines. As a variant of JavaScript, JSON is itself a JavaScript and should be stored in the source code.

A great advantage of JSON is that the data format can be used across platforms. Today, it is used mainly for the transfer and storage of structured data. Likewise, web apps or web uses with JSON objects can be used.

JSON is characterized by its syntax, which consists primarily of name-value pairs. An object is marked with curly brackets. Within the object, further individual properties, i.e. qualities, can be defined. For each property there is a value separated by a colon. That is why JSON has become increasingly popular over the past few years - because its structure is simpler than XML, for example.

740x400_JSON-LD JSON-LD JSON Guide

JSON-LD, by contrast, stands for "JavaScript Object Notation for Linked Data." With JSON-LD, structured data can be incorporated in one website. Since 2010, JSON-LD has had a W3C standard notation. The specification of the markup language was developed by Manu Sporny.

In contrast to other markup methods for structured data such as microformats, RDFa and microdata are not directly designated in the source code, but rather the meta tasks are separated from the actual website content via a script.

JSON-LD rests on JSON notation and was expanded to "types" and "properties" in order to transfer data or linked data.

JSON-LD can be read by common search engines, and Google Gmail can process JSON-LD data.

“Linked Data”

When you implement JSON into a website, this data can be arranged simply within the site, because the supplier is always this website. If, however, search engines should read various data marked with JSON, this can lead to improper interpretations and improper allocations.

The expansion of JSON to "Linked Data" (LD) ensures that the structured data can be assigned to a website. For this, the element "type" is added. Via this element, for example, the URI is connected with the data set. Fundamentally, JSON-LD is not established with a specific vocabulary.

Targeted Use of JSON-LD

JSON-LD lists the elements of a website and structures this data. These can then be clearly assigned and read by a search engine. On the basis of these structured data, search engines can improve and better organize their search results.

Where is JSON-LD inserted in the HTML code?

Google suggests to insert JSON-LD <head> in the area of the HTML document. Search engines can nevertheless also <body> read the data from the segment. Moreover, there is the possibility that Google will read dynamically-generated JSON-LD tags via the Google Tag Manager. How this works is described in detail in this article.

Why should I use JSON-LD?

JSON-LD is a very simple opportunity to generate structured data. This data with JSON-LD can be easily stored in the <head> area <script> tag of an HTML document. In this way, the code snippet can be loaded separate from the HTML code. In comparison with other markups, the danger of errors is thus clearly less.

Thanks to the simple script language, you are usually not dependent on a programmer to create markups and to incorporate them into your website.

If you already use JSON data, you can easily use JSON-LD.

A JSON-LD code snippet can appear as:

<script type="application/ld+json">
"@context": "http://schema.org",
"@type": "Book",
"name": "XXL Guide for JSON-LD",
"publisher": "onpage.org",
"inLanguage": "English",
"@type": "EBook"
"@type": "Offer",
"price": "0,00",
"priceCurrency": "EUR",


This example shows you how JSON-LD consists of name-value pairs. Specific values are reserved with the @ character, for example for '@context' and '@type.' These values are relevant for search engines, and they are what differentiates JSON-LD from conventional JSON data.

By giving the URL in the segment "context," the structured data is connected with a reference by means of which the data is read. The search engine is referred to by the additional specification of @type in the complete URl http://schema.org/Book. In this way, it is ensured that the structured data contained in the script is obtained from the vocabulary of schema.org.

So that the search engine understands that a JSON-LD file is at hand, the script must contain this element:

<script type="application/ld+json">


Development of JSON-LD Data

In this brief sequence, it is clear how JSON-LD data is created and how it is created as name-value pairs. It is easy for humans to determine the value of the respective pairs, even without a clear notice. In this example, it is clear that "name" indicates the name of the object and "homepage," the respective website. For search engines, however, the necessary reference must be created. Therefore, corresponding name-value pairs are created with JSON-LD.

"name": "Mr. OnPage",
"homepage": "http://onpage.org",

JSON syntax with keyword

In the following example, the JSON data is enriched with linked data. This deals with so-called keywords that are inserted into the code. The additional data is inserted with the @ character.

The most important keywords in this case are @context and @type.

"@context" : "http://schema.org/",
"@type" : "Person",
"name" : "Mr. OnPage",
"url" : "http://onpage.org/"

@context: With this element, the vocabulary that relates to the entire script is referenced. In the above-named example, the reference is schema.org.

@type: This element designates the plan that is used within the reference. Within this plan, furthermore, individual qualities can be constituted as name-value pairs. These are called properties. In the example given here, "name" and "url" are the properties of the pattern "person." With schema.org, all types of properties and patterns can be used.

Note: In schema.org you will find many prepared plans as well as the accompanying properties that can already be read by search engines such as Google.

With JSON-LD, so-called "nested entities" can also be created. These are properties with various "types" that are listed within a JSON-LD data set. Thus, every new property must be defined anew. To do this, a comma is placed before the final curly bracket.

Tip 1: Consider how types and properties with schema.org are case-sensitive and that lowercase and capitalized letters are taken into account.

Tip 2: In creating structured data, ensure that you use all properties that are available through schema.org for your chosen type.

Thus, simple properties can be added to JSON-LD:

<script type="application/ld+json">
"@context": "http://schema.org",
"@type": "Book",
"name": "XXL Guide for JSON LD",
"publisher": "OnPage.org",

Add More Complex Properties

Here, you will create "nested entities." The listed example is now completed with further details that relate to the pattern for "offers" in accordance with schema.org. As described above, the additional property is separated from the embedded property. In this way, a hierarchy is created within the keyword "type."

JSON-LD vs. Microdata and RDFa-Syntax

JSON-LD uses the same arrangement for the schemata such as other formats that distinguish structured data.

"@context" : "http://schema.org/",
"@type" : "Person",
"name" : "Mr. OnPage",
"url" : "http://onpage.org/"

Microdata syntax according to schema.org:

<div itemscope itemtype="http://schema.org/Person">
<span itemprop="name">Mr. OnPage</span>
<span itemprop="url">http://onpage.org</span>

RDFa syntax in accordance with schema.org:

<div vocab="http://schema.org/" typeof="Person">
<span property="name">Mr. OnPage</span>
<span property="url">http://onpage.org</span>

All three markups can be read by search engines. The advantage of JSON-LD is that is does not have to be implemented in the HTML source code of the website.

Designate Structured Data with JSON-LD: Events

Google recommends that webmasters, for example, distinguish events with JSON-LD.

In the HTML code, an event can appear as:

With JSON-LD, all details of this element can be delivered to Google as structured data. Thus, the contents of the properties can be dynamically loaded and stored as a script. As with other markups, it is not necessary that the data actually exists in the HTML code.

<script type="application/ld+json">
"@context" : "http://schema.org",
"@type" : "Event",
"name" : "Newcomer band in Munich",
"startDate" : "2017-01-01T20:00",
"url" : "http://www.concert_site.com/Band/2017-01-01",
"offers" : {
"@type": "AggregateOffer",
"url" : "http://www.concert_site.com/Band/2017-01-01/tickets",
"lowPrice" : "99",
"offerCount" : "134"
"location" :
"@type" : "Place",
"sameAs" : "http://www.location.com/",
"name" : "Event Location",
"address" :
"@type" : "PostalAddress",
"streetAddress" : "Partystreet 1",
"addressLocality" : "Munich",
"postalCode" : "89000"

Here's how you can test the JSON-LD script

JSON-LD can consist of very simple code elements. However, if interlaced elements are incorporated, the code will become complex very quickly and errors can arise. In order to check whether your JSON-LD code is actually functioning and is being correctly read by search engines, Google offers the Structured Data Testing Tool.

In the tool, select: check a code snippet. Finally, click on "Fetch and Validate."

If you insert the example code from above, you get the following:

json-ld-example JSON-LD JSON Guide

Figure 1: Google Structured Data Testing Tool.

You see that Google shows not only errors in the JSON-LD code, but also gives you notices on possible properties which your code should contain.

Use of JSON-LD for SEO

With JSON-LD you can increase and improve the presence of your website in the Google SERPS. Thus Google recommends JSON-LD, for example, in order to be shown in the Google Knowledge Graph and to generate so-called "rich cards."

Both elements are present in the SERPs and are generally shown via the regular organic search terms. With the help of JSON-LD, the visibility of a website can be increased and, additionally, you can win more traffic.

Through the use of JSON-LD, it becomes easier for search engines to read your web content. On the one hand, relevant data is transferred in a structured fashion. On the other hand, JSON-LD is outsourced as a script. Thereby, the source code is streamlined and the Googlebot requires less time to index your site.

In spite of these advantages, JSON-LD is not recommended by Google for all markups. This may be because the transfer of structured data by script is extremely vulnerable to spam. If conventional microdata or RDFa is used, only the available HTML code can be marked.

Because searches will be increasingly language-based in the future, a markup such as JSON-LD is very important, because web content can be made more readable for search engines through structured data. At the same time, this designated content perfectly suits the user's search needs. So if you want to be set up for the language searches that are increasingly being used by GoogleNow and the mobile Google search, you should engage with structured data early on. JSON-LD offers a simply chance to do this.

Using the JSON-LD Markup Checklist - How-To

How easy it will be for you to implement JSON-LD depends largely on how familiar you are with the vocabulary of schema.org and how well you master JSON-LD syntax.

1. Before you begin, consider: What do you want to tag with markup and what goal do you have? In this way you can better evaluate whether or not the effort will really be worth it.

Make sure your content can be designated with the vocabulary of schema.org. Some properties may not make sense for your goals. Thus, for example, it is not really expedient to designate events if they are not yours.

And as far as goals: Would you like to achieve a particular marketing goal? Or is this just a first test? Always bear in mind that markup helps search engines understand your central and important content in a structured fashion. See which markups Google is already using and where these are implemented.

2. Create a list with possible properties and values: Write down all the name-value pairs that you would like to mark. Later, check whether or not it's even possible to mark with schema.org.

3. Check possible sources for markups: With JSON-LD, you don't have to find the path anew. Use resources from Google in order to become more familiar with the topic. Use available examples and modify them for your purposes.

4. Use schema.org types: On the site schema.org, there are many different code examples for types and properties. See which entities might apply to you.

5. Copy the necessary elements and insert them into an editor: You can simply copy the available examples and tailor them to your website. Make sure that you insert all necessary <script> tags.

6. Complete your code with possible embedded properties: Complement existing properties with further characteristics.

7. Test your code snippets: The Structured Data Testing Tool from Google is available for this.

8. Consider how the JSON-LD should be implemented: As a very simple possibility, you can simply insert the code into the area of your site or use the template. In this case, it might make sense to use the services of a web developer.

Possible Pitfalls in Implementation of JSON-LD

If you cannot validate your JSON-LD code snippet with the Google Testing Tool, it could be due to several mistakes. Here, you will find the most frequent ones:

  • Syntax: These quotation marks “are not the same as these." Use only straight quotation marks. Pay attention to commas. In the tool from Google, a red X is usually inserted if a comma is missing or if too many are inserted.

  • Vocabulary: Make sure that only required or allowed properties are used within the specifications from schema.org.

  • Webmaster Guidelines: Only mark information with JSON-LD that is actually to be found on your site. It is possible to transfer other information by script, but this practice can be treated by Google as spam. In the worst case, your site will no longer be listed in the index.

  • Copy/Paste: Don't insert any markup that you have already used in Office programs such as Windows. Instead, use an HTML editor for editing JSON-LD.


At first glance, JSON-LD may seem too big and complex for beginners. But with JSON-LD, it is easier to generate structured data for search engines than with other methods such as microformats or RDFa, because the HTML code with JSON-LD does not have to be directly designated.

In any case, you should check whether markups make sense for your web presence. Because if it works, you could be presented as a Rich Card or in the Google Knowledge Graph. In any case, in terms of further digital search assistants, such as Google Now or others, structured data is an important markup element for the future of the search.

W3C documentation of JSON-LD:

Ryte users gain +93% clicks after 1 year. Learn how!

Published on May 17, 2017 by Eva Wagner