Technical pillar / check schema-validation

JSON-LD validity (schema.org spec conformance)

Every JSON-LD block on the page should declare @context (https://schema.org), declare a @type, and parse as valid JSON.

By Shimon Carroll, Founder, SEO for AI Agents · Last updated

What this check measures

For each <script type="application/ld+json"> block we attempt to parse the payload, confirm @context resolves to https://schema.org (or an https://schema.org subgraph), and confirm a @type is declared. We do NOT validate every required property of every type at this stage; that depth lives in per-type checks (LocalBusiness, MedicalBusiness, LegalService, LoanOrCredit, RealEstateAgent).

Why it matters

Schema is the structured-data signal that classic Google uses for rich results and that AI engines (ChatGPT, Claude, Perplexity, Gemini) use to triangulate entities and topical claims. A malformed JSON-LD block (trailing comma, missing quote, broken @context) is silently dropped by every consuming engine; the page reverts to unstructured signal. The cost of a broken block is the same as having no schema at all, with the added downside of false confidence on the engineering side.

How we score it

PASS if every JSON-LD block parses, declares @context resolving to schema.org, and declares a @type. FAIL if any block fails any of the three. Severity defaults to MEDIUM. Vertical adapters frequently bump this to HIGH on critical pages (LoanOrCredit for MCA, MedicalBusiness for doctors, LegalService for lawyers, RealEstateAgent for real estate).

Confidence-flag rules

Confidence is HIGH for all outcomes; JSON-LD blocks are static in the HTML and parsing is deterministic. The only MEDIUM-confidence case is when the page returns gzip but the response is decoded partially due to truncation; we suppress the finding in that case rather than emit a low-confidence false positive.

Common mistakes

  • Hand-writing JSON-LD in a template and forgetting to escape a quote in a string field, breaking the parse.
  • Setting @context to "http://schema.org" instead of "https://schema.org"; the http variant still parses but Google has documented a preference for https.
  • Declaring @type as a string when the schema requires an array (multiple types) or vice versa.
  • Embedding JSON-LD inside a noscript block, making it invisible to both classic and AI crawlers.

How to fix it

Generate JSON-LD from server-side helpers (typed TypeScript objects passed through JSON.stringify) rather than hand-writing JSON in templates. Use the Schema Markup Validator (schema.org's own tool) and Google's Rich Results Test to verify each page type. For Next.js, render the JSON-LD inside a Server Component via dangerouslySetInnerHTML with a JSON.stringify of a typed object.

Primary sources

Changelog

  • · Initial publication. We validate against the live schema.org JSON-LD vocabulary, not a 2020 snapshot.
← Back to the methodology indexRun an audit