How to Fix Missing FAQPage Schema on Your FAQ Pages

Your site has pages with question-and-answer content but no FAQPage structured data, or no FAQ content at all. By the end of this guide you will have identified every page with real FAQs, added FAQPage JSON-LD that matches the visible text, and validated it.

By Updated ⏱ 20 minutes per page template🎯 Beginner● Medium impactGEO / AI
Illustration: FAQPage schema fix guide
GEO / AI · FIX GUIDE FAQPage schema IMPACTEFFORT TIME20 minutes per page template LEVELBeginner

Why it matters

FAQPage markup gives search engines and AI answer engines (Google AI Overviews, Bing Copilot, ChatGPT search, Perplexity) an explicit, machine-readable map of each question and its answer. Without it they have to infer Q&A pairs from accordions and headings, which often fails when answers sit in collapsed or JavaScript-rendered panels. Google has shown FAQ rich results only for a small set of authoritative government and health sites since 2023, so don't expect expanded snippets.

org, is read by Bing and AI crawlers, and makes your answers easier to quote and attribute.

✕Beforehttps://example.com/shipping shows 6accordion questions, but the pagesource has no <script✓Afterhttps://example.com/shipping outputsone FAQPage JSON-LD block whose 6Question/Answer pairs match the

What you need

Edit access to page templates, theme code or per-page custom code
A list of pages that show questions and answers (FAQ, product, pricing, support pages)
Google Rich Results Test or validator.schema.org

Step-by-step fix

1

List every page that shows FAQ content

Open your audit report and note the URLs flagged as having FAQ content without FAQPage markup. Also look for pages the audit may not list yet: accordions, "Frequently asked questions" headings, and H2/H3 headings phrased as questions followed by a short answer. Group the URLs by template (FAQ page, product page, blog post) so you fix each template once.

Pro tip: Product and pricing pages often hold the questions buyers ask AI assistants, such as returns, delivery times and contract length. They are usually worth marking up first.
2

Add a genuine FAQ section if you have none

If the audit reports "No FAQ content to mark up", your site has no Q&A content to describe. Add a visible FAQ section built from real customer questions, taken from support tickets, sales calls or Search Console queries. Put each question in a heading and the answer directly below it.

Keep answers to roughly 40–80 words, and make them direct and self-contained.

html
<section id="faq">
  <h2>Frequently asked questions</h2>
  <h3>How long does shipping take?</h3>
  <p>Example Co ships orders within 1 business day. Standard delivery in the US takes 3–5 business days, and express delivery takes 1–2 business days. You receive a tracking link by email as soon as your parcel leaves our warehouse.</p>
  <h3>Can I return an item?</h3>
  <p>Yes. You can return unused items within 30 days of delivery for a full refund. Start a return at example.com/returns and print the prepaid label.</p>
</section>
Pro tip: Don't invent questions to stuff keywords. FAQPage markup is only appropriate when the page itself presents the questions and answers to visitors.
3

Write the FAQPage JSON-LD

Create one FAQPage object per page. Add each question to the mainEntity array as a Question with a name (the question) and an acceptedAnswer of type Answer with a text property. Copy the wording exactly from the visible page.

Simple HTML such as <a>, <p>, <ul> and <strong> is allowed inside text.

html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "How long does shipping take?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Example Co ships orders within 1 business day. Standard delivery in the US takes 3–5 business days, and express delivery takes 1–2 business days. You receive a tracking link by email as soon as your parcel leaves our warehouse."
      }
    },
    {
      "@type": "Question",
      "name": "Can I return an item?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes. You can return unused items within 30 days of delivery for a full refund. Start a return at <a href=\"https://example.com/returns\">example.com/returns</a> and print the prepaid label."
      }
    }
  ]
}
</script>
Pro tip: Use JSON-LD rather than microdata. It is the format most crawlers and audit tools parse reliably, and it is easier to keep separate from your layout.
4

Generate the markup from the same data as the page

Hand-written JSON-LD drifts out of sync when someone edits an answer. Store the FAQs in one place, such as a CMS field, a metafield or an array, then render both the visible HTML and the JSON-LD from that source. The example below shows a Next.js App Router server component that does this.

javascript
const faqs = [
  { q: 'How long does shipping take?', a: 'Example Co ships orders within 1 business day. Standard delivery takes 3–5 business days.' },
  { q: 'Can I return an item?', a: 'Yes. Return unused items within 30 days of delivery for a full refund.' }
];

export default function ShippingPage() {
  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'FAQPage',
    mainEntity: faqs.map(f => ({
      '@type': 'Question',
      name: f.q,
      acceptedAnswer: { '@type': 'Answer', text: f.a }
    }))
  };
  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, '\\u003c') }}
      />
      <section>
        {faqs.map(f => (<div key={f.q}><h3>{f.q}</h3><p>{f.a}</p></div>))}
      </section>
    </>
  );
}
Pro tip: Render the script on the server. Some AI crawlers do not execute JavaScript, so markup injected only on the client side, for example by Google Tag Manager, may never be seen.
5

Place the script and avoid duplicates

Put the script in the <head> or anywhere in the <body> of the page that shows the FAQs. Don't add it site-wide. Check that a plugin or theme isn't already outputting a second FAQPage block, because two conflicting blocks can cause validation warnings.

If the page already has other JSON-LD (Organization, Product, BreadcrumbList), you can keep those as separate scripts or combine everything in one @graph array.

html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "Organization", "name": "Example Co", "url": "https://example.com" },
    { "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "Can I return an item?", "acceptedAnswer": { "@type": "Answer", "text": "Yes, within 30 days of delivery." } } ] }
  ]
}
</script>
Pro tip: Use FAQPage only where the site owner writes both the questions and the answers. Pages where users submit questions and answers, such as forums or community Q&A, should use QAPage instead.
6

Validate and re-run the audit

org. Confirm that FAQPage is detected with zero errors and the expected number of questions. Then view the raw page source (Ctrl+U or Cmd+Option+U) and check that the JSON-LD appears in the server-rendered HTML.

Finally, re-run the audit and confirm the URLs no longer appear as affected.

text
curl -s https://example.com/shipping | grep -o '"@type": *"FAQPage"'
Pro tip: In Google Search Console, the FAQ enhancement report may stay empty because of Google's 2023 restriction. That does not mean the markup failed.

Platform-specific notes

WordPress

In the block editor, use the Yoast SEO "FAQ" block or the Rank Math "FAQ by Rank Math" block. Both render the visible Q&A and output FAQPage JSON-LD automatically, merged into the plugin's schema graph. Don't also paste a manual script, or you will create duplicates. For classic themes without these plugins, add the script through a custom field or a child theme's wp_head hook, limited to that page with is_page().

Shopify

Go to Online Store > Themes > Edit code. For product FAQs, store the Q&A in a metafield (for example a JSON metafield product.metafields.custom.faq) and loop over it in a snippet included in main-product.liquid. Escape values with the | json filter. For a single page, add a "Custom Liquid" section in the theme editor containing the script. Many FAQ apps output their own schema, so check for duplicates first.

Wix

Open the page in the editor, then go to Page settings > SEO basics > Advanced SEO > Structured data markup, and paste the JSON-LD. Paste only the JSON, without the <script> tags. The built-in Wix FAQ app may not output FAQPage schema, so verify with the Rich Results Test before relying on it.

Webflow

For a static page, open Page settings > Custom code > Inside <head> tag and paste the script. For CMS-driven FAQs, add an Embed element to the collection template and insert CMS fields into the JSON. Make sure answer fields don't contain unescaped double quotes.

Next.js

Render the JSON-LD as a <script> inside a server component, using JSON.stringify and escaping '<' as \u003c, as Next.js recommends. Avoid next/script with strategy="afterInteractive" for structured data, because that loads it only on the client. In the Pages Router, place it in the page component or inside next/head.

Check that it worked

✅ How to verify

  • Google Rich Results Test detects "FAQ" with the correct number of valid items and no errors
  • validator.schema.org shows a FAQPage with Question and acceptedAnswer nodes and no warnings
  • View source (not DevTools Elements) shows the JSON-LD in the initial HTML, and its question text matches the visible page
  • Re-running the audit shows no affected URLs for FAQPage schema

⚠️ Common mistakes

  • Marking up questions that don't appear on the page, or answers whose text differs from what visitors see
  • Adding the same FAQPage block site-wide through the header template, so every page claims the same FAQs
  • Injecting the JSON-LD only through Google Tag Manager or client-side JavaScript that AI crawlers don't execute
  • Leaving a plugin's FAQ schema active while also pasting a manual block, which produces duplicate or conflicting FAQPage objects

Is this still an issue on your site? Run a free audit — ZORO checks this and 294 other SEO, AI-visibility, accessibility and security signals, with fixes for your platform.

Check my site free

FAQ

Does FAQPage schema still work after Google limited FAQ rich results?

Since August 2023, Google shows FAQ rich results only for well-known authoritative government and health sites. The markup is still valid, and Google, Bing and AI answer engines still read it to understand your Q&A content. It is worth adding where you have genuine FAQs, but don't expect expanded search snippets.

Can I put FAQPage schema on product pages?

Yes, as long as the questions and answers are visible on that product page and written by you. It can sit alongside Product schema, either in separate scripts or in one @graph array.

How many questions should a FAQPage include?

There is no required minimum or maximum. Include every Q&A pair that is visible on the page. In practice, 3–10 focused questions with direct 40–80 word answers are easiest for AI engines to quote.

Should I use FAQPage or QAPage?

Use FAQPage when your organisation writes both the questions and the answers. Use QAPage when users ask and answer, for example in forums or community Q&A, where one question can have several submitted answers.