How to Debug Schema in Headless / Custom Builds
Headless and custom builds give you full schema control — and full responsibility for what breaks. Distinctive debug patterns: schema missing entirely (monolith would have provided it), data drift (CMS field changes invalidate schema), hydration mismatches affecting JSON-LD. This guide covers headless schema debugging. Pair with schema debugger guide.
Step-by-step: How to debug schema in headless / custom builds
- Inventory expected vs actual schema. List what should be present: Organization, WebSite, Article on blog posts, Product on product pages, FAQPage on FAQs, BreadcrumbList. Audit each page type in Rich Results Test — note which schemas appear, which are missing.
- Fix missing schema. If Article is missing on blog posts: schema helper isn't being called from blog page template. Check page.tsx (Next.js) or equivalent. Likely fix: import buildArticleSchema, call with post data, render via <script>.
- Fix wrong @type values. schema-dts (if used) catches at compile time. Without it: Rich Results Test errors flag wrong @type. Common: using 'BlogPosting' when you mean 'Article' (both valid, but different rich result eligibility); using 'WebPage' when something more specific exists.
- Resolve data drift. CMS field renamed — schema helper still references old name → returns undefined. Validate against actual CMS data: if post.author is undefined, schema's author field is broken. Add validation in schema helper: throw if required field missing.
- Fix hydration-related JSON-LD issues. Rare but possible: schema rendered client-side gets stripped on hydration. Solution: always render schema from Server Components or directly in <head>. Never render schema only conditionally on client.
- Validate every page type. Rich Results Test on representative URL per type: homepage, blog post, product, category, FAQ. Each should show expected schemas. Save baseline.
- Monitor Search Console. Enhancements report shows schema errors per type. Set email alerts. Headless builds regress schema regularly — catch fast.
🔍 Debug headless schema
Find missing, wrong and conflicting schema in your headless build.
Run Schema Debugger →Frequently Asked Questions
Why does headless commerce often have missing schema?
Standard ecommerce platforms (Shopify, WooCommerce) output Product schema automatically. Headless = you implement it. Common oversight: developer builds frontend without considering schema, ships without it. Catches in audit weeks later when traffic drops. Always implement schema before launch.
How do I find which schemas are missing across a headless site?
Crawl with Screaming Frog → enable structured data extraction. Report shows schema per URL. Filter URLs without expected schema. Or: Search Console Enhancements section shows what Google detected — gaps suggest missing schema.
Can schema break from CMS field changes?
Yes — if your schema helper references CMS field names directly, renaming a field breaks the schema. Defence: validate field presence in schema helper, throw or omit field if missing. Type-safe with schema-dts and TypeScript-typed CMS data (Sanity, Contentful with TypeGen).
Best headless schema validation tools?
Rich Results Test (Google) — authoritative for Google. Schema Markup Validator (schema.org/dev/validator) — broader schema.org coverage. Lighthouse SEO audit — basic schema checks. For continuous monitoring: Lumar, ContentKing, or custom CI scripts.
Why does my Next.js JSON-LD pass Rich Results Test but fail Search Console?
Search Console validator is slightly stricter than Rich Results Test. Common gaps: Rich Results Test allows warnings; Search Console can flag those as errors. Address all warnings, not just errors, before deploying.