FAQ Schema Generation That Actually Matches the Page

FAQ schema is the most abused structured data type on the web. Pages mark up questions that are not visible, answers that are truncated versions of the text, and questions nobody searches for. Google's guidance is explicit: the marked-up content must be visible to users, and the markup must not be used to hide content that is not on the page. A generator that ignores those rules produces rich-result eligibility problems rather than rich results.

Start from what the page already answers

The usable question set comes from three sources: headings phrased as questions, a visible FAQ section, and query data from Search Console showing what the page already ranks for.

Pull candidate questions from Search Console first. A page receiving impressions for "does X work offline" has demonstrated demand and likely already answers it somewhere. Writing an answer that matches the page's actual content is straightforward; inventing a question the page never addresses is how mismatches happen.

If the page has no FAQ section, the honest options are to add visible questions with real answers or to skip FAQ schema. There is no third option where invisible markup helps.

An answer generated from the model's general knowledge will contradict the page. Feed the generator the section of the page that addresses the question and require it to produce an answer of 40–60 words using only that text. Then verify programmatically that each answer's key phrases appear in the page body.

A simple check catches most drift: for each answer, confirm that at least 60% of its content words occur in the page text. Answers that fail are either paraphrases of content that is not visible or hallucinations.

Build valid FAQPage JSON-LD

The minimal valid structure is a FAQPage with mainEntity containing Question items, each with acceptedAnswer of type Answer and a text value.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "Does the exporter work offline?",
    "acceptedAnswer": { "@type": "Answer", "text": "Yes. Parsing and export run locally..." }
  }]
}

Escape HTML entities, keep the JSON valid, and inject it as a single script tag. Validate with the Rich Results Test and the Schema Markup Validator; the two disagree often enough that both are worth running.

Know when FAQ rich results appear

Google restricted FAQ rich results in 2023 to authoritative government and health sites. For most commercial sites, FAQ schema no longer produces a visible rich result, even when it is valid. That does not make it useless: the markup still helps machines parse question-answer pairs, and AI answer engines often quote FAQ sections because they are already in the right shape.

The practical implication is that FAQ schema should follow visible, genuinely useful FAQs rather than drive page design. Do not add ten low-value questions solely for markup.

Mapping questions to page sections, and maintaining the mapping

FAQ answers go stale when pricing, availability, or features change. Treat each marked-up answer as content with an owner and a review date. A quarterly audit that compares the JSON-LD against the rendered DOM catches the most common failure — a redesigned section where the visible answer changed but the schema did not.

The rule that keeps this useful: if a user cannot read the answer on the page, it does not belong in the markup.

Before generating answers, map each candidate question to the section of the page that answers it. A question with no mapped section is either missing content or an invented query; both should be dropped or routed to a writer.

Keep the mapping in the CMS as structured data rather than reconstructing it at build time. When the section changes, the mapping breaks loudly instead of the schema silently drifting from the page.

Answer shape, and handling similar questions

A 40–60 word answer that opens with the direct response extracts better than a paragraph that builds up to it. Avoid pronouns that reference earlier context ("this", "it") because the extracted answer may appear without that context.

Include the condition in the answer when it is short: "Free for personal use; the team plan starts at..." A conditional answer without the condition is the most common way FAQ markup becomes misleading.

Two questions that differ only in phrasing should be one question. Duplicate coverage inside one page's FAQ weakens the answer to both and looks like padding to a reader.

If two genuinely distinct questions share an answer, keep both but write distinct answer text rather than copy-pasting. Duplicate answer text is a signal of over-generation.

The JSON-LD build step, and when schema is not worth it

Generate the JSON-LD from the same source as the rendered FAQ component so the two cannot diverge. A React component that renders questions from an array should serialize the same array into the script tag.

Validate in CI with a schema parser rather than a regex. The Rich Results Test is a manual check; a parser catches malformed JSON and missing required properties on every build.

Set a review date per FAQ. When a product change invalidates an answer, remove the question and the markup together. Stale FAQ markup is worse than none because it can generate a rich result that contradicts the page's own pricing or availability.

If the FAQ section is removed in a redesign, the structured data must be removed in the same deploy. Orphaned markup pointing at content that no longer exists is a common post-redesign regression and a quick way to lose eligibility across the whole site.

Monitoring, retirement, and the visible-answer rule

Pages with one question and a short answer do not need FAQPage markup. Neither do pages whose questions are navigational. The markup is for genuine question-answer content, and adding it to every page dilutes the signal without adding value.

Every question in the markup must be answerable from the page as a user sees it. Markup generated from a separate FAQ document that never appears on the page is a removal waiting to happen.

Generate both from one source: render the visible accordion from the same data that produces the JSON-LD.

Remove the markup the moment the visible content stops supporting it. A page that loses its FAQ section but keeps the JSON-LD is the most common way a site earns a structured-data penalty, and it usually happens during a redesign rather than deliberately. Tie the markup to the component that renders the answers, so deleting the component deletes the schema, and add the check to the template test rather than to a quarterly review.