JSON-LD's Big Day at Google

by Aaron Bradley on January 16, 2015

in Search Engines, Semantic Web, SEO

JSON-LD's Big Day at Google

Yesterday Google made three announcements which were not only relevant to practitioners of semantic search engine optimization ("semantic SEO"), but which also explictly expanded the role JSON-LD plays in the Google search universe.

As the name suggests, JSON-LD is JSON-based serialization for linked data – literally JavaScript Object Notation (JSON) for Linked Data (-LD). That is, a standards-based method of creating machine-readable data across websites.

You'll find some links to further resources about JSON-LD at the end of this article, but for those familiar with marking up HTML documents using microdata, RDFa or microformats, the salient practical point from a development standpoint is that JSON-LD does not need to be present in the <body> of a page. Instead it can be embedded in a <script> in the <head> of a page (or anywhere else in the page, for that matter).

For example, in microdata the name property of the schema.org type Article can be expressed, inline, like this:

<!DOCTYPE html>
<html lang="en">
    <title>JSON-LD's Big Day at Google</title>
    <div itemscope itemtype="http://schema.org/Article">
    <h1 itemprop="name">JSON-LD's Big Day at Google</h1>

Using JSON-LD this same data can declared using a <script> in the <head>:

<!DOCTYPE html>
<html lang="en">
    <title>JSON-LD's Big Day at Google</title>
    <script type="application/ld+json">
      "@context": "http://schema.org/",
      "@type": "Article",
      "name": "JSON-LD's Big Day at Google"
    <h1>JSON-LD's Big Day at Google</h1>

While the schema.org team officially recommended JSON-LD as a format for use with schema.org in June 2013, Google has only slowly been embracing its use as a method of providing structured data for websites (for other applications – especially those that employ schema.org actions, like email markup – Google, Bing and Yandex have all being employing JSON-LD).

Google's restrictions on the use of JSON-LD to this point make sense in the context of their guidelines for the use of structured data on websites, which have more-or-less required that data being marked up on webpages also be visible to humans viewing the page, and JSON-LD is not inline markup.

While those guidelines remain broadly in place, yesterday's announcements both expand the situations in which Google sanctions the use of JSON-LD, and very explicitly set the stage for a much more JSON-LD-friendly Google moving forward.

JSON-LD for Events in Google's Knowledge Graph

On a post on the Google Webmaster Central Blog, Justin Boyan announced an expansion of the previously-announced ways by which events could be marked up so that they display in the Knowledge Graph.

A link to a ticketing site for an event can now be declared, even if the target URL is not on the website on which the markup is found. "Delegated event listings" have been introduced, by which an event can be declared on one site's home page that points to another. The schema.org types eligible for Knowledge Graph events cards have been expanded from MusicEvent to include ComedyEvent. And, finally, event venues can now add markup which will support the display of a card that shows all upcoming events at that venue.

What's common to all these event enhancements, as evidenced by the revised Google Developers documentation for events, is that JSON-LD can be used when any sort of event declaration is required.

While the documentation gives a nod to other syntaxes, saying that "you can mark up your content in microdata or RDFa syntax if you prefer" (emphasis mine), but pride of place is given to JSON-LD, in which all the examples are presented, as is this brief example in the announcement for delegated event listings:

<script type="application/ld+json">
{"@context" : "http://schema.org", 
 "@type" : "MusicGroup", 
 "name" : "Your Band or Performer Name", 
 "url" : "http://your-official-website.com", 
 "event" : "http://other-event-site.com/your-event-listing-page/"

Specifying Social Profiles to Google

Google's Zineb Ait Bahajji announced on Google+ that it is now possible to specify the official URL of social media profiles for people or individuals, so that these may be displayed in the search results; the post points to the full documentation on social profile links on Google Developers.

And – you guessed it – these social media declarations may be made using JSON-LD, and as long as the syntactically-correct markup is published on a page of an official website accessible to Googlebot you're good to go: the profiles in question need not appear in the visible content of a page.

Here, for example, is the markup I've just added to my "about Aaron" page on this site:

<script type="application/ld+json">
{ "@context" : "http://schema.org",
  "@type" : "Person",
  "name" : "Aaron Bradley",
  "url" : "http://www.seoskeptic.com/",
  "sameAs" : [ "https://www.facebook.com/aaranged",

A New-and-Improved Structured Data Testing Tool Now Supports JSON-LD

Another Webmaster Central post announced, among other things, a long-awaited update to Google's Structured Data Testing Tool.

At this point you'll be utterly unsurprised to learn that one of the improvements to the Tool is support for JSON-LD, lacking in in the original incarnation of the Structured Data Testing Tool (née the "Rich Snippets Testing Tool").

Google Structured Data Testing Tool output for JSON-LD

Google Structured Data Testing Tool output for JSON-LD. Click to enlarge.

As per the example above, the new Testing Tool provides not only syntactical support for JSON-LD, but also Google-specific vocabulary support. That is, it will alert you not only if you've made a syntax error (an error in how you've coded your JSON-LD), but a usage error in the eyes of Google (such as the alert about the omission of the affiliation property in the Person code displayed above).

Incidentally, we added a bookmarklet to the structured data tools section of this site yesterday, providing one-click access to structured data information about the page you're currently viewing (this was used to generate the example above).

A Google Commitment to Support JSON-LD Moving Forward

In older documentation about rich snippets, Google was fairly prescriptive about marking up non-visible content with structured data declarations.

In general, Google won't display any content in rich snippets that is not visible to human user [sic]. […] Google will ignore content that isn't visible to human users, so you should mark up the text that visitors will see on your web pages.

In a new page titled "Structured Data Policies" on Google Developers, this hard line is considerably softened (and, incidentally, Google's preference for schema.org considerably hardened). The new policies officially endorse JSON-LD as a markup format, and now demand that marked-up data be accurately reflective of information on the marked-up page, rather than explicitly visible there.

[Structured data] may be embedded in your webpage using any of three supported formats: JSON-LD, RDFa, and microdata. […] High-quality structured data must not create a misleading or deceptive experience for search users. It should be an accurate reflection of the topic and content already found on the page, such as text, images, and videos.

The guidelines go on to talk of "algorithmic and manual quality checks to ensure that structured data meets relevancy standards," which suggests that Google has gotten better at evaluating the relevancy of structured data to on-page spiderable content, rather than needing to rely on inline markup to verify that relevance.

Does this mean that webmasters wanting to use JSON-LD can now derive the same benefit from JSON-LD-encoded data as they would receive for that same data expressed using microdata or RDFa? As the new Google Developers page on schema.org makes clear, not quite:

So far, JSON-LD is supported for all Knowledge Graph features, sitelink search boxes, and Event Rich Snippets; Google recommends the use of JSON-LD for those features. For the remaining Rich Snippets types and breadcrumbs, Google recommends the use of microdata or RDFa.

This passage is prefaced by the sentence "Google is in the process of adding JSON-LD support to more markup-powered features." The emphasis is mine, because this quote was pulled from the schema.org guidelines page as it appeared on 16 January 2015; one day prior that sentence said support would be added "to all markup-powered features."

Nonetheless, the announcements Google made yesterday provide considerable hope to those of us that appreciate the ease-of-use, superior machine readability and extensibility of JSON-LD.

JSON-LD Resources

If you have time (as in 13 minutes and 15 seconds) to check out only one resource about JSON-LD, make it this exceptional video introduction by Manu Sporny, both an author and editor of the W3C JSON-LD specification.

Finally, here are some other resources and reference pages on JSON-LD.

UPDATE (17 February 2015). Manu has added two further JSON-LD videos to YouTube.

  • JSON-LD: Core Markup
    "An overview of some of the core markup features of JSON-LD including types, aliasing, nesting, and internationalization support."
  • JSON-LD: Compaction and Expansion
    "An overview of JSON-LD's compaction and expansion features and how you can use them to merge data from multiple sources."

{ 31 comments… read them below or add one }

1 Lloyd Silver January 16, 2015 at 9:00 pm

Thanks for the blog post. This is great news and should really make things easier going forward to mark up pages.

I tried to find on Google what specifically can be marked up with JSON-LD as it relates to the knowledge graph but can’t find anything. I know we can mark up (now) social profiles, events, telephone numbers, logos. Is there anything else?


2 Aaron Bradley January 19, 2015 at 10:03 am

Thanks Lloyd. Yes, I think you have the list of entities for which Google currently respects about right. Regarding not being able to find anything about JSON-LD as it relates to the Knowledge Graph, Google – as per their documentation on the subject – actually considers logos, corporate contacts and social profile links to be Knowledge Graph features.


3 Ankit Rathi January 21, 2015 at 8:40 pm

Thank You Aaron Bradley for the beautiful post about mark up and schema.

I have a question, I have used “Rating schema.org” on my website in side bar for app page, but it’s showing only on inner pages, it’s not showing on home page. I don’t know what is the problem, Can you help me to fix this.

Thank You.


4 Aaron Bradley January 22, 2015 at 10:05 am

Thanks for your comment Ankit. I’d need to have further information about your site and what you’re trying to accomplish in order to be able to answer your question.

But please don’t provide further details here: if you ask this question either at the relevant Google Product forum or at the Semantic Search Marketing Community on Google+ you’ll have others besides me that are able to weigh in on your question.


5 margaret ornsby February 10, 2015 at 9:09 pm

I don’t come from a web developer background, so this post has really helped the penny drop. Thank you for such an informative and helpful post.

If I’ve understood correctly, JSON-LD context gives us the ability give search engines all the info we want about an entity or page wants without having necessarily to clog up a page with data in a layout that may not suit our design (as is the case with schema) – so long as the info is congruent with what’s in html on the page. Yes?

Am I correct then in saying if it’s an “itemtype” in schema, it’s an @type in JSON-LD, and if it’s an “itemprop” it’s simply the name of the prop?

Do you know if other search engines such as Bing are on board with JSON-LD?

And thank you too for the answer you gave Lloyd – I hadn’t seen that document before either and found it useful as well.


6 Aaron Bradley February 17, 2015 at 3:11 pm

Thanks for your comment Margaret.

“If I’ve understood correctly, JSON-LD context gives us the ability give search engines all the info we want about an entity … so long as the info is congruent with what’s in html on the page. Yes?”

Exactly so!

“Am I correct then in saying if it’s an “itemtype” in schema, it’s an @type in JSON-LD, and if it’s an “itemprop” it’s simply the name of the prop?”

Yes, the “itemtype” attribute for microdata is equivalent to @type (in conjunction with @context) in JSON-LD. (Note that’s “in microdata” rather than “in schema” though. Microdata is a syntax, whereas schema[.org] is a vocabulary, and so the microdata element itemtype can be used to declare a type from any vocabulary. For example, the declaration itemtype="http://data-vocabulary.org/Person/" is valid microdata.)

In microdata, yes, the “itemprop” is the name (key) of the property, and the contained element is the value of that property. In JSON-LD, since JSON uses key-value pairs, there’s no attribute to indicate the property name, but it’s rather the first part of that key-value pair.

For example, let’s say we want to say “the name of this organization is ‘Acme Industries’.” The type is schema.org/Organization. To declare the name in microdata we would markup up HTML something like this:
<span itemprop="name">Acme Industries</span>

In JSON-LD the property “name” is the key and “Acme Industries” is the value:
"name": "Acme Industries"

“Do you know if other search engines such as Bing are on board with JSON-LD?”

As far as I know not for the sort of declarations that Google is now supporting, but they’re on board with JSON-LD in different ways. The Bing app indexing mechanism, for example, permits use of JSON-LD, as does structured data for Yandex Islands (the latter under review at time of writing).


7 margaret ornsby February 17, 2015 at 4:29 pm

Thank you!


8 Rohit Kaushik February 16, 2015 at 4:45 am

Hello Aaron,

Now your Article Is relay Informative.

I have 1 Issue in my website one is Google is Not cache my Updated Meta title, description could you please check and guide me what is the Issue.

Website Is http://www.emarketz.net/


9 Aaron Bradley February 17, 2015 at 3:19 pm

Thanks for your comment Rohit. I’m unsure of what you’re asking, though. As your question doesn’t appear to be related to structured data, I suggest you try asking for help at the Technical SEO Community on Google+.


10 Bogi March 6, 2015 at 10:13 am

Thanks very much for the info. I must admit that I’ve read the post twice, but as a non-programmer, I’m still struggling to make sense of this. Are there any utilities which can help with implementing this?


11 Darren Shaw March 23, 2015 at 9:40 am

Hi Aaron,

We would love to improve the local business schema markup on our clients’ sites with all possible options in the markup, but Google’s requirement to actually display that information on the page messes with our design. JSON-LD looks to be a perfect solution to this problem.

Is it acceptable to Google to use JSON-LD for this?



12 Aaron Bradley March 23, 2015 at 2:56 pm

Thanks for your comment Darren.

What you ask is very much the question of the moment, as JSON-LD is a exemplary method of providing information about local businesses (or even not-so-local businesses) that, being separated from the presentation layer, provides more options in terms of both what information is provided and the form that information takes.

Right now the situation is somewhat ambiguous. On one hand, Google explicitly permits businesses to provide information about their logo, company phone numbers and social media profile links in JSON-LD, and without those data values being present on the page where the JSON-LD is embedded.

On the other hand, Google has recently changed their new structured data documentation to ensure it carries the same interdiction on marking up “non-visible content” that appeared on their original rich snippet guidelines.

Would a site that provides local business information in JSON-LD that doesn’t exist in the visible content be penalized for doing so? I find that unlikely, but of course it’s possible. Will Google respect that information (for example, if a local businesses’ location in included only in JSON-LD structured data, will it be used when Google tries to return results for the location in question)? Even harder to say, but probably not (ignoring that data representing the only “penalty” attached to its use).

Will Google admit this sort of data to be supplied with JSON-LD in the future? While prognostication is a dangerous game, for what it’s worth I think they will continue to open up the types for which JSON-LD can be used, and I think the LocalBusiness schema is one of the likeliest candidates for this expansion, especially if Google can figure out how to cross-reference JSON-LD-provided LocalBusiness (or, more broadly, Organization) data with some other source of those data as a trust measure.


13 Darren Shaw March 23, 2015 at 3:20 pm

Thanks for the reply Aaron.

It’s a shame. There is so much rich data that we can provide via schema, but it can really mess with the page layout and design if we choose to provide it all.

I guess for now, we’ll just do what we can with schema markup on the page, and stick the logo, phone numbers, and social links in JSON-LD. I assume it’s ok to have them both on the page?


14 Aaron Bradley March 23, 2015 at 4:04 pm

A shame indeed! And yes, the consensus seems to be that it’s alright to use JSON-LD alongside on-page markup (i.e. microdata or RDFa) as long as you’re not providing the same information in two different formats.

I use the less-than-precise word “information” somewhat deliberately above in order for you or any reader to judge how strict they want to be about what’s considered “the same information.” If you were, say, to provide logo information about Acme Inc. via JSON-LD in the <head>, but address information via microdata in the <body>, you’re good-to-go insofar as those are different properties(logo and address, respectively), but they are different properties of the same entity (Acme Inc.).

I bring this up because in a comment on the subject on JSON-LD, David Deering noted:

I’ve asked about the same thing myself and according to John Mueller, it’s ok to combine microdata and JSON-LD on the same page, as long as the same entities are not marked up with both syntaxes.

Technically speaking in the case you bring you bring up we’re talking about marking up different types of information for the same entity. So there’s no way in which one piece of data can either contradict or duplicate the other, but Google might take the view that it’s going to pay attention to only one entity declaration when two or more for the same entity are present – or perhaps ignore both. Caveat emptor.


15 Darren Shaw March 23, 2015 at 4:19 pm

Haha. So much guesswork. Thanks Aaron!


16 Jesse Kohl April 24, 2015 at 11:54 am

Really enjoyed this post. I think it was also telling that the SearchAction schema launched not too long ago for the sitelinks searchbox was only available as JSON (and schema.org) seems to confirm that if I’m not wrong.


17 Sandeep August 4, 2015 at 4:24 am

i use Local and other JSON-LD tags in my website before 2 month.. i follow all process maintain above but but this in not working till now…..how long time take for working..


18 satish October 30, 2015 at 12:15 am

Do we have any tool ,If we want to test JSON-LD with in our corp network before going live.

https://developers.google.com/structured-data/testing-tool/ , This tool will only check JSON-LD format is correct or not .

Once we added JSON-LD in our home page , I want to test it on QA/Dev envronments.
google.com may not be able to access or Dev/QA environments.

The only way to catch any issues is after going live. This is something scary .
We need to test before it is going live , Need help any tool available to test on QA/Dev environments.

Use case – Search any term in google.com , JSON-LD need to be executed and search results should display in google.com search results.


19 Aaron Bradley October 30, 2015 at 10:05 am

Thanks for your comment. Both the Structured Data Testing Tool and the Structured Data Linter accept direct input so if you take the source of your code and paste it into one of those tools you should be able to successfully test that code.

If this won’t work because you want to know how Google processes dynamically served elements (like JSON-LD injected asynchronously), then as far as I know your only recourse is to replicate your Dev/QA page(s) to a publicly accessible test environment (employing <meta name="robots" content="noindex"> in order to ensure your test pages don’t end up getting indexed).


20 Angie February 10, 2016 at 3:24 pm

Hi Aaron,
Quick question. In your article you mentioned adding JSON script in the header, but I was wondering the weigh off of adding it to the footer to comply with page speed best practices. Could you see any hindrance in adding it there?


21 Aaron Bradley February 10, 2016 at 4:31 pm

Hi Angie. JSON-LD can just as easily be added to the <body> as to the <head>, and to the same effect.

Google explicitly says this on one of their pages on adding event markup:

You can embed data in a web page using schema.org field names and the new JSON-LD data format. JSON-LD is easy to produce with many widely available JSON encoders. The data, enclosed within the <script type=”application/ld+json”> … </script> tags as shown in the examples below, may be placed in either the <HEAD> or <BODY> region of the page that displays that event. Either way, it won’t affect how your document appears in users’ web browsers.

So no hindrance at all to add it to the footer.


22 Jon March 2, 2016 at 9:09 pm

Good post. I have been using JSON-LD fro some time now for all types of SMB local and national businesses and have seen good results. We have only embedded the code in the header of our header.php or in the body of the doc. My questions is, have you used JSON-LD as an external file linked to header like a script or a style sheet? I prefer not to use embedded or inline code on website if possible, keeps everything nice clean. Thanks for your hep!


23 Aaron Bradley March 22, 2016 at 4:37 pm

Thanks for your comment Jon.

There’s no direct analogy between JSON-LD and an external style sheet, as JSON-LD does need to be provided to the search engine bot when it crawls your page, and can’t be provided as a linked resource.

However, you can load the JSON-LD dynamically, which provides a method by which you’re able to avoid actual inline embedding of the code. Simo Ahava wrote an excellent post describing how to do this using Google Tag Manager.


24 forsberg May 2, 2016 at 8:36 am

Well, it’s quite obvious to me after reading the article _why_ google wants us (therefore, recommends) to use json-ld, since it helps them to build their central data base of knowledge, called knowledge graph. I checked by the way recently the knowledge graph, and well, at the moment it’s faaar from being really useful 😉

Anyway, I (and others, as well) have no business in helping google with anything, especially when it comes to centralizing anything and taking the traffic from your sites to their services or apps. So I recommend therefore to NOT use json-ld, as the results are the same, and will be – as long as majority of people will not use things like these. Because then, google will have no choice but to follow people how they build their websites.


25 Aaron Bradley June 6, 2016 at 4:38 pm

Thanks for your comment.

And you’re absolutely right: Google (and the other search engines) are encouraging the use of structured data markup so they can build entity graphs like the Knowledge Graph, which in turn facilitates the ability to provide rich information about those entities in the search results and expose connections about those entities.

The Knowledge Graph not useful? There I certainly disagree, but if you think it’s a great user experience to make a mobile searcher go to a website to have their question “what’s the height of the Eiffel Tower?” then I guess you don’t find the Knowledge Graph useful.

And you’re equally entitled to your opinion that Google is bent on “taking the traffic from your sites to their services or apps” and that search engines should be confined to sending people to websites, but it is one to which I do not subscribe.


26 Aaron Humphreys June 12, 2016 at 5:56 pm

Do you happen to know if Google crosschecks the JSON-LD data to the page content?

For instance, on each page in the footer can I include additional information about a business in the JSON-LD, but not have all of that information actually present in the markup?


27 Aaron Bradley June 13, 2016 at 12:19 pm

Hi Aaron – thanks for question.

The short answer is “yes, probably.” In its recently-revised quality guidelines on structured data markup, Google has this to say:

Markup should not be used to hide content not visible to users in any form, since it might create a misleading or deceptive search experience. For example, if the JSON-LD markup describes a performer, the HTML body should describe that same performer.

We perform algorithmic and manual quality checks to ensure that structured data meets relevancy standards. In cases where we see structured data that does not comply with these standards, we reserve the right to disable rich snippets for a site in order to maintain a high-quality search experience for our users.

This doesn’t mean that all content needs to be visible on the page. For business information this might include information that isn’t feasible to provide in human-readable text, such as geographic coordinates. And it might be acceptable to provide useful information about a business that isn’t on the page where the business entity is described – say, the home page – such as business hours,


28 karthic Raja September 1, 2016 at 10:59 pm


I have implemented schema.org first time, I have used JSON-LD in my page and microdata used in another page,but I have checked in google, it didn’t show , please let me know as simply which is better JSON-LD or microdata for use ?


29 Aaron Bradley September 20, 2016 at 4:42 pm

Both will work equally well, but I wouldn’t recommend mixing and matching the two if you can avoid it. From a functional perspective both JSON-LD and microdata should provide the same ultimate result for Google so on that front I’d be hard-pressed to say one was “better”, but for what its worth I do find JSON-LD far easier to work with.


30 Andrew.S September 14, 2016 at 7:46 am

After research, I have found NO evidence of Bing actually using JSON-LD.
Microdata and RDFa markups for schema, yes, but that is it.

Not even their documention mentions JSON-LD:

Do you have evidense to backup your sentence:
“(for other applications – especially those that employ schema.org actions, like email markup – Google, Bing and Yandex have all being employing JSON-LD).”


31 Aaron Bradley September 20, 2016 at 4:37 pm

Thanks for your comments and question Andrew.

JSON-LD has, indeed, very limited exposure in the Bing and Microsoft universe, although Cortona uses it for flight information, and its also supported by Bing for app actions. Bing also claims that their newest search APIs “follow the latest structured data standards (Schema.org, JSON-LD)”, but I’ve yet to see any evidence of this in either the API documentation or the output (as least as far as I can recall).

On the Yandex side, their structured data validator API explicitly supports JSON-LD. And their Interactive Answers feature will, apparently, support JSON-LD for both form and button descriptors. They were also going to support it for Islands, but it doesn’t look as though anything has yet come of that plan.

In summary, Google’s going all-in when it comes to JSON-LD (not only as a means by which webmasters can provide structured data to Google but in other products as well, like the output for Knowledge Graph Search API queries), but the other search engines to date? Not so much.


Leave a Comment

Previous post:

Next post: