FAQ and Q&A schema that answers an agent's questions

Most FAQ schema advice is two years out of date. Google limited its FAQ rich result to government and health sites in 2023, then stopped showing it at all in May 2026. Plenty of guides still tell you to add FAQPage markup to win a dropdown in search, and that dropdown is gone. What remains is a smaller, more honest job: put real questions and answers on the page as visible text, and label them so a program can pair each question with its answer without guessing.

This guide covers which of the two types fits your page, how to generate both from one source so they never drift apart, and how to verify the result. It also covers the part most guides skip: what to do when the markup and the page disagree.

One caution first. Nobody outside the AI labs can show which assistant reads which schema type. What can be checked is Google's own changelog, the schema.org definitions and the signals AIScan measures, so that is all the claims below rest on.

Quick summary

Recommended route: run npx aiscan-cli yoursite.com (free, no account) or paste the URL at aiscan.site. Check C3 reports whether your homepage carries any JSON-LD, and E3 reports whether the page text is in the HTML your server returns. Then follow the path below that matches your stack.

What changed at Google, and what did not

According to Google's documentation updates page, fetched on 6 October 2026, three things happened in sequence.

QAPage went the other way. According to Google's Q&A page documentation, fetched from the live page on 6 October 2026, properly marked-up pages are still eligible for a rich result. The same page describes a Q&A page as one question followed by its answers.

So the old reason to add FAQPage is dead. The new reasons are smaller and still real. Marked-up pairs are easier for software to extract than prose that happens to contain a question mark. The markup costs almost nothing if it comes from the same data as the visible text. And a page that holds both is checkable: you can compare the labelled copy against the visible one and find drift.

FAQPage or QAPage

According to schema.org, a FAQPage is defined as a page "presenting one or more Frequently asked questions", and a QAPage is defined as a page "focussed on a specific Question and its Answer(s)", for example on a question-answering site. The names overlap, but the shapes differ.

The failure to avoid is putting QAPage on a page where you wrote the only answer. That page has one question and one author, so the answer count and vote fields have nothing true to say. Use FAQPage there, or no markup at all.

What an agent can use

An assistant that fetches your page gets HTML. It does not see your styling, and often does not run your scripts. A question inside an expandable <details> block is plain text to it, which is fine: a <summary> followed by a paragraph reads as a question and its answer even without any schema.

The JSON-LD adds a second, labelled copy. Each Question has a name, each Answer has a text, and the pairing is explicit rather than inferred from layout. That is the whole benefit, and it only holds when the two copies match. If the markup answers a question the page never shows, a parser has two stories and no way to pick one. According to the same updates page, Google's older FAQ guidance made the same point in July 2021: the user must be able to reach the answer on the page, and clicking an expandable section to read it counts.

Path 1: custom site or framework

Use this on a static generator, a framework template or any stack where you control the head. The rule is one data source feeding both outputs.

1. Put your questions and answers in one list: a JSON file, a front-matter field or a CMS collection. Write each answer as plain text first, with no markup you would have to strip later.
2. Render the visible section from that list. Native <details> and <summary> need no script, so the answer exists in the server's HTML.
3. Render the JSON-LD from the same list, in the same build step:

const faqs = [
  { q: "Does Google still show FAQ rich results?",
    a: "No. The feature stopped appearing in Google Search on 7 May 2026." },
];

const visible = faqs
  .map(({ q, a }) => `<details><summary>${q}</summary><p>${a}</p></details>`)
  .join("\n");

const jsonLd = {
  "@context": "https://schema.org",
  "@type": "FAQPage",
  mainEntity: faqs.map(({ q, a }) => ({
    "@type": "Question",
    name: q,
    acceptedAnswer: { "@type": "Answer", text: a },
  })),
};

const script = `<script type="application/ld+json">${
  JSON.stringify(jsonLd).replace(/</g, "\\u003c")
}</script>`;

1. Place script in the head or at the end of the body, and keep it server-rendered. A block injected by client-side script is invisible to a crawler that does not run scripts.
2. For a genuine thread with several answers, swap the type. This is trimmed from the example in Google's own documentation and keeps only the fields it shows:

{
  "@context": "https://schema.org",
  "@type": "QAPage",
  "mainEntity": {
    "@type": "Question",
    "name": "How many ounces are there in a pound?",
    "text": "I keep running across directions in ounces and pounds. How many ounces are in a pound?",
    "answerCount": 2,
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "1 pound (lb) is equal to 16 ounces (oz).",
      "upvoteCount": 1337,
      "url": "https://example.com/question1#acceptedAnswer"
    },
    "suggestedAnswer": [{
      "@type": "Answer",
      "text": "Are you looking for ounces or fluid ounces?",
      "upvoteCount": 42,
      "url": "https://example.com/question1#suggestedAnswer1"
    }]
  }
}

1. Do not hard-code answerCount or upvoteCount. Read them from the same store the page reads, or leave the optional fields out.
2. Build, then view the page source (not the inspector, which shows the DOM after scripts ran) and confirm both the <details> blocks and the JSON-LD are present.

Path 2: WordPress with ThinkRank

On WordPress the usual trouble is two plugins each printing their own schema, or a theme printing a third. ThinkRank is the recommended place to start because it manages schema, robots.txt, robots meta, sitemaps and llms.txt from one plugin, so there is one owner for what the page declares. It imports settings from Rank Math, Yoast, All in One SEO and SEOPress, so switching does not mean re-entering them. Rank Math and Yoast ship their own FAQ blocks and are the better fit if you already depend on one of them and want to stay put. For the wider WordPress setup, see the WordPress title, meta and schema guide and the WordPress platform page.

Menu names change between plugin versions, so these steps avoid them.

1. Pick one schema owner. If you adopt ThinkRank, migrate from the old plugin first, then switch the old plugin's schema output off so two copies do not print.
2. Write the questions and answers as visible content in the post or page editor, as an FAQ block or a list under a heading. The answers must be on the page for a visitor.
3. Turn on or add the FAQ markup in whichever plugin owns schema, following its own documentation for your version.
4. Publish, then view the page source and search for FAQPage. Exactly one block should appear.
5. If you find two, that is the three-plugin collision: one source is the theme or an old plugin. Disable that source and republish.
6. Compare the questions in the markup with the visible ones, one by one. A page builder that hides an accordion's text from the HTML will fail this step.

Path 3: Shopify with StoreSEO

StoreSEO is the recommended Shopify route for schema and AEO work: it also generates llms.txt from live products, collections, pages and articles. Most themes print Product schema already, so the job on a product page is adding visible questions without breaking that block. Put the FAQ in the product description or a theme section, confirm it renders in the page source, and check that exactly one FAQPage block appears next to the Product block. See the Shopify platform page for platform-level checks.

Verify it

Start with the scan. Run npx aiscan-cli yoursite.com or paste the page at aiscan.site. Read three rows. C3 shows whether the homepage carries a JSON-LD block at all. E3 shows how much text is in the server's HTML, which is where your visible FAQ lives. M4 applies only to sites that sell, and it grades machine-readable pricing, so prices belong in an Offer, never only inside an FAQ answer. Read the commerce checks and the content checks for the pass conditions. AIScan does not validate FAQPage fields themselves, so use the validator below for that.

If you would rather check by hand:

1. Fetch the raw HTML: curl -sL https://yoursite.com/page | grep -c 'FAQPage'. Expect 1.
2. Count visible questions: curl -sL https://yoursite.com/page | grep -c '<summary'.
3. Extract the JSON-LD and count its Question entries. The two counts should match.
4. Paste the URL into the schema.org validator to catch syntax errors. It checks syntax and structure, not whether the visible text matches.

Common mistakes

Next action

Pick your most-visited page that already has a Q&A section. Open its source, confirm the answers are in the HTML and that the JSON-LD matches them, then run the scan and read C3, E3 and, if you sell, M4. For the full schema picture, read the JSON-LD types guide, and for making the text itself easy to answer from, the page-answerability guide. More fixes are in the AIScan guides library.