The Google Structured Data Testing Tool (SDTT) is a free tool created by Google to help you validate and test the syntactical correctness and alignment to Google recommendations of your schema markup. It is a fairly easy web development tool to use, so don’t be scared. While the Structured Data Testing tool is great, the Google Web Master Tools Structured Data report is still the “report of record” for whether Google has crawled, and discovered your schema markup.
The Structured data testing tool is checking for a couple of things:
- Required & Recommended properties for Google Features
- Accurate Schema Markup Syntax (JSON-LD, Microdata, RDFa)
Google’s New Structured Data Testing Tool
On December 19th, Google announced their new Structured Data Testing tool on their blog. The new structured data testing tool has limited use case support, in this first release only supporting Recipes, Movies, Courses and Job Posting.
On Twitter on the release day, John Mueller suggested that new use cases and support for new features would be added regularly.
Google’s Structure Data Documentation – Required and Recommended Properties
Google uses structured data to better understand the content on your website and to enable special search result features. These features range from rich results for reviews, to knowledge graphs about a local business. Each of the 40+ features is listed in Google documentation. The first step to doing markup and also troubleshooting your schema markup is to undersatnd exactly what Google wants, so to do this you’ll need to spend some time reading the documentation. Alternatively, you can use tools that guide you on the required and recommended fields, like Schema App. These required and recommended properties are things first thing that the testing tool is validating for.
The required and recommended fields are illustrated in the documentation as seen in the example below.
Schema Markup Syntax – JSON-LD, Microdata and RDFa
The other more complicated thing to learn is how to write schema markup. Today, Google prefers JSON-LD for all schema markup. Read more about the different types of Structured Data in Google’s Introduction to Structured Data.
Good news, if you aren’t a coder, there are lots of tools available to generate JSON-LD, so you don’t have to learn it. What’s also great about generating JSON-LD, is that if you are using a professional and well-maintained tool, you will NEVER get any syntax errors! Awesome eh!
Schema App has a free JSON-LD generator online, and a Schema App Software as a Service Toolset to generate and manage your schema markup for any part of the schema.org vocabulary. Merkle’s JSON-LD generator is easy to use, and covers some but not all required and recommended fields. We recommend that if you are using an online JSON-LD generator like Merkle’s, just double check the Google Documentation for the required and recommended fields and make sure to include them and that it is maintained.
How to use the Structured Data Testing Tool
Step 1: Go to Google’s Structured Data Testing Tool
Step 2: Enter the page or code you want to test. There are two options in this step.
Option 1: Enter the URL you want to Test. Click Run Test.
Option 2: If you don’t have the URL, but just a block of JSON-LD or Microdata you wan to test. Click on the Code Snippet menu item. Enter your Code into the window on the page page and click Run Test.
Step 3: See what Schema Markup is on the page.
Intimidated by code and/or wondering what you’re looking at? Here’s a breakdown:
- The top left shows the URL you’ve typed in and is where the code on the left side of the page is being pulled from.
- On the right side under where it says “Detected” is the list of structured data entities. Clicking on an entity on the right will open it up and show you further details. If your webpage doesn’t have structured data, then this will be empty.
- The play button in the center is the validate button.
- NEW TEST does what you think it does. It allows you to run another test for a different URL or a new code snippet.
Tips for Using the Google Structured Data Testing Tool
- Click on an entity on the right side of the page. Where it exists in the code will be highlighted on the left side of the page. This way you can track something down (like an error) quickly.
- You can edit the code on the left-hand side panel. This is useful if you’re troubleshooting an error and want to try and type in a solution quickly. After you’ve finishing making some changes, click the validation button.
- Follow this link and use the Structured Data Testing Tool bookmarklet by Kevin Polley. You’ll be able to test the schema markup for a webpage with one click! We use this each and every day to test pages without copying and pasting.
Common Structured Data Testing Tool Errors and How to Fix Them
Testing and troubleshooting your schema markup can require a steep learning curve. Often our users come to us to help solve an error they see in the Google Structured Data Testing Tool (SDTT) because it is not clear what the error is about, or how to fix it. Below we’ve listed the most common Structured Data testing tool errors and what they mean, so you can fix them.
A value for the <class type> field is required
The most common kind of error is a missing required property. Examples of the error are “A value for the image field is required” or “A value for the url field is required.”
If you see an error that says “A value for the [xyz] field is required.” then you’re missing a required property for one of Google’s search features. You must include all the required properties for an object to be eligible for appearance in Google Search with enhanced display. So you very much want to fix these errors. (quick tip: If this information isn’t available on the page then you should consider finding a way to include it). Let’s fix an example:
We forgot to include an image for our LocalBusiness entity. To fix the error simply open that data item, locate the missing property in the form builder, and enter the required information.
The Schema App form builder mirrors Google’s structured data search documentation. By filling out all the Required Properties you’ll help ensure your eligibility for the Google search features related to that schema.org class type.
To help keep you on track, saving changes without filling out all the required or recommended properties will generate a warning.
The <property> field is recommended. Please provide a value if available.
Recommended property warnings are when you are missing a Google recommended property. Common examples are:
The address field is recommended. Please provide a value if available.
The priceRange field is recommended. Please provide a value if available.
The telephone field is recommended. Please provide a value if available.
As you might assume, fixing the error for a recommended property is less important than a required property. However, they are still important. According to Google documentation including recommended properties can help encourage your eligibility to appear in search results with an enhanced display. So while these properties are only recommended, we strongly recommend including them. To do so, follow the same process as a missing required property.
ContactPoint must be attached to a parent with a declared type.
You might come across an error that says: ContactPoint must be attached to a parent with a declared type. It looks like this:
This is an error Google has shown for a while. You probably do have your contact point data item within an organization (or subclass of) data item. However, the URI for the organization data item is the homepage and the URI for the contact point is the contact page. If that is the case your schema markup IS correctly done, and the SDTT is giving a really stringent error, and you can ignore it.
If you are using Schema App, here is how to set up a Contact Point.
All values provided must have the same domain.
You may get worried if you see an error that says: All values provided for http://www.example.com/ must have the same domain. It may be confusing because you haven’t intentionally made markup for an example webpage, right? Here is what it looks like:
This error is misleading and we only see this reported when you copy & paste the JSON-LD into the SDTT. Ignore these errors as they will go away when the code is applied to a live URL. Test the live URL after deployment to be sure.
[x class type] is not a known valid target type for the [y property]
Properties may expect certain class types, and will generate an error if it finds an unexpected class type. That error will state that the unexpected class type is not a known valid target type. Here is an example:
The property hoursAvailable isn’t expecting a ContactPoint, so the SDTT is providing an error. Alternatively, if you have a class type that is expected, such as DayOfWeek, then you don’t get this error. These errors let you know that the class type is inappropriate for the property that is being described and if that is information you’re looking to include it probably belongs elsewhere. As you can see below, the expected class types are called out in the Schema App form builder:
The faint lettering lets you know what kind of related data item to create.
You can also look up the property at Schema.org and see what class types are expected. Here is the geo property as an example.
If you are using Schema App, here is a video tutorial on how to set it up.
The address field is recommended
The SDTT is asking for a missing address property but you’ve included it a number of times elsewhere. What exactly is going on!?
This may be the result of Schema App not showing markup three hops from the original data item. If it is more than two hops, we may not pull in all the address departments. Two things to do if you are seeing this. First, contact us at firstname.lastname@example.org and let us know the type of entity and data and we’ll create the exception to allow that data to be shown. Alternatively, you can create the related data item and make the URI the same as the main page and add #name at the end so that all that data is shown automatically. For example, if you are doing local business schema markup, and want to include all the details about sub-organizations (perhaps they don’t have their own page). The URI for the business would be https://www.business.com, the URI for the Sub-organization would be https://www.business.com/#location1. Now Schema App will deploy all the markup on www.business.com.
Syntax Errors – Uncategorized Errors
An uncategorized error is kind of syntax error that is generated if something unexpected or wrong has occurred within your JSON-LD. You might find these errors if you’ve copied the JSON-LD from Schema App and missed something, or if you’ve changed the JSON-LD in some way.
Common versions of this include:
- Missing ‘,’ or ‘}’ in object declaration.
- Duplicate key found.
If you run into this problem, you have to get into the code. If you’re intent on editing or creating the JSON-LD yourself then the error description can help you find the error source. Or if you use Schema App, go back to Schema App and regenerate the JSON-LD. This is where using a JSON-LD generator can help you quickly solve this problem.
Unknown Type – The Type “x” is not a type known to Google
The concepts within the schema.org vocabulary are ever-growing. It’s important to use them specifically (and to spell them right!) or you’ll get an error stating it “is not a type known to Google”:
Be sure to check any spelling if you’ve copied or edited the JSON-LD because mixing up even one character will cause an error.
Uncategorized Errors resulting from “curly” quotations
Uncategorized errors can show up in SDTT when you use “curly” quotations (also referred to as “smart” quotations). Ryan Rodden reports that this “demon error” is commonly found on the Mac text editor. The thing that makes it really complicated it that it doesn’t appear to be an error because it is still officially a quotation mark. He reports that the workaround is to open a text editor and before doing any code, hit Shift+Command+T to start from plain text format.
How do you know if this is what you are running into? Within the Google testing tool, look to see if the “@type” is gray or black. If it is black, this is likely the problem. Related markup will appear in red.
Publisher.itemtype has an invalid value!
The attribute publisher.itemtype has an invalid value is an error that we’ve seen a number of times and is actually a limitation of the SDTT itself.
One of the required properties for an Article (or other CreativeWork) is the attribute publisher. This property will describe the publisher of the creative work. The values that are expected of this property are Organization and Person. The SDTT will provide an error for any schema.org class other than Organization. This includes Person all subclasses of Organization such as LocalBusiness, Corporation, ProfessionalService, and so on. Therefore this is a limitation of the SDTT validation results. If you’re experiencing this error and the schema.org class you have associated for the Publisher attribute is either Person or a subclass of Organization then you can safely ignore this error.
Duplicate field telephone is not allowed.
Many people have reported seeing the error, “Duplicate field telephone is not allowed”.
What is happening here? Well, there are some properties that do not allow duplicate information. The telephone property is one of them. If you’ve seen this error it means that you’re going to either have to choose one to keep, or create another data item.
Do you have any errors you can’t figure out? Send them over. We’ll update this blog with the common errors and resources to help you fix them.