pseo-schema

pSEO Schema Markup

Implement JSON-LD structured data that gives search engines explicit semantic understanding of every programmatic page.

Core Principles

1. JSON-LD format: Always use JSON-LD, not Microdata or RDFa
2. Context-appropriate types: Match schema type to the page's actual content
3. Data-driven generation: Schema is built from the same data that drives the page
4. Valid and complete: Every schema block must pass Google's Rich Results Test
5. No fabrication: Only include fields backed by real data

Baseline Schema (Every Page)

Every pSEO page should include these foundational types:

• WebSite — once per site (on the homepage or via a shared layout), declares site-level search and name
• WebPage — on every page, declares the page URL, name, description, and dateModified
• BreadcrumbList — on every page with navigation hierarchy

These are in addition to the content-specific types below.

Schema Types by Page Context

Page Type	Primary Schema	Supporting Schema
Content/article page	Article	BreadcrumbList, FAQPage, WebPage
Product page	Product	BreadcrumbList, AggregateRating, WebPage
FAQ/Q&A page	FAQPage	BreadcrumbList, WebPage
How-to/tutorial page	HowTo	BreadcrumbList, FAQPage, WebPage
Category/hub page	CollectionPage	BreadcrumbList, ItemList, WebPage
Local/location page	LocalBusiness	BreadcrumbList, FAQPage, WebPage

Implementation Steps

1. Create Schema Generator Functions

Build a module of pure functions that produce schema objects from page data:

// lib/schema.ts

export function generateArticleSchema(data: PageData, url: string) {
  return {
    "@context": "https://schema.org",
    "@type": "Article",
    headline: data.h1,
    description: data.metaDescription,
    url,
    datePublished: data.publishedDate,
    dateModified: data.lastModified,
    author: { "@type": "Organization", name: "..." },
    publisher: { "@type": "Organization", name: "..." },
  };
}

// IMPORTANT: FAQPage schema is ONLY valid when the FAQ content is
// visible on the page itself. Google requires the questions and answers
// to be present in the rendered HTML, not just in the JSON-LD.
// Never add FAQPage schema to a page that does not render the FAQs.
export function generateFAQSchema(faqs: FAQ[]) {
  if (!faqs?.length) return null;
  return {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    mainEntity: faqs.map((faq) => ({
      "@type": "Question",
      name: faq.question,
      acceptedAnswer: {
        "@type": "Answer",
        text: faq.answer,
      },
    })),
  };
}

export function generateWebPageSchema(data: PageData, url: string) {
  return {
    "@context": "https://schema.org",
    "@type": "WebPage",
    name: data.title,
    description: data.metaDescription,
    url,
    dateModified: data.lastModified,
  };
}

export function generateBreadcrumbSchema(
  items: { name: string; url: string }[]
) {
  return {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    itemListElement: items.map((item, i) => ({
      "@type": "ListItem",
      position: i + 1,
      name: item.name,
      item: item.url,
    })),
  };
}