JSON-LD Validation: Test and Debug Structured Data Step by Step

JSON-LD is the script block that carries your structured data. A single missing comma can stop the whole block from being read, and a perfectly valid block can still be ineligible for a search feature because a required field is missing. JSON-LD validation is the routine of checking both things: that the code parses, and that the content meets the rules of the feature you want.

This guide is for site owners, SEOs and developers who add or maintain structured data and want a repeatable way to test and debug it. You will learn which tool answers which question, how to test code before it is live, how to test a live page, how to read what Google actually found, and how to monitor for breakage after launch. Passing every test does not mean a rich result will show. Google decides what to display, and says so in its guidelines.

Before you begin

You need the JSON-LD block (or the page URL that contains it) and, for monitoring, a verified Search Console property for the site. See Set Up Google Search Console if you do not have one yet.

Know what you are testing against. There are two different questions:

Is the markup well formed and sensible? Is it valid JSON, with sensible schema.org types and properties?
Is the markup eligible for a Google feature? Does it contain the properties Google requires for, say, product or organization results?

Different tools answer different questions. Use more than one. Allow about 30 minutes for the first run on a template. Nothing here changes your live site, so the risk is low. If the page you want to test is on a staging server behind a login, Google's tool cannot reach it unless you use a tunnel to expose it temporarily, so plan for that.

The four tools and what each is for

Rich Results Test

Google's Rich Results Test checks the structured data on a page and shows which rich result types it could enable in Google Search. You can enter a URL or switch to the code option and paste a snippet, then re-run as often as you like. It tests as a smartphone by default and you can switch to desktop. It reads JSON-LD, RDFa and Microdata.

The results show a crawl summary (whether the fetch worked, the user agent, whether robots.txt allowed it), then each detected item with a status of valid, warning, error or unparseable. In Google's description, invalid items are errors, and items that are valid but incomplete are warnings. For some result types it also shows a preview.

Schema Markup Validator

The Schema Markup Validator at validator.schema.org was announced by Schema.org as the successor to Google's old Structured Data Testing Tool. Schema.org describes it as a general-purpose check that JSON-LD, RDFa and Microdata follow common conventions and that types and properties are not combined in unusual ways. Unlike the Rich Results Test, it does not check against the requirements of any particular product or service. Use it when you want to know whether the markup says what you mean, or when a feature is not supported by the Rich Results Test. Google's own documentation on site names, for example, says the Rich Results Test does not support that feature and suggests a general schema testing tool instead.

URL Inspection tool

URL Inspection in Search Console shows what Google fetched for a URL. Google's introduction to structured data says it can confirm that Google has found your structured data. It also helps you check that the page is not blocked by robots.txt, a noindex tag or a login, which would stop the markup being used at all.

Search Console reports

After launch, the rich result status reports in Search Console show how many items are valid or invalid across the site. In Google's help text, valid items have no critical issues and can appear as rich results. Invalid items have at least one critical issue that prevents that. Non-critical issues appear in an "Improve item appearance" table. Reports cannot fix anything for you: changes happen in your site's source.

Step-by-step instructions

Step 1: Check the JSON syntax first

Before any Google tool, make sure the text is valid JSON. Common syntax faults are a missing or extra comma, a missing closing brace, straight quotes replaced by curly quotes from a word processor, unescaped quotation marks inside a string, and comments. The JSON-LD standard does not allow comments. The Rich Results Test ignores them, but Google warns that they can cause errors elsewhere, so remove them before you publish. If the parser fails before it can tell which type you meant, the Rich Results Test reports the problem under "Syntax errors in items of unknown type".

What success looks like: a plain JSON parser or an editor with JSON checking accepts the block with no errors.

Step 2: Test the code snippet

Open the Rich Results Test, choose the code option and paste the block. Fix every error, then look at each warning and decide if the property is true and worth adding. A warning means valid but incomplete; it does not mean the markup is broken.

Pay attention to the detected item list. If the item you expected is missing, the type may be misspelled, the @context may be wrong, or the block may be nested in a way that hides it. Google supports http://schema.org and https://schema.org style contexts (and a couple of other Google-approved ones) but not custom remote contexts.

What success looks like: the expected item is detected, with no errors.

Step 3: Run a second opinion in the Schema Markup Validator

Paste the same block or URL into the Schema Markup Validator. Look for warnings about unknown properties or odd type combinations. This catches mistakes such as using a property on a type that does not have it. Remember that a pass here says nothing about Google's eligibility rules, and a warning here is not necessarily a Google problem.

What success looks like: the types and properties are recognised and nothing looks out of place.

Step 4: Test the live URL

Once the page is deployed, enter its URL in the Rich Results Test. This tests the rendered page as Google fetches it. Check the crawl section. Google lists blocked or unloadable images, CSS and scripts as warnings, with causes such as timeouts, 404 errors, login requirements and robots.txt blocks aimed at Google-InspectionTool. Blocked important resources can change how Google understands the page, so unblock those on your own site. Results can vary between runs if resources load inconsistently, so repeat a surprising result before acting on it.

Common fetch failures include DNS errors, private IP addresses, server errors, invalid SSL certificates, an unreachable robots.txt, and "Hostload exceeded" when your server is at capacity for Google's requests. The related guide Robots.txt Blocking Google or Bing covers the robots.txt case.

What success looks like: the live test fetches the page and detects the same items as the snippet test.

Step 5: Compare source with rendered HTML

If your markup is added by JavaScript or a tag manager, the raw HTML source and the rendered page can differ. In the Rich Results Test, expanding an issue and clicking its description opens a code explorer on the rendered source at that location. Compare it with "view source" in your browser. For product markup, Google recommends the initial HTML, because JavaScript-generated markup can make Shopping crawls less frequent and less reliable. For other types, make sure the rendered markup is stable and does not depend on user actions.

What success looks like: you know whether the markup is in the raw HTML, the rendered HTML, or both.

Step 6: Check what Google found in Search Console

Use the URL Inspection tool on the live URL and read the result. Then wait. Google says recrawling and reindexing can take several days. After that, open the relevant rich result report and look at valid and invalid counts. Issue details show first-detected and last-crawled dates, and Google notes that if an issue is fully resolved but reappears within 90 days, the first-detected date stays the original date.

What success looks like: the report counts the page as valid, or shows only non-critical items you have chosen to leave.

Step 7: Make testing part of every release

Structured data breaks quietly when a template changes. Add a short test to your release routine: after each deploy that touches templates, test one URL of each page type. Google's introduction says templating or serving problems can break markup later, so keep watching the reports. Crawvix's structured data check reads the JSON-LD blocks on the pages it samples, reports blocks that do not parse and checks for basic fields on common types. It does not read Microdata or RDFa and it does not replace Google's tools, so treat it as an early warning rather than a verdict.

What success looks like: a recurring task checks one URL per template after each release.

Reading errors and warnings

Google's error messages name the property at fault. A "Missing field" message means add the property, and it also applies when the field is present but empty. "Invalid value" and "Invalid object type" messages mean the data type is not what the documentation expects. Our companion guide, Fix the Most Common Rich Results Test Errors and Warnings, goes through the list.

Final verification checklist

The JSON-LD parses with no syntax errors and has no comments.
The Rich Results Test detects every item you expect, with no errors.
Warnings have been reviewed and either fixed or consciously accepted.
The Schema Markup Validator shows no unexpected type or property problems.
The live URL test fetches the page without blocked important resources.
The markup is in the HTML Google receives, not only added after user actions.
URL Inspection shows the page is fetchable and indexable.
The Search Console report shows the page as valid after Google recrawls.
One URL per template is retested after each release.

Common mistakes to avoid

Trusting one tool. The Rich Results Test and the Schema Markup Validator answer different questions. Use both.
Testing only the snippet. A snippet can pass while the live page fails because of a block, a redirect or an extra script. Always test the live URL.
Curly quotes and stray commas. Edit JSON in a code editor, not a word processor.
Leaving comments in. Remove them even though a test ignores them.
Ignoring warnings forever. Warnings flag incomplete data. Review them, because a missing property may be one you could easily add.
Expecting instant results. Allow several days after a fix, and do not rewrite the markup every hour.
Blocking the tester. If robots.txt blocks Google-InspectionTool, the page cannot be tested.
Assuming a pass means a rich result. Valid markup makes a page eligible, nothing more.

Frequently asked questions

Which tool should I use first?

Use a JSON syntax check, then the Rich Results Test with the code option. Add the Schema Markup Validator for a general check.

Why does the validator pass but the Rich Results Test fail?

The Schema Markup Validator checks general schema.org conventions. The Rich Results Test checks Google's requirements for specific features, so a missing required property fails only there.

Can I test a page on a staging site?

Only if Google can reach it. A page behind a firewall, a password or a local machine needs a tunnel to be tested.

How long are saved tests kept?

Google says test code and state are saved for about 90 days, and you can share a results link.

Does valid markup mean I will get a rich result?

No. Google says structured data does not ensure a rich result, and its systems choose what to show.

Official references

Next step: See how Crawvix checks a website and capture a baseline once scanning opens. This guide provides technical information, not a guarantee of rankings, traffic or index inclusion.