Tutorial

FAQ Schema Markup Guide: Get Google Rich Results in 2026

Add FAQ schema markup to your website with JSON-LD structured data. Step-by-step guide with code examples for static sites, React, Next.js, and API-driven FAQ pages.

TheFAQApp TeamApril 6, 20268 min read

What Is FAQ Schema Markup?

FAQ schema markup is structured data you add to your web pages to tell Google that your content contains questions and answers. When Google recognizes this markup, it can display your FAQ content as rich results — expandable question-and-answer pairs directly in search results.

Rich results take up more visual space in search, increase click-through rates, and establish your page as an authoritative source for that topic.

The schema type is FAQPage from Schema.org, and the recommended format is JSON-LD (JavaScript Object Notation for Linked Data).

What Rich Results Look Like

When your FAQ schema is valid, Google may display your questions directly in search results:

Each question appears as a collapsible accordion
Users can expand answers without clicking through to your site
Your listing takes up significantly more vertical space than competitors
Multiple questions can appear for a single page

This visibility boost is especially valuable for product pages, pricing pages, and support content.

Basic JSON-LD FAQ Schema

Here is the simplest valid FAQ schema you can add to any HTML page:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is thefaq.app?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "thefaq.app is an API-first FAQ platform that lets you manage and deliver FAQ content through a REST API and TypeScript SDKs."
      }
    },
    {
      "@type": "Question",
      "name": "How much does it cost?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "thefaq.app offers a free tier with 50 FAQs and 1,000 API requests per month. Paid plans start at $19/month."
      }
    }
  ]
}
</script>

Place this <script> tag in the <head> or <body> of your page. Google will parse it regardless of position, but <head> is the convention.

Rules for Valid FAQ Schema

Each question must have exactly one accepted answer — no multiple answers per question
The full answer text must be in the markup — don't use truncated text or "read more" links
Answers can contain HTML — links, lists, and basic formatting are allowed in the text field
Questions must be visible on the page — don't add schema for questions that aren't displayed to users
Don't use FAQ schema for forums or user-generated Q&A — use QAPage schema instead

Adding FAQ Schema to a Static HTML Site

For simple websites, add the JSON-LD script directly to your HTML:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Frequently Asked Questions - Your Company</title>
  <meta name="description" content="Find answers to common questions about our product.">
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "How do I get started?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Sign up for a free account at app.thefaq.app. No credit card required. You can create your first FAQ category and start adding questions immediately."
        }
      },
      {
        "@type": "Question",
        "name": "Can I use the API on the free plan?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Yes. Every plan includes full REST API access, including the free tier. You get 1,000 API requests per month and 1 API key on the free plan."
        }
      }
    ]
  }
  </script>
</head>
<body>
  <!-- Your FAQ content here -->
</body>
</html>

This works for any static site, WordPress theme, or hand-coded page. No build tools or frameworks required.

Adding FAQ Schema in React

For React applications, generate the JSON-LD dynamically from your FAQ data:

interface FAQItem {
  question: string;
  answer: string;
}

function FAQSchema({ faqs }: { faqs: FAQItem[] }) {
  const schema = {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    mainEntity: faqs.map((faq) => ({
      "@type": "Question",
      name: faq.question,
      acceptedAnswer: {
        "@type": "Answer",
        text: faq.answer,
      },
    })),
  };

  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
    />
  );
}

// Usage
const faqs = [
  { question: "What is your refund policy?", answer: "We offer a 30-day money-back guarantee on all paid plans." },
  { question: "Do you offer an API?", answer: "Yes, every plan includes full REST API access." },
];

function FAQPage() {
  return (
    <>
      <FAQSchema faqs={faqs} />
      <h1>Frequently Asked Questions</h1>
      {faqs.map((faq) => (
        <details key={faq.question}>
          <summary>{faq.question}</summary>
          <p>{faq.answer}</p>
        </details>
      ))}
    </>
  );
}

This approach keeps your schema in sync with the displayed content — if you add a question to the array, both the visible FAQ and the schema update together.

Adding FAQ Schema in Next.js

Next.js has built-in support for JSON-LD through its metadata API. Here is how to add FAQ schema to a Next.js App Router page:

// app/faq/page.tsx
import type { Metadata } from "next";

const faqs = [
  {
    question: "What is thefaq.app?",
    answer: "An API-first FAQ platform with TypeScript SDKs, AI generation, and embeddable widgets.",
  },
  {
    question: "Is there a free plan?",
    answer: "Yes. The free plan includes 50 FAQs, 1,000 API requests per month, and a hosted FAQ page.",
  },
];

export const metadata: Metadata = {
  title: "FAQ - Your Product",
  description: "Answers to frequently asked questions.",
};

export default function FAQPage() {
  const schema = {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    mainEntity: faqs.map((faq) => ({
      "@type": "Question",
      name: faq.question,
      acceptedAnswer: {
        "@type": "Answer",
        text: faq.answer,
      },
    })),
  };

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
      />
      <h1>Frequently Asked Questions</h1>
      {faqs.map((faq) => (
        <section key={faq.question}>
          <h2>{faq.question}</h2>
          <p>{faq.answer}</p>
        </section>
      ))}
    </>
  );
}

For dynamic FAQ content fetched from an API, combine this with the @faqapp/nextjs SDK:

import { FAQClient } from "@faqapp/core";

const faq = new FAQClient({
  apiKey: process.env.FAQ_API_KEY!,
  organizationSlug: "my-org",
});

export default async function FAQPage() {
  const { data: questions } = await faq.questions.list();

  const schema = {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    mainEntity: questions.map((q) => ({
      "@type": "Question",
      name: q.question,
      acceptedAnswer: {
        "@type": "Answer",
        text: q.answer,
      },
    })),
  };

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
      />
      <h1>Frequently Asked Questions</h1>
      {questions.map((q) => (
        <section key={q.id}>
          <h2>{q.question}</h2>
          <div dangerouslySetInnerHTML={{ __html: q.answer }} />
        </section>
      ))}
    </>
  );
}

With this approach, your FAQ schema is always in sync with your API content. When you update a question in the thefaq.app dashboard, both the page content and the structured data update automatically on the next request.

API-Driven FAQ Schema (The Better Way)

Hardcoding FAQ schema works for small, static FAQ pages. But as your FAQ grows, you need a system that:

Keeps schema and displayed content in sync automatically
Handles additions, edits, and deletions without code changes
Works across multiple pages and categories

This is where an API-first FAQ platform shines. With thefaq.app, your hosted FAQ pages automatically include valid JSON-LD FAQ schema — no manual markup needed.

If you're building a custom frontend, the SDK gives you the data you need to generate schema dynamically:

import { FAQClient } from "@faqapp/core";

const client = new FAQClient({
  apiKey: process.env.FAQ_API_KEY!,
  organizationSlug: "my-org",
});

// Fetch questions for a specific category
const { data: questions } = await client.questions.list({
  category: "pricing",
});

// Generate JSON-LD schema
const faqSchema = {
  "@context": "https://schema.org",
  "@type": "FAQPage",
  mainEntity: questions.map((q) => ({
    "@type": "Question",
    name: q.question,
    acceptedAnswer: {
      "@type": "Answer",
      text: q.answer,
    },
  })),
};

No more manually editing schema when content changes. No more schema drift. Your structured data is always accurate because it comes from the same source as your displayed content.

Validating Your FAQ Schema

Before deploying, verify your schema is valid:

Google Rich Results Test

Go to Google's Rich Results Test
Enter your page URL or paste the HTML
Look for "FAQ" in the detected structured data
Fix any errors or warnings

Schema Markup Validator

Go to Schema.org Validator
Paste your JSON-LD code
Verify the structure matches the FAQPage specification

Common Validation Errors

Error	Cause	Fix
Missing `acceptedAnswer`	Question without an answer	Add the `acceptedAnswer` object
Invalid `@type`	Typo in type name	Use exactly `FAQPage`, `Question`, `Answer`
Empty `text` field	Answer text is blank	Add the full answer text
`name` field missing	Question text not provided	Add the `name` field with the question

FAQ Schema Best Practices

Do

Include all visible questions in the schema — schema should match displayed content
Use full answer text — don't truncate or summarize
Keep answers updated — stale schema hurts trust signals
Add schema to category pages — if you have multiple FAQ categories, each page gets its own schema
Use an API to generate schema — avoids manual maintenance and drift

Don't

Don't add questions not visible on the page — Google may issue a manual action
Don't use FAQ schema on pages that aren't FAQ pages — product pages, about pages, and homepages are not FAQ pages
Don't duplicate schema across pages — each question should appear in schema on one page only
Don't use FAQ schema for user-generated Q&A — use QAPage instead
Don't stuff keywords into questions — write natural questions that match user intent

FAQ Schema and SEO Impact

FAQ schema doesn't directly improve rankings, but it significantly impacts visibility:

Higher click-through rates — Rich results are more eye-catching than plain blue links
More SERP real estate — FAQ accordions push competitors down the page
Voice search compatibility — Google Assistant and other voice tools pull from FAQ schema
Featured snippet eligibility — Well-structured FAQ content is more likely to appear in position zero

For a deeper dive into FAQ SEO strategy beyond schema markup, read our complete FAQ SEO guide.

Skip the Manual Work

If you're spending time manually writing and maintaining FAQ schema markup, there's a faster path. thefaq.app automatically generates valid JSON-LD FAQ schema on every hosted FAQ page. You manage content through the dashboard or API, and the schema stays in sync.

For custom frontends, the TypeScript SDK gives you the data to generate schema dynamically — no hardcoding, no drift.

Try thefaq.app free → — 50 FAQs, full API access, automatic schema markup. No credit card required.

Ready to build your FAQ?

Create searchable, API-powered FAQ pages in minutes. Free to start — no credit card required.

Get started free Read the docs

Continue reading