How to add or fix structured data at scale with Claude Code

Claude Code can add or fix structured data across a whole site in one session: it audits what markup each template outputs today, writes JSON-LD that fills itself from the page's own data, and checks every page for markup that says something the page doesn't. That last check is the one that matters. Google's rule is "Don't mark up content that is not visible to readers of the page," and a common schema problem at scale is exactly that: a rating nobody sees, an old price, an opening time that changed.

This guide covers the process step by step, with example prompts, the check that proves each step worked, and what a person reviews. Structured data (also called schema markup) is code that labels facts on a page, such as a business name, a product price or an article's author, in a vocabulary from schema.org. As of October 2026 Google no longer shows FAQ rich results, so this guide also covers what to do with FAQ markup you already have.

What structured data does, and what it doesn't

Google uses structured data to understand a page and, for supported types, to show a richer search result. Its search gallery lists the types it supports as of October 2026, including Article, Breadcrumb, Event, Local business, Organization, Product snippet, Review snippet, Recipe and Video. It doesn't promise anything: "Google does not guarantee that your structured data will show up in search results, even if your page is marked up correctly."

The list changes. Google's documentation updates page says the FAQ rich result "will no longer appear in Google Search starting May 7, 2026," and the FAQ documentation was removed in June 2026. HowTo rich results were removed earlier. So before you ask Claude to add a type, check that it's still in the gallery. That is also why a fixed list in an old checklist, or in a model's memory, is a poor guide.

Two more limits are worth knowing. A structured data manual action "means that a page loses eligibility for appearance as a rich result; it doesn't affect how the page ranks in Google web search." And for AI features, Google's guide says "Structured data isn't required for generative AI search." Markup is worth doing well. It isn't a ranking switch.

Step 1: Audit what your site outputs today

Work on a local or staging copy, on a branch in git. Ask Claude Code to crawl it and extract every JSON-LD block, plus any Microdata or RDFa, per URL.

Example prompt: Crawl the local build and, for every page, list the structured data types it outputs, the template or file that generates each block, and whether the JSON parses. Group the results by template. Don't change any files yet.

The check: the report covers every page in the build, and each block traces to a file. If a block has no source file, it's probably injected by a plugin, a tag manager or a third-party widget, and you need to find it before you add more. Google notes it "can read JSON-LD data when it is dynamically injected," so injected blocks count too, and they can duplicate what your templates already output.

Step 2: Decide which types each page type should carry

This is a person's job, informed by the audit. Write the decisions down as a short table in your CLAUDE.md or a project file, so every later session follows them. Our guide to writing a CLAUDE.md for a website shows where that goes.

Then check each chosen type's page in Google's documentation for required properties. Google says items "missing required properties are not eligible for rich results," and that "it is more important to supply fewer but complete and accurate recommended properties" than every possible one.

Step 3: Put business facts in one place

A common source of sitewide schema errors is the same fact typed in several places: a phone number in the footer, in the contact page and in three JSON-LD blocks. When one changes, the others drift. Ask Claude to move those facts into one data file that both the visible page and the markup read from.

Example prompt: Find every place the business name, address, phone and hours appear, in page text and in structured data. Propose one data file that holds them, and show me which templates would read from it. Plan only.

The check: a search for the old phone number or address finds it only in the data file. If you later change a fact, our guide to changing a fact everywhere with Claude Code covers the copies people forget, including the ones inside structured data.

Step 4: Write the markup in templates, filled from page data

With decisions and data in place, ask Claude to generate JSON-LD in each template, pulling values from the same fields the page displays. Use /plan first so you see which files it will touch.

Example prompt: Add Article and Breadcrumb JSON-LD to the blog post template. Take the headline, author, dates and image from the same fields the page renders. If a field is empty on a page, leave that property out instead of filling a default. Don't add FAQ or HowTo markup.

The instruction about empty fields matters. A script that fills gaps with a default author or today's date produces markup that is valid and wrong, which no validator will catch.

Step 5: Validate syntax, then compare markup with the page

Run two kinds of checks. Neither replaces the other.

1. Syntax and eligibility. Ask Claude to parse every JSON-LD block in the build and report any that fail. Then test a sample of each template in Google's Rich Results Test. Google says the Rich Results Test and URL Inspection tool "catch most technical errors."
2. Visible-content match. Ask Claude to write a script that, for each page, checks that key values in the markup (name, price, rating, dates, address) appear in the page's visible text.

Example prompt: For every page, compare the values in its structured data with the visible text of the page. List any value that doesn't appear on the page, any rating or review count with no visible reviews, and any date in the future or more than a year older than the page's visible date.

The check: zero parse errors, a clean sample in the Rich Results Test, and an empty mismatch list or a list a person has reviewed line by line. Google's structured data policies say quality guidelines "are not easily testable using an automated tool," which is why the match script and a person both matter.

Step 6: Clean up markup that no longer earns anything

Old sites often carry markup for features that have changed. As of October 2026:

• FAQ and HowTo markup won't produce those rich results in Google. You can leave valid FAQ markup that matches a visible FAQ, or remove it to simplify templates. That is a judgment call, not an emergency. Don't present it to anyone as a way to get rich results.
• Duplicate blocks from a plugin and a theme describing the same thing should be reduced to one source.
• Ratings and reviews that aren't shown on the page, or weren't written by real customers, should come out. Google's policies name "fake reviews" as misleading content.

Use a hook if you want a rule enforced every time. A Stop hook can run the parse check whenever Claude finishes a reply; see hooks for website projects.

Step 7: Deploy, then monitor

A person reviews the diff, especially the data file and any template change, and approves the deploy. After launch, Google's intro guide says to watch the "Rich result status reports after deployment," because markup "might break after deployment due to templating or serving issues." Re-run your parse and match scripts against the live site on a sample, and schedule them to run again after future template changes.

When we rebuilt eseospace.com, structured-data types were one of the elements our SEO parity check compared on old and new pages, alongside titles, meta descriptions, robots, canonicals and H1s. The rebuild case study describes that check.

What a person must review

Titles and meta descriptions get the same treatment; see rewriting titles and meta descriptions at scale. The overview of where schema fits in SEO work is in Claude Code for technical SEO.

Conclusion

Structured data at scale is a good Claude Code job because it's repetitive and testable, but the test that matters most is the one validators skip: does the markup say only what the page says? Audit first, decide types per page type, keep business facts in one file, generate markup from page data, validate syntax and visible content, and have a person approve the facts before anything ships. If you want help with the markup itself, see our schema markup services. More guides are in our Claude Code Guide.

Frequently asked questions