How to Add Schema Markup to an AI-Built Site (and Check It)

What you're actually adding

Schema markup is a short description of a page written for machines instead of people: "this page is an article, published on this date, by this organisation", or "this page answers these questions". The format Google recommends is JSON-LD, which sits inside one <script type="application/ld+json"> tag. Visitors never see it. It doesn't change how the page looks, and it doesn't add any content. It describes content that's already on the page, in a form a search engine can read without guessing.

Here's what one looks like, for a page with a visible FAQ section. There's one question object for each question on the page, in the same order:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Your first question, word for word",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Your first answer, word for word"
      }
    }
  ]
}
</script>

You don't need to write this yourself. Your AI coding agent writes it; your job is knowing where it should go and checking that it arrived. If you haven't picked a type yet, start with our guide to the schema types a small site actually needs.

One thing has to be true first: the site is published at its own address. An app that only exists inside an AI chat has no page for a search engine to visit, so schema does nothing there yet.

Does schema markup go in the head or the body?

Either works. Google's documentation describes JSON-LD as a script tag "in the <head> and <body> elements of an HTML page", and it reads the block from both. The head is the usual home, but a block in the body isn't a mistake. What matters far more is which pages it ends up on.

The question that decides where it goes: one file, or one per page?

Every schema block describes something. Some things are true of your whole site: its name, the organisation behind it. Others are true of one page only: this article's date, this page's questions, this page's place in the menu. The trouble starts when a page-only block lands somewhere that every page shares.

That happens easily on an AI-built site, because many of them are single-page apps. A single-page app, in MDN's words, "loads only a single web document" and then swaps the content inside it with JavaScript. Every address on the site is served that same one file, usually called index.html. If your AI pastes an FAQ block into it, every page on your site claims to answer those questions, including pages that don't. That's markup describing content readers can't see, which is exactly what Google's guidelines rule out.

So a single-page app needs page-specific schema added by the part of the app that builds each page, not by the shared file. That means JavaScript puts the block in place when the page is shown. Google handles this: its documentation says it "can read JSON-LD data when it is dynamically injected into the page's contents". Crawlers that don't run JavaScript can't. A December 2024 study by Vercel found that many AI crawlers, including the ones behind ChatGPT and Claude, didn't run JavaScript. Some builders send crawlers a finished copy of each page, which closes that gap. Our guide to checking what your site shows a crawler explains how to find out whether yours does.

If your site is built as separate pages, each with its own HTML file, it's simpler: each page's block goes in that page's own file. Not sure which kind of site you have? Ask your AI before adding anything: the prompt below starts with that question.

Where your builder fits in

AI website builders handle schema in different ways, and those ways change. Some let your AI coding agent edit every file. Some have an SEO panel that writes certain schema types for you. Base44, for example, documents a breadcrumb block it adds to every page by itself, and a setting to stop it adding its own structured data (Google's term for schema markup). That matters for one reason: if your builder already adds a type and you add your own copy, the page ends up with two blocks describing the same thing, and they may disagree.

So before adding anything, find out what's already there. Ask your AI, check your builder's own help pages for "structured data" or "schema", and look at a live page (the checks below).

How to check it's really there

These checks need no coding. Run them on your live address, not the builder's preview link, and on at least two different pages.

1. Run the page through Google's Rich Results Test

Open Google's Rich Results Test and give it the page's address. Google recommends the address over pasting code, because the address test runs the page's JavaScript the way Google does. It lists the structured data it found and flags errors and warnings. It only reports the types Google can show as rich results (search listings with extras, such as star ratings), so a type it doesn't support won't appear in its list even when it's on the page. FAQPage and HowTo are two of those, since Google no longer shows either as a rich result. For those, the next check is the one that counts.

2. Look for the block in View Source

Open the page's source (in Chrome, Ctrl+U, or Cmd+Option+U on a Mac) and search it for application/ld+json. If the block is there, every crawler gets it. If the Rich Results Test found it but View Source doesn't show it, JavaScript is adding it: Google gets it, and crawlers that don't run JavaScript may not.

3. Compare it with the visible page

Read the block next to the page. Every question in an FAQ block should appear on the page, word for word. Every step in a HowTo block should be a step the page walks through. The headline and dates should match what the page shows.

4. Make sure one page's block isn't on every page

Open a second, unrelated page and check it the same way. If it carries the first page's FAQ, article or breadcrumb block, the markup is in a shared file and needs moving.

The one mistake that undoes all of this

Markup that describes something the page doesn't show. Google's guidelines say plainly: "Don't mark up content that is not visible to readers of the page." It's rarely deliberate. The markup drifts: someone rewords an FAQ answer or cuts a step, and the schema block keeps the old version. If Google treats the mismatch as a structured data issue, it can issue a manual action, and the page loses its eligibility for rich results. Google says that doesn't affect how the page ranks, but the markup stops doing anything useful. The fix is a habit: whenever the visible text changes, the block changes in the same edit. Treat the page as the source of truth and write the schema to match it, never the other way round.

The prompt to give your AI

Copy this into your AI coding agent's chat and fill in the parts in square brackets. It asks the AI to explain where the markup will go before it adds anything.

I'm not a coder. I want to add [schema type, e.g. FAQPage]
schema markup, as JSON-LD, to this page: [page address or name].

Before you change anything:
1. Tell me whether my site is one shared HTML file for every
   page (a single-page app) or a separate file per page.
2. Tell me what structured data is already on this page,
   including anything my builder adds by itself.
3. Tell me exactly where you'll put the new block, and confirm
   it will appear on this page only, not on every page.

When you add it:
4. Use only text that is visible on the page, word for word.
   Don't invent ratings, prices, reviews or questions.
5. Tell me whether the block will be in View Source or added
   by JavaScript when the page loads.
6. Tell me how to check it in Google's Rich Results Test.

Wait for my yes before you change any files.

What to check in the AI's answer

• It answered the shared-file question. If it's putting page-specific schema into index.html on a single-page app, stop it: that block will show up on every page.
• It looked for what's already there. An answer that doesn't mention existing markup may create a second, clashing block.
• Every field matches the page. Compare the questions, steps, headline and dates with what a visitor sees. Anything that isn't on the page comes out.
• It said how the block gets there. "In View Source" or "added by JavaScript" are both real answers. "It's handled" isn't.
• It waited for your yes. If it changed files before you agreed, ask it to show you exactly what it changed.