{"id":7658,"date":"2016-07-16T14:03:04","date_gmt":"2016-07-16T13:03:04","guid":{"rendered":"https:\/\/www.brainlabsdigital.com\/?p=7658"},"modified":"2025-06-20T18:26:11","modified_gmt":"2025-06-20T18:26:11","slug":"how-to-implement-structured-data-with-json-ld","status":"publish","type":"post","link":"https:\/\/www.brainlabsdigital.com\/how-to-implement-structured-data-with-json-ld\/","title":{"rendered":"How to implement structured data with JSON-LD"},"content":{"rendered":"\n

Chances are, you\u2019ve already heard of JSON-LD \u2014 you might even be using it already. Kudos to you if that\u2019s the case. If you haven\u2019t heard of it, I\u2019d urgently recommend you to read up<\/a> on what is becoming an ever-more important part of SEO. Its increasing importance is down to its selection as Google\u2019s structured data approach of choice, as it\u2019s more flexible than microdata and more easily maintainable in the long run.<\/p>\n\n\n\n

What do I mean by more flexible? Put simply, JSON-LD lets you place all your structured data between a special pair of <script> tags in the <head> of the HTML, much as you would with Google Analytics tracking snippets or canonical tags. No more bugging your developers to make simple changes. Compared to the old ways of adding structured data, that\u2019s a big improvement.<\/p>\n\n\n\n

<head>
...
<script type=\"application\/ld+json\">
\/\/ your JSON-LD goes in here...
<\/script>
...
<\/head>
<\/pre>\n\n\n\n
The flip side of that flexibility, though, is that JSON-LD is still a relatively new concept to most users, and it\u2019s easy to get the structure wrong. It\u2019s easy to believe that you can read JSON-LD, but not truly understand the structure.<\/p>\n\n\n\n
The good news is it isn\u2019t that hard to get right. By the end of this post, you\u2019ll understand enough to understand<\/em> any JSON-LD you come across.<\/p>\n\n\n\n
Plain old JSON<\/h2>\n\n\n\n
The “JSON” in JSON-LD stands for “JavaScript Object Notation”. Although it owes its name to Javascript, it came into its own as a flexible format for passing data around between all kinds of applications. When you call an API \u2014 the Google Analytics API, for example \u2014 the results often come back in the JSON format. And you might also have heard of mongoDB \u2014 a so-called NoSQL database used by some of the biggest companies on the web<\/a> to organise huge amounts of data. JSON is all over the web, but it\u2019s usually behind the scenes. To learn it by example, let’s make some JSON to describe a person:<\/p>\n\n\n\n
{
<\/code><\/pre>\n\n\n\n
 \"@type\" : \"Person\",
\n \"first name\" : \"Mark\",
\n \"last name\" : \"Zuckerberg\",
\n \"age\" : 32
\n}
<\/code><\/pre>\n\n\n\n
Remember, this is just JSON \u2014 not JSON-LD \u2014 so don’t add it to any web pages! We haven’t gone very far with our model of a person, but that doesn’t matter. We used curly braces to surround the object, and within it, we’ve defined three properties. In each case, we put the name of the property and its value, separated by a colon. Wherever we used non-numeric characters, we enclosed the name or value with quotation marks. So “age”: 32, for example, shows that this person is 32.<\/p>\n\n\n\n
But 32 what? Days, months, or years? Of course, in this case, we know it to be years, but a computer wouldn’t necessarily know that. So let’s expand our model slightly:<\/p>\n\n\n\n
{
\n \"@type\" : \"Person\",
\n \"first name\" : \"Mark\",
\n \"last name\" : \"Zuckerberg\",
\n \"age\" :{
\n         \"value\" : 32,
\n         \"units\" : \"years\"
\n        }
\n}
<\/code><\/pre>\n\n\n\n
Instead of just using a value and hoping a computer can guess what we mean, we’ve gone further and used another JSON object to represent this person’s age. We can now say his age is 32 years. Probably the most common schema mistake I see on e-commerce sites is defining prices incorrectly, because money, like time, can be measured in different units. We’ll get to a practical example in just a moment.<\/p>\n\n\n\n
Before we move on, though, let’s create another person to sit alongside the one we already have:<\/p>\n\n\n\n
{
\n \"@type\" : \"Person\",
\n \"first name\" : \"Mark\",
\n \"last name\" : \"Zuckerberg\",
\n \"age\" : {
\n          \"value\" : 32,
\n          \"units\" : \"years\"
\n         },
\n \"children\" : []
\n}
\n{
\n \"@type\" : \"Person\",
\n \"first name\" : \"Maxima\",
\n \"last name\" : \"Zuckerberg\",
\n \"age\" : {
\n          \"value\" : 0,
\n          \"units\" : \"years\"
\n         }
\n}

<\/code><\/pre>\n\n\n\n
This is perfectly valid JSON. But what we don’t have is any sense of how the two people relate to one another. As far as a computer is concerned, they are independent. We could think of many ways to show the relationship, but I’ve created a ‘children’ property for our first person and put an empty list as its value. In JSON we can use square brackets to store a list. We can put nearly anything in a list, including JSON objects. The list can be empty — as it is right now — or it could have only one item in it, or it could have very many.<\/p>\n\n\n\n
{
\n \"@type\" : \"Person\",
\n \"first name\" : \"Mark\",
\n \"last name\" : \"Zuckerberg\",
\n \"age\" : {
\n           \"value\" : 32,
\n           \"units\" : \"years\"
\n         },
\n \"children\" : [{
\n \"@type\" : \"Person\",
\n \"first name\" : \"Maxima\",
\n \"last name\" : \"Zuckerberg\",
\n \"age\" : {
\n           \"value\" : 0,
\n           \"units\" : \"years\"
\n         }
\n }]
\n}<\/code><\/pre>\n\n\n\n
Now our list of children has one person object  in it. We could add more the usual way: by putting a comma between each of them.<\/p>\n\n\n\n
Making the jump from JSON to JSON-LD<\/h2>\n\n\n\n
LD stands for Linked Data. For SEO we care about using JSON objects to represent data linked to the page. The kinds of objects we want to create are all those laid out in Schema<\/a>. Think of Schema as a vocabulary that major search engines have agreed upon. And JSON-LD is the grammar \u2014 the way we structure the object and add it to the page. When we use Schema, search engines know how to interpret our JSON objects.<\/p>\n\n\n\n
Schema.org<\/h3>\n\n\n\n
In the example above, I just made up the rules as I went along. First, the people we created had names; then they had separate properties for first and last names. Then we changed the age property from a single number to a JSON object with a value and a unit. Then we added an optional list of children. I was defining my own schema as I went along. Of course, left to their own devices, everybody would do this in a slightly different way. Enter Schema.org, which is more or less a rulebook on how we should structure certain objects on our own websites. By sticking with the Schema.org rulebook, we can be consistent with all the other sites out there; Google will then be able to understand what we mean.<\/p>\n\n\n\n
Building a Product<\/h3>\n\n\n\n
One of the most common uses for JSON-LD is defining a product. It\u2019s also where people tend to make the most mistakes. Getting price data right is especially important if you\u2019re looking for products to show up in product feeds.<\/p>\n\n\n\n
We’ll now make some JSON-LD to represent a product. Start with empty braces:<\/p>\n\n\n\n
<\/p>\n\n\n\n
{\n\n}
<\/code><\/pre>\n\n\n\n
Add a property called @context. Its value will be the schema.org website. This property says: “this object follows the rules laid out at http:\/\/schema.org”:<\/p>\n\n\n\n
{\n\n @context: \"http:\/\/schema.org\"\n\n}
<\/code><\/pre>\n\n\n\n
Schema.org defines various types. A type tells us how to structure an object: which properties we should use and what values we\u2019re allowed to put in them. There are loads of examples on schema.org, representing all kinds of things, like a Person<\/a>, an Event<\/a>, and even a Taxi Reservation<\/a>.<\/p>\n\n\n\n
The type we\u2019re going to use is called “Product<\/a>“. Add that as the value of our @type property:<\/p>\n\n\n\n
{\n\n @context : \"http:\/\/schema.org\",\n\n @type : \"Product\"\n\n}<\/code><\/pre>\n\n\n\n
Pricing<\/h3>\n\n\n\n
This is where it often seems to go wrong. Once you\u2019ve created a product, it\u2019s natural to want to add a price to it straightaway \u2014 after all, the price is one of the most important facts about a product. But schema.org doesn\u2019t allow you to add prices directly to products. There\u2019s an important middle step: creating offers<\/em>.<\/p>\n\n\n\n
To see why this is necessary, take a look at the chart below (taken from Amazon price tracker camelcamelcamel<\/a>). It shows the price of a notebook on Amazon over time. But at any given point, the notebook \u2014 the same product<\/em> \u2014 is on offer from more than one seller. Amazon sells it directly at one price, and third-party sellers at a range of other prices.<\/p>\n\n\n\n
\"amazon
A graph showing the price change of a single item on Amazon.<\/sub><\/em><\/figcaption><\/figure>\n\n\n\n
<\/p>\n\n\n\n
So we have to add offers<\/em> to our product. Each offer can have one or more prices<\/em>. Prices have a currency<\/em> and a value<\/em>. It\u2019s easiest to begin with the price and work your way up. Here\u2019s how we\u2019d represent the “Sold by Amazon” price:<\/p>\n\n\n\n
{\n\n \"@type\" : \"PriceSpecification\",\n\n \"currency\"  : \"GBP\",\n\n \"value\" : 9.88\n\n}<\/code><\/pre>\n\n\n\n
That\u2019s simple enough. We then need to wrap it up in a slightly larger object that will represent the offer:<\/p>\n\n\n\n
{\n\n \"@type\" : \"Offer\",\n\n \"description\" : \"Sold By Amazon\",\n\n \"price Specification\" :\n\n {\n\n       \"@type\" : \"PriceSpecification\",\n\n       \"currency\" : \"GBP\",\n\n       \"value\" : 9.88\n\n   }\n\n}<\/code><\/pre>\n\n\n\n
Here we put the price into a property called PriceSpecification<\/a> and put that into an Offer<\/a>, which is the entire object you see above. The offer has a description, where we identify it as “Sold by Amazon”. Having packaged all that up, we need to put it in a property called “Offers”, on the product:<\/p>\n\n\n\n
\"\"\/<\/figure>\n\n\n\n
Your JSON-LD should now look like this:<\/p>\n\n\n\n
{\n\n   \"@context\" : \"http:\/\/schema.org\",\n\n   \"@type\": \"Product\",\n\n   \"name\": \"Moleskine Notebook\",\n\n   \"offers\" : [\n\n      {\n\n       \"@type\" : \"Offer\",\n\n       \"description\": \"Sold By Amazon\",\n\n       \"priceSpecification\" :\n\n            {\n\n             \"@type\" : \"PriceSpecification\",\n\n             \"currency\": \"GBP\",\n\n             \"value\": 9.88\n\n            }\n\n       }]\n
}<\/code><\/pre>\n\n\n\n
That might seem like a lot of hassle just to add a price, but the advantage of it is that it\u2019s very flexible. If your company starts selling different variants of the same product at different price points, adding refurbished or open-box products, or even starts allowing marketplace sellers as Amazon does, it\u2019ll be easy to add new price information. Just make a new Offer<\/strong> object and add it to the list. In our example \u2014 the Moleskine Notebook on Amazon \u2014 we can easily add a marketplace offer at \u00a35.07:<\/p>\n\n\n\n
{\n\n \"@context\" : \"http:\/\/schema.org\",\n\n \"@type\": \"Product\",\n\n \"name\": \"Moleskine Notebook\",\n\n \"offers\" : [\n\n    {\n\n     \"@type\" : \"Offer\",\n\n     \"description\": \"Sold By Amazon\",\n\n     \"priceSpecification\" :\n\n          {\n\n            \"@type\" : \"PriceSpecification\",\n\n            \"currency\": \"GBP\",\n\n            \"value\": 9.88\n\n          }\n\n     },\n\n {\n\n     \"@type\" : \"Offer\",\n\n     \"description\": \"3rd Party Marketplace Seller\",\n\n     \"priceSpecification\" :\n\n          {\n\n            \"@type\" : \"PriceSpecification\",\n\n            \"currency\": \"GBP\",\n\n            \"value\": 5.07\n\n          }\n\n     }\n\n]\n\n}<\/code><\/pre>\n\n\n\n
Multiple Objects<\/h3>\n\n\n\n
Another common mistake is more subtle, because there are no mistakes in the syntax, so it won\u2019t trigger any errors or warnings in the Structured Data Testing Tool. Let\u2019s say we have two videos on a page, and we\u2019ve marked them both up with JSON-LD like this:<\/p>\n\n\n\n
{\n
 \"@context\": \"http:\/\/schema.org\/\",\n\n \"@id\": \"https:\/\/mydomain.com\/boring-5-second-video\",\n\n \"@type\": \"VideoObject\",\n\n \"duration\": \"PT5S\",\n\n \"name\": \"Boring video\",\n\n \"thumbnailUrl\": \"https:\/\/mydomain.com\/boring-video-thumbnail.jpg\",\n\n \"description\": \"A short and boring video\",\n\n \"uploadDate\": \"20160727\"\n\n}\n\n{\n\n \"@context\": \"http:\/\/schema.org\/\",\n\n \"@id\": \"https:\/\/mydomain.com\/interesting-30-minute-video\",\n\n \"@type\": \"VideoObject\",\n\n \"duration\": \"PT30M\",\n\n \"name\": \"Interesting video\",\n\n \"thumbnailUrl\": \"https:\/\/mydomain.com\/long-video-thumbnail.jpg\",\n\n \"description\": \"An interesting video with a cool thumbnail image\",\n\n \"uploadDate\": \"20160727\"\n\n}
<\/code><\/pre>\n\n\n\n
This is more common than you might think, especially when we\u2019re relying on some kind of automation to generate the JSON-LD (and we usually are). Put the above snippet into the Structured Data Testing Tool <\/a>and you\u2019ll find it just silently ignores the second video altogether. It\u2019s a bit like the “Person” object we invented earlier \u2014 a computer just doesn\u2019t have any way of understanding the relationships unless you tell it what they are. Given a bunch of objects that look the same, Google doesn\u2019t know which one is the most important. So they just take the first one. In this example, that would mean the wrong thumbnail showing up in video SERPs.<\/p>\n\n\n\n
Next steps<\/h2>\n\n\n\n
There\u2019s no substitute for actually understanding the structure of your JSON-LD. Once you\u2019ve grasped these basic concepts, you can go a lot further than we have here. Thinking back to the Moleskine Notebook, for example, we could have added lots of relevant information:<\/p>\n\n\n\n