You publish a product page, add an FAQ block, or ship a new article template. A week later your star ratings vanish from the search results, or an FAQ snippet that used to show up stops appearing. You open Search Console's structured data report and it tells you there's an "Invalid item" or a vague warning about a missing field. It doesn't tell you which field, in which template, on which of your 400 pages.
This is the normal experience of debugging structured data, and it's worse than it needs to be. Most of the pain isn't the schema itself. It's not knowing how to read the errors, not testing before deploy, and not understanding that Google's validator and its rich results eligibility check are two different systems with two different bars to clear.
Why Search Console's Structured Data Reports Are Vague by Design
Search Console aggregates errors across your entire site and reports them by error type and page count, not by exact broken value. If forty pages share a template and the template has a bug, you get one error type with forty affected URLs and a sample of three. That's useful for scale, useless for figuring out what's actually wrong with the code.
The report also lags. Google recrawls and reprocesses pages on its own schedule, so a fix you shipped this morning might not show as resolved for several days. Teams see the error still listed, assume the fix didn't work, and start changing things that were already correct. Before you touch anything, confirm the report's "last crawled" date is actually after your deploy.
Photo by Yan Krukau on Pexels
Syntax Errors vs. Validation Warnings vs. Eligibility Failures
These are three different failure modes and they need different fixes.
Syntax errors mean the JSON-LD itself is malformed: a trailing comma, an unescaped quote inside a string, a missing closing brace. JSON itself is a strict format, and any block with a syntax error is discarded entirely by parsers, structured data and all. Run your rendered page source through a plain JSON linter before you even look at schema-specific tools. If it's not valid JSON, nothing else matters yet.
Validation warnings mean the JSON parses fine, but a required or recommended property is missing, wrong type, or malformed, like a datePublished that isn't ISO 8601, or a Review without a reviewRating. The page still has structured data; it's just incomplete against the schema.org type definition.
Eligibility failures are the trickiest. The markup can be fully valid schema.org JSON-LD and still not qualify for a rich result, because Google layers its own policy requirements on top of the spec: content visibility, page quality signals, and per-feature rules that change over time. Valid markup is necessary but not sufficient for rich results.
Reading a JSON-LD Block Without Guessing
Open the page's rendered HTML (not the template source, the actual output after any client-side rendering) and find the <script type="application/ld+json"> block. Copy just that block, nothing else, into a standalone JSON viewer to confirm it parses. Then check three things in order:
@contextand@typeare present and spelled exactly as schema.org defines them."@type": "Product"is correct;"@type": "product"will fail silently in some parsers and pass in others, which is exactly the kind of inconsistency that makes bugs hard to reproduce.- Required properties for that type are all present. Schema.org's own type pages list required vs. recommended properties for common types like
Product,Recipe, andFAQPage. - Nested types resolve correctly. An
AggregateRatingnested inside aProductneeds its own valid@type,ratingValue, andreviewCount. A common mistake is nesting a plain object without the@typefield, which makes it invisible to the parser as a typed entity.
Common Mistakes That Pass Syntax Checks But Still Fail Rich Results
A block can be syntactically perfect JSON and still not earn a rich result. The usual suspects:
Markup that doesn't match visible content
Google requires that structured data reflect what a user actually sees on the page. If your FAQPage schema lists five questions but only three are visible in the rendered HTML (the other two were removed from the design months ago and nobody deleted the schema), that's a mismatch, and it's one of the more common reasons rich results get suppressed without an explicit error.
Client-side rendering the crawler never sees
If your JSON-LD block is injected by JavaScript after initial page load, and your rendering pipeline doesn't wait for it, some crawl paths will index the page before the script runs. Test with the rendered DOM, not the page source you'd see from "view source," which shows the pre-render HTML.
Duplicate or conflicting schema on the same page
Two plugins, or a template plus a manual override, both emitting Organization schema with different logo or sameAs values. Parsers don't merge conflicting duplicates gracefully; they either pick one arbitrarily or the page ends up with contradictory signals.
Placeholder or template values that never got replaced
"name": "{{product_name}}" shipped to production because a templating bug swallowed the substitution silently. This passes basic JSON validation every time, because it's syntactically valid, just semantically wrong.
Testing Structured Data Before It Reaches Search Console
The fastest feedback loop is local, not waiting on Google's crawl schedule.
- Pull the rendered HTML for a representative page from each template (don't just test the homepage) and check the JSON-LD block against schema.org's vocabulary for required fields on that type.
- Automate a check in CI that greps rendered output for
application/ld+jsonblocks and confirms they parse as valid JSON on every build. This catches syntax errors before they ever ship, which is the cheapest place to catch them. - Spot-check with Google's Rich Results tool against a live or staged URL before a template change goes out broadly, not after.
- Keep a small fixture file of "known good" structured data per template so a diff against it flags accidental removals during refactors.
- When you're unsure whether a property is required or merely recommended for a given type, check the type definition directly rather than guessing from an old blog post; schema.org's spec changes and gets extended over time, most recently maintained under the stewardship of the W3C community process.
"The teams that stop getting burned by structured data are the ones who test it in CI like any other contract, not the ones who check Search Console more often." - Dennis Traina, founder of 137Foundry
Debugging Nested and Multi-Type Schema
Pages that combine multiple schema types, a Product with a nested Offer and an AggregateRating, or an Article with an embedded Person for the author, fail in more subtle ways because an error in the nested object doesn't always surface clearly at the parent level. Isolate the nested block and validate it on its own first, then reattach it and validate the whole structure again. If the whole thing fails but the pieces pass individually, the bug is almost always in how they're connected, a missing @type on the nested object, or an array where a single object was expected.
Multi-type pages are also where the "matches visible content" rule bites hardest, because there's more surface area for the data and the DOM to drift apart over time as the page gets redesigned and nobody revisits the schema.
Photo by Mathias Reding on Pexels
Photo by Liudmyla Honcharova on Pexels
What to Do When Google Ignores Valid Structured Data Anyway
Sometimes the markup validates cleanly, matches the visible content, and still doesn't produce a rich result. This isn't always a bug on your end. Google reserves the right to withhold any rich result based on broader page quality signals, seasonal feature availability, or policy changes that aren't always documented at the moment they roll out.
Before assuming it's a Google-side issue, rule out the checkable causes: confirm the page isn't blocked by robots.txt or a noindex tag (structured data on a non-indexable page is ignored), confirm the URL in Search Console matches the canonical version of the page, and confirm you're not looking at cached validator results from before your fix. Only after those are ruled out is it reasonable to treat it as a Google-side eligibility decision outside your control.
Photo by Bahram Yaghooti on Pexels
A Structured Data QA Checklist for Every Deploy
Treat this like any other pre-deploy check, not a one-time setup task:
- JSON-LD parses as valid JSON on the rendered page, not just the template source
@typevalues match schema.org's exact casing and naming- All required properties for each type are present and correctly typed
- Nested objects have their own
@typedeclarations - Markup content matches what's visible in the rendered DOM
- No duplicate schema blocks emitting conflicting values for the same entity
- No leftover placeholder or templating syntax in production output
- Page is indexable (no
noindex, not blocked byrobots.txt)
Run this after every template change, not just after a full redesign. Most structured data regressions come from small template edits, not big rebuilds.
When It's Worth Bringing in Outside Help
If your structured data errors span dozens of templates, or the CMS makes it hard to see rendered output before publish, this becomes a recurring maintenance problem rather than a one-time fix. That's usually the point where a broader technical SEO services engagement pays for itself: someone building the CI checks, the fixture tests, and the render-time validation once, instead of every team member rediscovering the same debugging process every time a rich result disappears.
137Foundry's web development team builds this kind of structured data QA directly into client deploy pipelines as part of our broader services, so schema regressions get caught before they ship instead of a week later in a vague Search Console report. If you want to know more about how we work or what else we handle, our about page has the details.
Structured data debugging isn't mysterious once you separate the three failure modes and stop trusting the aggregate report to tell you exactly what broke. Read the rendered JSON-LD directly, test it before it ships, and keep a checklist that catches the boring, repeatable mistakes before they cost you a rich result.
