@probeo/jsonld

Fast, zero-dependency JSON-LD validator for schema.org structured data.

Why?

There's no good package for this. Existing options are either too loose (just check JSON is valid) or too complex (full JSON-LD spec compliance that nobody needs for SEO). This is the practical middle ground — validate what Google actually requires for rich results, fast, zero dependencies, clear output.

Tested against real production sites. The bugs it catches are real.

Install

npm install @probeo/jsonld

Usage

Validate from HTML

Pass raw HTML and get results for all JSON-LD blocks on the page:

import { validateHtml } from "@probeo/jsonld";

const result = validateHtml(html);

console.log(result.blocks);    // 2
console.log(result.errors);    // 3
console.log(result.warnings);  // 5
console.log(result.results);   // per-block results

Validate a parsed object

import { validateObject } from "@probeo/jsonld";

const result = validateObject({
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "My Article",
  "author": { "@type": "Person", "name": "Jane Doe" },
  "datePublished": "2024-01-15",
});

console.log(result.valid);   // true
console.log(result.issues);  // warnings for missing recommended fields

Get all issues sorted by severity

import { validateHtml, getIssues } from "@probeo/jsonld";

const result = validateHtml(html);

for (const issue of getIssues(result)) {
  console.log(`[${issue.severity}] ${issue.path}: ${issue.message}`);
}
// [error]   $.headline: Missing required property "headline" for Article
// [warning] $.image: Missing recommended property "image" for Article

Output

interface ValidationResult {
  blocks: number;    // JSON-LD blocks found on the page
  errors: number;    // total errors (block is invalid, Google won't use it)
  warnings: number;  // total warnings (reduces quality, may miss rich results)
  results: BlockResult[];
}

interface BlockResult {
  index: number;              // nth block on the page (0-indexed)
  type?: string | string[];   // @type value(s)
  valid: boolean;             // false if any errors present
  issues: ValidationIssue[];
}

interface ValidationIssue {
  path: string;              // dot notation — "$.headline", "$.offers[0].price"
  message: string;
  severity: "error" | "warning";
  type?: string;             // the schema type that raised this issue
}

Errors mean Google will not use the structured data (missing required fields, invalid JSON, missing @context).

Warnings mean the data is valid but incomplete — missing recommended fields, non-URL values in URL fields, non-ISO dates.

What It Validates

Structure

• @context present and references schema.org (http:// and https:// both accepted)
• @type present and is a recognized schema.org type
• @graph blocks — each node validated individually
• Suspicious plugin/theme types flagged (SEO, Tapita, Booster, etc.)

Required and recommended fields

Per-type required and recommended properties matching Google's rich results documentation. Missing required fields are errors. Missing recommended fields are warnings.

Field types

• URL fields (url, image, logo, etc.) — must look like a URL
• Date fields (datePublished, uploadDate, etc.) — must be ISO 8601
• Number fields (price, ratingValue, etc.) — must be positive numbers
• Protocol-relative URLs (//cdn.example.com) accepted as valid

Nested types

• Product.offers → Offer or AggregateOffer
• BreadcrumbList.itemListElement → ListItem
• FAQPage.mainEntity → Question
• Question.acceptedAnswer → Answer
• HowTo.step → HowToStep or HowToSection
• Event.location → Place or VirtualLocation
• Review.reviewRating → Rating
• And more — see schema type definitions

Supported Types (25)

Covers every schema.org type Google uses for rich results:

| Type | Rich Result Feature | |---|---| | Article, BlogPosting, NewsArticle | Article rich results | | Product, Offer, AggregateOffer | Product rich results | | Organization, LocalBusiness | Knowledge panel, local pack | | Person | Knowledge panel | | WebSite, WebPage, AboutPage, ContactPage | Sitelinks search, breadcrumbs | | FAQPage, Question | FAQ rich results | | BreadcrumbList, ListItem | Breadcrumb trail | | HowTo, HowToStep | How-to rich results | | Event | Event rich results | | Review, AggregateRating | Review snippets | | VideoObject, ImageObject | Video, image rich results | | JobPosting | Job posting rich results | | Recipe | Recipe rich results | | SoftwareApplication | App rich results | | Course | Course rich results | | Service | Service rich results |

Unknown types produce a warning but not an error — the block is still considered valid.

Real-World Behavior

Validated against real production sites. A few things this catches that simpler validators miss:

• Epoch date defaults — CMS systems often default datePublished to 0001-01-01T00:00:00. Flagged as a bad date format.
• ratingCount vs reviewCount — Google accepts both. Many sites use ratingCount. Both pass.
• Relative vs absolute URLs — /images/photo.jpg fails the URL check. //cdn.example.com/photo.jpg passes (protocol-relative is valid).
• Nested type mismatches — Product.offers containing a Service instead of an Offer is flagged.
• Missing priceCurrency — Required on Offer even when price is 0.
• Plugin schema spam — Types like TapitaSEOApp, SeoBooster flagged as suspicious.

Replacing manual schema validation

If you're currently validating JSON-LD by hand or with a one-off regex:

// Before
const scripts = html.match(/<script type="application\/ld\+json">(.*?)<\/script>/gs);
const json = JSON.parse(scripts[0].replace(/<[^>]+>/g, ''));
if (!json['@type'] || !json.name) throw new Error('invalid schema');

// After
import { validateHtml } from "@probeo/jsonld";
const result = validateHtml(html);
if (result.errors > 0) {
  console.log(getIssues(result).filter(i => i.severity === 'error'));
}

See Also

| Package | Description | |---|---| | fast-a11y | Zero-DOM accessibility checker with axe-core compatible output | | @probeo/anymodel | Unified LLM router, 11+ providers |

License

MIT