Schema Sentry 🛡️

Type-safe JSON-LD structured data for Next.js App Router—built for SEO, AI discovery, and CI validation.

Getting Started • Documentation • Examples

Schema Sentry provides a type-safe SDK and CLI for generating, validating, and auditing JSON-LD structured data with deterministic output. Designed for predictable diffs, CI-grade enforcement, and maximum discoverability across both traditional search engines (Google, Bing) and AI-powered systems (ChatGPT, Claude, Perplexity).

Current release: v0.5.0 (new schemasentry scaffold command with pattern-based auto-detection) Next release target: v0.6.0 (VS Code extension and CLI visualization)

✨ Features

• 🔒 Type-safe JSON-LD builders for 15+ schema types (Organization, Article, Product, FAQPage, HowTo, VideoObject, ImageObject, Event, Review, and more)
• 🎯 Deterministic JSON-LD output for clean, reviewable version control diffs
• ⚛️ App Router <Schema /> component for seamless Next.js integration
• 🧭 Manifest-driven schema coverage ensures every route has proper structured data
• 🔍 CLI validation with clear, actionable errors for CI/CD pipelines
• 📊 Schema audit — Analyze site health, detect missing/incomplete schema
• 📥 Automated data collection — collect command scans built apps to auto-generate schema data files
• 🧪 CLI commands — init, validate, audit, collect, scaffold for complete workflows
• 🏗️ Schema scaffolding — scaffold command auto-generates schema stubs from URL patterns (/blog/* → BlogPosting, /products/* → Product)
• 📄 HTML Reports — Generate shareable reports with --format html --output <path>
• 🗣️ PR Annotations — GitHub Actions annotations with --annotations github
• 📴 Zero network calls in OSS mode (privacy-first, offline-friendly)
• 🤖 AI-ready output optimized for LLM consumption, citations, and AI agent recommendations

🧠 Why Structured Data Matters for Both Traditional and AI Search

The Problem

Modern content discovery happens through two channels:

1. Traditional Search (Google, Bing) - Rich snippets, knowledge panels, improved rankings
2. AI-Powered Discovery (ChatGPT, Claude, Perplexity, AI agents) - Contextual answers, citations, voice assistants

Teams often add JSON-LD late, inconsistently, or incorrectly. This leads to:

• ❌ Missing rich snippets in Google search results
• ❌ AI systems failing to understand and cite your content
• ❌ Hard-to-debug CI failures after content changes
• ❌ Inconsistent JSON-LD creating noisy diffs in version control

The Solution

Schema Sentry enforces structured data in CI, ensuring your content is:

• ✅ Machine-readable for both search engines and AI systems
• ✅ Deterministically generated for clean, reviewable diffs
• ✅ Validated automatically before deployment
• ✅ Complete across all routes via manifest-driven checks

AI is eating the web. ChatGPT, Claude, Perplexity, and AI agents now drive significant traffic. Structured data is how AI understands and recommends your content.

Schema Sentry = Better SEO + AI Discovery

Feature	Traditional SEO	AI/LLM Discovery
Rich snippets	✅	✅ Better citations
Knowledge panels	✅	✅ Contextual answers
Voice search	✅	✅ Voice assistant results
AI agent recommendations	❌	✅ Direct inclusion

By using Schema Sentry, you're not just optimizing for Google—you're making your content discoverable by the next generation of AI-powered search.

📦 Packages

Package	Version	Description
@schemasentry/core		Typed builders and validation primitives
@schemasentry/next		App Router <Schema /> component
@schemasentry/cli		CI validation and report output

🚀 Install

# pnpm
pnpm add @schemasentry/next @schemasentry/core
pnpm add -D @schemasentry/cli

# npm
npm install @schemasentry/next @schemasentry/core
npm install -D @schemasentry/cli

# yarn
yarn add @schemasentry/next @schemasentry/core
yarn add -D @schemasentry/cli

🧩 App Router Usage

import { Schema, Article, Organization } from "@schemasentry/next";

const org = Organization({
  name: "Acme Corp",
  url: "https://acme.com"
});

const article = Article({
  headline: "Launch Update",
  authorName: "Jane Doe",
  datePublished: "2026-02-09",
  url: "https://acme.com/blog/launch"
});

export default function Page() {
  return (
    <>
      <Schema data={[org, article]} />
      <main>...</main>
    </>
  );
}

🗺️ Manifest and Coverage

{
  "routes": {
    "/": ["Organization", "WebSite"],
    "/blog/[slug]": ["Article"]
  }
}

🧪 CLI

Quick start

1. Generate starter files:

pnpm schemasentry init

2. Optionally scan your app and add WebPage entries for discovered routes:

pnpm schemasentry init --scan

3. Validate coverage and rules:

pnpm schemasentry validate \
  --manifest ./schema-sentry.manifest.json \
  --data ./schema-sentry.data.json

4. Audit schema health:

pnpm schemasentry audit --data ./schema-sentry.data.json
pnpm schemasentry audit --data ./schema-sentry.data.json --manifest ./schema-sentry.manifest.json

5. Scan for missing routes:

pnpm schemasentry audit --data ./schema-sentry.data.json --scan

6. Generate an HTML report:

pnpm schemasentry audit \
  --data ./schema-sentry.data.json \
  --manifest ./schema-sentry.manifest.json \
  --format html \
  --output ./schema-sentry-report.html

All commands

pnpm schemasentry init

pnpm schemasentry init --scan

pnpm schemasentry audit \
  --data ./schema-sentry.data.json

pnpm schemasentry audit \
  --data ./schema-sentry.data.json \
  --manifest ./schema-sentry.manifest.json

pnpm schemasentry audit \
  --data ./schema-sentry.data.json \
  --scan

pnpm schemasentry validate \
  --manifest ./schema-sentry.manifest.json \
  --data ./schema-sentry.data.json

pnpm schemasentry validate \
  --manifest ./schema-sentry.manifest.json \
  --data ./schema-sentry.data.json \
  --format html \
  --output ./schema-sentry-validate-report.html

pnpm schemasentry audit \
  --data ./schema-sentry.data.json \
  --format html \
  --output ./schema-sentry-audit-report.html

pnpm schemasentry collect \
  --root ./out \
  --output ./schema-sentry.data.json

pnpm schemasentry collect \
  --root ./out \
  --check \
  --data ./schema-sentry.data.json

pnpm schemasentry collect \
  --root ./out \
  --routes / /blog /faq \
  --strict-routes \
  --check \
  --data ./schema-sentry.data.json

pnpm schemasentry scaffold \
  --manifest ./schema-sentry.manifest.json \
  --data ./schema-sentry.data.json

pnpm schemasentry scaffold \
  --manifest ./schema-sentry.manifest.json \
  --data ./schema-sentry.data.json \
  --write

pnpm schemasentry scaffold \
  --manifest ./schema-sentry.manifest.json \
  --data ./schema-sentry.data.json \
  --write \
  --force

The CLI emits JSON output by default and exits with code 1 on errors, making it perfect for CI/CD pipelines. Use --format html --output <path> to generate a shareable report file. Use --annotations github in GitHub Actions to emit PR annotations. Recommended field checks run as warnings by default. Disable them with --no-recommended. See docs/ci.md for complete CI workflow examples.

Optional Config

Create schema-sentry.config.json to control defaults:

{
  "recommended": false
}

CLI flags override config. Use --config ./path/to/config.json to point at a custom file.

Understanding Manifest vs Data

File	Purpose	How It Works
schema-sentry.manifest.json	Defines expected schema types per route	You create this manually - tells Schema Sentry what each page should have
schema-sentry.data.json	Contains the actual schema data	You create this manually - mirrors your actual schema

Why two files? The manifest ensures every route has the right schema type. The data file validates that your actual schema matches expectations.

Use schemasentry init to generate starter files. Add --scan to include all discovered routes as WebPage entries, and use schemasentry audit --scan to detect missing routes later.

✅ Supported Schema Types (V1)

• Organization
• Person
• Place
• LocalBusiness
• WebSite
• WebPage
• Article
• BlogPosting
• Product
• VideoObject
• ImageObject
• Event
• Review
• FAQPage
• HowTo
• BreadcrumbList

🧪 Example App

A minimal Next.js App Router example lives in examples/next-app and includes a manifest and data file. It targets Next.js 16.1.6 and React 19.1.1.

Run the end-to-end workflow demo (init -> collect -> validate):

pnpm --filter schema-sentry-example-next-app schema:e2e

✅ Compatibility

• Next.js App Router (Next.js 13.4+)
• React 18+
• Node.js 18+

🛣️ Roadmap

See ROADMAP.md for planned milestones and future work.

🤝 Contributing

See CONTRIBUTING.md for workflow, scope guardrails, and expectations.

📄 License

MIT © Arindam Dawn

💬 Support

• Report bugs: https://github.com/arindamdawn/schema-sentry/issues/new?template=bug_report.md
• Request features: https://github.com/arindamdawn/schema-sentry/issues/new?template=feature_request.md
• Discussions: https://github.com/arindamdawn/schema-sentry/discussions

---

Made with ❤️ for the Next.js community