Skip to content
master
Switch branches/tags
Code

Structured Data - JSON-LD

Join the chat at https://gitter.im/Jays-Structured-Data/Lobby

Structured Data is hard when you're starting out. Conflicting info. Old outdated information. Poor documentation. I've spent a significant amout of time trying to master it. Now you can benefit from all my hard work and testing. Everything here works properly or it wouldn't be here. Many of these will provide the fancy Google Search Enhancements you desire and ensure your content types are marked up properly.

Structured Data News

Dec 15th 2020 (View)

Google provides an update on their Structured Data Testing Tool's future. (Saved!) Read more!
May 25th 2020 (View)

Tony McCreath has created a very cool tool to visualize structured data at any given URL. Simply enter a URL by clicking the "Fetch from URL" button and behold. Try it out!
Apr 6th 2020 (View)

Google has released documentation to guide the implementation of structured data via JavaScript, whether by using Google Tag Manager with JSON-LD or custom JS. Read more.
Sept 13th 2019 (View)

Google's John Mueller clarified on the September 11 edition of #AskGoogleWebmasters that JSON structured data can be inserted in the head as well as the body of your pages. Read more.
Apr 16th 2019 (View)

Yoast adds drastically enhanced Structured Data support to Wordpress with their latest version of their plugin. Read more.
Feb 25th 2019 (View)

Another uproar hits the web after SEJ posts that Google has declared Structured Data shouldn't be inserted via Google Tag Manager. While it's tough to argue against such a reputable source, I'd like to point out that one important quote was omitted in the article from the discussion. "While you can use GTM to add SD to pages, and some people do, it's more complex and brittle." The article also pointed to the fact that the Structured Data testing tool can't see SD that's been inserted onto a page by GTM as proof that it's not meant to be done. But this is a fairly well known issue that is worked around by inserting it via Javascript (See below). I've asked @JohnMu to elaborate or affirm but he never seems to address these challenging questions directly. Or he's cryptic about it. John is always cited as the guy who is saying GTM insertion shouldn't be done, but he's also a guy who knows that it can be done successfully.
Jul 13th 2018 (View)

Google's Structured Data Testing Tool has stopped seeing Structured Data thats been inserted via Google Tag Manager. This caused a minor little uproar on Twitter when Google's John Mueller tweeted a response of "I wouldn't rely on a tool like GTM to add Structured Data". One blog immediately twisted this into wrote that Google itself has now declared that GTM should not be used for inserting Structured Data. Which is ridiculous. A new way to insert Structured Data via Google Tag Manager has been found by Simo Ahava and this method allows for the testing tool to detect the Structured Data 100% fine. This tool by Saijo George can help you generate the Google Tag Manager friendly version of your JSON-LD code.


Primer

Total newb to all this? See this great beginner's guide on Moz

Installation

A.) Hand code it in (Learn more)

Ugh! This is not easily maintainable at scale.

Although the Structured Data CAN be placed in the head and work properly, Google's examples show it being placed in the body immediately after the opening body tag. Their CodeLab shows it in the head though.

Google's John Mueller clarified on the September 11 edition of #AskGoogleWebmasters that JSON structured data can be inserted in the head as well as the body of your pages. Read more


B.) Use Google Tag Manager (Learn more)

Use Google Tag Manager to insert the code with the "Custom HTML" tag. (See screenshot below.) Why Tag Manager? Because Tag Manager can dynamically change the Structured Data based on the content of the page! (eg: Blog posts) See this article and this older Moz article for more information on how to do that.

UPDATE: Google changed something. Now, in order to have the Structured Data Testing tool detect inserted Structured Data properly, it must be inserted programatically. Pasting your desired Structured Data within this snippet below will allow it to be detected properly by the testing tool.

<!-- GOOGLE TAG MANAGER VERSION -->
<!-- Credit: https://twitter.com/SimoAhava/status/1001397355403468802 -->
<!-- Source: https://github.com/JayHoltslander/Structured-Data-JSON-LD -->
<script>
(function() {
   var jsonData =

// PASTE THE JSON THAT YOU WANT TO USE, HERE.
// Only paste what's within the <script> block.
// Your pasted content should start with a { and end with a }

; var el = document.createElement('script');
el.type = 'application/ld+json';
el.innerHTML = JSON.stringify(jsonData);
document.head.appendChild(el);
})();
</script>

See also:

🔍 Screenshot


C.) Use a Wordpress plugin (Learn more)


Contents

AggregateRating.json

An average rating based on multiple ratings or reviews utilizing the AggregateRating schema. Be sure to read this article to see why using this example as written might not be the best idea. Hmm. 🤔 Also note that using a 3rd party's ratings (like say Google or Yelp) for a localBusiness seems to go against Google's guidelines. BUT, also see this note on using 3rd party reviews.



Article.json

If you’re a publisher website, the more specific schema types like NewsArticle or BlogPosting are recommended (choose one or the other, depending on your site/content). Leveraging these markups accordingly can help your content to appear in Google News and in-depth articles search suggestions. See: Enabling Rich Snippets for Articles. Note: To show up in Google's News Carousel not only will the page require Structured Data but it's also required to be a valid AMP page. If you are using the official AMP Plugin for Wordpress you will definitely want to use Tag Manager to insert your Structured Data as opposed to other methods since you will be able to dynamically generate Schema.org JSON-LD Tags from pages that contain the correct pattern for your posts. eg: ?amp=1 or /amp



BlogPosting

An even more specific version of Article for a blog post. See the BlogPosting schema for more info.



BreadcrumbList.json

The BreadcrumbList schema allows you to mark up the breadcrumbs on your site to generate breadcrumb rich snippets for your pages in the SERPs. Learn more.



Course.json

The Course schema allows you to mark up courses on your site to generate rich snippets for your courses in the SERPs. Learn more.



Dataset.json

The Dataset schema is for a body of structured information describing some topic(s) of interest. It should use the sameAs property to link to the canonical page. Learn more.



FAQPage.json

The FAQPage schema is different than Q&A and is (obviously) for a FAQ page. A Frequently Asked Question (FAQ) page contains a list of questions and answers pertaining to a particular topic. Properly marked up FAQ pages may be eligible to have a rich result on Search and Markup Action for the Google Assistant, which can help your site reach the right users. Learn more.



HowTo.json

The FAQPage schema is used to explicitly tell Google that your content is a how-to. A how-to walks users through a set of steps to successfully complete a task, and can feature video, images, and text. For example, “How to tie a tie” or “How to tile a kitchen backsplash”. If each step in your how-to must be read in sequence, it's a good sign that HowTo structured data could benefit your content. Learn more.



ImageObject.json

An example of the ImageObject schema. Demonstrates use of the exifData schema.



ItemList-1.json

The ItemList schema makes a page's items eligible for the Carousel Feature on mobile devices (Screenshot). This example is for a summary page which has a short description of each item in the list, and each item points to a separate details page that is focused entirely on one item. The details page is where the more detailed Structured Data on the item would be located. See: Docs https://developers.google.com/search/docs/guides/mark-up-listings#summary-page--multiple-full-details-pages



ItemList-2.json

The ItemList schema makes a page's items eligible for the Carousel Feature on mobile devices (Screenshot). This example is for a single, all-in-one-page list hosts all list information, including full text of each item: for example, a gallery of recipes for various kinds of muffins, all contained on one page. See: Docs https://developers.google.com/search/docs/guides/mark-up-listings#single-all-in-one-page-list



ItemList-3.json

The ItemList schema makes a page's items eligible for the Carousel Feature on mobile devices (Screenshot). This example shows usage with the CollectionPage schema.



ItemList-4.json

This example shows possible usage for an ecommerce category page with Product schema items listed within it. This is valid schema however Google has stated that the Product schema is for use on "a product page that describes a single product" A Google documentation writer had this to say when asked about this exact snippet/use-case.



ItemList-5.json

Another example of a list similiar to the example above but laid out differently.



JobPosting.json

Adding structured data makes your job postings eligible to appear in a special user experience in Google Search results leading to increased chances of discovery and conversion. Your postings are eligible to be displayed more prominently in the dedicated Job Search UI, featuring your logo, reviews, ratings, and job details. The new user experience enables job seekers to filter by various criteria like location or job title, meaning you’re more likely to attract applicants who are looking exactly for that job. Learn more.



LocalBusiness.json

An example of a LocalBusiness with multiple locations defined. Each location having it's own defined service areas.



LocalBusiness-2.json

An example of a LocalBusiness customized for a law firm. Demonstrates combined @types (LocalBusiness/Organization/LegalService) and Corporate Contact useage.



LocalBusiness-3.json

A detailed example of a complex LocalBusiness customized for a Notary. Demonstrates combined @types (LocalBusiness/Organization/Notary) and Corporate Contact useage.



LocalBusiness-4.json

An example of a LocalBusiness customized for an online store with no physical location. Demonstrates combined @types (LocalBusiness/Organization/Store)



Movie.json

The Movie schema in JSON-LD format. Mark up your movie lists with structured data so users can explore movies through Google Search. You can provide details about the movies, such as the title of the movie, director of the movie, and an image of the movie. The movie carousel is only available on mobile devices. Learn more



Person.json

My personal structured data snippet for "Person" in JSON-LD format.



Product.json

The Product schema in JSON-LD format. There are two types of pages where you would typically use this markup: a product page that describes a single product, or a shopping aggregator page that lists a single product, along with information about different sellers offering that product. Don't use this schema on a page that contains many products like a category page. Learn more



Question-w-Answers.json

An example of some markup that results in Rich Snippets for Questions as observed in the wild being used on Stack Exchange websites. SERP Screenshot This example includes additional Schema types for "Answer" and "QAPage" which do not seem to be required but complement each other.



Recipe.json

The Recipe schema can result in Rich Snippets for Recipes. Learn more.



Service.json

A collection of services that a LocalBusiness may provide with per/service ratings.



ServiceArea

How to define a service area for a local business.



SiteNavigationElement.json

The SiteNavigationElement schema can help increase search engines’ understanding of your site structure and navigation and can be used to influence organic sitelinks. (See also WPHeader on this page for an example of usage within a Navbar!)



SpeakableSpecification

For Voice search a SpeakableSpecification indicates via css selector(s) sections of a document that are highlighted as particularly speakable. See this article for more info.



WebSite.json

The WebSite schema markup helps generate the Sitelinks Search Box feature for brand SERPs and can help your site name to appear in search results. You must, of course, have an existing site search on your website to enable the Sitelinks Search Box element.
Includes:

WPHeader.json

("Webpage Header" not "Wordpress Header") Define structured Data for items within a site's header with the WPHeader schema. Includes SiteNavigationElements within! Also see an example of this in use within the snippet WebSite.json



VideoObject.json

A site with embedded or hosted video content can leverage the VideoObject schema. Google primarily displays video rich snippets for YouTube videos, but this will help video rich snippets to appear for your Web pages in Google Video Search. Google Resource Page: Enabling Rich Snippets for Videos



ViewAction

Indicates where something should be viewed. One of the most common implementations is in Google App indexing, where it enables a URL from a website indexed in search results, to be opened inside the corresponding App (if installed in the user's device).




Tips & Tricks

You can link snippets together and reuse them (DRY) by defining and referencing their @id (These are called "Node identifiers") Learn more about them here.

To-do

View


Testing

The code

The results

See also:

Tools

Articles

Discussions

Sources