You can use an example to explain how JSON works

How to tag your website with JSON-LD according to

At JSON-LD it is a syntax recommended by the W3C, with which structured data as well as generally applicable schemas for data structuring can be embedded in the compact JSON format.

Structured data helps search engines to better understand websites. A semantic annotation makes it possible to create contexts of meaning, to read out information automatically and to transfer it to other forms of representation. Google - the most widely used search engine of our time - relies on structured data to provide users with rich search results and other SERP elements. Advantage for the website operator: Search results highlighted in this way catch the eye and increase the visibility of a website.

The prerequisite for this is that all relevant information has been marked accordingly. Over time, the internet community has become diverse Data structuring standards developed. We will show you why you should prefer JSON-LD to alternative data formats such as Microformats, RDFa or Microdata.

What is JSON-LD?

JSON-LD (JavaScript Object Notation for Linked Data) is a JSON-based method of embedding structured data in a website. In contrast to other formats for data structuring such as Microformats, RDFa and Microdata, the marking is not done as source text annotation. Instead, metadata is in a script tag separate from the website content in the head- or body-Element of the HTML document implemented. JSON-LD uses the JSON notation and extends it with a syntax with which data can be identified according to generally applicable, globally uniform schemes.

The JSON-LD specification comes from Digital Bazaar founder Manu Sporny and has been an official W3C recommendation since January 16, 2014.

What is JSON?

The abbreviation JSON stands for JavaScript Object Notation and denotes a compact, text-based format for the exchange of data that is easy to process both by humans and by machines. JSON is a derivative of JavaScript, but can also be used across platforms regardless of the programming language. JSON is used as the data format for serialization - the mapping of programmable objects in a sequential form of representation - Transferring and storing structured data, used in web applications and mobile apps. The syntax of a JSON object essentially consists of Name-value pairs, which (with the exception of numerical values) are placed in double quotation marks and separated by a colon. Each name-value pair usually starts on a new line and ends with a comma. Exception: The last name-value pair before the closing bracket bracket is noted without a comma.

The following example illustrates the basic scheme of the JSON syntax:

The word pair "Manu Sporny" can be found in the introductory section of the text. Based on the context, a human reader will quickly understand that the sequence of letters is a name and interpret the stored hyperlink as a reference to the website of the JSON-LD developer. Programs such as web browsers or search engine crawlers, on the other hand, need metadata to establish such a connection. This is exactly what JSON offers.

The code example shows the two name elements "name" and "homepage" with their respective values. A program that reads a website with this JSON object is thus able to identify “Manu Sporny” as the name and “” as the homepage.

What is Linked Data (LD)?

While the meaning assignment with JSON within a website works without any problems, the Analysis of JSON data from various websites quickly to one Ambiguity problem. As a rule, programs parse a large number of websites and evaluate the information obtained in databases. For example, with the JSON code listed above, it cannot be guaranteed beyond any doubt that the name elements “name” and “homepage” are always used in the same context across different websites. To rule out ambiguity, JSON-LD supplements the classic JSON notation Context-creating elements. This is done on the basis of linked data. These are freely available data on the Internet that can be called up using the Uniform Resource Identifier (URI).

Further information on linked data can be found in the following video by JSON-LD developer Manu Sporny:

With another click you load the video from YouTube. In this case, YouTube can set cookies over which we have no influence.

In order to prepare JSON for linked data, JSON-LD supplements the classic name-value pairs of the JSON notation with so-called Keywords. Keywords are introduced in the JSON-LD syntax with a preceding @ sign. The key words are of central importance @context and @type. While @context defines the vocabulary on which the award is based @type which data type (schema) it is.

The project offers a standardized schema database for data structuring. On the project website of the same name, website operators can find various data schemes (types) as well as "properties" assigned to these data types, which enable detailed semantic labeling of website content.

In principle, JSON-LD is not restricted to any special vocabulary. The search engine providers Bing, Google and Yahoo! The project, which was launched, is considered to be a quasi-standard for the semantic annotation of website content.

Supplemented by the corresponding context elements, the following code results for the above example:

The keyword @context in line 2 defines the vocabulary on which the semantic markup is based - here In line 3, the data type “Person” is entered using the keyword @type introduced. This data type is specified in more detail in lines 4 and 5 by the properties "name" and "url". A program that parses this example code can identify the text element “Manu Sporny” marked as “name” as the name of a person according to the data type “Person” according to The name-value pairs introduced by "name" and "url" are used as properties (properties) of the schema "Person" is processed. The underlying vocabulary determines which properties can be assigned to a scheme.

With another click you load the video from YouTube. In this case, YouTube can set cookies over which we have no influence.

Advantages of JSON-LD compared to other data formats

The Assignment of schemes and properties is done with JSON-LD analogous to other formats for the semantic marking of website content. Converted into a source text annotation, the above example script could also be labeled with Microdata or RDFa according to without any loss of information.

Microdata syntax according to

RDFa syntax according to

The big advantage of JSON-LD over competing formats, however, is that Metadata is not embedded directly in the HTML code but can be implemented separately at any point. JSON-LD is implemented in the HTML code using the script tag according to the following scheme:

In relation to the example given above, the following designation results in accordance with

Even if JSON is noted in script tags, it is not executable code.

The strict separation of HTML and semantic annotation not only scores with one significantly better readability of the source text. An implementation of this type also enables dynamic generation of data structures independent of the visible content. With JSON-LD, metadata can thus be entered via the backend and read from a database and generated automatically by template become. This enables convenient semantic annotation even for dynamic web content that is taking up more and more space on the Internet.

JSON-LD for search engine optimization

The project has named JSON-LD as one of the preferred data formats since June 2013. And Google also recommends (if possible) the script-based integration of metadata via JSON-LD. Such an award is the basis for diverse SERP elementsthat Google uses to present users with advanced search results.

Google uses different forms of presentation for search results: In addition to the Basic Results (simple search results) have also been used by users for a number of years, depending on the search query Featured Results and Knowledge Graph Results. While Basic Results (if at all) only have simple extensions such as breadcrumbs, Featured Results and Knowledge Graph Results offer potential for extensive extensions - also called enhancements or search result features by Google.

In Google terminology, the term Featured Result is used for extended search results in which the displayed content comes from only one source - the linked website. Other names for SERP elements of this type are Rich Search Result and Rich Cards. If a featured result enables user interactions, Google speaks of an enriched search result. In the case of Knowledge Graph Results, on the other hand, Google does not rely on a single website, but on the Knowledge Graph algorithm, which brings together content from various sources on the Internet. Knowledge Graph Results are also known as Knowledge Graph Cards, Knowledge Graph Boxes or Knowledge Graph Displays. If Google finds several relevant rich cards or knowledge graph cards for a search query, these are displayed as a carousel - a list format for different data types - on the SERPs.

Google currently supports JSON-LD markup for the following extensions. The search engine provider provides an example of each search result feature in the search gallery at

  • Breadcrumbs: The so-called breadcrumb navigation shows the position of the current webpage in the hierarchy of the website. Website operators who semantically mark breadcrumbs allow Google to display them on the SERPs. Breadcrumbs are one of the few search result features that Google also uses in Basic Results.
  • Company contact information: If company contact information has been tagged semantically, Google can display it in the SERPs as a Knowledge Graph Display, a form of representation of the Knowledge Graph algorithm.
  • Logos: With a logo markup, website operators make it clear which graphic should be used by the search engine as the company logo. This enables Google to add a logo to search results for the company in question.
  • Sitelinks Searchbox: If a website provides a search function and this has been semantically marked, Google may display search results for the website with a sitelinks search box.
  • Social Profile Links: If markup is used for links to social media profiles, Google may add buttons to the Knowledge Graph Display for people or organizations. Google currently supports JSON-LD markup for Facebook, Twitter, Google+, Instagram, YouTube, LinkedIn, Myspace, Pinterest, SoundCloud and Tumblr.

Website operators who want their content to be clearly visible on the Google SERPs have the option of semantically marking different data types. It should be noted that Google alone selects whether a search result is displayed as a basic result or with extensions. Google currently supports JSON-LD markup for the following data types and uses this to prepare information as Rich Search Results, Enriched Search Results or Knowledge Graph Results.

  • Items: Website operators who semantically mark news or blog articles allow Google to include them in the top stories carousel or to add search result features such as headings or thumbnails to the SERPs.
  • Books: If website operators offer JSON-LD markup for information relating to books, Google creates a Knowledge Graph Card for relevant search queries. This not only contains clear information about the book, but also enables Google users to purchase it directly from the search engine if required.
  • Music (entries for musicians and albums): Similar to information on books, music offers can also be annotated. This enables Google to generate knowledge graph cards for music content. These not only offer searchers information about albums and musicians, but also enable interactions such as playing the music or making purchases.
  • Course offers: Website operators who provide courses (e.g. language courses) with a JSON-LD markup that enables the title, a short description and the provider to be automatically read out have the chance that Google will display this information as extended search results in the SERPs plays off.
  • Events: Providers of public events such as concerts and festivals have the option of annotating relevant information (e.g. location of the event, date and time) via JSON-LD so that Google can automatically extract this information and list it on the SERPs or in other Google products how maps can display.
  • Job advertisements: Job offers that organizations publish on their website can also be marked in such a way that Google can read relevant information for extended search results.
  • Entries from local providers: Local providers who offer structured data on the business or restaurant website enable Google to create knowledge graph cards that are displayed for relevant search queries on the SERPs or in Google Maps (see also Create Google Maps Entry). For example, if a Google user is looking for a Vietnamese restaurant, Google will play a carousel with suitable providers nearby.
  • Records: Data records such as CSV tables or files in proprietary formats can also be made accessible to the search engine via JSON-LD markup.
  • Podcasts: Google supports a JSON-LD markup for podcast information. Correspondingly excellent offers can be displayed and played directly in the search engine.
  • Videos: Content providers who provide structured data such as a description, a link to a preview image, the upload date or the playback time for videos on your website allow Google to extract this information and display it as rich cards or in the form of carousels to play off the SERPs.
  • Movies and Shows: If a website provides structured data on film offers or shows, Google transfers this information to the search results pages as knowledge graph cards for relevant search queries. If necessary, these can be expanded to include interactive elements that enable the consumption or purchase of the offer.
  • Recipes: For some years now, Google has also been offering cooking recipes as a featured result in the search engine. The prerequisite for this is that the providers of the content provide all relevant recipe information as structured data. One possible display on the SERPs is a carousel with matching rich cards for the search query.
  • Reviews: Google supports ratings for various data types such as local shops, restaurants, products, books, films, or creative work. The corresponding content is shown as a snippet. Google differentiates between reviews of individual authors and contributions on review portals. If semantic annotation is available, both types of evaluation are displayed as featured results on the SERPs for relevant search queries.
  • Products: Online retailers who provide product information such as prices, availability or reviews as structured data on their website enable Google to display this information as rich search results for relevant search queries.

Extended search results - regardless of whether they are featured results or knowledge graph displays - have one main advantage for website operators: They stand out from other search results on the SERPs.

Google places displays and carousels for Featured Results in an exposed position above the Basic Results and thus Position zero Knowledge Graph Displays also appear either as a carousel at the top of the page or separated by a frame to the right of the organic web search.Extended search results offer website operators the chance to achieve pole position on the search results page without having to invest time and money in improving the organic ranking.

But not only that highlighted position, various extensions such as thumbnails, ratings, text excerpts and interactive elements attract the searcher's attention and encourage them to click. Website operators can assume that the Click-through rate significantly increased for extended search results compared to Basic Results.

In addition, advanced search results will have a positive effect on the Bounce rate awarded. Unlike Basic Results, which usually only contain the meta title, a URL and a short description, advanced search results give Google users a comprehensive impression of what content they can expect on the linked website. A searcher can therefore check the relevance of a website for his own search query before calling it up and only click when necessary.

However, Google does not use the presence or absence of semantic labeling via JSON-LD as a ranking factor. Matt Cutts, former head of the Google web spam team, made this clear in 2012 in the following YouTube video from the Google Webmasters series:

With another click you load the video from YouTube. In this case, YouTube can set cookies over which we have no influence.

As with the application, JSON-LD also scores with crawlability by outsourcing the markup to separate script sections. Compared to alternative annotations such as Microdata or RDFa, JSON-LD allows one despite semantic annotation lean source codethat can be quickly crawled and easily indexed by the Google bot and other crawlers.

But the outsourcing of structured data also has disadvantage. In principle, at Google and other search engine providers, the basic rule applies that only the content that is also available to human site visitors is labeled as machine-readable. With JSON-LD, however, any markup can theoretically be implemented, even if there is no equivalent for the metadata in the actual website content. In this case, both the search engine and the user are promised possible added value that such a decorated website does not offer. In practice, such an approach is not advisable. Otherwise website operators run the risk of Web Spam Measures to be punished.

In order to prevent website visitors from accidentally exceeding the limits of search engine compliant semantic annotation, Google offers the Structured Data General Guidelines a detailed set of rules that can essentially be reduced to the following points:

  • Format: Structured data must be available in one of the three established formats Microdata, RDFa or JSON-LD. Google recommends the latter.
  • Accessibility: Structured data pages must be accessible to Googlebot. Access control methods (e.g. via robots.txt or noindex) prevent the metadata from being read out.
  • Content equivalence: The JSON-LD markup may only describe entities that are also described in the HTML code.
  • Relevance: A JSON-LD markup should only refer to relevant equivalents of the data types used. For example, a website operator who labels a technical manual as a recipe violates the guideline of relevance.
  • Completeness: All data types listed in the JSON-LD markup (types) must be complete and including the required properties (properties) be awarded. Data types that lack essential properties are not suitable for advanced search results.
  • Specificity: Linked data projects like offer a variety of data types. In order to qualify their own content for an extended display of search results, website operators should choose schemes as specific as possible.

In principle, the following applies: the more properties are provided in the form of structured data, the higher it is Added value for the Google user. Google therefore takes the amount of information provided into account when ranking rich cards. And website operators also benefit from the most complete markup possible. For example, according to Google, searchers prefer job advertisements with a salary or reviews including a star rating.

JSON-LD according to A step-by-step guide

In the following, we will use an example to show you how you can enrich your website with relevant metadata as efficiently as possible. The JSON-LD tutorial is based on the vocabulary of the project.

Step 1: preliminary considerations

The implementation of structured data is associated with a greater or lesser effort, depending on the scope of the website. So think about which ones in advance aims You achieve with the semantic markup and how much working hours You want to invest in the annotation.

As a rule, markup should structure website information and present it in a form that can be read by search engines. The aim is to demonstrate to Google and Co. that a website optimized in this way provides the best resources for relevant search queries on the main topic of the project. Therefore, ask yourself the following questions:

  • What are the main contents of your website?
  • What added value do these potential visitors offer?
  • What content is so relevant to the focus of your website that it should be given a search engine friendly rating?

Step 2: Identify relevant content

Make a list of all content that offers value. Decide what content potential visitors should be alerted to on the search results pages.

For example, Google recommends tagging JSON-LD for information that Events affect. Event announcements for concerts, musicals or theater performances, e.g. B. represent according to the following scheme:

Typical information of the data type "Event" is the date and time, the price, the availability of tickets, the address of the event location and links to further information on the event or the location. Human site visitors are able to extract this information from a section of text, a table or other forms of representation and assign it to the relevant context. Programs like search engine crawlers, on the other hand, need them Metadata that contain instructions on how to process the information presented. JSON-LD delivers this in the form of a data format that is inserted separately from the content at any point in the HTML source code. provides you with generally applicable rules on how you, as a website operator, create JSON-LD markup and embed it in your website.

Step 3: choose schemes offers website operators a comprehensive vocabulary for structuring data. Overall, the database includes around 600 typesdealing with more than 860 properties to be specified in more detail.

There are two strategies to choose from when choosing suitable data types:

  • Theoretically, you are free to compare all previously determined content with the available data types of the vocabulary and to select the most specific data type for the respective content element. Such a procedure is tedious and usually unnecessary.
  • In practice, website operators usually limit themselves to a subset of the data types: If you only pursue the goal of providing the search engine with structured data with the JSON-LD markup, it is sufficient to initially limit yourself to the data types provided by Google currently supported and described in detail in the Google developer area.

We recommend strategy b. - and for the following reason: Google offers detailed documentation for all data types supported by the search engine. For each data type there is a Example markup made available.

Use the examples that Google lists in the developer area as a template for your own JSON-LD markup.

You don't have to reinvent the wheel to provide your website with structured data. If you have no previous experience with the syntax of JSON-LD, it saves time and energy to fall back on ready-made patterns instead of having to write the markup for each data type from scratch.

In the Google documentation website operators can find the following markup example for events:

The script tags define the element from line 01 to line 39 as Script of the type "application / ld + json". The following information is aimed at programs that are able to read linked data in JSON format.

On the first level there are the keywords “@context” and “@type” with the values ​​“” and “Event” (lines 03 and 04). A parsing program receives the instruction here that the following information is added to the "Event" scheme according to are to be assigned, these are therefore specific characteristics of the event described. These are represented in the form of name-value pairs.

Also on the first level are the properties "name", "startDate", "location", "image", "description", "enddate", "offers" and "performer", to which the respective event information is assigned as values. A search engine crawler can thus unequivocally identify the information "Jan Lieberman Concert Series: Journey in Jazz" as the title of the event (name) and "2017-04-24T19: 30-08: 00" as the exact start time (StartDate).

Analogous to RDFa and Microdata, it also supports JSON-LD syntax Nesting. A property is not assigned a value, but a (sub-) scheme, which in turn can be determined more precisely with specific properties. You will find such a case on the second level of the code example on lines 08, 27 and 35.

In line 08, for example, the event property “location” is defined as a (sub) schema of the type “Place” and given the properties “name” and “address”. The “address” property, in turn, is defined in line 11 as a (sub) schema of the “PostalAddress” type and in turn marked with the schema-specific properties “streetAddress”, “addressLocality”, “postalCode”, “addressRegion” and “addressCountry”.

Each nested level is enclosed in curly brackets and thus separated from the higher level.

Extract (lines 07 to 18): provides website operators with data types in the form of a hierarchical tree structure, which is becoming more and more specific based on the most general data type “Thing”.

In the following step, we will show you how to adapt the Google example for the data type "Event" to the event announcement listed above.

Step 4: adapt the JSON-LD markup

The Google documentation only contains examples that show how the listed data types can be identified via JSON-LD. If these are used as templates for your own metadata markup, the code must be individually adapted in each case. It may be helpful to refer to the documentation refer to the appropriate data type to learn more about the use of a particular schema and possible properties. The following example shows an individual adaptation of the Google sample code for the event data type:

In the first step, we replaced all values ​​of the sample markup with corresponding values ​​from the event announcement listed above. There were Inapplicable (sub) schemas and properties deleted. For example, we have left out the “addressRegion” property, as this is not common in Germany. Instead of “PerformingGroup” we use the (sub) schema “Person” under “performer”, because we are not dealing with a band but with an individual performer. Finally, we added information to the markup that was not recorded in the Google template. In line 07 and line 10, for example, URLs to the event or to the venue can be found. Possible properties can be found in the documentation if required.

Even if you're creating your JSON-LD markup from scratch without a template, you should take a look at the Google documentation page for the specific data type. The search engine market leader gives both supported data types here required as well as recommended properties at.

Make sure that your JSON-LD markup always contains all the necessary properties. Only then will your website participate in the ranking for advanced search results such as rich cards. You should also try to provide values ​​for all recommended properties in order to increase your chances of ranking.

The examples given in the Google documentation always contain all required and recommended properties.

It is best to test whether your markup is missing important properties with the one provided by Google Validation tool.

Step 5: test the JSON-LD markup

By nesting schemas, (sub) schemas and properties, complex JSON-LD markups are possible. The separation of HTML markup and semantic markup still ensures a significantly better readability than with comparable data formats based on source text annotation. To avoid programming errors, Google is sticking with the Structured Data Testing Tool a free way to validate JSON-LD code for data structuring.

Proceed as follows:

  1. Insert the JSON-LD code into the provided input field using copy & paste

You can choose to insert the markup itself or the URL of the website whose metadata markup you want to test.

  1. Start validation by clicking on "Run Test"

During the validation, the tool reads out the structured data of the JSON-LD markup and checks it for completeness. Users are shown the data read out in a tabular overview. This also includes notes and warnings, provided the tool Syntax error or missing data could determine.

The test script we create is error-free and contains all the required properties. If we now delete the required property "startDate", for example, we get the following output:

Syntax errors such as the missing comma at the end of a name-word pair can also be localized.

  1. Generate preview
    In addition to the test function, the Google Structured Data Testing Tool offers a preview mode. This gives website operators a foretaste of what an extended search result based on the tested, validated markup could look like.

Error implementing JSON-LD markup

If Google does not display extended search results for your website despite JSON-LD markup, you have usually made an error in structuring the data. Check your code again, paying attention to the following sources of error:

  • Syntax error: The JSON-LD syntax is simple and clear. But as with any markup language, errors occasionally creep in. A well-known source of error is the difference between double coding characters ("...") and typographical quotation marks ("..."). While coding characters are used in programming, quotation marks are used to mark literal speech in written language. Since word processing programs often convert double encoding characters to quotation marks automatically, it is best to use an editor such as Notepad to create your JSON-LD markup. The single quotation marks that are otherwise often used in program code are also not permitted in JSON.
  • Incomplete, incorrect or unspecific vocabulary: The hierarchical tree structure of defines exactly which properties can be used with which data type. If you use a property for a data type that does not support it, the corresponding value cannot be interpreted by Google. The code is classified as incorrect. The Google Structured Data Testing Tool also detects such errors.

All types and properties of the vocabulary are case-sensitive. There is thus a difference in meaning due to the upper and lower case of letters.

Always use the documentation pages and validate your JSON-LD code using the Structured Data Testing Tool. Also note the Structured Data General Guidelines as well as the general Webmaster Guidelines by Google to avoid rule violations that can lead to exclusion from ranking for advanced search results.

Similar articles

Bootstrap Tutorial: Getting Started with the Twitter Framework

Bootstrap is considered one of the best solutions in the online world when it comes to creating cross-device websites with ease. But what exactly is behind the framework, which was actually planned as an in-house optimization tool by Twitter? Can even absolute newbies achieve results that are worth seeing without in-depth knowledge of CSS, JavaScript and HTML?

What is

The path to Web 3.0 can only be treaded with structured data. But website operators who want to help web crawlers or screen readers with semantic annotation are faced with a confusing selection of awards. In order to create clarity in this regard, the community project was launched. The standardized mark-up is based ...

How to tag your website with RDFa according to

RDFa is a standard recommended by the W3C for embedding metadata in HTML, HTML5, XHTML and other XML dialects. The data format is considered to be the cornerstone of the Semantic Web. A standardized vocabulary is made available by the project. Get to know the application possibilities and limits of the data format and gain an insight into the award of ...

How to mark up your website with Microdata according to

Microdata offers a simple and at the same time flexible meta-syntax for the semantic annotation of website content. The use of a uniform markup according to ensures high compatibility with web browsers and search engine crawlers. Mark your HTML code with Microdata according to and benefit from extended search result displays such as rich ...