No FAQPage schema on an FAQ section

What Is This Issue

Pages with visible FAQ or Q&A sections are missing FAQPage schema. While Google reduced FAQ rich result display in 2023, the schema still provides strong signals for AI Overviews and voice search.

Without FAQPage schema:

AI search engines can’t properly understand your Q&A content
Voice search results won’t be able to provide your FAQ answers
Structured Q&A data is not available for search engines
Users may not find quick answers to common questions

A proper FAQPage schema should include: @type (FAQPage), mainEntity with Question entities, each having name (question text) and acceptedAnswer with Answer type containing text (answer text).

Why Is This Important

FAQPage schema is important for AI search and voice assistants:

AI Overviews: Provides structured Q&A data that AI engines can use to answer user queries
Voice search: Voice assistants can read FAQ answers directly from structured data
Featured snippets: Q&A content may appear in featured snippets
User experience: Helps search engines understand and surface your FAQ content
Voice assistants: Enables voice assistants to provide accurate answers from your FAQ

Resolving this issue improves your SEO health score by ensuring Q&A content is properly structured for AI search and voice assistants.

How XeoPix Detects This

XeoPix follows these logical steps to detect missing FAQPage schema:

Detect FAQ pages: The crawler identifies pages with:
- FAQ URL patterns (/faq, /help, /support)
- Visible accordion Q&A sections
- Heading text containing “FAQ”, “Frequently Asked Questions”, etc.
Extract structured data: The crawler looks for JSON-LD, Microdata, or RDFa blocks on the page
Check for FAQPage schema: The crawler verifies if any schema block has:
- @type set to FAQPage
- mainEntity property containing Question entities
Validate schema completeness: If FAQPage schema is found, the crawler checks for:
- Each Question has name property (question text)
- Each Question has acceptedAnswer property
- Each acceptedAnswer has text property (answer text)
- Schema Q&A matches visible page content
Trigger conditions: The issue is flagged when:
- Page has FAQ content but no FAQPage schema
- FAQPage schema exists but questions are missing acceptedAnswer
- Schema Q&A does not match visible page content

How To Fix

Identify FAQ pages: Look for pages with FAQ URL patterns (/faq, /help, /support) or accordion Q&A sections

Add FAQPage JSON-LD structured data to the page’s <head> or before </body>:


{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is your return policy?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "We offer 30-day returns for all products in original condition."
      }
    },
    {
      "@type": "Question",
      "name": "Do you ship internationally?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes, we ship to over 150 countries worldwide."
      }
    }
  ]
}

Ensure schema matches visible content:
- The Q&A in schema must exactly match what is visible on the page
- Do not include hidden or collapsed Q&A unless expanded by default
- All acceptedAnswer text should be visible by default
Sync dynamically: Update schema dynamically from your CMS FAQ content
Validate with Google’s Rich Results Test

Notes

Google reduced FAQ rich result display in 2023, but the schema still provides strong signals for AI Overviews and voice search
Only use FAQPage schema for pages that actually have FAQ content
Ensure each Question has both name (question text) and acceptedAnswer with text (answer text)

What We Store

Storage Level

Page Level — This issue is evaluated for each individual URL that contains structured data.

Database Table / Prisma Model

PageStructuredData

Stored Fields

Field	Type	Description
schemaType	SchemaType	The type of schema (e.g., Organization, Person)
schemaFormat	SchemaFormat	The format of the schema (JSON-LD, Microdata, RDFa)
schemaIdentifier	String?	Unique identifier for the schema
rawJson	Json?	The raw JSON-LD or structured data content
schemaErrors	Json?	Array of validation errors found in the schema
isValidSchema	Boolean?	Whether the schema is valid according to validation
missingFields	Json?	Array of required fields that are missing

Detection Dependencies

The following data sources are required to evaluate this issue:
HTML Document — The crawler parses the HTML to find structured data (JSON-LD, Microdata, RDFa)
Structured Data Validation — The extracted schema is validated against Schema.org definitions
Schema Parser — JSON-LD scripts, Microdata attributes, and RDFa markup are parsed

Examples

Example 1: Missing FAQPage Schema on FAQ Page

Problematic state:


<!-- FAQ page without FAQPage schema -->
<html>
  <head>
    <title>Frequently Asked Questions - Example Store</title>
  </head>
  <body>
    <h1>Frequently Asked Questions</h1>
 
    <h2>What is your return policy?</h2>
    <p>We offer 30-day returns for all products in original condition.</p>
 
    <h2>Do you ship internationally?</h2>
    <p>Yes, we ship to over 150 countries worldwide.</p>
  </body>
</html>

Corrected state:


<!-- FAQ page with FAQPage schema -->
<html>
  <head>
    <title>Frequently Asked Questions - Example Store</title>
    <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "FAQPage",
        "mainEntity": [
          {
            "@type": "Question",
            "name": "What is your return policy?",
            "acceptedAnswer": {
              "@type": "Answer",
              "text": "We offer 30-day returns for all products in original condition."
            }
          },
          {
            "@type": "Question",
            "name": "Do you ship internationally?",
            "acceptedAnswer": {
              "@type": "Answer",
              "text": "Yes, we ship to over 150 countries worldwide."
            }
          }
        ]
      }
    </script>
  </head>
  <body>
    <h1>Frequently Asked Questions</h1>
 
    <h2>What is your return policy?</h2>
    <p>We offer 30-day returns for all products in original condition.</p>
 
    <h2>Do you ship internationally?</h2>
    <p>Yes, we ship to over 150 countries worldwide.</p>
  </body>
</html>

Example 2: FAQPage Schema with Multiple Questions

Corrected state:


{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "How long does shipping take?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Standard shipping takes 3-5 business days. Express shipping takes 1-2 business days."
      }
    },
    {
      "@type": "Question",
      "name": "What payment methods do you accept?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "We accept Visa, Mastercard, American Express, PayPal, and Apple Pay."
      }
    },
    {
      "@type": "Question",
      "name": "Can I track my order?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Yes, you will receive a tracking number via email once your order ships."
      }
    }
  ]
}

Example 3: Incomplete FAQPage Schema

Problematic state:


{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is your return policy?"
    }
  ]
}

Missing acceptedAnswer property

Corrected state:


{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is your return policy?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "We offer 30-day returns for all products in original condition."
      }
    }
  ]
}

Unit Test

Test File

xeopix-crawling-v2/__tests__/seo-audit-checks/structuredDataRichResults/issue-62-faq-schema.test.js

Purpose

Validates that the crawler correctly detects when a page with FAQ content (FAQ classes, headings, or text patterns) is missing a FAQPage schema.

Tested Function

runStructuredDataRichResults()

Issue Information

Issue Number: 62
Issue Code: faq_schema_faq
Toggle Group: structuredDataRichResults

Test Scenarios

Positive Test Cases

FAQPage schema present: Page has a FAQPage schema with mainEntity containing Question/Answer entries — no issue reported.
No FAQ content: Page has no FAQ-related content — no issue reported.

Negative Test Cases

FAQ class detected: Page has elements with faq-item or faq-question class but no FAQPage schema — issue is reported with detectionHints.hasFaqClass set to true.
FAQ heading detected: Page has “FAQ” or “Frequently Asked Questions” headings but no schema — issue is reported with detectionHints.hasFaqHeading set to true.
FAQ text patterns detected: Page has “frequently asked questions” or “Question: / Answer:” text patterns but no schema — issue is reported with detectionHints.hasFaqText set to true.

Boundary Cases

None.

Edge Cases

Empty HTML: <html></html> — no issue reported, no crash.
Malformed HTML: Unclosed tags — no crash.

Expected Outcome

Pass

Issue should not be reported when a FAQPage schema is present or when the page has no FAQ-related content.

Fail

Issue should be reported when the page contains FAQ-related content (classes, headings, or text patterns) but lacks a FAQPage schema. Detection hints indicate which pattern was matched.

Validation

Correct issue detection when FAQ content exists without schema
No issue detection when FAQPage schema is present
No issue detection when no FAQ content exists
Detection hints (hasFaqClass, hasFaqHeading, hasFaqText) populated correctly
Graceful handling of empty and malformed HTML

xeopix-crawling-v2/toggleGroups/structuredDataRichResults.js
xeopix-crawling-v2/issueCodes.js
xeopix-crawling-v2/utils/context.js
xeopix-crawling-v2/utils/issues.js
xeopix-crawling-v2/utils/schema.js

Coverage Summary

Covers presence of FAQPage schema
Covers detection of FAQ class names, headings, and text patterns
Covers absence of false positives when no FAQ content exists
Covers empty HTML resilience
Covers malformed HTML resilience

References

Schema.org — FAQPage — Schema.org
Google — FAQ Rich Result — Google Search Central
Google Rich Results Test — Google Search Central

No FAQPage schema on an FAQ section

What Is This Issue

Why Is This Important

How XeoPix Detects This

How To Fix

Notes

What We Store

Storage Level

Database Table / Prisma Model

Stored Fields

Detection Dependencies

Examples

Example 1: Missing FAQPage Schema on FAQ Page

Example 2: FAQPage Schema with Multiple Questions

Example 3: Incomplete FAQPage Schema

Unit Test

Test File

Purpose

Tested Function

Issue Information

Test Scenarios

Positive Test Cases

Negative Test Cases

Boundary Cases

Edge Cases

Expected Outcome

Pass

Fail

Validation

Related Production Files

Coverage Summary

References