@power-seo/schema

@power-seo/schema

Type-safe JSON-LD structured data for TypeScript and React — 23 schema.org builder functions, 22 React components, schema graph support, and field validation. Works in Next.js, Remix, Node.js, and Edge runtimes.

@power-seo/schema gives you a fully typed, builder-function API for generating Google-compliant schema.org markup — with compile-time type checking on every schema property, a validateSchema() utility that surfaces missing required fields before pages go live, and pre-built React components that render <script type="application/ld+json"> tags in one line. Combine multiple schemas into a single @graph document via schemaGraph() so Google parses all of them. All 23 schema types are independently importable and tree-shakeable.

Zero runtime dependencies — only @power-seo/core as a peer.

Why @power-seo/schema?

	Without	With
Field type safety	❌ Hand-written JSON, no types	✅ Typed builder functions catch missing fields at compile time
Multiple schemas per page	❌ Separate <script> tags, Google may miss some	✅ schemaGraph() combines all into one @graph document
Field validation	❌ Silent failures in rich results	✅ validateSchema() returns structured issues before deploy
React rendering	❌ Manual dangerouslySetInnerHTML boilerplate	✅ <ArticleJsonLd> and 21 other components in one import
Schema coverage	❌ Only Article/FAQ in most packages	✅ 23 types: Article, Product, FAQ, LocalBusiness, Event, Recipe, and more
Framework support	❌ WordPress / next-seo only	✅ Next.js, Remix, Node.js, Edge, static site generators

Features

• 23 schema.org type builder functions — Article, BlogPosting, NewsArticle, Product, FAQPage, BreadcrumbList, LocalBusiness, Organization, Person, Event, Recipe, HowTo, VideoObject, Course, JobPosting, SoftwareApplication, WebSite, ItemList, Review, Service, Brand, SiteNavigationElement, ImageObject
• 22 pre-built React components — <ArticleJsonLd>, <BlogPostingJsonLd>, <NewsArticleJsonLd>, <ProductJsonLd>, <FAQJsonLd>, <BreadcrumbJsonLd>, <LocalBusinessJsonLd>, <OrganizationJsonLd>, <PersonJsonLd>, <EventJsonLd>, <RecipeJsonLd>, <HowToJsonLd>, <VideoJsonLd>, <CourseJsonLd>, <JobPostingJsonLd>, <SoftwareAppJsonLd>, <WebSiteJsonLd>, <ItemListJsonLd>, <ReviewJsonLd>, <ServiceJsonLd>, <BrandJsonLd>, and <JsonLd> (generic, renders any schema)
• schemaGraph() — combine multiple schemas into a single @graph document for optimal Google parsing
• toJsonLdString() — serialize any schema object to a safe JSON-LD string for dangerouslySetInnerHTML
• validateSchema() — validate required fields without throwing; returns { valid, issues } with severity, field, and message per issue
• React optional — all 23 builder functions work without React; 22 React components available via /react subpath export
• Type-safe API — TypeScript-first with full typed interfaces for every schema type including nested objects
• Tree-shakeable — import only the schema types you use; zero dead code in your bundle
• Dual ESM + CJS — ships both formats via tsup for any bundler or require() usage

Comparison

Feature	@power-seo/schema	next-seo	schema-dts	json-ld.js	react-schemaorg
Typed builder functions	✅	Partial	❌	❌	❌
Ready-to-use React components	✅	✅	❌	❌	Partial
@graph support	✅	❌	❌	✅	❌
Built-in field validation	✅	❌	❌	❌	❌
Works without React	✅	❌	✅	✅	❌
23 schema types	✅	Partial	✅	✅	❌
CI / Node.js usage	✅	❌	✅	✅	❌
Zero runtime dependencies	✅	❌	✅	❌	❌
TypeScript-first	✅	Partial	✅	❌	❌
Tree-shakeable	✅	❌	✅	❌	❌

Installation

npm install @power-seo/schema

yarn add @power-seo/schema

pnpm add @power-seo/schema

Quick Start

// Builder function approach (works without React)
import { article, toJsonLdString } from '@power-seo/schema';

const schema = article({
  headline: 'My Blog Post',
  description: 'An informative article about SEO.',
  datePublished: '2026-01-15',
  dateModified: '2026-01-20',
  author: { name: 'Jane Doe', url: 'https://example.com/authors/jane-doe' },
  image: { url: 'https://example.com/article-cover.jpg', width: 1200, height: 630 },
});

const script = toJsonLdString(schema);
// → '{"@context":"https://schema.org","@type":"Article","headline":"My Blog Post",...}'

// React component approach
import { ArticleJsonLd } from '@power-seo/schema/react';

<ArticleJsonLd
  headline="My Blog Post"
  description="An informative article about SEO."
  datePublished="2026-01-15"
  author={{ name: 'Jane Doe', url: 'https://example.com/authors/jane-doe' }}
  image={{ url: 'https://example.com/cover.jpg', width: 1200, height: 630 }}
/>;
// Renders: <script type="application/ld+json">{"@context":"https://schema.org",...}</script>

Usage

Builder Functions (No React Required)

Call any builder function with a typed props object to produce a schema-ready JSON-LD object, then pass it to toJsonLdString() for serialization or schemaGraph() to combine with other schemas.

import { product, toJsonLdString } from '@power-seo/schema';

const schema = product({
  name: 'Wireless Headphones',
  description: 'Premium noise-cancelling headphones.',
  image: { url: 'https://example.com/headphones.jpg' },
  offers: {
    price: 149.99,
    priceCurrency: 'USD',
    availability: 'InStock',
  },
  aggregateRating: {
    ratingValue: 4.7,
    reviewCount: 312,
  },
});

console.log(toJsonLdString(schema));

React Components

Import from the /react entry point for pre-built JSON-LD components that render <script type="application/ld+json"> tags:

import { FAQJsonLd, BreadcrumbJsonLd } from '@power-seo/schema/react';

function PageHead() {
  return (
    <>
      <FAQJsonLd
        questions={[
          { question: 'What is JSON-LD?', answer: 'A structured data format used by Google.' },
          { question: 'Do I need React?', answer: 'No — builder functions work without React.' },
        ]}
      />
      <BreadcrumbJsonLd
        items={[
          { name: 'Home', url: 'https://example.com' },
          { name: 'Blog', url: 'https://example.com/blog' },
          { name: 'My Post' },
        ]}
      />
    </>
  );
}

Schema Graph (Multiple Schemas Per Page)

Use schemaGraph() to combine multiple schema objects into a single @graph document. This ensures Google parses all schemas on the page, not just the first <script> tag it finds.

import {
  article,
  breadcrumbList,
  organization,
  schemaGraph,
  toJsonLdString,
} from '@power-seo/schema';

const graph = schemaGraph([
  article({ headline: 'My Post', datePublished: '2026-01-01', author: { name: 'Jane Doe' } }),
  breadcrumbList([
    { name: 'Home', url: 'https://example.com' },
    { name: 'Blog', url: 'https://example.com/blog' },
    { name: 'My Post' },
  ]),
  organization({ name: 'Acme Corp', url: 'https://example.com' }),
]);

const script = toJsonLdString(graph);
// → '{"@context":"https://schema.org","@graph":[{...},{...},{...}]}'

Field Validation

validateSchema() checks required fields and returns a structured result without throwing. Use it in CI pipelines to catch missing fields before pages are published.

import { article, validateSchema } from '@power-seo/schema';

const schema = article({ headline: 'Incomplete Article' }); // missing datePublished, author

const result = validateSchema(schema);
// result.valid → false
// result.issues → [
//   { severity: 'error', field: 'datePublished', message: 'datePublished is required for Article' },
//   { severity: 'error', field: 'author', message: 'author is required for Article' },
// ]

if (!result.valid) {
  const errors = result.issues.filter((i) => i.severity === 'error');
  console.error(`${errors.length} validation error(s) found`);
  errors.forEach((i) => console.error(` ✗ [${i.field}] ${i.message}`));
  process.exit(1);
}

FAQ and Breadcrumb Builder Signatures

faqPage() and breadcrumbList() accept plain arrays directly — not a config object wrapper:

import { faqPage, breadcrumbList } from '@power-seo/schema';

// faqPage takes a plain array of { question, answer } items
const faq = faqPage([
  { question: 'What is schema.org?', answer: 'A shared vocabulary for structured data.' },
  { question: 'Does Google require JSON-LD?', answer: 'JSON-LD is the recommended format.' },
]);

// breadcrumbList takes a plain array of { name, url? } items
const breadcrumb = breadcrumbList([
  { name: 'Home', url: 'https://example.com' },
  { name: 'Products', url: 'https://example.com/products' },
  { name: 'Headphones' },
]);

Next.js App Router

Use builder functions in page.tsx to generate JSON-LD for server-side rendering:

import { article, toJsonLdString } from '@power-seo/schema';

export default function BlogPost({ post }: { post: Post }) {
  const schema = article({
    headline: post.title,
    description: post.excerpt,
    datePublished: post.publishedAt,
    dateModified: post.updatedAt,
    author: { name: post.author.name, url: post.author.profileUrl },
    image: { url: post.coverImage, width: 1200, height: 630 },
  });

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: toJsonLdString(schema) }}
      />
      <article>{/* page content */}</article>
    </>
  );
}

Security note: toJsonLdString() escapes <, >, and & to their Unicode escape sequences (\u003c, \u003e, \u0026) so a schema string value such as "</script>" cannot break out of the surrounding <script> tag. This protection is applied automatically — you do not need to sanitize schema field values yourself when using toJsonLdString() or the React components. If you write schema JSON manually and inject it with dangerouslySetInnerHTML, apply the same escaping or use toJsonLdString().

CI Validation Gate

Block deploys when schema validation fails:

import { validateSchema } from '@power-seo/schema';
import { allPageSchemas } from './build-schemas';

for (const schema of allPageSchemas) {
  const result = validateSchema(schema);
  if (!result.valid) {
    const errors = result.issues.filter((i) => i.severity === 'error');
    if (errors.length > 0) {
      console.error('Schema validation failed:');
      errors.forEach((i) => console.error(` ✗ [${i.field}] ${i.message}`));
      process.exit(1);
    }
  }
}

API Reference

Entry Points

Import	Description
@power-seo/schema	Builder functions, utilities, and TypeScript types
@power-seo/schema/react	React components for rendering JSON-LD script tags

Builder Functions

Function	Schema @type	Rich Result Eligible
article(props)	Article	Yes — Article rich results
blogPosting(props)	BlogPosting	Yes — Article rich results
newsArticle(props)	NewsArticle	Yes — Top Stories
product(props)	Product	Yes — Product rich results
faqPage(questions)	FAQPage	Yes — FAQ rich results
breadcrumbList(items)	BreadcrumbList	Yes — Breadcrumbs in SERP
localBusiness(props)	LocalBusiness	Yes — Local Business panel
organization(props)	Organization	Yes — Knowledge Panel
person(props)	Person	Yes — Knowledge Panel
event(props)	Event	Yes — Event rich results
recipe(props)	Recipe	Yes — Recipe rich results
howTo(props)	HowTo	Yes — How-to rich results
videoObject(props)	VideoObject	Yes — Video rich results
course(props)	Course	Yes — Course rich results
jobPosting(props)	JobPosting	Yes — Job Posting results
softwareApp(props)	SoftwareApplication	Yes — App rich results
webSite(props)	WebSite	Yes — Sitelinks Searchbox
itemList(props)	ItemList	Yes — Carousel results
review(props)	Review	Yes — Review snippet
service(props)	Service	Partial
brand(props)	Brand	Partial
siteNavigationElement(props)	SiteNavigationElement	Partial
imageObject(props)	ImageObject	Yes — Image rich results

Utility Functions

Function	Signature	Description
toJsonLdString	(schema: object, pretty?: boolean) => string	Serialize schema to safe JSON-LD string
schemaGraph	(schemas: object[]) => object	Combine schemas into a single @graph document
validateSchema	(schema: object) => { valid: boolean; issues: ValidationIssue[] }	Validate required fields; returns structured issues

React Components

Import all components from @power-seo/schema/react.

Component	Props	Description
<ArticleJsonLd>	Omit<ArticleSchema, '@type' | '@context'>	Article schema
<BlogPostingJsonLd>	Omit<ArticleSchema, '@type' | '@context'>	BlogPosting schema
<NewsArticleJsonLd>	Omit<ArticleSchema, '@type' | '@context'>	NewsArticle schema for Top Stories
<ProductJsonLd>	Omit<ProductSchema, '@type' | '@context'>	Product with offers and ratings
<FAQJsonLd>	{ questions: Array<{ question: string; answer: string }> }	FAQPage schema
<BreadcrumbJsonLd>	{ items: Array<{ name: string; url?: string }> }	BreadcrumbList schema
<LocalBusinessJsonLd>	Omit<LocalBusinessSchema, '@type' | '@context'>	LocalBusiness schema
<OrganizationJsonLd>	Omit<OrganizationSchema, '@type' | '@context'>	Organization schema
<PersonJsonLd>	Omit<PersonSchema, '@type' | '@context'>	Person schema
<EventJsonLd>	Omit<EventSchema, '@type' | '@context'>	Event schema
<RecipeJsonLd>	Omit<RecipeSchema, '@type' | '@context'>	Recipe schema
<HowToJsonLd>	Omit<HowToSchema, '@type' | '@context'>	HowTo schema
<VideoJsonLd>	Omit<VideoObjectSchema, '@type' | '@context'>	VideoObject schema
<CourseJsonLd>	Omit<CourseSchema, '@type' | '@context'>	Course schema
<JobPostingJsonLd>	Omit<JobPostingSchema, '@type' | '@context'>	JobPosting schema
<SoftwareAppJsonLd>	Omit<SoftwareAppSchema, '@type' | '@context'>	SoftwareApplication schema
<WebSiteJsonLd>	Omit<WebSiteSchema, '@type' | '@context'>	WebSite with SearchAction
<ItemListJsonLd>	Omit<ItemListSchema, '@type' | '@context'>	ItemList schema
<ReviewJsonLd>	Omit<ReviewSchema, '@type' | '@context'>	Review schema
<ServiceJsonLd>	Omit<ServiceSchema, '@type' | '@context'>	Service schema
<BrandJsonLd>	Omit<BrandSchema, '@type' | '@context'>	Brand schema
<JsonLd>	{ schema: object }	Generic — any schema object

Types

Type	Description
ArticleSchema	Props for Article, BlogPosting, and NewsArticle builder functions
ProductSchema	Props for product() builder
FAQPageSchema	Output type of faqPage()
BreadcrumbListSchema	Output type of breadcrumbList()
LocalBusinessSchema	Props for localBusiness() builder
OrganizationSchema	Props for organization() builder
PersonSchema	Props for person() builder
EventSchema	Props for event() builder
RecipeSchema	Props for recipe() builder
HowToSchema	Props for howTo() builder
VideoObjectSchema	Props for videoObject() builder
CourseSchema	Props for course() builder
JobPostingSchema	Props for jobPosting() builder
SoftwareAppSchema	Props for softwareApp() builder
WebSiteSchema	Props for webSite() builder
ItemListSchema	Props for itemList() builder
ReviewSchema	Props for review() builder
ServiceSchema	Props for service() builder
BrandSchema	Props for brand() builder
ValidationIssue	{ severity: 'error' | 'warning'; field: string; message: string }

Use Cases

• Blog posts and articles — Article and BlogPosting schema for Google Discover and Top Stories eligibility
• FAQ pages — FAQPage schema for FAQ accordion rich results in SERPs
• Product pages — Product schema with offers and aggregate ratings for product rich results and star display
• Local business sites — LocalBusiness schema for Google Business Panel and Local Pack
• Recipe sites — Recipe schema for rich cards with images, ratings, and cooking time
• Job boards — JobPosting schema for Google for Jobs integration
• Event pages — Event schema for Google Events rich results
• Course platforms — Course schema for education carousels in Google Search
• Software landing pages — SoftwareApplication schema for app details in results
• Multi-schema pages — schemaGraph() to combine Article + Breadcrumb + Organization into a single @graph
• CI content pipelines — validateSchema() to block deploys when required fields are missing

Architecture Overview

• Pure TypeScript — no compiled binary, no native modules
• Zero runtime dependencies — only @power-seo/core as a peer dependency
• Framework-agnostic — builder functions work in any JavaScript environment with no DOM requirement
• SSR compatible — safe to run in Next.js Server Components, Remix loaders, or Express handlers
• Edge runtime safe — no Node.js-specific APIs; builder functions run in Cloudflare Workers, Vercel Edge, Deno
• Tree-shakeable — "sideEffects": false with named exports per schema type
• Dual ESM + CJS — ships both formats via tsup for any bundler or require() usage

Supply Chain Security

• No install scripts (postinstall, preinstall)
• No runtime network access
• No eval or dynamic code execution
• CI-signed builds — all releases published via verified github.com/CyberCraftBD/power-seo workflow
• Safe for SSR, Edge, and server environments

The @power-seo Ecosystem

All 17 packages are independently installable — use only what you need.

Package	Install	Description
@power-seo/core	npm i @power-seo/core	Framework-agnostic utilities, types, validators, and constants
@power-seo/react	npm i @power-seo/react	React SEO components — meta, Open Graph, Twitter Card, breadcrumbs
@power-seo/meta	npm i @power-seo/meta	SSR meta helpers for Next.js App Router, Remix v2, and generic SSR
@power-seo/schema	npm i @power-seo/schema	Type-safe JSON-LD structured data — 23 builders + 22 React components
@power-seo/content-analysis	npm i @power-seo/content-analysis	Yoast-style SEO content scoring engine with React components
@power-seo/readability	npm i @power-seo/readability	Readability scoring — Flesch-Kincaid, Gunning Fog, Coleman-Liau, ARI
@power-seo/preview	npm i @power-seo/preview	SERP, Open Graph, and Twitter/X Card preview generators
@power-seo/sitemap	npm i @power-seo/sitemap	XML sitemap generation, streaming, index splitting, and validation
@power-seo/redirects	npm i @power-seo/redirects	Redirect engine with Next.js, Remix, and Express adapters
@power-seo/links	npm i @power-seo/links	Link graph analysis — orphan detection, suggestions, equity scoring
@power-seo/audit	npm i @power-seo/audit	Full SEO audit engine — meta, content, structure, performance rules
@power-seo/images	npm i @power-seo/images	Image SEO — alt text, lazy loading, format analysis, image sitemaps
@power-seo/ai	npm i @power-seo/ai	LLM-agnostic AI prompt templates and parsers for SEO tasks
@power-seo/analytics	npm i @power-seo/analytics	Merge GSC + audit data, trend analysis, ranking insights, dashboard
@power-seo/search-console	npm i @power-seo/search-console	Google Search Console API — OAuth2, service account, URL inspection
@power-seo/integrations	npm i @power-seo/integrations	Semrush and Ahrefs API clients with rate limiting and pagination
@power-seo/tracking	npm i @power-seo/tracking	GA4, Clarity, PostHog, Plausible, Fathom — scripts + consent management

About CyberCraft Bangladesh

CyberCraft Bangladesh is a Bangladesh-based enterprise-grade software development and Full Stack SEO service provider company specializing in ERP system development, AI-powered SaaS and business applications, full-stack SEO services, custom website development, and scalable eCommerce platforms. We design and develop intelligent, automation-driven SaaS and enterprise solutions that help startups, SMEs, NGOs, educational institutes, and large organizations streamline operations, enhance digital visibility, and accelerate growth through modern cloud-native technologies.

© 2026 CyberCraft Bangladesh · Released under the MIT License