0
# z-schema
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: z-schema
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install z-schema`
10

11
## Core Imports
12

13
```javascript
14
const ZSchema = require("z-schema");
15
```
16

17
For TypeScript:
18

19
```typescript
20
import ZSchema = require("z-schema");
21
// or
22
import * as ZSchema from "z-schema";
23
```
24

25
## Basic Usage
26

27
```javascript
28
const ZSchema = require("z-schema");
29

30
// Create validator instance
31
const validator = new ZSchema();
32

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

37
if (!valid) {
38
    console.log(validator.getLastErrors());
39
}
40

41
// Asynchronous validation
42
validator.validate("hello", schema, function(err, valid) {
43
    if (!valid) {
44
        console.log("Validation failed:", err);
45
    }
46
});
47
```
48

49
## CLI Usage
50

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

53
```bash
54
# Install globally
55
npm install -g z-schema
56

57
# Validate a schema
58
z-schema mySchema.json
59

60
# Validate JSON against schema
61
z-schema mySchema.json myData.json
62

63
# Use validation options
64
z-schema --strictMode mySchema.json myData.json
65
z-schema --noEmptyStrings --breakOnFirstError schema.json data.json
66
```
67

68
## Architecture
69

70
z-schema is built around several key components:
71

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

79
## Capabilities
80

81
### Core Validation
82

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

85
```javascript { .api }
86
class ZSchema {
87
    constructor(options?: ZSchema.Options);
88
    
89
    validate(
90
        json: any, 
91
        schema: any, 
92
        options?: any, 
93
        callback?: (err: any, valid: boolean) => void
94
    ): boolean;
95
    
96
    validateSchema(schema: any): boolean;
97
}
98
```
99

100
[Validation](./validation.md)
101

102
### Format Validation
103

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

106
```javascript { .api }
107
// Static methods for format management
108
static registerFormat(
109
    formatName: string, 
110
    validatorFunction: (value: any) => boolean
111
): void;
112

113
static getRegisteredFormats(): string[];
114
```
115

116
[Format Validation](./format-validation.md)
117

118
### Schema Management
119

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

122
```javascript { .api }
123
setRemoteReference(
124
    uri: string, 
125
    schema: any, 
126
    validationOptions?: any
127
): void;
128

129
compileSchema(schema: any): boolean;
130

131
getResolvedSchema(schema: any): any;
132
```
133

134
[Schema Management](./schema-management.md)
135

136
### Error Handling
137

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

140
```javascript { .api }
141
getLastError(): ZSchema.SchemaError;
142

143
getLastErrors(): ZSchema.SchemaErrorDetail[];
144

145
getMissingReferences(arr?: any[]): string[];
146
```
147

148
[Error Handling](./error-handling.md)
149

150
## Configuration Options
151

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

154
```javascript { .api }
155
interface Options {
156
    // Timeout and performance
157
    asyncTimeout?: number;
158
    breakOnFirstError?: boolean;
159
    
160
    // Validation strictness
161
    strictMode?: boolean;
162
    noEmptyStrings?: boolean;
163
    noEmptyArrays?: boolean;
164
    noTypeless?: boolean;
165
    
166
    // Schema requirements
167
    forceAdditional?: boolean;
168
    forceItems?: boolean;
169
    forceProperties?: boolean;
170
    
171
    // Error reporting
172
    reportPathAsArray?: boolean;
173
    ignoreUnknownFormats?: boolean;
174
    
175
    // Custom validation
176
    customValidator?: (report: any, schema: any, json: any) => void;
177
}
178
```
179

180
## Type Definitions
181

182
```javascript { .api }
183
interface SchemaError extends Error {
184
    name: string;
185
    message: string;
186
    details: SchemaErrorDetail[];
187
}
188

189
interface SchemaErrorDetail {
190
    message: string;
191
    code: string;
192
    params: string[];
193
    path: string;
194
    description: string;
195
    inner: SchemaErrorDetail[];
196
}
197
```