Skip to content

Validation & Diagnostics

Every builder in unschema-graph enforces two layers of protection: compile-time TypeScript types for your code editor, and strict runtime Zod validation for dynamic and external data.

unschema-graph validates the constraints implemented by its schemas. It does not claim to validate the entire Schema.org vocabulary or guarantee eligibility for search-engine rich results.

The library keeps three concerns separate:

Layer What it checks
JSON-LD syntax and graph composition Serializable structure, identities, references, and graph rules implemented by Core.
Implemented Schema.org model Types and properties supported by a generic builder such as Article.
Consumer profile Additional rules implemented for a consumer, such as GoogleArticle.

Generic builders do not reject an entity only because a Google-required field is missing. Opt into a consumer profile when that is your target:

import { Article, GoogleArticle } from '@unschema-graph/core';
const genericArticle = Article({ headline: 'Schema.org article' });
const googleProfileArticle = GoogleArticle({
headline: 'Article profile',
image: '/cover.jpg',
datePublished: '2026-10-01',
author: 'Ada Lovelace',
});

GoogleArticleSchema and GoogleRecipeSchema are exported for direct composition. Their rules describe the profiles currently implemented by the library; passing them is not a promise that Google will index or display a rich result.


Unlike standard TypeScript types which vanish after compilation, unschema-graph validates data at runtime using Zod.

Built-in schemas are strict: unknown or misspelled properties are rejected immediately:

src/pages/article.astro
import { Article } from '@unschema-graph/astro';
const article = Article({
headline: 'Getting started with unschema-graph',
image: '/cover.jpg',
datePublished: 'today',
author: 'Ada Lovelace',
// ❌ Typo caught by both TypeScript and runtime Zod:
datePublised: 'today',
});

When an error occurs, unschema-graph formats the Zod issue into a readable diagnostic with exact property paths and typo suggestions.


You can control how validation failures are handled:

Mode Behavior on Invalid Input Recommended Use
throw Throws a detailed SchemaValidationError CI / Production Builds (prevent deploying broken schemas)
warn Logs a formatted terminal warning and returns null Local Development (avoids interrupting page iteration)
silent Returns null silently without console logging Custom error handling pipelines

In Astro (astro.config.mjs):

astro.config.mjs
import { defineConfig } from 'astro/config';
import { schemaGraph } from '@unschema-graph/astro';
export default defineConfig({
integrations: [
schemaGraph({
// Throw during production build, warn in development:
onError: process.env.NODE_ENV === 'production' ? 'throw' : 'warn',
}),
],
});

You can override the severity for any individual builder call via its second argument:

const optionalProduct = Product(externalData, { onError: 'warn' });

When processing external APIs, headless CMS webhooks, or user-submitted content that may be incomplete or invalid, use .safeParse() to avoid throwing exceptions:

src/lib/cms-loader.ts
import { Article } from '@unschema-graph/core';
const result = Article.safeParse(cmsPayload);
if (result.success) {
// result.data is strictly typed ArticleOutput
console.log('Valid article:', result.data.headline);
} else {
// result.error is SchemaValidationError
console.warn('Invalid CMS schema:', result.error.message);
console.table(result.error.details);
}

When result.success is false, result.error.details provides structured diagnostic records:

interface IssueDetail {
code: string; // e.g. 'unrecognized_keys', 'invalid_type'
path: string; // e.g. 'Article.headline', 'Article.author.name'
message: string; // Human-friendly description
expected?: string; // Expected type or schema constraint
received?: string; // Actual value or type received
suggestion?: string; // Typo suggestion if applicable
}

Entity relationships add specialized guidance. For example, passing a Product as a WebSite.publisher produces:

Property "WebSite.publisher"
Expected: Organization | Person | @id reference
Received: Product
Suggestion: Pass Organization(...), Person(...), '#organization', or { '@id': '#organization' }.

The same path, expected, received, and suggestion values are available in error.details, so terminal output, CI, the Astro development toolbar, and future IDE tooling can consume one stable diagnostic shape.


When Schema.org introduces cutting-edge properties that are not yet part of the standard library, use withAdditionalProperties():

src/pages/product.astro
import { Product, withAdditionalProperties } from '@unschema-graph/astro';
const baseProduct = Product({
name: 'Mechanical Keyboard',
image: 'https://example.com/keyboard.jpg',
});
// Attach custom or preview Schema.org properties after validation
const product = withAdditionalProperties(baseProduct, {
color: 'Midnight Blue',
switchType: 'Tactile Silent',
});

Validation tells you whether data matches a builder. It does not test the HTML emitted by your application or guarantee eligibility on an external platform. Run the compiled HTML audit after your production build.

Next: learn how dates and durations are normalized.