Set your website apart with JSON-LD according to Schema.org

Struc­tured data helps search engines to better un­der­stand websites. A semantic an­nota­tion makes it possible to establish new meanings/contexts, auto­mat­ic­ally read in­form­a­tion, and transfer it to other forms. Google, by far the most used search engine, bases itself on struc­tured data with the aim of providing users with rich search results and other such SERP elements. The advantage to the website operator is these sorts of search results greatly increase the vis­ib­il­ity and are much more likely to get the attention of potential customers.

One re­quire­ment is that all relevant in­form­a­tion is ap­pro­pri­ately marked. Over time, the internet community has developed various standards for data struc­tur­ing. Here we outline why you should choose JSON-LD al­tern­at­ive data formats like Mi­cro­formats, RDFa or Microdata.

JSON-LD stands for JavaS­cript Object Notation for Linked Data. It is a JSON-based method of embedding struc­tured data in a website. Unlike other formats of data struc­tur­ing like Mi­cro­formats, RDFa, and Microdata, the marking is not done as source text an­nota­tion. Instead the metadata is im­ple­men­ted as a script tag separate from the website content in the head or body element of a HTML document. JSON-LD uses the JSON notation and extends this with a syntax that allows data to be dis­tin­guished according to uni­ver­sally valid, globally stand­ard­ised schemata.

JSON-LD’s spe­cific­a­tion comes from Digital Bazaar’s founder, Manu Sporny, and since 16 January 2014 has been the official W3C re­com­mend­a­tion.

The acronym JSON stands for JavaS­cript Object Notation and refers to the compact, text-based format for ex­chan­ging data. It is easy to process both for humans and machines. JSON is a de­riv­at­ive of JavaS­cript, however, it can be im­ple­men­ted across various platforms re­gard­less of the re­spect­ive pro­gram­ming language. As a data format for seri­al­isa­tion – the mapping of pro­gram­mable objects into a se­quen­tial rep­res­ent­a­tion format – JSON is used for trans­fer­ring and storing struc­tured data for websites and mobile apps. The syntax of a JSON object is es­sen­tially made up of name value pairs (with the exception of figures) placed in double quotation marks and noted sep­ar­ately by a colon. Each name value pair normally begins in a new line and ends with a comma. The exception here is the last name value pair before the closing bracket which is noted without a comma.

The following example makes clear the basic schema of JSON syntax:

In the opening sentence, you see the word pair ‘Manu Sporny’. A human reader would quickly figure out from the sequence of letters that this is a name and that the hyperlink is a reference to the web presence of the JSON LD developer. Programs like web browsers and search engine crawlers require metadata to create such a con­nec­tion. This is what JSON offers.

The example code shows both name elements ‘name’ and ‘homepage’ with their re­spect­ive values. This ensures that a program that reads a website with this JSON object is in a position to identify ‘Manu Sporny’ as a name and ‘http://manu.sporny.org/about/’ as a homepage.

While the as­sign­ment of meaning with JSON works perfectly within a website, the analysis of JSON data from different websites quickly leads to an ambiguity problem. Usually it is the case that programs parse a large number of websites and evaluate the in­form­a­tion obtained in databases. For example, with the above-mentioned JSON code, it cannot be guar­an­teed that the elements ‘name’ and ‘homepage’ are always used in the same meaning context across different websites. To avoid am­bi­gu­ities, JSON-LD adds con­tex­tu­al elements to the classic JSON notation. This is done on the basis of linked data – freely-available data on the Internet that can be accessed via Uniform Resource Iden­ti­fi­er (URI).

Further in­form­a­tion on linked data can be found in the following video from the JSON-LD developer Manu Sporny:

In order to prepare JSON for linked data, JSON-LD sup­ple­ments the classic name value pairs of JSON notation with so-called keywords. Keywords are in­tro­duced in the syntax of JSON-LD preceded by the @ symbol. The keywords @context und @type are of par­tic­u­lar sig­ni­fic­ance here. While @context defines the un­der­ly­ing vocab­u­lary of the label, @type specifies the data type (schema) used.

A stand­ard­ised schema database for data struc­tur­ing is offered by the project Schema.org. On the project website of the same name, website operators can find various data schemata (types) as well as the ‘prop­er­ties’ assigned to these data types, which make a detailed semantic display of the website’s content possible.

When the ap­pro­pri­ate context elements are added, the following code results for the above example:

The keyword @context in column 2 defines the vocab­u­lary on which the semantic label is based – in this case Schema.org. In column 3, the data type ‘Person’ is im­ple­men­ted with the help of the keyword @type. This data type is specified further in columns 4 and 5 through the char­ac­ter­ist­ics ‘name’ and ‘url’. So, a program that parses this sample code can identify the text element ‘Manu Sporny’, which is marked as ‘name’, as the name of a person. This is according to the data type ‘person’ according to Schema.org. The name value pairs in­tro­duced by ‘name’ and ‘url’ are processed as prop­er­ties of the ‘Person’ schema. The un­der­ly­ing vocab­u­lary de­term­ines which prop­er­ties can be assigned to a schema.

With JSON-LD, the as­sign­ment of schemas and prop­er­ties takes place by analogy to other formats for the semantic marking of web page contents. Converted in a source text an­nota­tion, the above example script could also be iden­ti­fied by Microdata or RDFa according to Schema.org, and this without any loss of in­form­a­tion.

Microdata syntax according to Schema.org:

RDFa syntax according to Schema.org:

The biggest advantage of JSON-LD compared to other com­pet­it­ors lies in the fact that metadata is not embedded directly in the HTML code, and instead can be im­ple­men­ted sep­ar­ately in the desired place. The im­ple­ment­a­tion of JSON-LD can be done with the help of a script tag according to the following schema:

Relating to the above example, the following award is made according to Schema.org:

The strict sep­ar­a­tion between HTML and semantic an­nota­tion not only scores points with clearly superior read­ab­il­ity of source texts. An im­ple­ment­a­tion of this sort also makes it possible for a dynamic gen­er­a­tion of data struc­tures, re­gard­less of visible content. With JSON-LD metadata can be imported via the backend, selected from a database, and then auto­mat­ic­ally generated via a template. This makes possible a more con­veni­ent semantic an­nota­tion, even for dynamic web content, that requires more space online.

Since June 2013, the web project Schema.org named JSON-LD one of the most prominent data formats. Google also re­com­mends (where possible) the script-based embedding of metadata via JSON-LD. Such a dis­tinc­tion is the basis for diverse SERP elements, which Google uses to present users with extended search results.

Google uses various present­a­tion forms for search results: In addition to the basic results, for years now users have also had access to featured results and knowledge graph results – depending on the exact search query. While basic results only have simple ex­ten­sions like bread­crumbs, if at all, featured results and knowledge graph results offer the potential for com­pre­hens­ive ex­ten­sions – also called en­hance­ments or search result features by Google.

Currently, Google supports a JSON-LD markup for the following ex­ten­sions below. An example for every search result feature can be found in the search gallery on de­velopers.google.com.

• Bread­crumbs: The so-called ‘bread­crumb’ nav­ig­a­tion shows the position of the current web page in the hierarchy of the website. Web page operators that se­mantic­ally feature bread­crumbs allow Google to display these in the SERPs. Bread­crumbs belong to the few search result features that Google also includes in the basic results.
• Contact in­form­a­tion: If the contact details for a business are featured se­mantic­ally, Google can show this as a knowledge graph display; a display form of the knowledge graph algorithm.
• Logos: With a logo markup, website operators make clear which graphic should be used by the search engine as the company logo. This makes it possible for Google to extend the search results for the company in question to include the business logo.
• Sitelinks search box: If a website provides a search function and has been written se­mantic­ally, Google may use a sitelink search box to find results about the website.
• Social media profile links: If you are using a markup for links to social media profiles, Google extends the knowledge graph display to include people or or­gan­isa­tions, and their cor­res­pond­ing buttons. Currently Google supports a JSON-LD markup for Facebook, Twitter, Google+, Instagram, YouTube, LinkedIn, Myspace, Pinterest, Sound­Cloud, and Tumblr.

Website operators who wish to make sure their content is well-placed and visible in the Google SERPs have the pos­sib­il­ity of se­mantic­ally featuring various data types. Here it is worth noting that only Google chooses whether a search result is shown as a basic result or as one with ex­ten­sions. Currently, Google supports a JSON-LD markup for multiple data types and uses these to process in­form­a­tion as rich search results, enriched search results, or knowledge graph results.

• Articles: Website operators, who wish to se­mantic­ally feature news and/or blog articles on their page, allow Google to include these in the top story carousel or add search result features such as headlines or thumb­nails to the SERPs.
• Books: It may be the case that those in charge of a website wish to offer a JSON-LD markup for in­form­a­tion per­tain­ing to books. If so, Google will create a knowledge graph card for the relevant search queries. These contain not just de­script­ive in­form­a­tion on the book, but also, if necessary, make it possible for search engine users to get the relevant in­form­a­tion directly from the search engine.
• Music (entries for artists and albums): Similar to in­form­a­tion on books, musical offers can also be annotated. This means that it is possible for Google to generate knowledge graph cards for music content. This not only offers search engine users in­form­a­tion about albums and artists, but also allows for in­ter­ac­tions with the music, e.g. playback or even pur­chas­ing.
• Course offers: Website operators, who provide courses (e.g. language courses) with a JSON-LD markup, make it possible to auto­mat­ic­ally read the course title, a short de­scrip­tion, and the course provider. There is also the strong pos­sib­il­ity that Google will use this in­form­a­tion as extended search results in the SERPs.
• Events: Those offering public events like concerts and festivals have the pos­sib­il­ity of an­not­at­ing all the relevant in­form­a­tion (e.g. event location, date, time, etc.) via JSON-LD, so that Google can auto­mat­ic­ally extract this in­form­a­tion and list it in the SERPs, as well as in other Google ap­plic­a­tions, e.g. Maps.
• Job ad­vert­ise­ments: Even job vacancies that or­gan­isa­tions publish on their website can be drawn up in such a way that Google can read the relevant in­form­a­tion and display it within extended search results.
• Local busi­nesses: Local busi­nesses that feature struc­tured data on the website of their store or res­taur­ant make it possible for Google to generate knowledge graph cards. These will then be displayed in the SERPS or in Google Maps during any relevant search queries. For example, if a Google user is searching for a Vi­et­namese res­taur­ant, Google will sub­sequently display a carousel with all relevant suitors in the area.
• Data sets: Even data sets like CSV tables or files in pro­pri­et­ary formats can be made ac­cess­ible for search engines via JSON-LD.
• Podcasts: Google also supports a JSON-LD markup for podcasts. The relevant featured offers can be viewed and even played directly in the search engine.
• Videos: Content providers that provide struc­tured data for videos on your website, such as a de­scrip­tion, a link to a thumbnail, the upload date, or playback time, allow Google to extract this in­form­a­tion and display it as rich cards or in the form of carousels on the SERPs.
• Films and shows: If a website delivers struc­tured data on films or shows, Google can transfer it to the search results pages as knowledge graph cards for relevant search queries. If required, these can be expanded with in­ter­act­ive elements that enable the consumer to watch or purchase the product
• Recipes: For several years now, Google has gone as far as offer cooking recipes as a featured result in their search engine. One pre­con­di­tion for this is that the provider of the content presents all the relevant in­form­a­tion as struc­tured data. One possible present­a­tion after a search query is in the SERPs in a carousel with the suitable rich cards.
• Ratings:  Google supports ratings for various Schema.org data types like local busi­nesses, res­taur­ants, products, books, films, and creative works. The present­a­tion of this content is carried out as a snippet. With this, Google dif­fer­en­ti­ates between the critiques made by in­di­vidu­al authors and entries on other rating portals. As long as they feature a semantic an­nota­tion, both types of rating will appear as a featured result in the SERPs as a result of the relevant search query.
• Products: Online retailers that present product in­form­a­tion (e.g. price, avail­ab­il­ity, ratings, etc.) on their website as struc­tured data make it possible for Google to display this in­form­a­tion as a rich search result after a search has been submitted.

Advanced search results can be very ad­vant­age­ous for website operators. Re­gard­less of whether we are dealing with featured results or knowledge graph displays, they will always stand out from the other search results.

Google places displays and carousels in a very visible location above the basic results. This is also known as ‘position 0’. Knowledge graph displays will appear either as a carousel at the top of the page or else in a separate frame to the right of the organic web search. What this then means is that advanced search results offer website operators the chance to achieve the pole position in the search results page without having to invest lots of time and money into improving organic rankings.

It is not only the high­lighted position but also various ex­ten­sions, such as thumb­nails, ratings, text excerpts, and in­ter­act­ive elements that attract the attention of the user and encourage clicks. Website operators can expect that the click-through rate for advanced search results will sig­ni­fic­antly increase when compared to the basic results.

In addition to this, it is said that advanced search results have a positive effect on the bounce rate. Unlike basic results, which usually only include the meta-title, a URL, and a short de­scrip­tion, advanced search results give Google users a com­pre­hens­ive view of what they can expect to find on the linked site. This then means that a user can check the relevance of a website for their own search query before they click on it, and therefore click only if necessary.

However, Google does not see the presence or absence of a semantic markup via JSON-LD as a ranking factor. The former head of the Google web spam team, Matt Cutts, clarified this in the following YouTube video from the Google Web Masters series in 2012:

As with the ap­plic­a­tion, JSON-LD also scores points for its craw­lab­il­ity by moving the markup to separate script sections. Compared to al­tern­at­ive an­nota­tions such as Microdata or RDFa, JSON-LD allows a lean source code. This is despite semantic an­nota­tion, which can be searched quickly and easily indexed by Google bot and other crawlers.

But the out­sourcing of struc­tured data also has its dis­ad­vant­ages. In principle, Google and other search engine providers apply the basic rule that only the content that is available to human visitors is machine-readable. However, with JSON-LD it is the­or­et­ic­ally possible to implement any markup, even if there is no equi­val­ent for the metadata in the actual website content. In this case, both the search engine and the user are promised a possible added value; something which a more em­bel­lished website does not offer. In terms of ease and prac­tic­al­ity, this approach is not advisable, as web site operators run the risk of being punished for online spamming.

To prevent website visitors from ac­ci­dent­ally exceeding the limits of semantic an­nota­tion in search engines, Google's Struc­tured Data General Guidelines provide a detailed set of rules. These can be reduced to the following points:

• Format: Struc­tured data needs to be in one of the three es­tab­lished formats; Microdata, RDFa, or JSON-LD. Google re­com­mends the latter.
• Ac­cess­ib­il­ity: Web pages with struc­tured data need to be ac­cess­ible for the Google bot. Access control methods (e.g. via robots.txt or noindex) prevent the reading of metadata.
• Content equi­val­ency: The JSON-LD markup can only describe entities, which can also be described in HTML code. 
• Relevance: A JSON-LD markup should refer only to relevant equi­val­ents of the data types used. For example, a website operator, who features a technical manual as a recipe, violates the directive of relevance.
• Com­plete­ness: All data types listed in the JSON-LD markup need to be marked com­pletely and include the required prop­er­ties. In fact, data types that lack essential prop­er­ties are not suitable for advanced search results.
• Spe­cificity: Linked data projects like Schema.org offer a variety of data types. In order for your content to qualify for an extended search result present­a­tion, website operators should choose schemata that are as specific as possible.

In the following para­graphs we show, with the use of an example, how to enrich a website in the most efficient way possible with relevant metadata. The JSON-LD tutorial is based on the vocab­u­lary of the Schema.org project.

The im­ple­ment­a­tion of struc­tured data can be more or less time-consuming, depending on the size of the website. Therefore, you should consider be­fore­hand which goals you would like to achieve with the semantic award, as well as how much time you would like to invest in the an­nota­tion.

As a rule, a markup should structure and present website in­form­a­tion in a form that can be read by search engines. The goal is to demon­strate to Google and co. that the optimised website provides the best resources for any relevant search queries relating to the web project's focus. You should ask yourself the following questions:

• What is the central content of your website?
• Of what value could it be to potential visitors?
• Which content in par­tic­u­lar is relevant to the focus of your website in order to make it ‘search engine friendly’?

Create a list of all content that is of some value. Then decide which content potential visitors should be made aware of before they click on the website, i.e. in the search results page.

For example, Google re­com­mends an an­nota­tion with JSON-LD for in­form­a­tion that has to do with events. In HTML, you can display event an­nounce­ments for concerts, musicals, or theatre per­form­ances according to the following scheme:

Typical in­form­a­tion of the data type ‘event’ includes date, time, price, avail­ab­il­ity of tickets, address of the venue, as well as links to further in­form­a­tion on the event or venue. Human page visitors can take this in­form­a­tion from a text section, a table, or other forms of present­a­tion, and then assign it to the cor­res­pond­ing context. On the other hand, programs such as search engine crawlers require metadata that contains in­struc­tions on how to process the in­form­a­tion presented. JSON-LD delivers these in the form of a data format, which is inserted at any position of the HTML source code, sep­ar­ately from the content.

Schema.org offers website operators a wide and com­pre­hens­ive vocab­u­lary for data struc­tur­ing. In total, the database comprises of around 600 types, which can be specified with more than 860 prop­er­ties.

When it comes to the selection of suitable data types there are two strategies to choose between:

1. In theory, they could compare all pre­vi­ously de­term­ined content with the available data types of the Schema.org vocab­u­lary, and then select the most specific data type for each content element. However, such an approach is lengthy and usually un­ne­ces­sary.
2. In practice, website operators usually limit them­selves to a subset of Schema.org data types. If you only use the JSON-LD markup with the goal of providing the search engine with struc­tured data, it is suf­fi­cient to first limit yourself to the data types that are currently supported by Google and described in detail in the Google developer area.

We recommend the latter of these options for the following reason: Google offers detailed doc­u­ment­a­tion for all data types supported by the search engine. An example markup is provided for each data type.

To equip your website with struc­tured data, you don't ne­ces­sar­ily have to reinvent the wheel. This is es­pe­cially the case if you have no ex­per­i­ence with the JSON-LD syntax. It will save you both time and energy to revert to pre­fab­ric­ated patterns instead of rewriting the markup for each data type from scratch.

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

The script tags define the element from line 01 to 39 as a script type ‘ap­plic­a­tion/ld+json’. The following in­form­a­tion is intended for programs that can read linked data in JSON format.

The first level contains the keywords ‘@context’ and ‘@type’ with the values ‘http://schema.org’ and ‘Event’ (lines 03 and 04). A parsing program receives the in­struc­tion that the following in­form­a­tion is to be assigned to the schema ‘Event’ according to Schema.org, meaning that it is a specific property of the event which is being described. These are displayed in the form of name value pairs.

Similarly, the first level also contains the prop­er­ties ‘name’, ‘startDate’, ‘location’, ‘image’, ‘de­scrip­tion’, ‘enddate’, ‘offers’, and ‘performer’, to which the re­spect­ive event in­form­a­tion is assigned as values. A search engine crawler can then identify the in­form­a­tion ‘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).

Similar to RDFa and Microdata, JSON-LD syntax supports nesting. A property is not assigned a value, but a (sub-)schema that can be de­term­ined with specific prop­er­ties. You will find such a case on the second level of the code example in lines 08, 27, and 35.

For example, in line 08 the event property ‘location’ is defined as a (sub-)schema of the type ‘Place’ and provided with the prop­er­ties ‘name’ and ‘address’. In turn, line 11 sees the property ‘address’ being defined as a (sub) schema of the type ‘PostalAd­dress’, and as a result is marked with the schema specific prop­er­ties ‘streetAd­dress’, ‘ad­dress­Lo­c­al­ity’, ‘postalCode’, ‘ad­dress­Re­g­ion’, and ‘ad­dressCoun­try’.

Each nested level is placed in brackets and sectioned off from the su­per­or­din­ate level.

Section (Line 07 to 18):

As such, Schema.org provides website operators with data types in the form of a hier­arch­ic­al tree structure. This is something 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 fit the above-mentioned event an­nounce­ment.

The Google doc­u­ment­a­tion contains only examples that show how the listed data types can be dis­tin­guished via JSON-LD. If these are used as templates for your own metadata markup, the code must always be adapted in­di­vidu­ally. It may be helpful to refer to the Schema.org doc­u­ment­a­tion for the cor­res­pond­ing data type to learn more about using a schema and possible prop­er­ties. The following example shows an in­di­vidu­al cus­tom­isa­tion of the Google pattern code for the data type ‘Event’:

What we have done in the first step is replace all values of the sample markup with cor­res­pond­ing values of the above event an­nounce­ment. Incorrect (sub-)schemata and prop­er­ties have been replaced. Instead of ‘Per­form­ingGroup’ we use the (sub-)scheme ‘Person’ under ‘performer’, because we are not dealing with a band but with a single per­form­ing artist. Finally, we added in­form­a­tion that was not included in the Google template to the markup. For example, line 07 and line 10 contain URLs relating to the event or event location. For possible prop­er­ties, please refer to the Schema.org doc­u­ment­a­tion.

Even if you decide to create your JSON-LD markup from scratch and without a template, you should still look at the Google doc­u­ment­a­tion page for each data type. Here, Google specifies both the required as well as the re­com­men­ded prop­er­ties for all supported data types.

The examples in the Google doc­u­ment­a­tion always include all required and re­com­men­ded prop­er­ties.

Checking whether your markup lacks important prop­er­ties is best done with the val­id­a­tion tool provided by Google.

The examples in the Google doc­u­ment­a­tion always include all required and re­com­men­ded prop­er­ties.

Checking whether your markup lacks important prop­er­ties is best done with the val­id­a­tion tool provided by Google.

You should always make sure to use the doc­u­ment­a­tion pages of Schema.org and validate your JSON-LD code using the Struc­tured Data Testing Tool. Also note the Struc­tured Data General Guidelines as well as Google's general Webmaster Guidelines to avoid rule vi­ol­a­tions, which could lead to exclusion from advanced search result ranking.