What Is FAQ Schema? A Developer’s Guide to FAQPage Structured Data

What is FAQ schema? FAQ schema is Schema.org FAQPage structured data, usually written as JSON-LD, that describes a page of questions with a single authoritative answer for each. It tells machines which text on the page is a question and which is its answer. It does not raise rankings, and since May 2026 it no longer earns an FAQ rich result in Google Search.

Last reviewed: October 10, 2026.

What is FAQ schema?

What does FAQ schema describe?

FAQ schema describes a web page containing frequently asked questions and answers. Schema.org defines an FAQPage as a web page presenting one or more frequently asked questions. Each question is a Question entity, and its answer is an Answer entity connected through acceptedAnswer. The Schema.org FAQPage definition lists the formal type and its properties.

For example, a developer documentation page might answer “Does SEOAgent edit files in my repository?” with one explanation. The visible question and answer are the content people read; the JSON-LD is a structured description of that same content.

How does FAQPage differ from QAPage?

FAQPage fits questions answered by the site or another authoritative source. QAPage describes a page built around one question where users submit answers, such as a community thread. A support page with approved answers is an FAQPage. A forum thread with several user responses is a QAPage.

Does FAQ schema still matter after Google dropped FAQ rich results?

Google deprecated the FAQ rich result on May 8, 2026, saying the feature “will no longer appear in Google Search starting May 7, 2026”, and removed its documentation on June 15, 2026. Both entries are in Google Search Central’s changelog. Before that, the feature had been limited since 2023 to well-known government and health websites, so most software sites had not seen an expanded FAQ snippet for years.

So the honest answer to “should I add FAQ schema for Google?” is: not for a rich result. There isn’t one any more. What is left:

• It is still valid Schema.org. The vocabulary did not change; only Google’s display feature went away.
• It is an explicit, machine-readable map of your Q&A. Any parser that reads JSON-LD, including other search engines and AI answer systems, gets the question/answer pairs without guessing at your HTML. Whether a given system uses it is that system’s decision, so treat this as a low-cost signal, not a promise.
• It costs almost nothing if you generate it. When the FAQ section and the JSON-LD come from the same data, they cannot drift apart. Automating schema markup in your codebase shows one way to derive FAQPage from the headings you already write.

If you have hand-written FAQ JSON-LD that is out of sync with the visible page, deleting it is a reasonable fix. Markup that disagrees with the page is worse than none.

How FAQPage structured data works

Which properties does FAQPage use?

The smallest useful structure has @context, @type, and mainEntity, which is a list of Question items. Each question needs a name (the question text) and an acceptedAnswer whose @type is Answer and whose text holds the answer.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "Does SEOAgent publish changes automatically?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "No. The coding agent writes proposed changes into your repository, and you approve and ship them."
      }
    }
  ]
}
</script>

Where should developers put the markup?

Put the JSON-LD in the page’s server-rendered HTML, in the head or the body. In a repository that usually means a route component, a page template, or a metadata module; the framework decides the exact file. The output matters more than the source: fetch the deployed page and confirm the script is in the HTML a crawler receives, not only in the DOM after JavaScript runs.

Every marked-up question and answer must also be visible on the page. Keep one FAQPage entity per page unless your framework deliberately merges several JSON-LD blocks into one @graph.

When should you skip FAQPage markup?

Skip it when the content is not a real FAQ:

• Questions or answers hidden from visitors.
• The same answers repeated across unrelated pages.
• Promotional copy dressed up as an answer.
• User-submitted answers marked up as if the site gave one authoritative response (use QAPage).
• Questions invented only to repeat a target keyword.

How to write FAQs that help readers

Write one specific question at a time. Put the direct answer in the first sentence, then add the condition, example, or detail a reader needs next. For “Does FAQ schema improve rankings?”, a useful answer starts with “No” and then explains what the markup does do.

Match the questions to the page’s search intent. A developer reading about repository-based SEO wants answers about rendered HTML, JSON-LD, and review workflows; a shopper wants return-policy details. Mixing both audiences produces vague FAQs that serve neither. And don’t turn every question into a variation of one keyword: a reader notices, and so does any quality system.

FAQ schema compared with other page metadata

FAQ schema is one of several things in a page’s HTML that describe it to machines. None of them substitutes for another, which is why a review should check each one on its own. What are SEO tags? covers the rest in more depth.

Element	What it describes	Developer check
FAQ schema (FAQPage JSON-LD)	Questions and their authoritative answers	Matches the visible FAQ text exactly
Title tag (<title>)	The page’s identity	Unique and descriptive per route
Meta description	A suggested search-result summary	Accurate, readable, about 150–160 characters
Canonical link	The preferred URL for the page	Absolute and self-referencing on the live origin
Visible FAQ content	What visitors actually read	Present in the server-rendered HTML

How to audit FAQ schema in a codebase

Start from the rendered page, then trace the output back to its source:

1. Search the repository for FAQPage, application/ld+json, and a sentence of the question text.
2. Fetch the deployed URL and read the raw HTML, not the browser’s DOM inspector.
3. Compare every JSON-LD question and answer with the visible text. Any mismatch is a bug.
4. Check the JSON parses, the types are spelled correctly, and the page has one FAQPage entity.
5. Validate it with the Schema Markup Validator. Google’s Rich Results Test no longer reports FAQ results, since the feature is gone.
6. Re-check after any change to the FAQ component, the route template, or the content data.

A validator catches syntax and property problems. It cannot tell whether an answer is misleading, out of date, or hidden, so a human still reads the answers.

Doing this with a coding agent

SEOAgent is built for this repository workflow. Its free Skill and seoagent CLI audit the live site from inside your coding agent and write proposed changes, including JSON-LD, into your repo for you to approve. It doesn’t publish to a CMS. In Claude Code, you review the diff, check the generated FAQPage against the visible FAQ, and ship it through your normal pull request. The SEO optimization feature covers audits, metadata, and schema; topic clusters map the related pages an FAQ should link to.

The test for any FAQ schema is simple: a visitor can see every answer, the JSON-LD describes exactly that text, and the change lives in the repository you ship.