@unschema-graph/core

Framework-independent Schema.org JSON-LD builders, runtime Zod validation, @graph resolution, Unicode anti-XSS serialization, duration parsing, and static HTML auditing.

@unschema-graph/core is the engine behind @unschema-graph/astro and @unschema-graph/svelte. The framework-neutral Core root export does not depend on Node built-ins and is suitable for browser/server runtimes. The maintained compatibility matrix is tested primarily on Node; Bun and Deno usage is best-effort unless explicitly listed in the compatibility matrix.

Installation

# pnpm
pnpm add @unschema-graph/core zod

# npm
npm install @unschema-graph/core zod

# yarn
yarn add @unschema-graph/core zod

# bun
bun add @unschema-graph/core zod

Usage

1. Build and validate Schema.org entities

import { Article, Organization, buildJsonLdGraph, serializeJsonLd } from '@unschema-graph/core';

// 1. Build entities with official typed builders
const publisher = Organization({
  '@id': '#organization',
  name: 'Acme Corp',
  url: 'https://example.com',
});

const article = Article({
  '@id': '#article',
  headline: 'Core TypeScript Structured Data',
  image: 'https://example.com/cover.jpg',
  datePublished: '2026-09-29',
  author: 'Ada Lovelace',
  publisher, // Typed entity-object reference!
});

// 2. Resolve references and deduplicate under a single @graph via automatic discovery
const graph = buildJsonLdGraph(article, {
  baseUrl: 'https://example.com',
});

// 3. Serialize safely into JSON-LD (recommended for <script type="application/ld+json"> injection)
const jsonString = serializeJsonLd(graph);

Relationship strings that look like fragments, paths, or absolute URIs become @id references. A plain name such as author: 'Ada Lovelace' expands only when that relationship defines a fallback type. Generic relationships without a fallback require a typed entity or an explicit reference such as '#person' or { '@id': '#person' }.

2. Runtime validation with safeParse

Validate untrusted external data (such as CMS responses or API payloads) before rendering:

const result = Article.safeParse(untrustedCmsData);

if (result.success) {
  const validatedArticle = result.data;
} else {
  console.error('Invalid structured data:', result.error.format());
}

Static Build Audit CLI

The package provides a built-in static audit CLI to perform structural JSON-LD and @graph checks on built HTML files (in dist/ or build/):

npx @unschema-graph/core audit dist

It inspects JSON-LD script blocks, parses JSON syntax, verifies @context and @type presence, and checks internal reference integrity without claiming full semantic or Google Rich Result eligibility validation.

You can also import the Node-only audit API directly in scripts:

import { auditHtmlDirectory } from '@unschema-graph/core/audit';

const report = auditHtmlDirectory('./dist');
console.log(`Scanned ${report.scannedFiles} HTML files with ${report.errors.length} errors.`);

Compatibility

| Environment | Supported Range | Notes | | :--- | :--- | :--- | | Node.js | >=22.12.0 | Oldest maintained LTS baseline tested in CI; required for tooling and @unschema-graph/core/audit. | | Zod | ^4.6.0 | Peer dependency for runtime validation. | | TypeScript | Project compiler | Strict mode recommended; generated declarations are tested through package consumers. | | Browser | Modern browsers | Root export is pure TypeScript/JavaScript with zero Node built-ins. |

The framework-neutral Core root export does not depend on Node built-ins and is suitable for browser/server runtimes. The maintained compatibility matrix is tested primarily on Node; Bun and Deno usage is best-effort unless explicitly listed in the compatibility matrix. Note that @unschema-graph/core/audit relies on Node filesystem APIs and is strictly Node-only.

Built-in schemas model a curated subset of the Schema.org 30.1 vocabulary baseline; this is not a claim of complete vocabulary or Google rich-result coverage.

Documentation

• Core Quick Start
• Architecture Pipeline
• Mental Model & Graph Resolution
• 51 Supported Builders
• Audit CLI & CI/CD
• Troubleshooting

License

MIT © Johan Ledoux