JSON-LD for your website

How to
Add HowTo structured data to a how-to article

How to add HowTo structured data to your how-to article

You might know that structured data in the form of Schema.org can do wonders for your search results. It also forms the basis for an ever-increasing amount of new and exciting developments on the search engine front. Google has said many times that structured data is beneficial. You can even introduce structured data that Google doesn’t officially endorse yet onto your page. Today, we’re going to look at a new and exciting piece of structured data: the HowTo. This is a how-to about a how-to on HowTo: HowToCeption!

Want rich snippets for your site? Try our Structured data training »

Structured data training Info

What is structured data?

Structured data is a sort of translator for search engines – it adds context to code. By adding Schema.org code, search engines can instantly figure out what every piece of content means, semantically speaking. This gives search engines the power to do cool stuff with your content, like highlighted snippets in search results, the Knowledge Graph or the carousel. There’s structured data for books, articles, courses, events, jobs, local businesses, music, recipes, products, reviews et cetera. Structured data is getting more important by the day and we’ll see more types emerge in the coming years.

If you want to learn more about structured data and find out ow to implement it yourself so you can win those coveted rich results, you can enroll in our Structured data training!

What is HowTo structured data?

According to Schema.org, a HowTo is “an instruction that explains how to achieve a result by performing a sequence of steps.” You can use HowTo structured data to mark up articles that come in a how-to form, but that are not recipes. If there is an element of consumption, it should be a recipe.

HowTo Schema.org was introduced in April 2017, but there is no sign of it yet in search engines. But since Google is increasingly looking at structured data to do cool stuff with, it’s not hard to predict that HowTo will follow soon. Think off it this way, since your Google Home can now read your structured data powered recipes out loud, why shouldn’t it be able to read that how-to on how to fix a leaky faucet or change the busted lights in your kitchen cabinet? There is already talk of Google getting partners interested in a sponsored how-to video deal, as reported by CNBC, which might just be powered by HowTo Schema.org.

Experimental and no support — yet!

This tutorial is purely to let you see what this HowTo structured data is all about. There’s no need to rush out right away and start adding this to your site. But do keep an eye on this, though, because we think it will arrive sooner rather than later. We also don’t know yet how Google will support it and which properties and it will required to get it to function. So, don’t take this post as gospel. With that said, let’s get going!

HTML code

To start, we need a piece of HTML to test our HowTo on. This is going to be a very simple example of a basic page with some content. We are going to base our content on a Knowledge base article about connecting Yoast SEO to Google Search Console. We’re going to mark up every piece of the HTML with HowTo Schema.org in the form of JSON-LD, as this is the preferable format. The content is nothing special, just a couple of steps following instructions. Below you can find the HTML for this page, slightly truncated.

<div>
	<strong>How To Add Your Website To Google Search Console</strong>
	<div>Cost: Free</div>
	<div>Time needed: About 10 minutes</div>
	<div>Necessary items:</div>
	<div>Yoast SEO</div>
	<div>Google Search Console</div>
	<div>
	<div>Preparation</div>
	<div>
		<div>
		<img src="yoast_seo_search_console.jpg" />
		Install Yoast SEO and activate your Google Search Console.
		</div>
	</div>
	<div>
		<div>
		Tip: Did you know you can check and fix crawl errors directly from Yoast SEO?
		</div>
	</div>
	</div>
	<div>
	<div>Adding your site to Search Console</div>
	<div>
		<div>
		Go to Google Search Console (former Google Webmaster Tools), sign into your Google account and click the red button to add your website.
		</div>
	</div>
	<div>
		<div>
		<img src="yoast_seo_search_console_2.jpg" />
		Copy the code for the HTML tag under the Alternate Methods tab.
		</div>
		<div>
		Tip: Please make sure you enter your complete url.
		</div>
	</div>
	<div>
		<div>
		Copy the code for the HTML tag under the Alternate Methods tab.
		</div>
		<div>
		Log in to your WordPress website and cick on ‘SEO’ in your menu. After that, click on General.
		</div>
		<div>
		Click on the ‘Webmaster Tools’ tab and add the code under ‘Google Search Console’. Click ‘Save Changes’.
		</div>
		<div>
		Switch back to Google Search Console (formerly Google Webmaster Tools) and click ‘Verify’.
		</div>
	</div>
	</div>
	<div>
	<div>Finishing up</div>
	<div>
		<div>
		Congratulations! You’ve connected your website to Google Search Console (former Google Webmaster Tools)!
		</div>
	</div>
	<div>
		<div>
		Now that you’ve verified and connected your website, you can submit your sitemap!
		</div>
	</div>
	</div>
</div>

Adding Schema.org

In the example, we’re breaking up the how-to in three parts: preparation, step-by-step directions and finishing the project. All three steps can be wrapped in a HowToSection, with individual HowToSteps and HowToDirections. You can even given an extra HowToTip if you want to add a relevant tip that can improve the job, but is not necessary for the end result. These are the building blocks that define the structure of the data.

So, let’s take a closer look at some of the parts used to build this how-to. Remember, there’s more to find on Schema.org/HowTo. These are some of the parts you will use often:

  • HowTo: To define that this data is a set of instructions to achieve something
    • Name: What’s the project called?
    • EstimatedCost: How much do the tools cost for instance?
      • MonetaryAmount: What currency is and for which amount?
    • TotalTime: How long does the job take? You can also specify a prepTime for preparation.
    • HowToTool: Which tools do you need? Maybe a hammer?
      • Supply: Do you need supply as well, like nails?
    • HowToItem: Which items do you need?
      • Name: Name of the item, list ‘em all
  • HowToSection: Is it preparation, starting or finishing up?
    • HowToStep: Every step needs its own type
      • HowToDirection: Descriptions for the step
      • BeforeMedia: An image of what the starting point looks like.
    • DuringMedia: You can add images or videos per step
    • AfterMedia: And even an image showing the endresult
    • HowToTip: if you want to give extra tips and tricks

You’ll see that the code is fairly straightforward: everything has a clear description. You can expand this code with a lot of properties from CreativeWork and some from Thing as well.

And now, the JSON-LD code

As you might know, JSON-LD is Google’s perfered data format for adding structured data. It’s easy to add since it isn’t embedded in the HTML code. In addition, it is very readable for humans. When running the code through Google’s Structured Data Testing Tool you might see that some variations give errors. For instance, if you use howToItem to determine which tools you need, you get an error, but if you use HowToTool it works perfectly fine. Same goes for supply and howToSupply. Keep in mind that the difference between supply and tool is that the former is consumed while doing the job. A hammer is a tool, while nails are its supply. You need both to finish your work, right? In our example, I could add a ‘computer’, an ‘internet connection’ or a ‘website’ as supply if I wanted to. You can also add a yield to determine what the outcome of the workshop is.

Get the most out of Yoast SEO, learn every feature and best practice in our Yoast SEO for WordPress plugin training! »

Yoast SEO for WordPress plugin training Info

<script type="application/ld+json">
{
	"@context":"http://schema.org",
	"@type":"HowTo",
	"name":"How To Add Your Website To Google Search Console",
	"estimatedCost":
	{
	"@type":"MonetaryAmount",
	"currency":"USD",
	"value":"0"
	},
	"totalTime":"00:10:00",
	"tool":
	[
	{
		"@type":"HowToTool",
		"name":"Yoast SEO WordPress plugin"
	},
	{
		"@type":"HowToTool",
		"name":"Google Search Console account"
	}
	],
	"steps":
	[
	{
		"@type":"HowToSection",
		"name":"Preparation",
		"itemListElement":
		[
		{
			"@type":"HowToStep",
			"itemListElement":
			[
			{
				"@type":"HowToDirection",
				"description":"Install Yoast SEO and activate your Google Search Console.",
				"duringMedia":
				{
				"@type":"ImageObject",
				"contentUrl":"yoast_seo_search_console.jpg"
				}
			},
			{
				"@type":"HowToTip",
				"description":"Did you know you can check and fix crawl errors directly from Yoast SEO?"
			}
			]
		},
		{
		}
		]
	},
	{
		"@type":"HowToSection",
		"name":"Adding your site to Search Console",
		"itemListElement":
		[
		{
			"@type":"HowToStep",
			"itemListElement":
			{
			"@type":"HowToDirection",
			"description":"Go to Google Search Console (former Google Webmaster Tools), sign into your Google account and click the red button to add your website."
			}
		},
		{
			"@type":"HowToStep",
			"itemListElement":
			[
			{
				"@type":"HowToDirection",
				"description":"Copy the code for the HTML tag under the Alternate Methods tab.",
				"duringMedia":
				{
				"@type":"ImageObject",
				"contentUrl":"yoast_seo_search_console_2.jpg"
				}
			},
			{
				"@type":"HowToTip",
				"description":"Please make sure you enter your complete url."
			}
			]
		},
		{
			"@type":"HowToStep",
			"itemListElement":
			{
			"@type":"HowToDirection",
			"description":"Copy the code for the HTML tag under the Alternate Methods tab."
			}
		},
		{
			"@type":"HowToStep",
			"itemListElement":
			{
			"@type":"HowToDirection",
			"description":"Log in to your WordPress website and click on ‘SEO’ in your menu. After that, click on General."
			}
		},
		{
			"@type":"HowToStep",
			"itemListElement":
			[
			{
				"@type":"HowToDirection",
				"description":"Click on the ‘Webmaster Tools’ tab and add the code under ‘Google Search Console’. Click ‘Save Changes’."
			},
				{
			"@type":"HowToStep",
			"itemListElement":
			{
			"@type":"HowToDirection",
			"description":"Switch back to Google Search Console (formerly Google Webmaster Tools) and click ‘Verify’."
			}
		}
			]
		}
		]
	},
	{
		"@type":"HowToSection",
		"name":"Finishing up",
		"itemListElement":
		[
		{
			"@type":"HowToStep",
			"itemListElement":
			{
			"@type":"HowToDirection",
			"description":"Congratulations! You’ve connected your website to Google Search Console (former Google Webmaster Tools)!"
			}
		},
		{
			"@type":"HowToStep",
			"itemListElement":
			{
			"@type":"HowToDirection",
			"description":"Now that you’ve verified and connected your website, you can submit your sitemap!"
			}
		}
		]
	}
	]
}
</script>

Adding structured data to your site with Google Tag Manager

Adding structured data requires you to edit the code of your pages. For most people, that requires help of their developers. There is an easier way, though. You can add structured data via the tags, triggers and variables available in Google Tag manager. What’s more, this way of adding your data gives you an extra amount of flexibility as you can save your variables and reuse them or even dynamically fill them. There are loads of options to explore. Annelieke wrote a post on how to add structured data to your site with Google Tag Manager.

A fun experiment

This was cool, right? Well, you might try to apply this on a live site, but keep in mind that search engines probably won’t do anything with it. Also, keep in mind that badly written or faulty structured data can do your site more harm than good. But — and there’s a big but —, since Google is heavily focusing on structured data and voice search via its Assistant, it’s fairly safe to say that howTo Schema.org will be next in line. As this is a new Schema.org, we’ll just have to wait for the official word from Google to arrive so we know how to apply this properly.

Read more: ‘Structured data: the ultimate guide’ »


18 Responses to How to add HowTo structured data to your how-to article

  1. wasim akram
    By wasim akram on 7 May, 2018

    This article has helped me very much for clearing my doubts about adding structred data in my website.

    • Iris Guelen
      By Iris Guelen on 7 May, 2018

      Good to hear that we could be of help Wasim! :)

  2. Arun Kumar
    By Arun Kumar on 1 May, 2018

    I have finally found how to add structured data on my site. That code snippet helped me a lot to add to my site. Thank you Edwin Toonen for this useful guide.

  3. Noor Alam
    By Noor Alam on 28 April, 2018

    Will this be available in the Yoast SEO plugin?

    • Edwin Toonen
      By Edwin Toonen on 30 April, 2018

      HowTo structured data is cool, but there is no support yet. We’re looking at better ways of implementing structured data, but no news on that front.

  4. Joyce Grace
    By Joyce Grace on 27 April, 2018

    This would be so awesome to have in a plugin, where the user just enters the info into say, WP custom fields, or something like that.

    It would also be great to get examples of json+ld tags for specific types of organizations. For example, I’m working on two schools right now, and sometimes it’s hard to get the structured data validated, since the allowable usage of data is complex. These cases also don’t always ‘fit’ into an expected type, for each of the data points you’d want to enter. And sometimes, you don’t know what the most reasonable type is to use. For example, if the school has multiple programs, do you use “makesOffer” or “offersCatalog”? Sometimes price range is also not really relevant, but it is recommended (shows up as a warning if not included). And then sometimes you want to be listed as an Educational Institution, but also a Local Business. Additional Type won’t work for totally different schemas. So then you have to decide which one is best to go with – or do you create two separate ones?

    Soooo…it is very awesome to have this post, and I can say that while googling this for some cases, it’s hard to find pre-made structures that we can copy-and-paste from, and then modify from there. I’d love to see more of these!

    Or a plugin perhaps? More comprehensive than what’s already out there…

    • Edwin Toonen
      By Edwin Toonen on 30 April, 2018

      Hi Joyce. Thanks for your great comment. You’re absolutely right and this is one of the main shortcomings of Schema.org — trying to figure out what to use while abiding all those rules. It’s awesome that you have all these types available, but it’s getting increasingly hard to see the forest through the trees. I myself would love a plugin like you suggest and, at Yoast, we love structured data so I hope we can put two and two together someday.

  5. NGScholar
    By NGScholar on 26 April, 2018

    Thanks for the writting, will Yoast SEO plugin be updated to support those features?

    • Edwin Toonen
      By Edwin Toonen on 30 April, 2018

      Yoast SEO already supports a small amount of structured data by default. We’re looking into other possibilities. No word yet, though.

  6. Presh Arthur
    By Presh Arthur on 26 April, 2018

    bro I actually don’t understand much about the schema code, please is there a topic about it here on yoast blog?

  7. sitesazan
    By sitesazan on 26 April, 2018

    Amazing post. Thanks Edwin

  8. Sean Casey
    By Sean Casey on 26 April, 2018

    Very interesting article, I’m sure Google will start to feature How-to’s soon in results. Does Yoast recommend a specific plugin for JSON-LD schema?

    • Edwin Toonen
      By Edwin Toonen on 30 April, 2018

      Hi Sean. Thanks for your comment. We don’t have a recommendation for a specific JSON-LD plugin. We use Google Tag Manager to add structured data to our pages. I’ve linked to a post about this in the article. Also, a couple of our plugins already add structured data by default.

  9. Lisa Clarke
    By Lisa Clarke on 26 April, 2018

    This is too cool. As someone who has written many a “HowTo” over the years, this topic gets my gears turning! I will definitely have to play with this. Thanks!

    • Edwin Toonen
      By Edwin Toonen on 30 April, 2018

      Hi Lisa. Yeah, this is great stuff. Looking forward to seeing what Google will do with this.

  10. Vinay Prajapati
    By Vinay Prajapati on 26 April, 2018

    Thanks for sharing this information. Let me know when Yoast will support schema structure to make custom posts like article, creative work, articlenews, technews, howto etc.

    • Edwin Toonen
      By Edwin Toonen on 30 April, 2018

      Thanks Vinay! We’re following the developments regarding structured data closely, but I cannot say yet what will end up in our products.


Check out our must read articles about Technical SEO