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.
Validation layers
Section titled “Validation layers”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.
1. Strict Runtime Validation
Section titled “1. Strict Runtime Validation”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:
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.
2. Severity Modes
Section titled “2. Severity Modes”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 |
Setting Global Severity
Section titled “Setting Global Severity”In Astro (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', }), ],});Overriding Per-Builder Call
Section titled “Overriding Per-Builder Call”You can override the severity for any individual builder call via its second argument:
const optionalProduct = Product(externalData, { onError: 'warn' });3. Safe Parsing with .safeParse()
Section titled “3. Safe Parsing with .safeParse()”When processing external APIs, headless CMS webhooks, or user-submitted content that may be incomplete or invalid, use .safeParse() to avoid throwing exceptions:
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);}Structured Issue Details
Section titled “Structured Issue 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 referenceReceived: ProductSuggestion: 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.
4. Extending Validated Entities
Section titled “4. Extending Validated Entities”When Schema.org introduces cutting-edge properties that are not yet part of the standard library, use withAdditionalProperties():
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 validationconst 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.