Validating your schema (and the 5 mistakes that kill it)

You have the entities (Lesson 1) and the code to ship them (Lesson 2). But schema fails silently — a broken block doesn't throw an error, it just gets skipped, and the citation you engineered for never arrives. This lesson is how to confirm it actually works, and the five mistakes that quietly kill it.

Why schema fails silently

There's no runtime error. A malformed or non-compliant block is simply ignored by the parser — your page renders fine, the engine just never sees the entity. Worse, schema that contradicts the visible page can trigger a structured-data manual action, which suppresses the whole site.

So "I added schema" is not the same as "schema is working." You have to verify.

The three-stage validation workflow

1. Before publish — two validators, every template.

• Google Rich Results Test (search.google.com/test/rich-results) — paste a URL or raw code; shows what Google can parse and which rich-result types you're eligible for.
• Schema.org validator (validator.schema.org) — stricter spec validation; catches type and property errors Google's tool quietly tolerates.

Run both on each new template before it ships.

2. After publish — the live reports.

• Google Search Console → structured-data / Enhancements reports — real-world parsing across your live pages, with error and warning counts.
• Bing Webmaster Tools markup validator — matters because ChatGPT Search runs on Bing's index. Most people never check this one.

Look about a week after publishing and clear anything flagged.

3. Ongoing — automate it (you're a dev; use that).

Type your JSON-LD with schema-dts (Google's official TypeScript types for schema.org) so invalid structures fail at compile time:

import type { Article, WithContext } from "schema-dts";

const article: WithContext<Article> = {
  "@context": "https://schema.org",
  "@type": "Article",
  headline: "Choosing your priority surfaces",
  datePublished: "2026-05-29",
  author: { "@type": "Person", name: "Your Name" },
};

Now a misspelled property or a wrong value type is a build error, not a silent production failure. For extra safety, add a CI check that parses each page's JSON-LD and asserts the required fields:

// scripts/check-schema.ts — fail the build if an Article is missing required fields
for (const block of extractJsonLd(html)) {
  if (block["@type"] === "Article") {
    for (const field of ["headline", "datePublished", "author"]) {
      if (!block[field]) throw new Error(`Article missing ${field} on ${url}`);
    }
  }
}

The five mistakes that silently kill it

1. Schema that doesn't match the page. Every date, rating, FAQ, and price in the markup must appear in the visible content. A mismatch is ignored at best and a manual action at worst — this is the single most common cause of structured-data penalties.
2. Invalid JSON. Trailing commas, unescaped quotes, smart quotes pasted from a CMS — one syntax error voids the entire block. Always build it with JSON.stringify (Lesson 2); never hand-write JSON-LD.
3. Missing required properties. An Article with no author or datePublished, a HowTo with no step, a Question with no acceptedAnswer — the type becomes ineligible. Validate against the spec, not vibes.
4. Orphaned entities. An author with no url, or a publisher whose name drifts across pages, means the trust graph from Lesson 1 never forms — you get isolated blocks instead of one attributable source. Keep the Organization byte-identical everywhere (the SITE constant from Lesson 2).
5. Client-side-only schema. Injected after hydration, so the crawler's first fetch sees nothing. Render it server-side, in the initial HTML — especially for the engines that don't execute JavaScript the way Googlebot does.

Your action checklist

• Run every new template through the Rich Results Test and validator.schema.org before shipping
• Wire schema-dts types so bad schema fails at build time
• Check Search Console and Bing Webmaster structured-data reports ~1 week post-publish
• Audit: does each block's data actually appear in the visible page?
• Audit: one consistent Organization; every author links to a live Person page
• Confirm the schema is in the server-rendered HTML (View Source, not just DevTools)

Sidebar — validate the template, not every page. Once a template passes both validators and your CI check, every page using it inherits correctness. Validation is a per-template cost, not a per-page chore — which is exactly what makes shipping schema across hundreds of pages sustainable for a solo founder.

That's the schema trust layer end to end: the types that earn citations, the code to ship them, and the validation that keeps them working. The next module makes these foundations engine-specific — the per-surface GEO tactics for ChatGPT, Perplexity, AI Overviews, and Claude.

→ Next: Module 3 — GEO-specific tactics (coming soon)