Testing structured data the right way

01Which tool should you use to test structured data?

Testing structured data means answering three different questions, and each has its own tool. The Rich Results Test is Google's tool for checking whether a page's structured data can produce Google rich results. The Schema Markup Validator is the schema.org community's tool for checking any markup against the schema.org vocabulary. Search Console's rich result reports show what Google found across your whole site after crawling it.

Most confusion comes from using one tool to answer another tool's question. A page can pass the validator and still be ineligible for any rich result. It can pass the Rich Results Test today and drop out of a Search Console report next month after a template change. And neither tool tells you what a crawler that does not run JavaScript receives.

The sections below take each tool in turn, explain how to read errors and warnings, then cover that fourth check: the raw HTML response. A workflow table at the end puts the steps in order for a WordPress site.

02What does the Rich Results Test check?

The Rich Results Test fetches a URL, or accepts a pasted code snippet, and reports which rich result types it found, with errors and suggestions for each item. According to Google's Rich Results Test help page, it supports JSON-LD, RDFa and microdata, fetches pages as Google-InspectionTool rather than with your credentials, and uses a smartphone user agent by default.

Three details from that page change how you should use it on WordPress:

• It reads the rendered page. The code explorer uses the rendered source code, so JSON-LD injected by JavaScript is visible to it. That reflects how Google processes the page, and can mislead you about other crawlers, as the AI crawler section explains.
• It needs public access. Page resources behind a firewall or a password are not available to the test. A staging site behind basic authentication cannot be tested by URL; paste the code instead, or expose the page temporarily through a tunnel.
• It forgives comments. The tool ignores comments inside JSON-LD blocks, but the help page notes that comments are not supported by the JSON-LD standard and may cause errors in actual use. Remove them before publishing.

The test also respects crawl rules. If a robots.txt rule or a noindex directive prevents Google from crawling the page, the help page says the page cannot be tested, and the Crawling section of the result shows why. On WordPress that usually points to a staging copy with search engines discouraged, or a security layer that blocks unfamiliar user agents.

Use URL mode for anything live. Google's guide to generating structured data with JavaScript recommends the URL input over the code input, because the code input has JavaScript limitations such as CORS restrictions. Code mode is still useful for drafting a block before it ships, or for testing a template change on a page you cannot expose.

If some page resources fail to load, the help page warns that results can vary from one run to the next. Look for a page loading issues warning before you assume your markup changed between two tests.

One more limit: the Rich Results Test reports rich result types, so it only speaks to the types Google supports. A valid schema.org node that feeds no rich result, such as a Person describing an author, gets no verdict of its own. For those, you need the validator.

03What replaced the Structured Data Testing Tool?

The Schema Markup Validator replaced Google's old Structured Data Testing Tool, which many WordPress tutorials still link to. In a December 2020 Search Central post, Google said it would move the tool to a new domain serving the schema.org community and that it would no longer check for Google rich result types.

The post was updated twice. In May 2021 schema.org announced the new home, named the Schema Markup Validator, and in August 2021 Google began redirecting the old testing tool to a landing page that helps you choose the right tool. The validator lives at validator.schema.org.

Use the validator for what the Rich Results Test leaves out. The same post explains that it suits types Google does not consume, giving schema.org's ExercisePlan as an example, which makes it the better tool for checking an entity graph: Organization, Person, WebSite and how they connect through @id. Those nodes matter beyond Google's rich results, because they are how a page states who publishes it and who wrote it.

The validator does not tell you whether Google will show anything. A page that is perfectly valid schema.org can still miss a property Google requires for a rich result, so run both tools on any page where a rich result is the goal.

04How do Search Console enhancement reports work?

Search Console's rich result reports, listed under Enhancements, or under Shopping for product snippets and merchant listings, show the structured data Google found on your property after crawling. Google's rich result report overview lists one report per supported type, including Breadcrumbs, Product snippets, Merchant listings, Review snippets, Recipes and Videos.

Two caveats from that page are worth memorising. First, a report appears only when Google finds valid markup of a supported rich result type, so no report does not mean no markup. Second, the reports show a sample of detected items rather than a complete list, and their numbers count items, not pages.

Each report splits items into valid and invalid. An invalid item has at least one critical issue that prevents it from appearing as a rich result. A table of non-critical issues, labelled Improve item appearance, lists problems on items that are still valid. After you fix a template, start validation from the issue's page so Google rechecks the affected URLs, and use the URL Inspection tool to check a URL that is missing from the report.

These reports are where template regressions surface. A theme update that drops a property shows up as a rising invalid count across hundreds of items, which no amount of single-page testing would reveal in time.

05What is the difference between errors and warnings?

An error, called a critical issue in Search Console, makes an item invalid: it cannot appear as that rich result until it is fixed. A warning, a non-critical issue, leaves the item valid but flags a missing recommended property or a value that could be better. The Rich Results Test uses the same split, reporting items as valid, valid with warnings, or invalid.

Do not chase every warning. A warning for a missing recommended property is a suggestion, and filling it with invented data creates a bigger problem than the warning it removes. Fill a recommended property only when the page genuinely shows that information.

Syntax errors are different and always worth fixing. The help page lists the parsing errors behind them, such as a missing comma or brace, an invalid number, or a bad escape sequence in a string. On WordPress, one common source is JSON built by joining strings in PHP; encoding a PHP array with wp_json_encode() avoids the whole class of error.

06What do AI crawlers see when they fetch your page?

Google renders pages. Its JavaScript structured data guide says Google Search can understand and process structured data that is available in the DOM when it renders the page, which is why the Rich Results Test shows JSON-LD added by Google Tag Manager or a front-end script.

Other crawlers do not all document the same behaviour. The crawlers that fetch pages for AI answer engines, identified by user agents such as OAI-SearchBot, GPTBot and PerplexityBot, are described in their operators' own documentation, and where JavaScript rendering is not documented the cautious assumption is that only the raw HTML response is read. Our guide to how ChatGPT and Perplexity read structured data covers each crawler in more detail.

The test is simple: fetch the page without a browser and look for the script block.

1. Run curl -s https://example.com/your-post/ | grep -c 'application/ld+json' to count the JSON-LD blocks in the raw HTML.
2. Compare the count with the items the Rich Results Test found. If the test finds markup that curl does not, that markup is injected by JavaScript.
3. Repeat with a crawler user agent, for example curl -s -A 'PerplexityBot' https://example.com/your-post/, to catch caching or security layers that serve bots a different page.
4. Read the block itself, not only the count, and check that its values match the visible page.

On WordPress the fix for injected markup is to move JSON-LD generation from a tag manager or front-end script into PHP. Markup printed through a WordPress hook is part of the HTML response that every crawler receives; markup added in the browser exists only for crawlers that render.

07A testing workflow for WordPress

Put the tools in order and most problems surface before they reach Search Console.

Test templates, not posts. On WordPress one template produces hundreds of pages, so pick one URL per template, such as a post, a page, a product and a category archive, and run the full workflow on each after any theme, plugin or WordPress update. Keep a dated note of each run: the URL, the template, the tool and the result. When a report changes weeks later, that log tells you whether the markup changed or Google's reading of it did.

When something tests clean but still does not show, move to the checklist for rich snippets that stop showing. When several plugins print markup, run the schema plugin audit before you fix anything, so you know which block each tool is reading.

Testing is one part of keeping structured data healthy on a WordPress site; the rest of the how-tos, from hand-written JSON-LD to WooCommerce, are in the WordPress section.