SEO’s Guide to Writing Structured Data (JSON-LD)

The Schema.org vocabulary is the ultimate collaborative.

Thanks to a mutual handshake between Google, Microsoft, Yahoo, and Yandex, we have a library of fields we can use to highlight and more aptly define the information on web pages. By utilizing structured data, we provide search engines with more confidence (i.e. a better understanding of page content), as Alexis Sanders explains in this wonderful podcast.

Doing so can have a number of positive effects, including eye-catching SERP displays and improved rankings.

If you’re an SEO, how confident are you in auditing or creating structured data markup using the Schema.org vocabulary? If you just shifted in your seat uncomfortably, then this is the guide for you. In it, I aim to demystify some of the syntax of JSON-LD as well as share useful tips on creating structured data for web pages.

Understanding the syntax of JSON-LD

While there’s a couple of different ways you can mark up on-page content, this guide will focus on the format Google prefers; JSON-LD.

Additionally, we won’t get into all of its complexities, but rather, those instances most commonly encountered by and useful to SEOs.

Curly braces

The first thing you’ll notice after the opening <script> tag is an open curly brace. And, just before the closing </script> tag, a closed curly brace.

All of our structured data will live inside these two curly braces. As we build out our markup, we’re likely to see additional curly braces, and that’s where indentation really helps keep things from getting too confusing!

Quotation marks

The next thing you’ll notice is quotation marks. Every time we call a Schema type, or a property, or fill in a field, we’ll wrap the information in quotation marks.

Colons

Next up are colons (no giggling). Basically, every time we call a type or a property, we then need to use a colon to continue entering information. It’s a field separator.

Commas

Commas are used to set the expectation that another value (i.e. more information) is coming.

Notice that after the informational field for the “logo” property is filled, there is no comma. That is because there is no additional information to be stated.

Brackets

When we’ve called a property that includes two or more entries, we can use an open bracket and a closed bracket as an enclosure.

See how we’ve included Go Fish Digital’s Facebook and Twitter profiles within the “sameAs” property? Since there’s more than one entry, we enclose the two entries within brackets (I call this an array). If we only included the Facebook URL, we wouldn’t use brackets. We’d simply wrap the value (URL) in quotes.

Inner curly braces

Whenever we’ve called a property that has an expected “type,” we’ll use inner curly braces to enclose the information.

In the above image, the “contactPoint” property was called. This particular property has an expected type of “ContactPoint.” Isn’t that nice and confusing? We’ll go over that in more detail later, but for now just notice that after the “contactPoint” property is called, an inner curly brace was opened. On the very next line, you’ll see the ContactPoint type called. The properties within that type were stated (“telephone” and “contactType”), and then the inner curly braces were closed out.

There’s something else in this use case that, if you can understand now, will save you a lot of trouble in the future:

Look how there’s no comma after “customer service.” That’s because there is no more information to share within that set. But there is a comma after the closed inner curly brace, since there is more data to come (specifically, the “sameAs” property).

Creating structured data markup with an online generator

Now that we know a little bit about syntax, let’s start creating structured data markup.

Online generators are great if you’re a beginner or as a way to create baseline markup to build off of (and to save time). My favorite is the Schema markup generator from Merkle, and it’s the one I’ll be using for this portion of the guide.

Next, you’ll need to choose a page and a markup type. For this example, I’ve chosen https://gofishdigital.com/ as our page and Organization as our markup type.

After filling in some information, our tool has created some fantastic baseline markup for the home page:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Go Fish Digital",
  "url": "https://gofishdigital.com",
  "logo": "https://gofishdigital.com/logo.png",
  "sameAs": [
    "https://www.facebook.com/GoFishDigital",
    "https://www.twitter.com/GoFishDigital",
    "https://www.instagram.com/GoFishDigital",
    "https://www.linkedin.com/company/go-fish-digital/"
  ]
}
</script>

Hopefully, after our lesson on syntax, you can read most (or all) of this example without a problem!

Validating your structured data

Of course, the ultimate goal of all this error checking is to get your code to validate.

Google testing tool will help you develop a bulletproof method of error checking, and that you’ll end up with the euphoric feeling that validated markup gives!

Using Google search for unique cases

The lessons and examples in this guide should provide a solid, versatile knowledge base for most SEOs to work with. But you may run into a situation that you’re unsure how to accommodate. In those cases, Google it. I learned a lot about JSON-LD structured data and the Schema vocabulary by studying use cases (some that only loosely fit my situation) and fiddling with the code. You’ll run into a lot of clever and unique nesting techniques that will really get your wheels spinning.

Structured data and the future of search

The rumblings are that structured data is only going to become more important in moving forward. It’s one of the ways Google gathers information about the web and the world in general.

It’s in your best interest as an SEO to untie the knot of JSON-LD structured data and the Schema vocabulary, and I hope this guide has helped do that.