FAQ Schema Explained: How to Add FAQPage JSON-LD to Your Pages (and What to Expect)

You paste FAQPage JSON-LD into a page, hit publish, and wait for the FAQ drop-down to show up in Google. It won’t. Google stopped showing FAQ rich results in Search from May 7, 2026.

Google supported FAQ structured data in Google Search from May 2019 (Google Search Central). Since September 2023 it showed FAQ rich results only for well-known, authoritative government and health websites. On May 8, 2026 it added a deprecation notice saying the feature would no longer appear in Google Search starting May 7, 2026, and on June 15, 2026 it removed the documentation (Google Search documentation changelog; see also our dated summary of Google’s docs). So FAQPage markup is no longer a way to get a Google rich result, and you should not add it expecting one.

FAQPage is still valid schema.org markup, and it can still be worth adding cleanly. It turns your visible on-page Q&A into a machine-readable set of Question → acceptedAnswer pairs that other systems may read. Google’s changelog does not say existing FAQ markup is invalid, but it no longer produces a rich result in Google Search.

Below, you’ll get the exact JSON-LD structure Google and schema.org expect, the implementation details that usually break (visibility mismatches, malformed JSON, escaping), and a simple way to check that the JSON parses before you ship. A passing check means valid markup, not a rich result.

What Is FAQPage JSON-LD (And When Should You Use It)?

FAQPage JSON-LD is a structured data format you add to a page to describe a list of questions and their answers in a machine-readable way. Think of it as labeling your on-page FAQ so search engines and other systems can parse each Question and its matching acceptedAnswer consistently.

Google defines an FAQ page as a page that “provides a list of frequently asked questions and answers on a particular topic.” (See Google’s announcement: New in structured data: FAQ and How-to.) In practice, that means the page contains multiple Q-and-A pairs written by you, the site owner, and visible to users on the page.

Use FAQPage markup when the answers are authoritative and final. Google’s 2019 guidance was explicit that FAQ structured data is only for official questions and answers, and you should not add FAQ schema to forums or pages where users submit answers.

When FAQPage Schema Fits (And When QAPage Fits Better)

Pick the markup based on who provides the answers:

FAQPage: Your business publishes the questions and the answers. Example: “Do you ship to Belgium?” with your official shipping policy.
QAPage: Users ask questions and users (or the community) submit answers. Google’s guidance says to use Q-and-A Page markup for that scenario. (Same Google post: New in structured data: FAQ and How-to.)

If your page mixes both, separate them. Put FAQPage JSON-LD on the official FAQ section, and keep community answers on a dedicated Q-and-A page with QAPage markup.

How Does FAQPage JSON-LD Work? The Exact Structure You Need

If you keep community answers on QAPage, your FAQPage JSON-LD can stay simple: a page-level type, then a list of questions with one official answer each. That’s the model schema.org defines for FAQ pages.

The required nesting is:

@type: FAQPage
mainEntity: an array of Question objects
each Question has name (the question text)
each Question has acceptedAnswer with an Answer and text (the answer)

Schema.org defines the FAQPage type as a page with a list of questions and answers (schema.org/FAQPage). Google’s FAQ structured data announcement uses the same “official Q&As” framing (Google Search Central).

Copy-Paste FAQPage JSON-LD Example

Put this in a <script type="application/ld+json"> tag. Replace the Q&A text with the exact questions and answers users can see on the page.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is FAQ schema?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "FAQ schema (FAQPage structured data) labels a page’s official questions and answers so search engines can parse them reliably."
      }
    },
    {
      "@type": "Question",
      "name": "Do the questions and answers need to be visible on the page?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes. Mark up only the questions and answers that appear in the page content for users."
      }
    }
  ]
}

Keep each Question focused on one intent. If you need multiple answers or user voting, you are back in QAPage territory.

How to Add FAQ Schema Step by Step (Without Breaking Your Page)

Keep each Question tied to one intent, then implement faq schema in a way that matches what users can actually read on the page. Most breakages happen when teams paste FAQPage JSON-LD that does not match the visible Q&A, or when they inject malformed JSON into the HTML.

Write the on-page FAQ first. Add a short FAQ section to the page with real questions and complete answers. If you hide the answers behind clicks, make sure users can still access the content without tricks.
Confirm every Q&A is visible. FAQPage markup is for official questions and answers written by the site owner, and users should be able to see them on the page (Google’s guidance: New in structured data: FAQ and How-to).
Generate the JSON-LD. Use Balzac’s FAQ Schema Generator to produce valid FAQPage JSON-LD with the right nesting (FAQPage > mainEntity > Question > acceptedAnswer). Copy the output as-is.
Place the code in your HTML. Paste the JSON-LD inside a <script type="application/ld+json"> tag in the page HTML. Put it in the <head> or near the end of <body>. Keep it on the same URL as the visible FAQ content.
Publish safely. If you use WordPress, add it via a custom HTML block (Gutenberg) or your SEO plugin’s schema area if it supports custom JSON-LD. If you use Webflow or Wix, add it in the page settings where custom code is allowed.

If you already maintain other structured data (Organization, BreadcrumbList, Product), create a clean combined script with Balzac’s Schema Markup Generator. It helps you avoid duplicate properties and copy-paste collisions across multiple schema types.

JSON-LD Escaping Rules and Other Gotchas That Cause Validation Errors

Once you start combining multiple schema types in one script, small JSON mistakes can break your FAQ schema even when the Q&A content is correct. Most validation errors come from basic JSON escaping, copy-paste edits, or markup that does not match what users can actually read on the page.

FAQPage JSON-LD Escaping Rules That Commonly Break Markup

JSON-LD is just JSON. Treat it like code, not content.

Quotes inside text: Escape double quotes inside name or text as \". If you paste copy with quotes, this is the first thing to check.
Line breaks: Avoid raw line breaks inside a JSON string. Keep answers on one line, or use \n if you must represent a new line.
Backslashes: Windows paths and regex patterns need escaping. A single \ in text can invalidate JSON if it forms an illegal escape sequence.
Special characters: Accents (common in Belgium, like é or ë) are fine in UTF-8. The problem is usually hidden control characters copied from Word or PDFs.

If you want to include links in answers, put HTML in the text field carefully. Keep tags simple (like <a>) and make sure quotes inside attributes do not break the surrounding JSON string.

Use the canonical property names from schema.org/FAQPage. Typos like acceptedAnswers or mainEntities fail validation.

Other Gotchas: Valid JSON, Invalid FAQPage

Mismatch with on-page content: The Question.name and Answer.text should match what users see. If your CMS edits the visible FAQ but you forget to update JSON-LD, you create a mismatch.
Duplicate questions: Repeating the same question across multiple FAQ blocks on one page (or repeating it in the array) creates messy, redundant markup.
Marking up thin FAQs: Two weak questions stuffed at the bottom of a page often read like schema spam. Write real Q&As first, then mark them up.

How to Test FAQ Schema With Google’s Rich Results Test (And What to Do Next)

Typos like acceptedAnswers fail fast, but plenty of FAQ schema issues look “fine” until you run a validator. Use a validator such as Google’s Rich Results Test or the Schema Markup Validator to check that your FAQPage JSON-LD parses correctly. Because Google no longer shows FAQ rich results, a pass tells you the markup is well formed, not that a rich result will appear.

Open the test: go to Google’s Rich Results Test.
Test the right thing: paste the page URL if it is already live. Paste code only if the page is not accessible yet.
Run the test and wait for Google to fetch the page and render it.
Inspect detected items: look for “FAQ” or “FAQPage” in the results list. Click it to see each Question and acceptedAnswer.
Fix errors first: errors usually mean the markup is malformed. Warnings usually mean optional fields are missing.

When you click an issue, the Rich Results Test shows the exact JSON path that failed. That’s your debugging map. Fix the JSON-LD in your HTML, publish, then rerun the test on the live URL.

What a Passing or Failing Test Means for FAQ Schema

A passing test means your FAQPage markup is syntactically valid and matches what schema.org expects. It does not mean Google will show an FAQ rich result: Google stopped showing them from May 7, 2026, whatever the test says.

A failing test usually means one of these is true:

Parsing failed: invalid JSON (often unescaped quotes or stray line breaks).
Required properties are missing: for example, a Question without acceptedAnswer.
Content mismatch: the Q and A in markup do not match what users can see on the page.
Wrong schema type: the page is a community Q and A and needs QAPage, not FAQPage.

After a test passes, publish, then make sure the visible FAQ and the markup stay in sync when templates change. There is no Google FAQ rich result to monitor any more, so judge the page by whether its questions and answers help readers.

FAQ Schema FAQs: Visibility, Limits, and Best Practices

When a validator shows the markup is valid, teams usually ask the same next questions about faq schema: how much to mark up, where to put it, and what to expect. Here are the answers that keep your FAQPage JSON-LD clean and defensible.

Do I get an FAQ rich result if I add FAQPage JSON-LD? No. Google’s changelog says the FAQ rich result stopped appearing in Google Search from May 7, 2026 (documentation removed June 15, 2026); before that it was limited to well-known, authoritative government and health sites. Treat the markup as a way to describe your page to machines that read it, not as a promise of extra space in the results.

Do questions and answers have to be visible on the page? Yes. Mark up only Q&A that users can read on that URL. Google frames FAQ structured data as “official questions and answers” and says you should not add it to pages where users can submit answers (Google Search Central).

How many questions should I include? Include the questions you can answer clearly and completely on-page. Stop when you start repeating yourself, adding edge cases, or writing answers that belong in a policy page. A tight set of high-intent questions beats a long list that reads like filler.

Where should I place the JSON-LD? Put the <script type="application/ld+json"> in the <head> or in the <body>. Search engines can read either. Pick one convention and stick to it across templates so your team can maintain it.

FAQPage vs HowTo vs QAPage

FAQPage: you publish the questions and one official answer per question (schema.org/FAQPage).
QAPage: users ask and users answer. Google explicitly points community Q&A pages to Q&A Page markup (Google Search Central).
HowTo: step-by-step instructions, with materials, tools, and ordered steps. Use it for procedures, not for a list of independent questions. Google also no longer shows HowTo rich results (it removed that documentation in September 2023).

Best practice that prevents most problems: write the FAQ section first, then generate markup from that exact text using Balzac’s FAQ Schema Generator. After you publish, rerun the URL in Google’s Rich Results Test and recheck it when templates change so they do not silently break your FAQPage JSON-LD.

Sources

New in structured data: FAQ and How-to