z-schema

Fast, lightweight JSON Schema validator for Node.js and browsers with full support for the latest JSON Schema draft (2020-12), plus draft-2019-09, draft-07, draft-06, and draft-04.

Install

npm install z-schema

Requires Node.js 22 or later.

Quick Start

ESM / TypeScript

import ZSchema from 'z-schema';

const validator = ZSchema.create();

try {
  validator.validate({ name: 'Alice' }, { type: 'object', properties: { name: { type: 'string' } } });
  console.log('Valid');
} catch (error) {
  console.log('Invalid:', error.details);
}

CommonJS

const ZSchema = require('z-schema');
const validator = ZSchema.create();

Browser (UMD)

<script src="z-schema/umd/ZSchema.min.js"></script>
<script>
  const validator = ZSchema.create();
  try {
    validator.validate('hello', { type: 'string' });
  } catch (error) {
    console.log(error.details);
  }
</script>

CLI

npm install --global z-schema
z-schema mySchema.json
z-schema mySchema.json myData.json
z-schema --strictMode mySchema.json myData.json

Usage

ZSchema.create() returns one of four validator variants based on the async and safe options:

Options	Class	validate() returns
{}	ZSchema	true (throws on error)
{ safe: true }	ZSchemaSafe	{ valid, err? }
{ async: true }	ZSchemaAsync	Promise<true> (rejects)
{ async: true, safe: true }	ZSchemaAsyncSafe	Promise<{ valid, err? }>

Sync Validation (Throw Mode)

By default, validate throws a ValidateError on failure. The error has a details array with structured error info.

const validator = ZSchema.create(); // returns ZSchema

try {
  validator.validate(json, schema); // returns true
} catch (error) {
  console.log(error.name); // 'z-schema validation error'
  console.log(error.message); // summary message
  console.log(error.details); // array of { code, message, path, ... }
}

Sync Validation (Safe Mode)

Use { safe: true } to get a ZSchemaSafe instance whose validate() returns a result object instead of throwing.

const validator = ZSchema.create({ safe: true }); // returns ZSchemaSafe

const result = validator.validate(json, schema); // { valid: boolean, err?: ValidateError }
if (!result.valid) {
  console.log(result.err!.details);
}

Async Validation (Throw Mode)

Pass { async: true } to support async format validators. Returns a ZSchemaAsync instance whose validate() returns a Promise.

const validator = ZSchema.create({ async: true }); // returns ZSchemaAsync

try {
  await validator.validate(json, schema); // Promise<true>
} catch (error) {
  console.log(error.details);
}

Async Validation (Safe Mode)

Combine both options to get a ZSchemaAsyncSafe instance — the promise always resolves (never rejects) with a result object.

const validator = ZSchema.create({ async: true, safe: true }); // returns ZSchemaAsyncSafe

const result = await validator.validate(json, schema); // Promise<{ valid, err? }>
if (!result.valid) {
  console.log(result.err!.details);
}

Schema Compilation

Pre-compile schemas at startup to validate $ref references and cache compiled schemas.

const validator = ZSchema.create();

const schemas = [
  { id: 'person', type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
  { id: 'team', type: 'object', properties: { lead: { $ref: 'person' } } },
];

try {
  validator.validateSchema(schemas);
} catch (error) {
  console.log('Schema errors:', error.details);
}

Custom Format Validators

Register custom format validators for sync or async checks.

const validator = ZSchema.create();

// Sync format
validator.registerFormat('uppercase', (value: unknown): boolean => {
  return typeof value === 'string' && value === value.toUpperCase();
});

// Async format
validator.registerFormat('user-exists', async (value: unknown): Promise<boolean> => {
  if (typeof value !== 'number') return false;
  const user = await db.getUserById(value);
  return user != null;
});

Remote References

If your schemas reference remote URIs, register them before validation.

const validator = ZSchema.create();

// Register a remote schema manually
validator.setRemoteReference('http://example.com/person.json', personSchema);

// Or set a schema reader to load them automatically
ZSchema.setSchemaReader((uri: string) => {
  const filePath = path.resolve(__dirname, 'schemas', uri + '.json');
  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
});

Version History

Version	Changes
v12	Default version is draft2020-12. Full support for draft-2020-12 and draft-2019-09.
v11	Default version is draft-07. Implemented draft-07 tests from JSON Schema Test Suite.
v10	Default version is draft-06. Implemented draft-06 tests from JSON Schema Test Suite.
v9	New factory API: ZSchema.create() replaces new ZSchema(). New cache algorithms.
v8	Schemas without $schema default to draft-04. Use { version: 'none' } for the old v7 behavior.
v7	Rewritten in TypeScript/ESM. Passes all JSON Schema Test Suite tests for draft-04.
v6	Legacy version. Draft-04 support.

Features

See docs/features.md for the full feature list.

Options

See docs/options.md for all constructor and per-call options.

Documentation

Document	Description
docs/usage.md	Detailed usage guide with all validation modes, error handling, and advanced features
docs/options.md	Constructor options and per-call validation options
docs/features.md	Feature catalog with examples
docs/MIGRATION.md	Migration guide for upgrading between major versions
docs/architecture.md	Internal architecture, module structure, and public API reference
docs/conventions.md	Code style, naming, and formatting conventions
docs/testing.md	Test framework, running tests, and writing new tests
docs/contributing.md	PR workflow and contribution guidelines

Contributing

This repository uses submodules. Clone with:

git clone --recursive https://github.com/zaggino/z-schema.git

See docs/contributing.md for the full contribution guide.

Contributors

Big thanks to:

Sergey Shandar	Ivan Goncharov	Pete Gonzalez (OLD ALIAS)	Simon R	Jason Oettinger	Jeremy Whitlock
Evgeny	Dan McGee	Thomas Hallock	Priit Kallas	Marco Santarelli	Jan Pilzer
Geraint	Renhe Li	Daniel Gerber	Anna Henningsen	Konstantin Vasilev	barrtender
Roman Hotsiy	RenaudS	Reese	Matti Schneider	Matthew Dahl	José F. Romaniello
Ivan Kasenkov	Tony Lin	Dominik Moritz	Dmitry Semigradsky	Tao Huang	BuBuaBu

and to everyone submitting issues on GitHub