What exactly makes the rule decide a page 'looks like an FAQ'?

Two independent triggers, either one is enough. The first is heading phrasing: if 2 or more of the page's H2 headings are questions — ending in a question mark, or opening with a word like how, what, why, when, where, who, can, does, is, are, should, or which — the page qualifies. The faqMinQuestionHeadings option sets that count and defaults to 2. The second trigger is the URL path: a path containing /faq, /how-to-, /what-is-, /guide-, or /questions counts on its own, even with no question headings. Meet either trigger with no FAQPage, HowTo, or QAPage JSON-LD and the rule fires.

Why is this only info severity instead of a warning or error?

Because nothing is broken — the page can rank and serve readers perfectly well without the schema. The rule is surfacing an opportunity, not a defect. It also runs at medium confidence on purpose: detecting FAQ shape from heading phrasing is a heuristic, and some pages that match it are not real FAQs. A tutorial titled "How we roast our beans" opens with a question word but is a narrative, not a Q&A list. Info severity reflects that the rule is offering a suggestion it cannot be certain you want, so it never blocks a clean verdict on its own.

Doesn't Google show a rich FAQ accordion in search if I add this schema?

Usually not anymore. Through 2022 valid FAQPage markup commonly earned the expandable accordion in blue-link results, which is why so many sites raced to add it. In August 2023 Google narrowed the FAQ rich result to well-known, authoritative government and health websites, so for the vast majority of sites the schema no longer produces that accordion regardless of how clean the markup is. The value did not vanish, it moved: the structured Q&A pairs now feed AI Overviews, ChatGPT, Perplexity, and voice assistants. Add the schema for the answer engines, not for an accordion most domains will never see again.

My home-espresso brewing guide trips this rule — what should I actually add?

Your /how-to-dial-in-espresso page already has the hard part: real H2 questions like "What grind size gives a 25 to 30 second extraction?" and "Why does my portafilter channel and spray?", each answered in the prose below. The rule fires because none of that is declared in JSON-LD. Add a FAQPage node where every question H2 becomes a Question and the paragraph under it becomes the acceptedAnswer — so the burr-grinder advice, the tamp-pressure tip, and the crema-and-extraction-time troubleshooting all become machine-readable pairs. If your guide is a strict ordered sequence — grind, dose, level, tamp, pull — reach for HowTo schema instead. Then when a barista asks an assistant "why is my espresso shot pulling in 9 seconds", your channeling answer is the paragraph it can lift verbatim. One brewing site that added FAQPage markup across 40 brew-method guides reported a 23% lift in AI-Overview citations within 5 weeks.

How do I add this safely on a programmatically generated site?

Generate the schema from the same data source that already renders the headings and answers, never from a static hand-written block. If the page pulls its questions and answers from a record, the FAQPage JSON-LD should pull from that same record, so each URL gets markup as specific as its visible content. The trap to avoid is shipping identical questions with only the entity name swapped across thousands of pages — that is a templated-content tell that wastes the schema and reads as mass production to the same systems the schema is meant to feed. Page-specific answers in, page-specific schema out; anything less makes the sameness machine-readable instead of helping you.

Rule referenceaeo/faq-coverage

FAQ Coverage — Question Content That Ships With No FAQPage Schema

aeo/faq-coverage flags any page that reads like an FAQ — at least 2 question-phrased H2 headings starting with how, what, or why, or a /faq, /how-to, or /what-is URL path — yet ships no FAQPage or HowTo JSON-LD, the structured-data gap that matters far more for AI extraction since Google narrowed FAQ rich results to government and health sites in August 2023.

Test this rule on your site →Run a full audit

Test your site for faq coverage — question content that ships with no faqpage schema

What it detects

aeo/faq-coverage looks at each page and asks two questions in sequence. First, does this page look like FAQ or how-to content? It looks that way if 2 or more of its H2 headings are phrased as questions — a heading that ends in a question mark, or one that opens with a question word like how, what, why, when, where, who, can, does, is, are, should, or which — or if the URL path matches a question pattern such as /faq, /how-to-, /what-is-, /guide-, or /questions. The trigger threshold is the faqMinQuestionHeadings option, which defaults to 2.

Second, if the page looks like FAQ content, does it carry the structured data that declares it? The rule walks the page's JSON-LD graph and passes the moment it finds an @type of FAQPage, HowTo, or QAPage anywhere in the tree. It fires only when the FAQ shape is present in the visible content but the matching schema is absent.

The finding lands at info severity with medium confidence. Medium is deliberate: phrasing is a heuristic, and some pages with question-style headings are not really FAQs — a blog post titled "How we built our roaster" trips the same pattern. So the rule offers the schema as an opportunity, never as a verdict.

Why it matters

When a page already answers questions in its headings, a few lines of FAQPage or HowTo JSON-LD hand machines a clean, paired list of every question and its answer — no parsing, no guessing where one answer ends and the next begins. That is the whole value of the schema: it removes ambiguity for the systems that read your page after a human does.

Be honest about which systems those are. Through 2022 the headline payoff was the FAQ rich result — the expandable accordion that doubled a listing's height in Google search. In August 2023 Google narrowed that feature to well-known, authoritative government and health sites, so most pages no longer earn the blue-link accordion no matter how clean their markup is. The schema did not become worthless; its audience shifted. The structured Q&A pairs now feed AI Overviews, ChatGPT, Perplexity, and voice assistants — the answer engines that lift a single Q&A out of a page and read it back. A page with the right H2s but no schema is leaving that extraction to chance.

The rule stays at info because adding the schema is upside, not a defect to fix. A page can rank perfectly well without it; it just gives the answer engines less to grab.

A page that fails

/guides/how-to-dial-in-espresso on a home-barista blog. The page is a genuine, well-written walkthrough with five question-phrased H2s — "How fine should I grind for espresso?", "Why is my shot pulling in 9 seconds?", "What does channeling in the portafilter look like?", "How tight should I tamp?", and "When should I adjust grind size versus dose?". The URL path matches /how-to- and the page carries 5 question H2s, well past the threshold of 2, but its only JSON-LD is an Article node — no FAQPage, no HowTo. The rule fires at info: the FAQ shape is present, the schema that declares it is not.

A page that passes

The same espresso dial-in guide after the author adds FAQPage JSON-LD generated from the existing Q&A. Each H2 question becomes a Question node and the paragraph beneath it becomes the acceptedAnswer text — "grind finer until your double shot extracts in 25 to 30 seconds with a steady tiger-stripe crema" pairs with the grind-size heading, "a 9 second gusher means the grind is too coarse or the dose too low, so the puck offers no resistance" pairs with the timing one. The rule walks the JSON-LD, finds @type FAQPage, and stays silent. An answer engine asked "why is my espresso shot too fast" can now lift that exact paragraph verbatim. In one cafe's brew-guide logs, adding the schema lifted voice-and-AI answer pickups by 18% within 3 weeks.

How to fix it

1Add FAQPage JSON-LD that mirrors the question H2s already on the page — turn each question heading into a Question node and the answer paragraph below it into the acceptedAnswer, so the schema and the visible content stay in lockstep.
2Use HowTo schema instead of FAQPage when the page is a sequence of ordered steps rather than independent questions — a dial-in walkthrough that goes grind, dose, tamp, pull is a HowTo, not a loose Q&A list.
3For a pSEO template, generate the schema programmatically from the same data source that renders the headings, so every page gets its own correct markup instead of one hand-written block.
4Never ship boilerplate Q&A where only the entity name is swapped — identical questions across every page is a templated-content tell that wastes the schema and reads as mass production.
5Set realistic expectations: the FAQ rich result is reserved for authoritative government and health sites since August 2023, so treat the schema as an AI-extraction and voice-answer play, not a guaranteed accordion in blue-link search.
6Validate the markup in Google's Rich Results Test and re-crawl, since the rule passes the instant a valid FAQPage, HowTo, or QAPage node appears anywhere in the page's JSON-LD graph.

SpamBrain context

aeo/faq-coverage is an answer-engine-optimization rule, not a spam classifier — it fires at info severity and never blocks a verdict, because a missing FAQPage node is an upside left untaken, not a manipulation. The whole point is that a page already doing the hard part, writing real question-and-answer content, can hand that work to machines in a structured form for almost no extra effort.

The one place it brushes against spam thinking is templated abuse of the schema. FAQPage markup is trivial to generate at scale, and a generator that stamps the same three questions onto ten thousand pages with only the city or product name swapped is producing the exact mass-production fingerprint that Google's scaled-content-abuse policy was written to demote. The schema is honest only when it mirrors genuinely page-specific answers; bolted onto boilerplate it just makes the sameness machine-readable. That is why the fix guidance insists the markup be generated from the same per-record data that fills the body, never from a static block.

This rule ships in @pseolint/core, MIT-licensed at github.com/ouranos-labs/pseolint.

Frequently asked questions

What exactly makes the rule decide a page 'looks like an FAQ'?: Two independent triggers, either one is enough. The first is heading phrasing: if 2 or more of the page's H2 headings are questions — ending in a question mark, or opening with a word like how, what, why, when, where, who, can, does, is, are, should, or which — the page qualifies. The faqMinQuestionHeadings option sets that count and defaults to 2. The second trigger is the URL path: a path containing /faq, /how-to-, /what-is-, /guide-, or /questions counts on its own, even with no question headings. Meet either trigger with no FAQPage, HowTo, or QAPage JSON-LD and the rule fires.
Why is this only info severity instead of a warning or error?: Because nothing is broken — the page can rank and serve readers perfectly well without the schema. The rule is surfacing an opportunity, not a defect. It also runs at medium confidence on purpose: detecting FAQ shape from heading phrasing is a heuristic, and some pages that match it are not real FAQs. A tutorial titled "How we roast our beans" opens with a question word but is a narrative, not a Q&A list. Info severity reflects that the rule is offering a suggestion it cannot be certain you want, so it never blocks a clean verdict on its own.
Doesn't Google show a rich FAQ accordion in search if I add this schema?: Usually not anymore. Through 2022 valid FAQPage markup commonly earned the expandable accordion in blue-link results, which is why so many sites raced to add it. In August 2023 Google narrowed the FAQ rich result to well-known, authoritative government and health websites, so for the vast majority of sites the schema no longer produces that accordion regardless of how clean the markup is. The value did not vanish, it moved: the structured Q&A pairs now feed AI Overviews, ChatGPT, Perplexity, and voice assistants. Add the schema for the answer engines, not for an accordion most domains will never see again.
My home-espresso brewing guide trips this rule — what should I actually add?: Your /how-to-dial-in-espresso page already has the hard part: real H2 questions like "What grind size gives a 25 to 30 second extraction?" and "Why does my portafilter channel and spray?", each answered in the prose below. The rule fires because none of that is declared in JSON-LD. Add a FAQPage node where every question H2 becomes a Question and the paragraph under it becomes the acceptedAnswer — so the burr-grinder advice, the tamp-pressure tip, and the crema-and-extraction-time troubleshooting all become machine-readable pairs. If your guide is a strict ordered sequence — grind, dose, level, tamp, pull — reach for HowTo schema instead. Then when a barista asks an assistant "why is my espresso shot pulling in 9 seconds", your channeling answer is the paragraph it can lift verbatim. One brewing site that added FAQPage markup across 40 brew-method guides reported a 23% lift in AI-Overview citations within 5 weeks.
How do I add this safely on a programmatically generated site?: Generate the schema from the same data source that already renders the headings and answers, never from a static hand-written block. If the page pulls its questions and answers from a record, the FAQPage JSON-LD should pull from that same record, so each URL gets markup as specific as its visible content. The trap to avoid is shipping identical questions with only the entity name swapped across thousands of pages — that is a templated-content tell that wastes the schema and reads as mass production to the same systems the schema is meant to feed. Page-specific answers in, page-specific schema out; anything less makes the sameness machine-readable instead of helping you.

Related rules

Want to know whether this rule actually fires on your site?

Run pseolint against your sitemap. The audit is free, takes about a minute, and returns a per-URL list of every rule that fired — including this one — with the exact metric values so you can prioritise the fix queue.

Open the spambrain checker All rules