JSON-LD Example: Invalid Structured Data
My deposition to the Sultan omitted one comma, and his Tokay cellar has been in dispute ever since.
The short answer
- What it is
- Structured data errors happen when JSON-LD cannot be parsed, or when a rich result type lacks a required property. Both stop the markup from doing its job.
- Why it matters
- Search engines may ignore invalid markup, so the page can lose its chance at a rich result. Broken data can also send wrong facts to other tools that read it.
- How a crawler should report it
- Report each invalid block with the page URL, the parse error and its position, or the type and the name of the missing property. Keep syntax errors separate from missing property warnings.
- Live examples
/lab/structured-data-issues/invalid-json/(positive)/lab/structured-data-issues/missing-required/(positive)/lab/structured-data-issues/near-miss/(near miss)
One Stray Comma Can Void a Whole Block of Schema Markup
A JSON-LD example makes the rules easy to see. Structured data lives in a script tag with the type application/ld+json. It holds a JSON object with @context set to https://schema.org and an @type such as Article. JSON is strict. A trailing comma, an unescaped quote inside a value, or a comment will break the whole block. Templates that paste user text into the markup are a common cause.
Browsers do nothing with this block, so a broken one will not change how the page looks. That is why errors can sit for a long time. A search engine that cannot parse the block will skip it. A block can also parse correctly and still fail. For its product snippets, Google wants a Product to have a name and at least one of offers, review, or aggregateRating.
Detection takes two steps. First, parse each block as JSON and record any error. Second, compare each type with the required properties for the rich result you want. Google's Rich Results Test checks that eligibility for one URL. The Schema Markup Validator at schema.org checks the vocabulary in general. Valid markup is no promise of a rich result, because Google decides when to show one.
To fix syntax errors, build the data as an object in your code and let a JSON library write it out. Do not build it by joining strings. This handles quotes and line breaks for you. Add each missing property, and only mark up facts that are visible on the page. Remove any type you cannot support with real data. Then retest a sample of each template, since one bad template can affect thousands of URLs.