Introduction To JSON-LD

Next: Knowledge Vaults

Whilst microdata is a popular way of embedding structured data with HTML markup, alternative ways of expressing structured data on web pages exist. JSON-LD is a popular alternative – and unlike microdata, is typically not embedded within the HTML layout of the page itself but as raw data in the header of a page.

After this tutorial, you should be able to:

  • Understand the key differences between microdata syntax and JSON-LD syntax.
  • Discern where the use of either syntax is most appropriate.
  • Write basic JSON-LD documents using schema.org vocabulary.

Estimated time: 5 minutes

You should have already understood the following lesson (and pre-requisites) before you begin:

JSON (JavaScript Object Notation) has become increasingly popular in recent years, with its more lightweight structure compared to XML making it a useful format for sending information over the internet in a way that requires less data bandwidth than a bulky XML document.

JSON-LD stands for JavaScript Object Notation for Linked Data and has been a W3C Standard since 2010. Structured data expressed in JSON-LD uses the familiar JSON structure but has been especially developed for expressing information using structured data (or, linked data) vocabularies – such as schema.org.

Note JSON-LD became a recommended syntax for expressing schema.org structured data in June 2013, as published on the schema.org blog. Just like the major search engines understand microdata markup in a page, they also understand JSON-LD in web pages.

3.1 A Starting Example

We begin by immediately giving a starting example of JSON-LD, to give you a feel for how it looks:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Book",
  "name": "Semantic Web Primer (First Edition)",
  "publisher": "Linked Data Tools",
  "inLanguage": "English",
  "bookFormat":
  {
     "@type": "EBook"
  },
  "offers":
  {
     "@type": "Offer",
     "price": "2.95",
     "priceCurrency": "USD",
  },
}
</script>

Do not concern yourself with the details for now, we will cover these gradually in this tutorial.

However, you might having read our Introduction To Schema.org tutorial find this example looks a little familiar. In fact, it is the exact same e-book that we defined using microdata in our previous tutorial, except we have expressed the same structured data instead using JSON-LD.

As a reminder, here is the microdata example from our previous tutorial again:

<div itemscope itemtype="http://schema.org/Book">

	<link itemprop="bookFormat" href="http://schema.org/EBook"/>
	<meta itemprop="publisher" content="Linked Data Tools"/>
	<meta itemprop="inLanguage" content="English"/>

	<p itemprop="offers" itemscope itemtype="http://schema.org/Offer">Only <b><span itemprop="price" content="2.95">$2.95</span></b>
	<meta itemprop="priceCurrency" content="USD" /></p>

	<h4>In <span itemprop="name">Semantic Web Primer (First Edition)</span></h4>

</div>

Just as a starting exercise, without concerning yourself with the detail see if you can see a little of how these two examples might define the same structured data.

We begin by building up this starting example again, step-by-step.

3.2 Define The Itemscope Using The JSON-LD Context

As you can see from our initial example, JSON-LD is structurally no different to any other JSON documents – consisting of a hierarchy of name-value pairs. However, JSON-LD contains specific reserved names, prefixed by the ‘@’ symbol – such as ‘@context’ and ‘@type’ above.

Although these are still just ordinary names in a JSON document, for JSON-LD readers such as search engines they give special instruction in how the values given to these name-value pairs should be treated.

Note JSON-LD is just an ordinary JSON document. It just contains some special reserved names that only JSON-LD readers can interpret.

Look again at the @context in the above example, which has been assigned the value ‘http://schema.org’. This instructs any reader of the document that any @type should be treated as if they are prefixed by this context. For example, with a @context of ‘http://schema.org’ above, @type ‘Book’ value above resolves in full to the URI http://schema.org/Book.

By defining a ‘@context’ for the document, and adding our ‘@type’ to resolve to http://schema.org/Book, we are stating that the structured data in the document describes a book using schema.org vocabulary. This is the precise equivalent of how we used the ‘itemscope’ syntax in our previous microdata example.

Let’s start our example again just by adding the context and type:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Book",
}
</script>

Next, we will learn how to add properties to our item using JSON-LD syntax.

Point Of Interest Just as we saw in our Introducing RDF/XML tutorial from our semantic web primer series, the ‘@context’ here is the equivalent to an XML namespace in RDF/XML, because it tells the reader to prefix all element names with this contextual namespace.

3.3 Adding Item Properties In JSON-LD

Adding item properties (such as our book format, or publisher name) is quite straightforward using JSON-LD.

For simple literal properties (such as names, or numbers) once we have defined our item scope, at the same level you can add properties as simple name-value pairs. Let’s add the book title, and language. We know from looking at the schema.org vocabulary that an item with URI http://schema.org/Book has the property names ‘name’ and ‘inLanguage’ for these particular properties respectively.

Remember You can find all the properties valid for a particular item type in schema.org simply by going to the item type URI in your web browser (e.g. http://schema.org/Book). In semantic web terms, these are known as ‘resolvable URIs’.

3.4 Adding Simple Properties

So let’s add these properties to our JSON-LD document:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Book",
  "name": "Semantic Web Primer (First Edition)",
  "publisher": "Linked Data Tools",
}
</script>

Note that this is the exact equivalent of using the ‘itemprop’ attribute in microdata to add properties to our item – to the search engine these mean the same things.

Not all properties are that simple though – some of them are nested items themselves. For example, the ‘offers’ property is not a simple literal value, but another item in itself. As we saw in our previous tutorial, the ‘offers’ property of our book is an example of such a property which has an item type http://schema.org/Offer.

3.5 Adding Complex Properties

Let’s add the ‘offers’ property to our item now:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Book",
  "name": "Semantic Web Primer (First Edition)",
  "publisher": "Linked Data Tools",
  "offers":
  {
     "@type": "Offer",
     "price": "2.95",
     "priceCurrency": "USD",
  },
}
</script>

We’ve added a new complex property by creating a new JSON hierarchy level underneath the ‘offers’ property. Just as our top level scope has the item type ‘Book’ using the reserved keyword @type, we use the same reserved keyword again to state that our new hierarchy level defines an item of type ‘Offer’.

Remembering that the @context we defined at the beginning of the document was http://schema.org, this @type expands again to become the schema.org item type http://schema.org/Offer.

Completing our example by adding the inLanguage and bookFormat properties gives us:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Book",
  "name": "Semantic Web Primer (First Edition)",
  "publisher": "Linked Data Tools",
  "inLanguage": "English",
  "bookFormat":
  {
     "@type": "EBook"
  },
  "offers":
  {
     "@type": "Offer",
     "price": "2.95",
     "priceCurrency": "USD",
  },
}
</script>

Before continuing, now would be a great opportunity to compare with our previous microdata example again. See if you can see more clearly now the equivalence of the two examples:

<div itemscope itemtype="http://schema.org/Book">

	<link itemprop="bookFormat" href="http://schema.org/EBook"/>
	<meta itemprop="publisher" content="Linked Data Tools"/>
	<meta itemprop="inLanguage" content="English"/>

	<p itemprop="offers" itemscope itemtype="http://schema.org/Offer">Only <b><span itemprop="price" content="2.95">$2.95</span></b>
	<meta itemprop="priceCurrency" content="USD" /></p>

	<h4>In <span itemprop="name">Semantic Web Primer (First Edition)</span></h4>

</div>

3.6 Why Use JSON-LD Versus Microdata?

JSON-LD was initially created to make it as easy as possible to bring legacy JSON data to the semantic web. So, if you already have a lot of data held in JSON documents (e.g. in a JSON document database, or a file) it can sometimes be the most straightforward solution to adding semantics to your raw JSON data.

If you prefer to keep the clutter out of your HTML layout too, you can publish your structured data separately from your HTML layout markup by adding JSON-LD to the header of your HTML page. For this reason, if you for example don’t have the ability to edit your organisation’s web pages, sometimes JSON-LD can be a suitable candidate.

Given that the structured data you defined in JSON-LD also isn’t interspersed with lots of HTML layout code, it is also arguably more human readable.

JSON-LD is well supported. For example, Google’s popular Gmail can read JSON-LD within an email.

3.7 A Quick Example Of Using JSON-LD To Express RDF Data

If you have read our Introducing Graph Data tutorial you should have learned about RDF, and how it can be used to publish raw machine-readable data on the web. JSON-LD isn’t just restricted to being used to express data in schema.org vocabulary, it can also be used to express data using other web ontologies.

Here’s a quick example of using JSON-LD to define a social profile using the popular FOAF (friend of a friend) vocabulary:

{
  "@context": 
  {
    "name": "http://xmlns.com/foaf/0.1/name",
    "homepage": {
      "@id": "http://xmlns.com/foaf/0.1/workplaceHomepage",
      "@type": "@id"
    },
    "Person": "http://xmlns.com/foaf/0.1/Person"
  },
  "@id": "https://www.linkeddatatools.com/johndoe",
  "@type": "Person",
  "name": "John Doe",
  "homepage": "https://www.linkeddatatools.com/"
}

We will not go into the details of this document here, as it is beyond the scope of this tutorial. However, if you wish to see a little more of how JSON-LD can define RDF then W3C’s JSON-LD specification contains some more examples.

You have completed this lesson. You should now understand the following:

  • The basic concepts of defining structured data using JSON-LD and schema.org vocabulary.
  • How JSON-LD syntax compares to microdata syntax.
  • Some of the uses and advantages of JSON-LD.
  • That JSON-LD is not just restricted to expressing data using schema.org vocabulary.

You should now be able to start the following tutorial: