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

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

An SEO’s Guide to Writing Structured Data (JSON-LD) 1920 1080 briangormanh

Posted by briangormanh

The Schema.org vocabulary is the ultimate collab.

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 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:

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

Creating custom structured data markup with a text editor

Baseline markup will do just fine, but we can go beyond the online generator presets, take full control, and write beautiful custom structured data for our page. On https://schema.org/Organization, you’ll see all the available properties that fall under the Organization markup type. That’s a lot more than the online tools offer, so let’s roll up our sleeves and get into some trouble!

Download a text editor

At this point, we have to put the training wheels away and leave the online tools behind (single tear). We need somewhere we can edit and create custom markup. I’m not going to be gentle about this — get a text editor NOW. It is well worth the money and will serve you far beyond structured data markup. I’ll be using my favorite text editor, Sublime Text 3.

Pro tip: Go to View > Syntax > Javascript > JSON to set your syntax appropriately.

I’ve gone ahead and pasted some baseline Organization markup from the generator into Sublime Text. Here’s what it looks like:

Adding properties: Easy mode

The page at https://schema.org/Organization has all the fields available to us for the Organization type. Our baseline markup doesn’t have email information, so I reviewed the Schema page and found this:

The first column shows that there is a property for email. Score! I’ll add a comma after our closing bracket to set up the expectation for more information, then I’ll add the “email” property:

The second column on Schema.org is the “expected type.” This time, it says “text,” which means we can simply type in the email address. Gosh, I love it when it’s easy.

Let’s keep pushing. I want to make sure our phone number is part of this markup, so let’s see if there’s a property for that…

Bingo. And the expected type is simply “text.” I’m going to add a comma after the “email” property and toss in “telephone.” No need to highlight anything in this example; I can tell you’re getting the hang of it.

Adding properties: Hard mode

Next, we’re going to add a property that’s a bit more complicated — the “address” property. Just like “email” and “telephone,” let’s track it on https://schema.org/Organization.

So, I do see “text,” but I also see an expected type of “PostalAddress.” The name of the game with data markup is: if you can be more specific, be more specific. Let’s click on “PostalAddress” and see what’s there.

I see a number of properties that require simple text values. Let’s choose some of these properties and add in our “address” markup!

Here are the steps I took to add this markup:

  • Placed a comma after the “telephone” property
  • Called the “address” property
  • Since the “address” property has an expected type, I opened inner curly braces
  • Called the “PostalAddress” type
  • Called the properties within the “PostalAddress” type
  • Closed out the inner curly braces

Can you spot all that from the image above? If so, then congratulations — you have completed Hard Mode!

Creating a complex array

In our discussion about brackets, I mentioned an array. Arrays can be used when a property (e.g. “sameAs”) has two or more entries.

That’s a great example of a simple array. But there will be times when we have to create complex arrays. For instance, Go Fish Digital has two different locations. How would we create an array for that?

It’s not all that complex if we break it down. After the North Carolina information, you’ll see a closed inner curly brace. I just entered a comma and then added the same type (PostalAddress) and properties for the Virginia location. Since two entries were made for the “address” property, I enclosed the entire thing in brackets.

Creating a node array using @graph

On April 16th, 2019, Joost de Valk from Yoast announced the arrival of Yoast SEO 11.0, which boasted new structured data markup capabilities. You can get an overview of the update in this post and from this video. However, I’d like to dive deeper into a particular technique that Yoast is utilizing to offer search engines fantastically informative, connected markup: creating a node array using @graph (*the crowd gasps).

The code opens with “@graph” and then an open bracket, which calls an array. This is the same technique used in the section above titled “Creating a Complex Array.” With the array now open, you’ll see a series of nodes (or, Schema types):

  • Organization
  • WebSite
  • WebPage
  • BreadcrumbList
  • Article
  • Person

I’ve separated each (see below) so you can easily see how the array is organized. There are plenty of properties called within each node, but the real magic is with “@id.”

Under the WebSite node, they call “@id” and state the following URL: https://yoast.com/#website. Later, after they’ve established the WebPage node, they say the web page is part of the yoast.com website with the following line:

isPartOf”:{“@id”:”https://yoast.com/#website“}.

How awesome is that? They established information about the website and a specific web page, and then made a connection between the two.

Yoast does the same thing under the Article node. First, under WebPage, they call “@id” again and state the URL as https://yoast.com/wordpress-seo/#webpage. Then, under Article, they tell search engines that the article (or, blog post) is part of the web page with the following code:

isPartOf”:{“@id”:”https://yoast.com/wordpress-seo/#webpage“}

As you read through the markup below, pay special attention to these two things:

  • The 6 nodes listed above, each separated to better visualization
  • The “@id” and “isPartOf” calls, which define, establish, and connect items within the array

Bravo, Yoast!

Source page: https://yoast.com/wordpress-seo/

Are you sure?
You must approve our cookie policy to use our site. I you refuse it you will redirect to the Google.
Refuse
Approve Cookies
Cookie Policy
Cookie Policy
This Bear Design Cookie Policy (“Policy”) outlines the general policy, practices, and types of cookies that Bear Design And Communications Ltd.. (“Bear Design”, “we”, “us” or “our”) may use to improve our services and your experience when visiting our websites.Cookies are small pieces of text used to store information on web browsers. They’re used by many websites to store and receive identifiers and other information on devices, such as a handheld phone or computer. Our site and services use cookies and other similar technologies (collectively in this Policy, “cookies”), in order to provide a better service to you and to generally improve our sites and services. For example, we may use cookies to help direct you to the appropriate part of our websites, by indicating that you are a repeat visitor. We may also use information to present you with services that are matched to your preferences.Some portions of our websites are functional without cookies, and you may generally choose whether to accept cookies. Most web browsers are set to accept cookies by default, however, you may be able to delete cookies yourself through your browser’s cookie manager. To do so, please follow the instructions provided by your web browser. Please note that disabling cookies will reset your session, disable auto-login, and may adversely the availability and functionality of our websites and the services we can provide to you.As part of our services, we may also place cookies on the computers of visitors to websites protected by Bear Design. We do this in order to identify malicious visitors, reduce the chance of blocking legitimate users, and to provide customized services.Our websites use first party cookies (i.e., cookies set directly by Bear Design) as well as third party cookies, as detailed in the table below.
Type of CookieWhy we use these cookiesWho serves them and where can you find out more information?
Analytics and research of usersThese are used to understand, improve, and research users visiting //beardesign.me and their needs for our product offerings. For example, we may use cookies to understand what pages a user browses before submitting a sales request form. We do not share information about this analysis with any third parties.Selected third parties listed and defined as follows:
  • Google Analytics – Web traffic tracking – //www.google.com/policies/privacy/
  • Bing – Conversion tracking from Bing ads – https://advertise.bingads.microsoft.com/en-us/resources/policies/microsoft-bing-adsprivacy-policy
  • Doubleclick – Google advertising platform that analyzes browsing activity across website to establish user profile – //www.google.com/policies/technologies/ads/
  • Twitter – Analyzes browsing activity across website to establish user profile – https://support.twitter.com/articles/20170514
  • Facebook – Analyzes browsing activity across website to establish user profile – https://www.facebook.com/policies/cookies/
A user can delete these cookies through browser settings.
Improving Website experienceThese provide functionality to help us deliver a better user experience for our website. For example, cookies help facilitate chats with our sales representatives, allow you to search the website, and deliver the user quickly to their intended website location.1st party and selected third parties as defined below:
  • __cfduid 3rd party cookie – This cookie is strictly necessary for Cloudflare’s security features
  • __hssc Cookie for keeping track of sessions. This is used to determine if we should increment the session number and timestamps in the __hstc cookie. It contains: the domain, viewCount (increments each pageView in a session), session start timestamp. (Expires: 30 min)
  • __hssrc Whenever HubSpot changes the session cookie, this cookie is also set. We set it simply to the value “1”, and use it to determine if the user has restarted their browser. If this cookie does not exist when we manage cookies, we assume it is a new session. (Expires: None. Session cookie)
  • __hstc The main cookie for tracking visitors. It contains: the domain, utk (see below), initial timestamp (first visit), last timestamp (last visit), current timestamp (this visit), and session number (increments for each subsequent session) (Expires: 2 years)
  • hsfirstvisit This cookie used to keep track of a user’s first visit. (Expires: 10 years)
  • hubspotutk This cookie is used for to keep track of a visitor’s identity. This cookie is passed to HubSpot on form submission and used when deduplicating contacts. (Expires: 10 years)
  • wordpress_ WordPress cookie for a logged in user.
  • wordpress_logged_in_ WordPress cookie for a logged in user.
  • wp-settings- WordPress also sets a few wp-settings-[UID] cookies. The number on the end is your individual user ID from the users database table. This is used to customize your view of admin interface, and possibly also the main site interface.
  • wp-settings-time- WordPress also sets a few wp-settings-{time}-[UID] cookies. The number on the end is your individual user ID from the users database table. This is used to customize your view of admin interface, and possibly also the main site interface.
  • __cfduid 3rd party cookie – This cookie is strictly necessary for Cloudflare’s security features
A user can delete these cookies through browser settings.
LAST UPDATE: 24.01.2018, LONDON
Approve
Refuse
Cookie Policy
This Bear Design Cookie Policy (“Policy”) outlines the general policy, practices, and types of cookies that Bear Design And Communications Ltd.. (“Bear Design”, “we”, “us” or “our”) may use to improve our services and your experience when visiting our websites.Cookies are small pieces of text used to store information on web browsers. They’re used by many websites to store and receive identifiers and other information on devices, such as a handheld phone or computer. Our site and services use cookies and other similar technologies (collectively in this Policy, “cookies”), in order to provide a better service to you and to generally improve our sites and services. For example, we may use cookies to help direct you to the appropriate part of our websites, by indicating that you are a repeat visitor. We may also use information to present you with services that are matched to your preferences.Some portions of our websites are functional without cookies, and you may generally choose whether to accept cookies. Most web browsers are set to accept cookies by default, however, you may be able to delete cookies yourself through your browser’s cookie manager. To do so, please follow the instructions provided by your web browser. Please note that disabling cookies will reset your session, disable auto-login, and may adversely the availability and functionality of our websites and the services we can provide to you.As part of our services, we may also place cookies on the computers of visitors to websites protected by Bear Design. We do this in order to identify malicious visitors, reduce the chance of blocking legitimate users, and to provide customized services.Our websites use first party cookies (i.e., cookies set directly by Bear Design) as well as third party cookies, as detailed in the table below.
Type of CookieWhy we use these cookiesWho serves them and where can you find out more information?
Analytics and research of usersThese are used to understand, improve, and research users visiting //beardesign.me and their needs for our product offerings. For example, we may use cookies to understand what pages a user browses before submitting a sales request form. We do not share information about this analysis with any third parties.Selected third parties listed and defined as follows:
  • Google Analytics – Web traffic tracking – //www.google.com/policies/privacy/
  • Bing – Conversion tracking from Bing ads – https://advertise.bingads.microsoft.com/en-us/resources/policies/microsoft-bing-adsprivacy-policy
  • Doubleclick – Google advertising platform that analyzes browsing activity across website to establish user profile – //www.google.com/policies/technologies/ads/
  • Twitter – Analyzes browsing activity across website to establish user profile – https://support.twitter.com/articles/20170514
  • Facebook – Analyzes browsing activity across website to establish user profile – https://www.facebook.com/policies/cookies/
A user can delete these cookies through browser settings.
Improving Website experienceThese provide functionality to help us deliver a better user experience for our website. For example, cookies help facilitate chats with our sales representatives, allow you to search the website, and deliver the user quickly to their intended website location.1st party and selected third parties as defined below:
  • __cfduid 3rd party cookie – This cookie is strictly necessary for Cloudflare’s security features
  • __hssc Cookie for keeping track of sessions. This is used to determine if we should increment the session number and timestamps in the __hstc cookie. It contains: the domain, viewCount (increments each pageView in a session), session start timestamp. (Expires: 30 min)
  • __hssrc Whenever HubSpot changes the session cookie, this cookie is also set. We set it simply to the value “1”, and use it to determine if the user has restarted their browser. If this cookie does not exist when we manage cookies, we assume it is a new session. (Expires: None. Session cookie)
  • __hstc The main cookie for tracking visitors. It contains: the domain, utk (see below), initial timestamp (first visit), last timestamp (last visit), current timestamp (this visit), and session number (increments for each subsequent session) (Expires: 2 years)
  • hsfirstvisit This cookie used to keep track of a user’s first visit. (Expires: 10 years)
  • hubspotutk This cookie is used for to keep track of a visitor’s identity. This cookie is passed to HubSpot on form submission and used when deduplicating contacts. (Expires: 10 years)
  • wordpress_ WordPress cookie for a logged in user.
  • wordpress_logged_in_ WordPress cookie for a logged in user.
  • wp-settings- WordPress also sets a few wp-settings-[UID] cookies. The number on the end is your individual user ID from the users database table. This is used to customize your view of admin interface, and possibly also the main site interface.
  • wp-settings-time- WordPress also sets a few wp-settings-{time}-[UID] cookies. The number on the end is your individual user ID from the users database table. This is used to customize your view of admin interface, and possibly also the main site interface.
  • __cfduid 3rd party cookie – This cookie is strictly necessary for Cloudflare’s security features
A user can delete these cookies through browser settings.
LAST UPDATE: 24.01.2018, LONDON
Approve
Refuse
Welcome
We use cookies to ensure that we give you the best experience on our website. Before you continue browsing you must approve or refuse our cookie policy.
Approve
Refuse
Cookie Policy