Fixing common JSON-LD structured data issues in Google Search Console

If you have ever implemented structured data on your website, you’ll likely have encountered structured data errors in Google Search Console.

When used correctly, structured data can be a powerful tool for showing enhanced results on Google Search results pages, which can increase site traffic and click-through rates. However, implementing structured data comes with its pitfalls and, due to the complexities of many websites, syntax and markup problems can be easily introduced.

Let’s explore some of the most common structured data errors and how to fix them. By understanding how to fix common problems that can arise, you’ll be able to easily troubleshoot common pain points and focus on enhancing your SEO and search visibility.

As always, we recommend reviewing Google’s documentation and structured data guidelines.

Table of Contents

• Errors vs Warnings
  • Unparsable structured data report
    • Parsing error
      • How to Resolve “Parsing Error” in JSON-LD
      • Common Issue: HTML tags in JSON-LD Structured Data
  • Bad escape sequence in string
    • How to Resolve “Bad escape sequence in string” in JSON-LD
  • Incorrect Value Type
    • How to Resolve “Incorrect Value Type” in JSON-LD
• Missing field
  • How to Resolve “Missing Field” in JSON-LD
• Invalid object type for field
  • How to Resolve “Invalid object type for field” in JSON-LD
• Either “offers”, “review”, or “aggregateRating” should be specified
  • How to Resolve “Either “offers”, “review”, or “aggregateRating” should be specified” in JSON-LD

Errors vs Warnings

In Google Search Console, structured data issues can be flagged with either red error circles or yellow warning triangles. This shows you the clear distinction between items that are invalid versus items that are warnings, or suggested areas to improve your structured data.

It’s important to ensure the invalid red items are resolved as a priority. Otherwise, your structured data will not be correctly parsed by browsers or search engines and, therefore, will not be eligible for rich results.

Errors – There is a problem that needs to be fixed that can result in rich results not being shown.

Warnings – A recommended property has not been used and indicates a non-essential problem that may require attention.

Unparsable structured data report

One common report you may see flagged in Search Console is “Unparsable Structured Data”. This report indicates you have introduced a syntax issue that is preventing Google from interpreting it properly.

Here are some of the most common errors and the approach to resolving them.

Parsing error

This particular error indicates there is a problem related to the parsing of specific characters in your structured data. Commas, curly brackets, and square brackets are key parts of JSON-LD syntax, which make up your structured data. If one is missing or implemented incorrectly, it can invalidate your entire markup.

Search Console is particularly helpful as you will be given examples of affected URLs on your website under the main error box. On clicking these URLs, you can view the specific lines of HTML on the page that are affected by the error.

How to resolve “Parsing Error” in JSON-LD

1. Identify where the error is – Google Search Console provides information on the location of the parsing issue within its reporting. This can help you find the line number where the issue is located.
2. Validate using JSON-LD validation tools – Using tools such as the schema.org Validator and other JSON-LD syntax validators can help you further pinpoint the exact issue within the markup. Look out for missing commas, curly brackets or square brackets.
3. Test the JSON-LD in an IDE or Code Editor – Code editing tools like Sublime Text or VSCode have colour-coded syntax highlighting that allows you to quickly identify issues on the fly while editing your code. Try importing your JSON document into a code editor in a .json file format to visually find the exact character that is flagging the issue.
4. Fix and monitor – Once you have found and fixed the error, ensure to validate your fix through Google Search Console.

Common issue: HTML tags in JSON-LD structured data

In some instances, you may find you haven’t identified any comma or curly brace issues in your markup. If you are populating property values dynamically with user-facing content areas, sometimes HTML tags can be incorrectly pulled into your key-value pairs, making the markup unparsable.

The example below shows that the description property has been populated with text from the user-facing content. However, the <p> and <span> tags have been incorrectly pulled in, breaking the string and invalidating the schema.

Google can often flag this problem as “Parsing error: Missing ‘,’ or ‘}’”, so it’s worth checking if this is true. If you find this happening, you’ll want to ensure HTML tags are stripped when strings are populated in your markup.

In most web stacks, there are simple ways to strip strings of HTML tags when implementing schema in this way. For example, if you use WordPress and PHP, the strip_tags function will allow you to return strings with HTML tags removed.

It’s best to take a look at the web stack specific to your website to resolve this issue.

Bad escape sequence in string

The previous example illustrated an issue related to HTML being pulled into your schema incorrectly. When properties are populated dynamically using body content areas, there are instances where this can pull undesirable characters into your values.

The Bad escape sequence in string error indicates that an escape sequence has been introduced into your structured data.

In the issue above, Google has interpreted an invalid escape sequence in your markup. This may be unintentional and means a backslash character “\” has been pulled into one of your values.

How to resolve “Bad escape sequence in string” in JSON-LD

1. Get familiar with escape sequences and JSON – In JSON, backslashes are used as “escape sequences” to represent special characters. Some examples include “\n” for newline, “\t” for tab etc.
2. Identify the location of the escape sequence – Use the Search Console report and other validators to understand where the sequence has been introduced to pinpoint the issue.
3. Check your strings for the backslash – Check the key-values pairs for the backslash character that is likely flagging the error.
4. Correct the issue – There can be three possible avenues for correcting this error:
   1. Removing the escape sequence – If the characters are not essential to your structured data, they should be removed.
   2. Correct the escape sequence – If the escape sequence is required but invalid, you must rectify it with a valid and appropriate one.
   3. Double-escape the backslash – If you need to include a literal backslash in your string, you will need to “double-escape” the sequence by wrapping the backslash in quotation marks like so: “\”
5. Fix and monitor – Once you have found and fixed the error, ensure to validate your fix through Google Search Console.

Incorrect value type

When you notice this error, it means that the value that has been declared is not a valid type for that property. For example, your schema has specified a number when a string was expected.

Every property in your markup has an expected type, and it’s important that each one is correctly matched up. On Schema.org’s main schema reference, you can review expected types for all possible properties.

How to resolve “Incorrect Value Type” in JSON-LD

1. Pinpoint the property causing the error – When reviewing the report in Search Console, look for the property name mentioned in the error message.
2. Check the expected value type – Use the Schema.org reference to know what the expected type is for the property. Below, you can see an example of some expected types for Product schema properties:
   
3. Check your assigned value – Review the value you have assigned to the property and see if it matches the expected data type. If it does not match, you will need to convert it so that it matches.
   1. Example: The expected value type of “url” is the URL format. If you have used Text format instead (such as not using a fully formatted URL), the value must changed to include the full URL including the https:// protocol
4. Fix and monitor – Once you have found and fixed the error, ensure to validate your fix through Google Search Console.

Missing field

A “Missing field” error in your structured data indicates you are missing a value from your key-value pair. This is a fairly common issue and can be easy to resolve.

In almost every case, when assessing this issue, you will notice the value is completely missing from the property in question. In this case, we are missing the value for the image property:

Usually, this issue is related to implementation. If you are dynamically populating the values in your schema using content fields, certain fields on certain pages have likely been left blank. Hence, your schema properties are missing values.

How to resolve “Missing Field” in JSON-LD

1. Identify the missing field – Using the Google Search Console report and other JSON-LD validators, you can pinpoint the exact field or property that is missing or invalid.
2. Review the Schema.org documentation – Check the required fields and values for the schema type and work out how to format your missing field correctly.
3. Add your missing field – If you are populating the values dynamically, you will need to ensure the values are populated in their appropriate fields on your website or in your CMS. If this isn’t the case, you will need to ensure the field is populated correctly according to your own setup.
4. Fix and monitor – Once you have found and fixed the error, ensure to validate your fix through Google Search Console.

Invalid object type for field

The “Invalid object type” error indicates that you have implemented an incorrect object type to the field highlighted in the error. As per the below example, the issue here is related to the field “offers”:

Similar to the “Incorrect value type” issue, this error occurs when the assigned value does not match the expected data type for the particular field. However, for this error, the issue is specifically related to object types.

If you are already familiar with JSON-LD syntax, you’ll know it’s common to nest objects within structured data, as this allows you to add additional properties that are not valid in your main schema type.

When introducing a new object into your JSON-LD, the object type is declared using the “@type” property. This error can indicate that the type you used is invalid or that the implementation is incorrect.

How to resolve “Invalid object type for field” in JSON-LD

1. Identify the object causing the error – As with all the errors, use Google Search Console as well as Schema.org’s validator to pinpoint which exact property or field is causing the problem.
2. Review Schema.org documentation for expected types – Review the schema types on schema.org to work out if you have declared the wrong type for the object.
   1. Example: If you are introducing an address as part of Organization schema, the declared “@type” should be “PostalAddress”:
      
3. Correct the object type – Once you have identified the valid type, correct this in your markup. Ensure you also include all the required properties that are needed for the object type to prevent a new “Missing property” error being introduced.
4. Fix and monitor – Once you have found and fixed the error, ensure to validate your fix through Google Search Console.

Either “offers”, “review”, or “aggregateRating” should be specified

This particular error is related to an issue in Product schema. Your product will not be valid for rich snippets if one of the specified properties is not included as part of the markup.

The Google Search Gallery provides information about the eligibility of Product schema for rich results and the required and recommended properties for this schema type. There is even an extensive list of examples of different types of implementation.

Under “Required Properties”, you will find the requirement to include either review, aggregateRating or offers as part of the markup to make the schema rich-result eligible:

How to resolve “Either “offers”, “review”, or “aggregateRating” should be specified” in JSON-LD

1. Identify the pages flagging the error – You may find this is an issue for a handful of product pages or your whole product template. Use Google Search Console’s report to understand which URLs are affected by this issue and which part of the markup on the page is invalid.
2. Review the Schema.org and Google Search documentation – Understand the usage guidelines for offers, aggregateRating, and review to understand the expected values of these properties.
3. Implement one of the required properties – You will need to update your JSON-LD to include one of these properties to make the schema valid.
   1. ‘offers’: For your product, you can include the ‘offers’ property to give details on the pricing & availability of the product. This is declared as the Offer or AggregateOffer type.
   2. ‘review’: If your products have reviews or ratings on the page, use this property to include review information. Declare this as the type Review.
   3. ‘aggregateRating’: Use this if your products have aggregated reviews or ratings. This is declared as the aggregateRating type.

Note: Not all 3 properties are required, but all 3 are recommended if possible and relevant to your product pages.