Over the past few months, I’ve been learning to implement JSON-LD onto our client’s sites as an alternative to Microdata and RDFa. While it’s significantly easier to understand and write than both other formats are, I noticed a shocking lack of information for beginners learning how to write in this format. Whether we’re talking about the proper tags to use or even the syntax of the language, there just weren’t any resources available to get down the basics. I could find endless debates over the nuances of the markup, but as a beginner, it all went clear over my head.
So why does it matter? Why keep banging my head against the wall while I tried to figure it out through endless trial and error?
It’s true that none of the search engines make full use of the markup yet, but over the past few years, it’s been gaining more and more support from Google, and it seems to be the direction Google’s moving. The main benefit of the markup is the ease of use: once you get a feel for how to write it, you’ll find yourself finishing a full markup for a page in a fraction of the time it would take you in the other languages. It’s also significantly easier to implement onto your site. Just write up the code and you can place it anywhere on the page. Just keep in mind that you should still keep your markup relevant to each page. You don’t want to markup the products that are in your store if you’re working on your homepage.
To begin, here’s a sample of code that I may use for one of my clients:
<script type=”application/ld+json”>
{
“@context”: “http://schema.org”,
“@graph”: [
{
“@type”: “LocalBusiness”,
“name”: “My Business”,
“openingHours”: “M-F 08:00-17:00”,
“paymentAccepted”: “USD”,
“priceRange”: “$$$”,
“address”: {
“@type”: “PostalAddress”,
“addressCountry”: “US”,
“addressLocality”: “Denver”,
“addressRegion”: “CO”,
“postalCode”: “80202”,
“streetAddress”: “1 Main St.”
},
“hasMap”: “http://maps.google.com/mybusiness”,
“sameAs”: [
“http://facebook.com/mybusiness”,
“http://twitter.com/mybusiness”
]
}
]
}
</script>
Now, what’s it all do?
“@context” and “@graph”
@context is what defines the vocabulary we’ll be using for our markup. You can use other websites besides https://schema.org, but if you’re reading this post, you probably don’t need to worry about that yet.
@graph is a useful line that I discovered more or less by accident (remember, there aren’t many resources for newbies). This line makes it very easy to implement multiple markups within the same script. For example, I can markup both a blog and the product featured in it. You can just as easily create multiple markups in multiple tags, but I’ve gotten in the habit of always using @graph, even if I don’t necessarily need it, for simplicity’s sake in case I ever need to go back and add more markup to a page. Keep in mind that for syntax here, you’ll need to include both the square bracket and the curly bracket after your @graph or it won’t compile correctly.
“@type”: “LocalBusiness”,
This defines what your markup is describing, in this case, a local business. You can see the full list of schemas here. Warning: there are a lot. It may take some searching around, but try to be as specific as possible here. For example, Corporation is a subset of LocalBusiness, so if you’re writing markup for a corporation, you should be sure to use that instead.
Properties
Alright, once you’ve got your type defined, browse through the full list of properties that it includes. You’ll want to use all of them that you can, as long as they’re relevant and included on your page. In this case, I’ve used “name,” “openingHours,” “paymentAccepted,” and so on. It may be tempting to include extra properties and try to “sneak in” extra keywords or other information, but as always, Google is on top of it, and they’ll punish your site if they discover any deception or misleading data. For best practices, just stick to what’s on your page.
You will learn as you go that certain properties are required to have. It’s all the same as in any other structured data format, but if you don’t already have a feel for what you’ll need, just run your code through The Structured Data Testing Tool, and it’ll let you know if you’re missing anything.
A lot of properties will need to be nested in JSON-LD, but don’t worry, as much of a headache as it is to nest properties correctly in Microdata, it’s remarkably easy with JSON-LD. Take a look at the example again:
“address”: {
“@type”: “PostalAddress”,
“addressCountry”: “US”,
“addressLocality”: “Denver”,
“addressRegion”: “CO”,
“postalCode”: “80202”,
“streetAddress”: “1 Main St.”
},
You’ll see that under “LocalBusiness” is “address” with another bracket and a declaration of a new object. All that it takes is one more set of curly brackets with another declaration nested within it. Simple.
Lists
Certain properties like “sameAs” which connects your website to your social media pages or “isBasedOnUrl” where you place the sources which you link to will let you list multiple values. To do this, you just enclose your list within square brackets with one item per line.
“sameAs”: [
“http://facebook.com/mybusines”,
“http://twitter.com/mybusiness”
]
Syntax
This is one of the easiest things to mess up, but also one of the easiest to fix (just don’t count on Google’s Structured Data Testing Tool to give you very detailed information, there’s most likely going to be a bit of trial and error.) So what are the most important things to remember?
- Every declaration is enclosed in quotes.
- After your entity declaration, include a colon before your property declaration.
- Every line ends with a comma except for opening brackets and the last line in a “set” (the last line before a closing bracket, or closing brackets when there’s not another opening bracket following it).
- Declarations are case sensitive and do not use spaces. Properties always start with a lowercase letter followed by capital letters for every subsequent word (openingHours). The exception to this is any declaration following “@type” will use capital letters for every word (PostalAddress).
- Make sure you close every bracket. I use a text editor that keeps a hanging indent after an opening bracket. It’s a standard coding trick, but it helps so much to quickly see where you’re missing a bracket.
If this doesn’t make sense yet, just play around with creating your own markup and use the example above as a guide for what kind of syntax to use and how to use it. I promise it’s much easier to understand than it is to explain. Once you’ve got it down, it’ll be second nature, and you’ll never even have to think about it again.
Tips
- Learn which properties are required for each declaration e.g. events requires a date and time.
- Explore the vocabulary. Browse schema.org and dig deep to find the most appropriate category, then dig even deeper into the properties and learn how each one works.
- The quickest way to learn is to practice. Even if you’re not completely sure how it works yet, try it out and test it in the Structured Data Testing Tool.
- When in doubt about an error you get, double-check your syntax! There’s probably an extra or missing quote, colon, comma, or bracket on the highlighted line or the one directly above or below it.
There’s sure to be a bit of frustration as you learn to use JSON-LD, but I recommend sticking with it. For one thing, after the initial frustration, you’ll find that it becomes so much simpler to use than other formats. Just a few days after diving into it, I was able to take a concept that I had virtually no understanding of, turn it into a streamlined process, and cut down the time I spent marking up pages to a meager fraction of what it was before. We also see slow, but steady progress from Google towards implementing JSON-LD and many experts are predicting that it will someday be the standard language to use. Mastering it now and embedding it on your sites early will guarantee you better and faster results in the SERPs than your competitors who aren’t so quick to pick it up.
