How to Ship Valid Schema Across Hundreds of Pages

Schema stops being a markup problem and becomes a systems problem somewhere around page fifty. One page's JSON-LD can be checked by eye; four hundred pages' cannot, and the failure mode is not one broken block but the same broken block replicated everywhere. This is how we generate and validate it across a fleet, including the defect class that taught us to check the output instead of the input.

How do you ship valid schema across hundreds of pages?

By making markup a byproduct of publishing rather than a task inside it. On our builds one YAML frontmatter block per page is the single source of truth: it renders the visible answer and takeaways, and the same fields emit the JSON-LD. A writer drops an MDX file in the right folder and the markup happens [our data].

Generation model as run across 400+ pages on 3 production builds [our data].

The dependency column is the reason generation beats authoring. Google's rule is that structured data must not describe "information that is not visible to the user, even if the information is accurate" — and a generated node cannot violate that rule unless the template does, at which point you fix it once. The per-type setup detail for the editorial node lives in Article schema setup, and the glossary case, which is the one type we can tie to a documented citation, is in DefinedTerm schema strategy.

Why does hand-authored markup fail at scale?

Because pages change and pasted blocks do not. Every hand-authored JSON-LD block is a snapshot of the page as it was on the day someone pasted it: the headline gets rewritten, the date moves, a section is cut, and the markup keeps describing the old page. Multiply by a few hundred pages and by however many people have edited them, and you have a body of markup nobody can vouch for.

The second failure is divergence between pages. Twelve writers hand-authoring Organization nodes produce twelve slightly different companies — different names, different URLs, different missing properties — which is the opposite of the entity clarity the markup exists to provide. Generation makes divergence impossible by construction, which is the same argument that makes canonical stances necessary for prose in publishing 60+ pages in parallel.

What breaks when you generate JSON-LD?

Escaping, almost every time. Prose fields carry quotes, apostrophes, newlines and angle brackets; a naive string-concatenation template drops them straight into a JSON document and produces something that no longer parses. The nastiest variant is a literal </script> sequence inside a string value, which terminates the script element early and leaves the rest of your markup rendering as text on the page.

We learned to gate for this rather than review for it. On our auto-finance build, a full adversarial review executed against the first 67-page tranche listed JSON-LD escaping among its findings, alongside the renderer defects the same build's output-gate lesson names: ordered lists shipping as run-on paragraphs, and literal asterisks appearing on 35 pages [our data]. Every one of those defects was invisible at the source layer, because the source was correct; the rendering was not.

Two rules came out of it. Serialize with a real JSON serializer and escape angle brackets on the way out, so no prose value can end the block. And run an output gate: render every page in CI, extract every JSON-LD block from the built HTML, parse it, and fail the build on anything that does not survive the round trip [our data]. Reviewing templates is not the same as reading output — the same lesson the visible-versus-markup layer teaches in JSON-LD vs visible HTML.

What should the gate actually check?

Four things, in increasing order of usefulness. That every block parses as JSON. That every node carries the required properties for its declared type. That every @id reference resolves to a node that exists — an Organization reference pointing at nothing is valid JSON and useless markup. And that the values match the page: a headline in the markup that no longer matches the rendered H1 is the drift problem returning through the back door.

What a gate cannot check is whether the type was the right choice in the first place. That stays a human decision made once per page shape, and getting it wrong is expensive at scale — we shipped an entire library on the wrong Q&A type before catching it, which is the correction documented in Article schema setup.

Does more markup mean more citations?

No, and the volume is exactly what makes that worth stating. Ahrefs tracked 1,885 pages adding JSON-LD between August 2025 and March 2026 against roughly 4,000 matched controls and found no meaningful AI citation lift; Google's own generative-AI guidance says "structured data isn't required for generative AI search, and there's no special schema.org markup you need to add." Four hundred pages of immaculate markup buys four hundred pages of eligibility for Google's rich-result pipeline and nothing in the answer layer.

Which sets the correct budget. Once the generation and the gate exist, the marginal cost of markup on the next page is effectively zero, and zero is the right price for a benefit this narrow. The work is paid once, in the contract and the gate — the same one-time cost that makes everything else in our generative engine optimization guide affordable at volume.

Against our own interest: if you have fewer than about thirty pages, none of this applies. Write the markup by hand, check it once, and spend the engineering time elsewhere — building a generation pipeline for a twenty-page site is infrastructure cosplay, and we would tell a prospective client the same thing before quoting them for it.