or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

error-handling.mdformat-validation.mdindex.mdschema-management.mdvalidation.md
tile.json

tessl/npm-z-schema

JSON schema validator for JavaScript with comprehensive validation capabilities and support for both synchronous and asynchronous validation modes

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/z-schema@5.0.x

To install, run

npx @tessl/cli install tessl/npm-z-schema@5.0.0

index.mddocs/

z-schema

z-schema is a comprehensive JSON Schema validator for JavaScript that supports both synchronous and asynchronous validation modes. It provides extensive configuration options for strict validation rules, custom format validators, and remote schema reference handling with support for JSON Schema Draft-4 specification.

Package Information

  • Package Name: z-schema
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install z-schema

Core Imports

const ZSchema = require("z-schema");

For TypeScript:

import ZSchema = require("z-schema");
// or
import * as ZSchema from "z-schema";

Basic Usage

const ZSchema = require("z-schema");

// Create validator instance
const validator = new ZSchema();

// Simple synchronous validation
const schema = { type: "string", minLength: 5 };
const valid = validator.validate("hello world", schema);

if (!valid) {
    console.log(validator.getLastErrors());
}

// Asynchronous validation
validator.validate("hello", schema, function(err, valid) {
    if (!valid) {
        console.log("Validation failed:", err);
    }
});

CLI Usage

z-schema provides a command-line interface for validating schemas and JSON files:

# Install globally
npm install -g z-schema

# Validate a schema
z-schema mySchema.json

# Validate JSON against schema
z-schema mySchema.json myData.json

# Use validation options
z-schema --strictMode mySchema.json myData.json
z-schema --noEmptyStrings --breakOnFirstError schema.json data.json

Architecture

z-schema is built around several key components:

  • Core Validator: Main ZSchema class that orchestrates validation operations
  • Schema Management: Handles schema compilation, caching, and remote reference resolution
  • Format System: Built-in format validators with extensible custom format registration
  • Error Reporting: Comprehensive error tracking with detailed validation failure information
  • Configuration System: Extensive options for controlling validation behavior and strictness
  • CLI Tool: Command-line interface for schema and JSON file validation

Capabilities

Core Validation

Primary validation functionality for validating JSON data against schemas, with support for both synchronous and asynchronous modes.

class ZSchema {
    constructor(options?: ZSchema.Options);
    
    validate(
        json: any, 
        schema: any, 
        options?: any, 
        callback?: (err: any, valid: boolean) => void
    ): boolean;
    
    validateSchema(schema: any): boolean;
}

Validation

Format Validation

Custom format registration system and built-in format validators for common data types like dates, emails, URIs, and IP addresses.

// Static methods for format management
static registerFormat(
    formatName: string, 
    validatorFunction: (value: any) => boolean
): void;

static getRegisteredFormats(): string[];

Format Validation

Schema Management

Schema compilation, caching, and remote reference resolution capabilities for handling complex schema relationships and dependencies.

setRemoteReference(
    uri: string, 
    schema: any, 
    validationOptions?: any
): void;

compileSchema(schema: any): boolean;

getResolvedSchema(schema: any): any;

Schema Management

Error Handling

Comprehensive error reporting system with detailed validation failure information and customizable error handling.

getLastError(): ZSchema.SchemaError;

getLastErrors(): ZSchema.SchemaErrorDetail[];

getMissingReferences(arr?: any[]): string[];

Error Handling

Configuration Options

z-schema provides extensive configuration options to control validation behavior:

interface Options {
    // Timeout and performance
    asyncTimeout?: number;
    breakOnFirstError?: boolean;
    
    // Validation strictness
    strictMode?: boolean;
    noEmptyStrings?: boolean;
    noEmptyArrays?: boolean;
    noTypeless?: boolean;
    
    // Schema requirements
    forceAdditional?: boolean;
    forceItems?: boolean;
    forceProperties?: boolean;
    
    // Error reporting
    reportPathAsArray?: boolean;
    ignoreUnknownFormats?: boolean;
    
    // Custom validation
    customValidator?: (report: any, schema: any, json: any) => void;
}

Type Definitions

interface SchemaError extends Error {
    name: string;
    message: string;
    details: SchemaErrorDetail[];
}

interface SchemaErrorDetail {
    message: string;
    code: string;
    params: string[];
    path: string;
    description: string;
    inner: SchemaErrorDetail[];
}