Schema Debugger Fixes: Every Finding, One Place
Structured data tells search engines and AI tools what a page is about: a product and its price, a recipe and its cooking time, a set of questions and answers. When the markup is wrong, the page loses the rich results it could have earned and the machines reading it get a muddled picture.
The Schema Debugger finds those problems and sorts them by how much they matter. This page explains what each kind of finding means, which to fix first, and which of our guides fixes it.
Errors, warnings and recommended fields
Every finding falls into one of three levels. Knowing the level tells you how urgent the fix is.
| Level | What it means | Effect | Fix |
|---|---|---|---|
| Error | A required property is missing, a value has the wrong type, or the JSON cannot be read at all. | The item is not eligible for rich results. If the JSON is broken, nothing in that block is read. | First, always. |
| Warning | A recommended property is missing or has a value Google cannot use. | The item can still be eligible, but the result shows less. | Second, starting with the fields that change the display. |
| Recommended field | A schema.org property that no search feature requires but that describes the page more completely. | No change to eligibility; clearer understanding for search engines and AI tools. | Third, where the information is genuinely on the page. |
Google's Rich Results Test uses the words "critical" and "non-critical" for the first two levels; the Schema.org validator reports problems against the vocabulary itself rather than against any search feature. The Schema Debugger shows both views, so you can see whether a finding blocks a rich result or only makes the markup less complete.
The fix guides
Each guide covers one kind of finding or one schema type from start to finish: what the finding means, what causes it, a corrected example, a step-by-step fix and the questions people ask most.
By level
Fixing blocking schema errors covers the problems that stop markup working: JSON that will not parse, missing required properties, values of the wrong type, dates in the wrong format and addresses that are not full URLs. Fixing schema warnings covers the missing recommended properties that make a result plainer than it could be, such as images, descriptions, brands and ratings. Adding recommended fields covers the wider schema.org vocabulary that helps search engines and AI tools understand who wrote a page, who publishes it and what it is about.
By schema type
Fixing aggregateRating covers star ratings: the rating and review counts, the scale, where ratings may appear, and why ratings a business writes about itself are not shown. Fixing Product schema covers offers, prices, currency, availability and the difference between product snippets and merchant listings. Fixing Recipe schema covers the required name and image, and the ingredients, steps, times and yield that make a recipe result useful.
Fixing FAQPage schema covers question and answer markup, which must match text visible on the page, and explains that Google now shows FAQ rich results mainly for well-known government and health sites. Fixing HowTo schema covers step markup, which Google no longer shows as a rich result but which still describes a process clearly to other search engines and AI tools.
By platform
The platform guides cover where the markup comes from and how to change it: WordPress, where SEO plugins and themes can both output schema; Shopify, where the theme, product data and apps all contribute; and headless and custom builds, where the markup must be in the HTML the server sends rather than added later in the browser.
The most common findings
A small number of problems account for most of what the Schema Debugger reports. Find the finding, then open the guide.
| Finding | Usual cause | Guide |
|---|---|---|
| JSON could not be parsed | A trailing comma, a missing comma, a stray quote or a comment inside the block. | Blocking errors |
| Missing required property | A plugin or template that leaves out a field the type needs, such as a Product with no offers, review or rating. | Blocking errors |
| Invalid date or time | A date written as text, or without the full ISO 8601 form. | Blocking errors |
| Invalid URL | A relative path where a full https address is needed. | Blocking errors |
| Missing image | No image on an Article, Product or Recipe. | Warnings |
| Rating not eligible | A rating on the business's own Organization or LocalBusiness, or a rating not shown on the page. | aggregateRating |
| Price or currency missing | An offers block without price and
priceCurrency. | Product |
| Markup not matching the page | Questions, reviews or prices in the markup that visitors cannot see. | FAQPage, aggregateRating |
| Duplicate or conflicting blocks | A theme and a plugin both outputting the same type with different values. | Platform guides |
What correct markup looks like
Most fixes end with markup that follows the same pattern: one JSON-LD block in the head, every value taken from the visible page, full URLs, full dates, and one clear main item. This Product example has no errors and no warnings:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Product",
"name": "Oak Garden Bench, 150 cm",
"image": "https://example.com/images/oak-bench-150.jpg",
"description": "A solid oak bench seating three, finished with outdoor oil.",
"sku": "OGB-150",
"brand": { "@type": "Brand", "name": "Northwood Furniture" },
"offers": {
"@type": "Offer",
"url": "https://example.com/products/oak-garden-bench-150",
"price": "349.00",
"priceCurrency": "GBP",
"availability": "https://schema.org/InStock",
"itemCondition": "https://schema.org/NewCondition"
}
}
</script>Four habits prevent most findings:
- Generate markup from the same data as the page. Prices, ratings and answers typed into the markup by hand drift away from the page and become errors.
- One source of markup per type. If a theme and a plugin both output Product or Organization markup, switch one off.
- Full values. Full https URLs, full ISO 8601 dates with a time and time zone, and
currency codes such as
GBP. - In the server's HTML. Google can read markup added by JavaScript, but later and less reliably, and many other crawlers and AI tools cannot read it at all.
Which checking tool to use
Several tools check structured data, and each answers a slightly different question. Using the right one saves time.
| Tool | What it tells you | Best for |
|---|---|---|
| Schema Debugger | Every JSON-LD block on the page, with errors, warnings and recommended fields, and why each matters. | Finding and fixing everything on a page in one pass. |
| Google Rich Results Test | Whether Google considers the page eligible for the rich result types it supports. | Confirming eligibility for a specific Google feature. |
| Schema Markup Validator | Whether the markup follows the schema.org vocabulary, for any type. | Types Google has no rich result for, such as Person or WebSite. |
| Google Search Console | Errors and valid items across the whole site, updated as Google recrawls. | Watching fixes take effect over time. |
A page can pass the Rich Results Test and still have problems the Schema Markup Validator reports, because the Rich Results Test only looks at the types Google uses for rich results. Checking both, or using the Schema Debugger which shows both views, avoids surprises.
A sensible order of work
- Run the page through the Schema Debugger and note every finding and its level.
- Fix anything that stops the JSON being read. One broken comma can hide every other problem in that block.
- Fix the remaining errors, starting with the main item on the page.
- Fix the warnings that change what a result shows: images, prices, ratings and dates.
- Remove markup that does not match the page, such as hidden reviews or answers, and duplicate blocks from a second plugin.
- Add recommended fields where the information is genuinely on the page.
- Test again, then check the enhancement reports in Google Search Console over the following weeks as Google recrawls the page.
For the full reference on how the debugger reads a page, see the Schema Debugger Guide, or see a finished report in the example report.
1. What is the difference between a schema error and a warning?
An error means a required property is missing, a value has the wrong type or the JSON cannot be read, and the item is not eligible for rich results until it is fixed. A warning means a recommended property is missing or unusable: the item can still be eligible, but the result shows less. Fix errors first, then the warnings that change what the result displays, such as images, prices and ratings.
2. Does valid schema guarantee a rich result?
No. Valid markup makes a page eligible, but Google decides whether to show a rich result based on the page, the search, the site and its own policies. Some types are also limited: Google stopped showing HowTo rich results and now shows FAQ rich results mainly for well-known government and health sites. Markup that is valid and matches the page is still worth having, because it describes the page clearly.
3. Why does the Schema Debugger say my JSON cannot be parsed?
Because something in the block breaks the JSON format, so nothing in it can be read. The usual causes are a trailing comma after the last item in a list or object, a missing comma between items, a straight quote inside a text value that has not been escaped, or a comment, which JSON does not allow. Fix the parse error first, because it hides every other problem in that block.
4. Why are my review stars not showing in Google?
Usually because the rating is on a type Google does not show stars for, or because the rating breaks its rules. Ratings that a business publishes about itself on its own Organization or LocalBusiness markup are not shown. Ratings must also be visible on the page, have a valid value and count, and describe the item the page is about. The aggregateRating guide covers each of these checks in turn.
5. Should schema be added with JSON-LD or with JavaScript?
Put JSON-LD in the HTML your server sends. Google can read markup that JavaScript adds after the page loads, but it does so later and less reliably, and many other search engines, social platforms and AI tools do not run JavaScript at all, so they never see it. If your site is built with a JavaScript framework, render the JSON-LD on the server or pre-render the pages, then check the page source to confirm it is there.
6. Why do I have two conflicting schema blocks on one page?
Usually because two tools output markup for the same thing: a theme and an SEO plugin, two SEO plugins, or a platform and an app. Each adds its own Product, Organization or WebPage block, often with different values, and search engines may use either. View the page source, find which tool writes each block, switch one off, and keep a single, complete and accurate block for each item on the page.
7. How long does it take for fixed schema to show in Google?
Google has to recrawl the page before it sees the new markup, which can take from a few days to several weeks depending on how often the page is visited. You can ask for a recrawl with the URL Inspection tool in Google Search Console. After that, watch the enhancement reports in Search Console, which update as Google processes the fixed pages and show whether the errors have cleared across the whole site.
The Schema Debugger fetches your page, extracts every JSON-LD block, checks it against the schema.org vocabulary and Google's rich result requirements, and lists each error and warning with its cause.
Open the Schema Debugger →