Online Tool Store
· 5 min read
How to Fix Invalid JSON-LD Structured Data
Manesh Jayawardhana
CIO & Co-founder
Your product pages have had structured data on them for six months and the rich results still haven’t appeared. You paste the markup into a testing tool and get back four warnings and one error, phrased in a way that assumes you already know the vocabulary — something about an expected type, and a property that “may be required” depending on context.
Structured data is one of those areas where the format is simple, the vocabulary is enormous, and the error messages are written for people who already understand both.
What JSON-LD structured data actually is
JSON-LD is a way of embedding machine-readable descriptions of a page’s content in a script tag. It’s ordinary JSON with two special keys: @context, which points at the vocabulary you’re using, and @type, which says what kind of thing you’re describing — an Article, a Product, a Recipe, an Organization.
Everything else is properties defined by that vocabulary. A Product has a name, an offers, a brand. An Article has a headline, an author, a datePublished.
Validation happens at two levels, and confusing them is where most of the frustration comes from. Syntax validation asks whether it’s valid JSON at all — unclosed braces, trailing commas, unescaped quotes. Vocabulary validation asks whether the properties you used exist on that type, whether required ones are present, and whether the values are the right shape. A syntactically perfect block can still be vocabulary nonsense.
Why people get stuck here
- Errors versus warnings. An error usually blocks a rich result. A warning usually doesn’t. Treating them equally wastes time on optional properties.
- Templating breaks the JSON. An apostrophe in a product name, injected unescaped into a template, produces invalid JSON on exactly the pages with the most interesting names.
- Nested types.
authorisn’t a string, it’s a Person or Organization object. This is the most common shape error. - Dates in the wrong format. ISO 8601 is expected; a human-readable date string won’t validate.
- Markup that doesn’t match the page. Structured data describing content that isn’t visible on the page is a policy problem, not just a technical one.
| Error | What It Means | Typical Fix |
|---|---|---|
| Missing required property | The type needs it for rich results | Add it, or reconsider the type |
| Invalid value type | A string where an object belongs | Nest a proper @type object |
| Parse error | The JSON itself is broken | Check for unescaped quotes from templating |
| Unrecognised property | Not part of that type’s vocabulary | Remove it or use the correct name |
What good structured data looks like
It’s valid JSON before anything else
Run a plain JSON parse first. If that fails, every vocabulary error you’re reading is noise from a block that couldn’t be parsed properly in the first place.
It reflects what’s on the page
The markup should describe content a visitor can actually see. Prices, ratings, and availability in the markup should match what’s rendered.
It’s generated, not hand-written per page
Structured data belongs in the template, populated from the same data that renders the visible content. Hand-maintained markup drifts out of sync immediately.
The required properties come first
Optional properties are optional. Get the required set correct for your type before adding anything else.
Common mistakes to avoid
- Copying an example without changing the values. Sample markup left in place on a live page is a genuinely common and embarrassing error.
- Marking up content that isn’t visible. Search engines treat this as a policy violation, not a technical one.
- Multiple conflicting blocks. Two different Product blocks on one page describing different products confuses everything downstream.
- Escaping problems from user-supplied data. Any field that can contain a quote or a backslash needs proper JSON escaping in the template.
- Assuming valid markup guarantees rich results. Validation is necessary, not sufficient — eligibility depends on much more.
How to do it with JSON-LD Validator & Auto-Fixer
Online Tool Store’s JSON-LD Validator & Auto-Fixer validates structured data and previews suggested fixes in your browser, with nothing uploaded anywhere.
- Copy the full contents of the script tag from your page’s source, not from your template file — you want the rendered output.
- Run it through the validator and read the parse result first. Fix syntax before anything else.
- Work through the errors before the warnings; errors are what block rich results.
- Review each suggested fix rather than applying it blindly — the tool can’t know what your page actually contains.
- Apply the change in your template, not on a single page, so it’s fixed everywhere.
- Re-check a page with awkward data — an apostrophe in the title, a missing price — since that’s where templating breaks.
The Schema Markup Generator, the FAQ Schema Builder, and the JSON Viewer all sit alongside this one.
Frequently asked questions
Does valid structured data guarantee rich results?
No. Valid markup makes a page eligible; whether rich results appear depends on the search engine’s own judgement about the page and the query. Invalid markup, however, reliably prevents them.
Should I fix warnings as well as errors?
Fix errors first — they’re what block eligibility. Warnings usually flag recommended-but-optional properties, which are worth adding when the data exists but aren’t urgent.
Is my markup sent to a server?
No. The validator runs entirely in your browser, so the markup — which may describe unreleased products or pricing — stays on your own machine.
Final thought
Parse first, errors second, warnings last, and fix it in the template rather than the page. Structured data problems are almost always template problems wearing a vocabulary disguise.