Structured data debugging.
Structured data errors show no symptom on the page; they only become visible through a validation tool or a test.
The most insidious trait of structured data is that it breaks silently. When a schema block goes bad, the page keeps looking normal, no error message appears, there is no visual symptom. Only the machines can no longer read that block — and nobody tells you. The defect can live for months.
That is why schema cannot be validated once after writing and left alone. Validation must be part of the deployment process; otherwise the next content change breaks it silently.
Two layers: syntax and meaning
Debugging has two separate layers, and they catch different things. The first is syntax: is the block a valid data structure, can it be parsed? A single missing comma or an unescaped quote invalidates all the structured data on that page — there is no such thing as a partial read.
The second is meaning: does the resulting list of nodes describe what the site actually is? A graph with flawless syntax and meaningless content is technically valid and serves no purpose. Validation tools catch the first layer automatically; the second requires human judgment.
- Syntax — does the block parse? Automated tools catch this.
- Required fields — are the fields the type demands filled? Automated tools warn.
- Format — are date, duration and number fields in the expected form? Automated.
- Identity links — are the referenced identities actually defined? Partly automated.
- Consistency with the screen — is what the schema says also on the screen? HUMAN judgment.
- Meaning — does the graph describe the site correctly? HUMAN judgment.
The last two rows are the most important, and no tool covers them. A fact present in the schema but absent from the screen shows green in a validation tool — because the tool does not read the page, only the block. That violation is caught only by a human or a purpose-written test.
Common breaking points
The recurring errors on real sites are well known, and most are born from content changes.
Unescaped special characters. A quotation mark or backslash in the content, written straight into the schema block, breaks the structure. It is the most frequent cause of breakage in hand-written schema and never appears in generator-produced schema — because escaping is automatic there.
Fields left empty. When a content field is deleted, an empty value can remain in the schema. An empty field is worse than an absent one: it looks like the type is filled but carries no information.
Broken identity references. A node can point at the identity of a node that is no longer generated. The graph stays technically valid, but the link leads nowhere and the structure dissolves.
Stale dates. The page gets updated; the date in the schema stays. That falsifies the freshness signal, and over time leads the engine to stop trusting it.
The lasting fix: wiring it to a test
Manual validation works exactly once. The lasting fix is wiring the schema check into the deployment process: every page’s blocks are parsed, the node types are listed, and the result is compared against the expected structure.
On this site that check lives inside the verification suite. On every run it measures that each route’s schema graph carries the expected nodes, that no identity link is broken, and that the question-and-answer blocks on screen match the schema. If a content change breaks the schema, the defect shows at deployment time — not at the next audit.
And the most valuable kind of test is the reverse guard: the test verifying that something which should not exist has not been added. A fabricated profile link, an unmeasured result figure, an unpublished price — all three can be added in good faith, and all three are rule violations. The reverse guard audits future good intentions too.
Validation tools and their limits
A few tools are available, and each answers a different question. Schema.org’s own validator checks syntax and type validity — it has the broadest scope. The search engines’ rich result test tools ask a narrow question instead: is this block sufficient for us to produce a rich result? The two are different things, and one can pass while the other fails.
This distinction confuses in practice. Getting a “not eligible” warning in a rich result tool does not mean the schema is broken — it only shows that the fields that engine wants for that appearance are missing. The schema can still be valid and still do its work for answer engines.
- General validator — syntax and type validity. Broadest scope.
- Rich result test — sufficiency for one specific appearance. Narrow scope.
- Search console reports — errors detected on live pages. Delayed but real.
- Your own test — project-specific rules. Asks the questions the tools do not.
The fourth row is the most valuable because it fills the gap the other three leave: that the information in the schema also exists on screen, that no fabricated field has been added, and that the dates are genuinely current — none of it can be audited by a general tool, and all of it can be audited by a test.
The debugging order
When a page is suspected of a schema problem, following an order saves time. First, is the block actually on the page — look at the source and confirm it exists; in a surprising number of cases the block is stuck behind a condition and never printed. Then, does it parse — paste it into a validator. Then are the types right, are the fields filled. Last, is it consistent with the screen.
When this order is skipped, the most common mistake is spending hours at the meaning layer only to discover late that the problem was a simple syntax break. The first two steps take a minute and resolve the majority of cases.
And every error solved once should be turned into a test. Nearly all schema breakage recurs — because its causes are structural, not accidental. An escaping error that happened once will happen again; a test that catches it means never spending those hours twice.