JSON-LD Validator Field Guide: Catching the Schema Markup That Costs You Rich Results

Structured data is the most failure-prone piece of "invisible" SEO work. A single misplaced comma, a date in the wrong format, or a missing image field can quietly disqualify a page from rich results for weeks before anyone notices the traffic drop.

The Structured Data Inspector (formerly "JSON-LD Validator") is the fast pre-flight check we run on every page we ship. This guide is the operator's notes: what shallow validation actually buys you, when to escalate to a full schema.org check, and how to read the per-block report without misreading it.

What the inspector checks

The inspector extracts two structured-data formats from the page and reports on each block independently:

JSON-LD — every <script type="application/ld+json"> block. Each is parsed, and the @type is matched against a known set.
Microdata — every element with an itemscope attribute, plus its itemtype and itemprop children.

For each block, the inspector reports three things:

The detected @type (or the equivalent Microdata itemtype).
Whether the block parsed at all (valid JSON, present itemtype).
The status of the fields that schema.org or Google specifically cares about — required fields, recommended fields, and format-sensitive fields (dates, URLs, numbers).

The check is structural, not exhaustive. The inspector confirms the block exists, the @type is known, the JSON parses, and the obvious required fields are present. It does not run the full schema.org spec.

What the inspector does not check

A few things that look like validation work but live elsewhere:

Full schema.org compliance — the full spec is thousands of rules across hundreds of types. The inspector covers the rules that catch real-world errors, not the ones that are technically correct.
Google rich-result eligibility — Google has additional requirements (image quality, publisher eligibility, spam policies) that only surface in Search Console. The inspector can confirm your block is well-formed; it cannot guarantee Google will show a rich result.
Cross-block consistency — if your page has an Organization block and a WebSite block, the inspector does not verify that the url in one matches the url in the other. That is a hand-audit.
Live rendering — the inspector parses the HTML, not the rendered DOM. If your JSON-LD is injected by client-side JavaScript, the inspector will not see it unless it is already in the source HTML.
AMP-specific extensions — application/ld+json inside AMP pages is valid, but the inspector parses the standard format. Use the AMP validator for AMP-specific extensions.

If a block passes the inspector, it is structurally sound. If it fails, something is wrong that you can fix in the source. That is the entire contract.

When to run it

Three moments, in the order they catch real bugs:

Before launch, on the production URL, after the CMS template is locked. JSON-LD regressions usually come from template changes, not from the schema content itself.
After any change to the head or schema-injection logic — a CMS upgrade, a plugin swap, a redesign, a new product type that needs a new @type block.
When diagnosing a specific complaint — a Search Console report showing structured-data errors, a sudden drop in rich-result impressions, or a partner noting that a page is missing a knowledge-panel entry.

Don't run it in CI on every commit. The inspector makes a network call, and a passing result today does not guarantee a passing result tomorrow. Save it for the moments above.

Reading the output

The result page has three sections: a summary (block count by format), a per-block card, and a per-field report. A few things to keep in mind:

A green block card means the block parsed, has a known @type, and is missing no required fields. It does not mean Google will index it as a rich result.
An amber block card means some required or recommended fields are missing. Look at the field-level report to see which ones.
A red block card means the block did not parse at all — invalid JSON, missing itemtype, or another structural problem. The block is doing nothing for SEO and is probably also breaking some downstream consumer.
The field-level dots — green = present and well-formed, amber = present but with a format issue, red = required and missing, grey = recommended and missing. The "required" / "recommended" tag tells you which it is.

The two formats that catch the most real-world bugs: ISO 8601 dates and well-formed URLs. If your @datePublished is "2026-07-11 14:30" instead of "2026-07-11T14:30:00Z", the inspector will flag it amber. Fix the format; do not silence the warning.

Common failures and how to fix them

A short list of the failures we see most often, in the order we see them:

1. Invalid JSON from a CMS template that concatenates strings into a JSON-LD block. This is the most common cause of a red block. The fix is to build the JSON-LD object as an actual data structure (an array, an object) and serialize it once at the end — not to concatenate strings.

2. A datePublished in the wrong format. A common variant is "July 11, 2026" (human-readable) when schema.org requires ISO 8601. The inspector flags this amber. Fix: pass the date through a serializer that emits ISO 8601, not a string-formatting helper.

3. A logo field as a string when the type expects an ImageObject. This is the inverse of the common bug — for Organization, the logo field accepts both. For other types, it may not. The inspector handles both correctly for Organization; for other types, check the spec.

4. A missing image field on Article or NewsArticle blocks. Google uses this for the article rich result. A block without image will not show a rich result, even if every other field is correct. The inspector flags it grey (recommended) — do not ignore it.

5. A sameAs array with stale social profiles. This is a content problem, not a validation problem, but the inspector surfaces it because the field is recommended. If the profile is dead, remove it; if it is alive, the inspector is just reminding you it is there.

Adding it to a release flow

The cleanest way to use the inspector is to make it one of the last three pre-launch steps, alongside a page-speed check and a content-snapshot diff. A simple flow:

Open the inspector on the staging URL.
Confirm every block on the page passes.
If a block is amber, look at the field-level report and decide whether to fix it before deploy or note it in the launch doc.
Re-run the inspector on the production URL after the deploy lands.
If a block changed @type or field requirements, also re-run Google's Rich Results Test on the production URL.

The inspector is a fast pre-flight, not the final word. Treat it as the check that catches the bugs you can fix in 30 seconds — bad JSON, wrong date format, missing required field. The deeper checks (image quality, policy compliance, eligibility) belong in Search Console and the Rich Results Test.

When to graduate to a custom system

If you are running the inspector more than a few times a week, you are probably at the point where a custom system makes more sense. A few signals that it is time:

You have a large site (hundreds of pages) and you need to audit all of them in parallel, not one URL at a time.
You ship multiple Article types per page and need to validate the array as a whole, not one block at a time.
You have internal templates that generate JSON-LD and you want a CI gate that fails the build on a known regression.
You need to verify cross-block consistency (the url in Organization matches the url in WebSite, the publisher in Article matches the site-level Organization).

In any of those cases, the right move is a custom validator that runs against your CMS or build pipeline, with whatever rules your schema needs. The free inspector is the right starting point, not the final word.

The inspector is at /tools/json-ld-validator. Run it on a staging URL before every launch, and on the production URL after every CMS change. The proxy makes one fetch per audit; nothing is stored, and nothing is sent to a third party beyond the URL you submit.