z-schema

JSON Schema validator for Node.js and browsers. Supports draft-04 and draft-06 (default).

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

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();

try {
  validator.validate(json, schema);
} 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 ZSchema.create({ safe: true }) to get a result object instead of exceptions.

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

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

Async Validation

Pass { async: true } to support async format validators. The validate method returns a Promise.

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

try {
  await validator.validate(json, schema);
} catch (error) {
  console.log(error.details);
}

// Or combine with safe mode:
const safeValidator = ZSchema.create({ async: true, safe: true });
const result = await safeValidator.validate(json, schema);
if (!result.valid) {
  console.log(result.err);
}

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 | | ------- | ------------------------------------------------------------------------------------------------- | | 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/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:

and to everyone submitting issues on GitHub