Computational Marketing

Your coding agent offered to add schema to every page: how to review the pull request before you merge it

A schema PR needs a page-by-page check that every JSON-LD value matches visible content.

· 8 min read
Cover illustration for “Your coding agent offered to add schema to every page: how to review the pull request before you merge it”
Features · November 21, 2026 · 8 min read · 1,692 words

A coding agent’s offer to add schema to every page calls for a code review, even for “just metadata. Every JSON-LD field must match what a visitor can actually read on the page. Schema labels existing facts. When a template supplies a value that is false for a particular page, the agent ships that falsehood at scale.

Why a coding agent's schema PR is a different kind of merge risk

The agent has added structured data across the site, and the diff looks orderly enough to merge. The offer is legitimate in principle. But the change is a mass annotation of facts, so the review must ask more than whether the code works.

An agent can produce files that each pass lint while the codebase drifts. With schema, that can mean a description or author value that makes sense in a shared template but is wrong on individual pages. The template is coherent. The claims are not.

Unlike a broken visual element, an inaccurate field may leave the page looking untouched. The contradiction is still available to an engine reading it, and a model may surface it as a hallucination when citing the page. That changes the review’s unit of attention. The reviewer must check each annotation against its page, because a template change that works does not prove the content is correct.

What AI systems actually do with your JSON-LD

JSON-LD fields express facts in readable text, rather than acting as invisible instructions to trust or cite a page. An author field makes a claim about authorship. An Organization block makes claims about identity. Those claims can reinforce what the page says. An orphaned or template-filled value can instead introduce a competing account of the same subject.

Yet readable markup is not a substitute for visible content. An October 2025 test found near-zero extraction across five engines when data appeared only in JSON-LD, Microdata, or RDFa. Ahrefs’ controlled test found no measurable rise in citations, and the only statistically significant change was a drop. Neither finding supports treating schema as a shortcut to more AI citations.

The practical rule follows from that distinction. If a fact is important for citation, make it visible on the page. If it is visible and correct, schema can reinforce it. Google’s official position in July 2026 is that structured data is not required for AI Overviews or AI Mode. Microsoft says schema helps search engines and Copilot understand content.

The failure modes a coding agent produces predictably

Template bleed is the first pattern to recognize. The agent fills every page from one template, copying a description, datePublished, or author that belongs to the blog index into individual posts. Each block may look complete in isolation. The error becomes clear only when the reviewer opens a post and compares the declared values with its content.

Entity duplication creates a different kind of contradiction. A plugin or CMS may already emit an Organization node, while the agent adds another with a conflicting @id. Now the site sends competing identity signals. This is why reviewing only the added code misses part of the risk, because the new graph must also agree with the schema already present.

Retired search features expose another predictable weakness. An agent that relies on older training data may confidently suggest FAQPage markup even though Google stopped showing it entirely on May 7, 2026, and removed it from its documentation on June 15, 2026. Google removed HowTo rich results on September 13, 2023. Familiar markup is not evidence of a current purpose.

Google’s Rich Results Test can accept technically valid markup even when its values do not match what a visitor reads. Under Google’s structured data policy, misleading markup is a quality problem.

Finally, correctness at merge time can decay. When a page changes but the annotation in its template stays the same, the schema falls out of sync with what is visible on the page. That drift can undermine continued citation by AI systems. It also means the review must establish how the markup stays accurate after approval.

A four-layer review framework for a schema PR

Diagram: Four-Layer Schema PR Review Framework. Visualizes: Show a stepped flow of four sequential review layers for a schema pull request.

Layer 1 consists of automated gates before human review begins. Start by checking whether the block can be parsed, then run Google’s Rich Results Test on a live URL. A valid block still needs a supported purpose, retrievable output, and truthful values.

For eligibility, check whether the proposed type is in the current rich-result gallery. FAQPage and HowTo fail the supported-feature gate. For retrieval, inspect the rendered HTML of the live URL to confirm that the <script> block appears in crawlable output, and check robots rules. Put these gates in CI so failures block the PR from reaching a human reviewer.

Layer 2 makes the change’s intent legible. Require the agent, or the engineer who triggered it, to explain in the PR description what was asked, which approach was taken, and which alternatives were considered and rejected. Why this markup on these pages? An agent-authored PR that cannot explain its reasoning is not ready for review.

Layer 3 is schema-specific risk triage, where human judgment takes over. Begin with an entity @id audit to see whether the PR introduces a second Organization or Person node. Keep one canonical @id per primary entity per site, with schema ownership centralized in a single source of truth. Then reject additions of FAQPage, HowTo, Sitelinks Searchbox, or anything on the retired list. Unused deprecated markup may be harmless, but that is not a reason to add it.

The central task is the markup-to-visible-content parity check. Extract each JSON-LD block from the diff, open the actual rendered page, and compare every declared property with what a visitor can read. Is the value present, and is it accurate here? This check tests the assertion the site is about to publish.

For authorship, the bad field is the blog index’s author copied onto a post that visibly names someone else. The good field matches that post’s visible attribution. For datePublished, the bad field borrows a shared date that does not describe this page. The good field matches the page’s displayed publication date. These are small differences in a diff. They are different factual claims to the engine consuming them.

Descriptions require the same page-level scrutiny. A generic description can be true of the blog as a whole while misrepresenting what an individual post covers. For a Product or Offer, price and availability must likewise agree with the page.

Give particular attention to author, datePublished, dateModified, description, address, price, and availability. These fields deserve scrutiny because their correctness depends on the specific content or entity being described. Do not infer parity from a nearby page. When a value is true in the template but false here, reject it or delete the property.

The 2026 evidence supports Organization with sameAs and @id for entity clarity, and Article or BlogPosting for machine-readable authorship and dates. BreadcrumbList and Product or Offer have a place where genuinely applicable. Treat other additions with proportional skepticism.

Sign-off and a rollback plan close the loop in Layer 4. Prepare the rollback before merging because schema errors may surface in Search Console or citation monitoring dashboards. That feedback loop is slow. Stage the rollout to a subset of pages where possible, so an incorrect template does not become incorrect everywhere at once.

Sign-off also needs a named owner or authoritative system. One person or one system should emit the authoritative schema graph, rather than multiple plugins or tools producing overlapping Organization or LocalBusiness nodes. This is a maintenance responsibility. Without clear ownership, even a carefully reviewed PR leaves the next change free to reintroduce the same conflicts.

What to do with schema that is accurate but adds nothing

“The markup is correct, so why not merge it?” is a fair question, but correctness alone does not establish value. A property that serves no current search feature or entity purpose adds maintenance surface. Someone must keep it synchronized later. That obligation grows when agents reopen the work next quarter and build on annotations whose purpose was never clear.

The type needs to make the page eligible for a rich result that still exists or help with entity-resolution work. Does it clarify a name, a sameAs relationship, or authorship that AI classification cannot reconstruct from prose alone? If the property does neither, delete it from the PR. “It can’t hurt” overlooks the possibility that inert markup today becomes contradictory after the content changes.

In practice, Organization with sameAs and a stable @id earns its keep on pages representing the brand, while Article or BlogPosting with accurate authorship and publication dates earns its keep on editorial content. Inclusion creates an obligation beyond the merge. Treat schema changes like code releases, with staged rollout, validation, and ongoing monitoring, because approving an annotation commits the site to keeping it true over time.

Connecting the reviewed schema to what AI answer engines actually measure

Organization and Person markup can help keep attribution the same when the same entity is named and linked in the markup, in the visible content, and in off-site mentions. That alignment leaves models less room to guess or attribute a fact to a competitor. The useful outcome is entity clarity and citation consistency.

To check that outcome, measure each engine on its own. Claude, ChatGPT, Gemini, and Perplexity draw from different source pools, so a gain in one is not a gain in another. A contradiction may suppress citations on one engine while leaving others unaffected. An aggregate result can hide that difference.

Run the real questions buyers ask through each engine on a fixed cadence. Log whether the brand is mentioned, whether it receives a linked citation, and which pages are cited. Look for stable attribution. The same cadence can surface pages needing a renewed parity check when markup and visible content diverge after the merge.

That makes the site-wide PR an opportunity to establish an authoritative entity graph. The review can enforce one @id per entity, one system emitting the graph, and a cadence for monitoring it. The responsibility does not end at approval. When the page changes, the annotation must change with it.

Sources

  1. General Structured Data Guidelines | Google Search Central | Documentation | Google for Developers
  2. AI Features and Your Website | Google Search Central | Documentation | Google for Developers
  3. 방법 및 FAQ 리치 결과 변경사항 | Google Search Central Blog | Google for Developers

More in Features