z-schema 11.0.1 → 12.0.0

package/README.md

@@ -1,6 +1,6 @@
 # z-schema
 
-JSON Schema validator for Node.js and browsers. Supports **draft-04** and **draft-06** (default).
+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.
 
 [![NPM](https://nodei.co/npm/z-schema.png?downloads=true&downloadRank=true)](https://www.npmjs.com/package/z-schema)
 
@@ -63,15 +63,24 @@ 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.
 
 ```typescript
-const validator = ZSchema.create();
+const validator = ZSchema.create(); // returns ZSchema
 
 try {
-  validator.validate(json, schema);
+  validator.validate(json, schema); // returns true
 } catch (error) {
   console.log(error.name); // 'z-schema validation error'
   console.log(error.message); // summary message
@@ -81,35 +90,41 @@ try {
 
 ### Sync Validation (Safe Mode)
 
-Use `ZSchema.create({ safe: true })` to get a result object instead of exceptions.
+Use `{ safe: true }` to get a `ZSchemaSafe` instance whose `validate()` returns a result object instead of throwing.
 
 ```typescript
-const validator = ZSchema.create({ safe: true });
+const validator = ZSchema.create({ safe: true }); // returns ZSchemaSafe
 
-const result = validator.validate(json, schema);
+const result = validator.validate(json, schema); // { valid: boolean, err?: ValidateError }
 if (!result.valid) {
-  console.log(result.err); // ValidateError with .details
+  console.log(result.err!.details);
 }
 ```
 
-### Async Validation
+### Async Validation (Throw Mode)
 
-Pass `{ async: true }` to support async format validators. The `validate` method returns a Promise.
+Pass `{ async: true }` to support async format validators. Returns a `ZSchemaAsync` instance whose `validate()` returns a `Promise`.
 
 ```typescript
-const validator = ZSchema.create({ async: true });
+const validator = ZSchema.create({ async: true }); // returns ZSchemaAsync
 
 try {
-  await validator.validate(json, schema);
+  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.
+
+```typescript
+const validator = ZSchema.create({ async: true, safe: true }); // returns ZSchemaAsyncSafe
 
-// Or combine with safe mode:
-const safeValidator = ZSchema.create({ async: true, safe: true });
-const result = await safeValidator.validate(json, schema);
+const result = await validator.validate(json, schema); // Promise<{ valid, err? }>
 if (!result.valid) {
-  console.log(result.err);
+  console.log(result.err!.details);
 }
 ```
 
@@ -173,8 +188,9 @@ ZSchema.setSchemaReader((uri: string) => {
 
 | 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.          |
+| **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.                |
@@ -195,6 +211,7 @@ See [docs/options.md](docs/options.md) for all constructor and per-call options.
 | [docs/usage.md](docs/usage.md)               | Detailed usage guide with all validation modes, error handling, and advanced features |
 | [docs/options.md](docs/options.md)           | Constructor options and per-call validation options                                   |
 | [docs/features.md](docs/features.md)         | Feature catalog with examples                                                         |
+| [docs/MIGRATION.md](docs/MIGRATION.md)       | Migration guide for upgrading between major versions                                  |
 | [docs/architecture.md](docs/architecture.md) | Internal architecture, module structure, and public API reference                     |
 | [docs/conventions.md](docs/conventions.md)   | Code style, naming, and formatting conventions                                        |
 | [docs/testing.md](docs/testing.md)           | Test framework, running tests, and writing new tests                                  |

package/cjs/index.d.ts

@@ -33,8 +33,10 @@ interface ZSchemaOptions {
     breakOnFirstError?: boolean;
     pedanticCheck?: boolean;
     ignoreUnknownFormats?: boolean;
+    formatAssertions?: boolean | null;
     customValidator?: (report: Report, schema: unknown, json: unknown) => void;
     customFormats?: Record<string, FormatValidatorFn | null>;
+    maxRecursionDepth?: number;
 }
 
 interface SchemaErrorDetail {
@@ -79,7 +81,7 @@ interface SchemaErrorDetail {
      * The schema keyword that caused this validation error.
      * Example: "required", "type", "minLength"
      */
-    keyword?: keyof JsonSchema;
+    keyword?: keyof JsonSchemaAll;
 }
 interface ReportOptions {
     maxErrors?: number;
@@ -92,6 +94,9 @@ type AsyncTask = [TaskFn, TaskFnArgs, TaskProcessFn];
 declare class Report {
     asyncTasks: AsyncTask[];
     commonErrorMessage?: string;
+    __$recursiveAnchorStack: JsonSchemaInternal[];
+    __$dynamicScopeStack: JsonSchemaInternal[];
+    __validationResultCache: Map<unknown, Map<unknown, boolean>>;
     errors: SchemaErrorDetail[];
     json?: unknown;
     path: Array<number | string>;
@@ -106,15 +111,22 @@ declare class Report {
     constructor(parentReport: Report, reportOptions: ReportOptions, validateOptions?: ValidateOptions);
     isValid(): boolean;
     addAsyncTask<FV, FN extends (...args: any[]) => FV>(fn: FN, args: Parameters<FN>, asyncTaskResultProcessFn: (result: ReturnType<FN>) => void): void;
+    /**
+     * Like {@link addAsyncTask}, but automatically saves the current `path` and
+     * restores it around `processFn`.  This eliminates the manual
+     * path-save/restore boilerplate that every async-aware validator would
+     * otherwise need.
+     */
+    addAsyncTaskWithPath(fn: (...args: any[]) => any, args: any[], processFn: (result: any) => void): void;
     getAncestor(id: string): Report | undefined;
     processAsyncTasks(timeout: number | undefined, callback: ValidateCallback): void;
     getPath(returnPathAsString?: boolean): string | (string | number)[];
     getSchemaPath(): Array<string | number>;
     getSchemaId(): string | undefined;
     hasError(errCode: string, errParams: Array<any>): boolean;
-    addError(errCode: ErrorCode, errParams?: ErrorParam[], subReports?: Report | Report[], schema?: JsonSchema | boolean, keyword?: keyof JsonSchema): void;
+    addError(errCode: ErrorCode, errParams?: ErrorParam[], subReports?: Report | Report[], schema?: JsonSchema | boolean, keyword?: keyof JsonSchemaAll): void;
     getJson(): unknown;
-    addCustomError(errorCode: ErrorCode, errorMessage: string, params?: ErrorParam[], subReports?: Report | Report[], schema?: JsonSchema | boolean, keyword?: keyof JsonSchema): void;
+    addCustomError(errorCode: ErrorCode, errorMessage: string, params?: ErrorParam[], subReports?: Report | Report[], schema?: JsonSchema | boolean, keyword?: keyof JsonSchemaAll): void;
 }
 
 type ErrorCode = keyof typeof Errors;
@@ -132,6 +144,7 @@ declare const Errors: {
     ARRAY_LENGTH_LONG: string;
     ARRAY_UNIQUE: string;
     ARRAY_ADDITIONAL_ITEMS: string;
+    ARRAY_UNEVALUATED_ITEMS: string;
     MULTIPLE_OF: string;
     MINIMUM: string;
     MINIMUM_EXCLUSIVE: string;
@@ -141,6 +154,7 @@ declare const Errors: {
     OBJECT_PROPERTIES_MAXIMUM: string;
     OBJECT_MISSING_REQUIRED_PROPERTY: string;
     OBJECT_ADDITIONAL_PROPERTIES: string;
+    OBJECT_UNEVALUATED_PROPERTIES: string;
     OBJECT_DEPENDENCY_KEY: string;
     MIN_LENGTH: string;
     MAX_LENGTH: string;
@@ -166,6 +180,8 @@ declare const Errors: {
     CONST: string;
     CONTAINS: string;
     PROPERTY_NAMES: string;
+    COLLECT_EVALUATED_DEPTH_EXCEEDED: string;
+    MAX_RECURSION_DEPTH_EXCEEDED: string;
 };
 declare class ValidateError extends Error {
     name: string;
@@ -187,7 +203,7 @@ declare class SchemaCache {
     getSchema(report: Report, refOrSchema: JsonSchema): JsonSchemaInternal;
     getSchema(report: Report, refOrSchema: JsonSchema[]): JsonSchemaInternal[];
     fromCache(path: string): JsonSchemaInternal | undefined;
-    getSchemaByUri(report: Report, uri: string, root?: JsonSchemaInternal): (JsonSchemaDraft7 & ZSchemaInternalProperties) | undefined;
+    getSchemaByUri(report: Report, uri: string, root?: JsonSchemaInternal): JsonSchemaInternal | undefined;
 }
 
 declare class SchemaValidator {
@@ -214,26 +230,59 @@ declare class ZSchemaBase {
     sv: SchemaValidator;
     validateOptions: ValidateOptions;
     options: ZSchemaOptions;
-    constructor(options?: ZSchemaOptions);
+    constructor(options: ZSchemaOptions | undefined, token: symbol);
     getDefaultSchemaId(): string;
     _validate(json: unknown, schema: JsonSchema | string, options: ValidateOptions, callback: ValidateCallback): void;
     _validate(json: unknown, schema: JsonSchema | string, callback: ValidateCallback): void;
     _validate(json: unknown, schema: JsonSchema | string, options: ValidateOptions): true;
     _validate(json: unknown, schema: JsonSchema | string): true;
     _validateSchema(schemaOrArr: JsonSchema | JsonSchema[]): true;
+    /**
+     * Register a format validator on this instance only (does not affect other instances or the global registry).
+     * @param name - The format name.
+     * @param validatorFunction - A sync or async function `(value: unknown) => boolean | Promise<boolean>`.
+     */
     registerFormat(name: string, validatorFunction: FormatValidatorFn): void;
+    /**
+     * Unregister an instance-scoped format validator.
+     * @param name - The format name to unregister.
+     */
     unregisterFormat(name: string): void;
+    /** Returns the names of format validators registered on this instance. */
     getRegisteredFormats(): string[];
+    /** Returns all supported format names (global + instance-registered). */
     getSupportedFormats(): string[];
+    /**
+     * Register a remote schema in this instance's cache so `$ref` can resolve to it.
+     * @param uri - The URI the schema will be known by.
+     * @param schema - The schema object or JSON string.
+     * @param validationOptions - Optional options used for schema preparation.
+     */
     setRemoteReference(uri: string, schema: string | JsonSchema, validationOptions?: ZSchemaOptions): void;
+    /**
+     * Extract unresolvable `$ref` URIs from a validation error.
+     * @param err - A `ValidateError` from a failed validation.
+     * @returns An array of unresolvable reference URIs.
+     */
     getMissingReferences(err: ValidateError): string[];
+    /**
+     * Extract unresolvable **remote** `$ref` URIs from a validation error (local fragment-only refs are excluded).
+     * @param err - A `ValidateError` from a failed validation.
+     * @returns An array of remote reference base URIs.
+     */
     getMissingRemoteReferences(err: ValidateError): string[];
+    /**
+     * Resolve a previously compiled schema by its `$id` / `id`, cleaning up internal bookkeeping properties
+     * and inlining resolved `$ref` targets.
+     * @param schemaId - The schema identifier to look up.
+     * @returns A clean, resolved copy of the schema, or `undefined` if not found.
+     */
     getResolvedSchema(schemaId: string): JsonSchema | undefined;
 }
 
 interface Reference {
     ref: string;
-    key: '$ref' | '$schema';
+    key: '$ref' | '$schema' | '$recursiveRef' | '$dynamicRef';
     obj: JsonSchemaInternal;
     path: Array<string | number>;
 }
@@ -248,89 +297,251 @@ declare class SchemaCompiler {
     compileArrayOfSchemasLoop(mainReport: Report, arr: JsonSchemaInternal[]): number;
 }
 
+/**
+ * Properties present in ALL JSON Schema drafts (04 through 2020-12) with
+ * identical types.  Draft-specific additions live on the individual draft
+ * interfaces in `json-schema-versions.ts`.
+ */
 interface JsonSchemaCommon {
     $ref?: string;
     $schema?: string;
-    id?: string;
     title?: string;
     description?: string;
     default?: unknown;
-    definitions?: Record<string, JsonSchema>;
     type?: string | string[];
-    properties?: Record<string, JsonSchema | boolean>;
-    patternProperties?: Record<string, JsonSchema>;
+    enum?: Array<unknown>;
+    format?: string;
     multipleOf?: number;
     minimum?: number;
-    exclusiveMinimum?: boolean | number;
     maximum?: number;
+    /** Draft-04: `boolean` modifier on `minimum`/`maximum`. Draft-06+: standalone `number`. */
+    exclusiveMinimum?: boolean | number;
+    /** Draft-04: `boolean` modifier on `minimum`/`maximum`. Draft-06+: standalone `number`. */
     exclusiveMaximum?: boolean | number;
     minLength?: number;
     maxLength?: number;
     pattern?: string;
-    additionalItems?: boolean | JsonSchema;
     items?: JsonSchema | boolean | Array<JsonSchema | boolean>;
+    additionalItems?: boolean | JsonSchema;
     minItems?: number;
     maxItems?: number;
     uniqueItems?: boolean;
+    properties?: Record<string, JsonSchema | boolean>;
+    patternProperties?: Record<string, JsonSchema>;
+    additionalProperties?: boolean | JsonSchema;
+    required?: string[];
     minProperties?: number;
     maxProperties?: number;
-    required?: string[];
-    additionalProperties?: boolean | JsonSchema;
     dependencies?: Record<string, string[] | JsonSchema>;
-    enum?: Array<unknown>;
-    format?: string;
     allOf?: JsonSchema[];
     anyOf?: JsonSchema[];
     oneOf?: JsonSchema[];
     not?: JsonSchema;
-    contentEncoding?: string;
-    contentMediaType?: string;
-    if?: JsonSchema | boolean;
-    then?: JsonSchema | boolean;
-    else?: JsonSchema | boolean;
+    definitions?: Record<string, JsonSchema>;
 }
 type JsonSchemaType = 'array' | 'boolean' | 'integer' | 'null' | 'number' | 'object' | 'string';
 interface ZSchemaInternalProperties {
     __$compiled?: unknown;
     __$missingReferences?: Reference[];
     __$refResolved?: JsonSchema;
+    __$dynamicRefResolved?: JsonSchema;
+    __$recursiveRefResolved?: JsonSchema;
+    __$resourceRoot?: JsonSchemaInternal;
     __$schemaResolved?: unknown;
     __$validated?: boolean;
     __$validationOptions?: ZSchemaOptions;
-    __$visited?: boolean;
 }
 
-type JsonSchemaVersion = 'draft-04' | 'draft-06' | 'draft-07';
-type JsonSchema = JsonSchemaDraft4 | JsonSchemaDraft6 | JsonSchemaDraft7;
-type JsonSchemaInternal = JsonSchema & ZSchemaInternalProperties;
+type JsonSchemaVersion = 'draft-04' | 'draft-06' | 'draft-07' | 'draft2019-09' | 'draft2020-12';
+/** Union of all draft-specific schema interfaces — the public API type. */
+type JsonSchema = JsonSchemaDraft4 | JsonSchemaDraft6 | JsonSchemaDraft7 | JsonSchemaDraft201909 | JsonSchemaDraft202012;
+/**
+ * Superset of ALL draft-specific properties with the widest possible types.
+ * Use inside the validator where the active draft is not known at compile time.
+ *
+ * NOTE: this is a manually defined interface (not a computed intersection)
+ * because `exclusiveMinimum` is `boolean` in Draft-04 and `number` in
+ * Draft-06+, which would yield `never` in a plain intersection.
+ */
+interface JsonSchemaAll extends JsonSchemaCommon {
+    /** Pre-`$id` identifier (draft-04 only). */
+    id?: string;
+    /** Schema identifier (replaces `id` from draft-06 onward). */
+    $id?: string;
+    const?: unknown;
+    contains?: JsonSchema;
+    propertyNames?: JsonSchema;
+    examples?: unknown[];
+    if?: JsonSchema | boolean;
+    then?: JsonSchema | boolean;
+    else?: JsonSchema | boolean;
+    contentEncoding?: string;
+    contentMediaType?: string;
+    $defs?: Record<string, JsonSchema>;
+    $anchor?: string;
+    $vocabulary?: Record<string, boolean>;
+    $recursiveAnchor?: boolean;
+    $recursiveRef?: string;
+    dependentSchemas?: Record<string, JsonSchema>;
+    dependentRequired?: Record<string, string[]>;
+    unevaluatedItems?: JsonSchema | boolean;
+    unevaluatedProperties?: JsonSchema | boolean;
+    maxContains?: number;
+    minContains?: number;
+    $dynamicAnchor?: string;
+    $dynamicRef?: string;
+    prefixItems?: Array<JsonSchema | boolean>;
+}
+/**
+ * Internal schema type used throughout the validator. Based on `JsonSchemaAll`
+ * so that validators can access any draft-specific property without narrowing.
+ */
+type JsonSchemaInternal = JsonSchemaAll & ZSchemaInternalProperties;
+/**
+ * JSON Schema Draft-04.
+ *
+ * Key differences from later drafts:
+ * - Uses `id` instead of `$id`.
+ * - `exclusiveMinimum`/`exclusiveMaximum` are boolean modifiers on `minimum`/`maximum`
+ *   (inherited as `boolean | number` from `JsonSchemaCommon` for cross-draft compatibility).
+ * - No `const`, `contains`, `propertyNames`, `examples`, `if`/`then`/`else`.
+ *
+ * @see https://json-schema.org/draft-04/draft-zyp-json-schema-04
+ */
 interface JsonSchemaDraft4 extends JsonSchemaCommon {
-    exclusiveMaximum?: boolean;
-    exclusiveMinimum?: boolean;
+    /** Schema identifier (draft-04). Replaced by `$id` in draft-06+. */
+    id?: string;
 }
+/**
+ * JSON Schema Draft-06.
+ *
+ * Additions over Draft-04:
+ * - `$id` replaces `id`.
+ * - `exclusiveMinimum`/`exclusiveMaximum` changed to standalone `number` values.
+ * - Added `const`, `contains`, `propertyNames`, `examples`.
+ *
+ * @see https://json-schema.org/draft-06/draft-wright-json-schema-validation-01
+ */
 interface JsonSchemaDraft6 extends JsonSchemaCommon {
     $id?: string;
-    examples?: unknown[];
     const?: unknown;
     contains?: JsonSchema;
     propertyNames?: JsonSchema;
+    examples?: unknown[];
+}
+/**
+ * JSON Schema Draft-07.
+ *
+ * Additions over Draft-06:
+ * - `if`/`then`/`else` conditional applicators.
+ * - `contentEncoding`, `contentMediaType`.
+ *
+ * @see https://json-schema.org/draft-07/draft-handrews-json-schema-validation-01
+ */
+interface JsonSchemaDraft7 extends JsonSchemaDraft6 {
+    if?: JsonSchema | boolean;
+    then?: JsonSchema | boolean;
+    else?: JsonSchema | boolean;
+    contentEncoding?: string;
+    contentMediaType?: string;
 }
-interface JsonSchemaDraft7 extends JsonSchemaCommon {
+/**
+ * JSON Schema Draft 2019-09.
+ *
+ * Additions over Draft-07:
+ * - `$defs` (replaces `definitions`), `$anchor`, `$vocabulary`.
+ * - `$recursiveAnchor`/`$recursiveRef` for recursive references.
+ * - `dependentSchemas`/`dependentRequired` (split from `dependencies`).
+ * - `unevaluatedItems`/`unevaluatedProperties`.
+ * - `maxContains`/`minContains`.
+ *
+ * @see https://json-schema.org/draft/2019-09/release-notes
+ */
+interface JsonSchemaDraft201909 extends JsonSchemaDraft7 {
+    $defs?: Record<string, JsonSchema>;
+    $anchor?: string;
+    $vocabulary?: Record<string, boolean>;
+    $recursiveAnchor?: boolean;
+    $recursiveRef?: string;
+    dependentSchemas?: Record<string, JsonSchema>;
+    dependentRequired?: Record<string, string[]>;
+    unevaluatedItems?: JsonSchema | boolean;
+    unevaluatedProperties?: JsonSchema | boolean;
+    maxContains?: number;
+    minContains?: number;
+}
+/**
+ * JSON Schema Draft 2020-12.
+ *
+ * Additions over Draft 2019-09:
+ * - `$dynamicAnchor`/`$dynamicRef` replace `$recursiveAnchor`/`$recursiveRef`.
+ * - `prefixItems` replaces the array form of `items`.
+ *
+ * @see https://json-schema.org/draft/2020-12/release-notes
+ */
+interface JsonSchemaDraft202012 extends JsonSchemaDraft201909 {
+    $dynamicAnchor?: string;
+    $dynamicRef?: string;
+    prefixItems?: Array<JsonSchema | boolean>;
 }
 
 type SchemaReader = (uri: string) => JsonSchema;
 
 declare class ZSchema extends ZSchemaBase {
-    /** @deprecated Use ZSchema.create() instead. */
-    private constructor();
+    /** @internal Use ZSchema.create() instead. */
+    constructor(options: ZSchemaOptions | undefined, token: symbol);
+    /**
+     * Register a global format validator available to all instances.
+     * @param name - The format name (e.g. `'email'`, `'date'`).
+     * @param validatorFunction - A sync or async function `(value: unknown) => boolean | Promise<boolean>`.
+     */
     static registerFormat(name: string, validatorFunction: FormatValidatorFn): void;
+    /**
+     * Remove a globally registered format validator.
+     * @param name - The format name to unregister.
+     */
     static unregisterFormat(name: string): void;
+    /** Returns the names of all globally registered format validators. */
     static getRegisteredFormats(): string[];
+    /** Returns a deep clone of the default options. */
     static getDefaultOptions(): ZSchemaOptions;
+    /**
+     * Register a remote schema in the global cache so any instance can resolve `$ref` to it.
+     * @param uri - The URI the schema will be known by.
+     * @param schema - The schema object or JSON string.
+     * @param validationOptions - Optional options used for schema preparation.
+     */
     static setRemoteReference(uri: string, schema: string | JsonSchema, validationOptions?: ZSchemaOptions): void;
+    /** Returns the current global schema reader, or `undefined` if none is set. */
     static getSchemaReader(): SchemaReader | undefined;
+    /**
+     * Set a global schema reader function used to resolve remote `$ref` URIs.
+     * @param schemaReader - A function `(uri: string) => JsonSchema | undefined`, or `undefined` to clear.
+     */
     static setSchemaReader(schemaReader: SchemaReader | undefined): void;
     static schemaSymbol: symbol;
     static jsonSymbol: symbol;
+    /**
+     * Create a validator instance.
+     *
+     * The returned type depends on the `async` and `safe` options:
+     * - `{}` → `ZSchema` — `validate()` returns `true` or throws.
+     * - `{ safe: true }` → `ZSchemaSafe` — `validate()` returns `{ valid, err? }`.
+     * - `{ async: true }` → `ZSchemaAsync` — `validate()` returns `Promise<true>` or rejects.
+     * - `{ async: true, safe: true }` → `ZSchemaAsyncSafe` — `validate()` returns `Promise<{ valid, err? }>`.
+     *
+     * @param options - Validator configuration. See `ZSchemaOptions` for all available settings.
+     * @returns A validator instance of the appropriate variant.
+     *
+     * @example
+     * ```ts
+     * const validator = ZSchema.create();
+     * validator.validate(data, schema); // throws on error
+     *
+     * const safe = ZSchema.create({ safe: true });
+     * const result = safe.validate(data, schema); // { valid, err? }
+     * ```
+     */
     static create(options: ZSchemaOptions & {
         async: true;
         safe: true;
@@ -342,31 +553,124 @@ declare class ZSchema extends ZSchemaBase {
         safe: true;
     }): ZSchemaSafe;
     static create(options?: ZSchemaOptions): ZSchema;
+    /**
+     * Validate JSON data against a schema.
+     * @param json - The data to validate.
+     * @param schema - A JSON Schema object or a schema id string (previously registered via `validateSchema`).
+     * @param options - Per-call options (`schemaPath`, `includeErrors`, `excludeErrors`).
+     * @returns `true` if valid.
+     * @throws {@link ValidateError} if validation fails, with a `details` array of structured errors.
+     */
     validate(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): true;
+    /**
+     * Validate JSON data against a schema, returning a result object instead of throwing.
+     * @param json - The data to validate.
+     * @param schema - A JSON Schema object or a schema id string.
+     * @param options - Per-call options.
+     * @returns `{ valid: true }` on success, or `{ valid: false, err: ValidateError }` on failure.
+     */
     validateSafe(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): ValidateResponse;
+    /**
+     * Validate JSON data against a schema asynchronously (supports async format validators).
+     * @param json - The data to validate.
+     * @param schema - A JSON Schema object or a schema id string.
+     * @param options - Per-call options.
+     * @returns A promise that resolves to `true` if valid.
+     * @throws {@link ValidateError} if validation fails (the promise rejects).
+     */
     validateAsync(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): Promise<true>;
+    /**
+     * Validate JSON data against a schema asynchronously, returning a result object.
+     * The promise always resolves (never rejects).
+     * @param json - The data to validate.
+     * @param schema - A JSON Schema object or a schema id string.
+     * @param options - Per-call options.
+     * @returns A promise resolving to `{ valid: true }` or `{ valid: false, err: ValidateError }`.
+     */
     validateAsyncSafe(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): Promise<ValidateResponse>;
+    /**
+     * Validate one or more JSON Schemas, compiling and caching them for later use with `validate()`.
+     * @param schemaOrArr - A single schema or an array of schemas (for cross-referencing).
+     * @returns `true` if all schemas are valid.
+     * @throws {@link ValidateError} if any schema is invalid.
+     */
     validateSchema(schemaOrArr: JsonSchema | JsonSchema[]): true;
+    /**
+     * Validate one or more JSON Schemas, returning a result object instead of throwing.
+     * @param schemaOrArr - A single schema or an array of schemas.
+     * @returns `{ valid: true }` on success, or `{ valid: false, err: ValidateError }` on failure.
+     */
     validateSchemaSafe(schemaOrArr: JsonSchema | JsonSchema[]): ValidateResponse;
 }
+/**
+ * Synchronous safe validator — `validate()` returns `{ valid, err? }` instead of throwing.
+ * Created via `ZSchema.create({ safe: true })`.
+ */
 declare class ZSchemaSafe extends ZSchemaBase {
-    /** @deprecated Use ZSchema.create() instead. */
-    private constructor();
+    /** @internal Use ZSchema.create() instead. */
+    constructor(options: ZSchemaOptions | undefined, token: symbol);
+    /**
+     * Validate JSON data against a schema.
+     * @param json - The data to validate.
+     * @param schema - A JSON Schema object or a schema id string.
+     * @param options - Per-call options.
+     * @returns `{ valid: true }` on success, or `{ valid: false, err: ValidateError }` on failure.
+     */
     validate(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): ValidateResponse;
+    /**
+     * Validate one or more JSON Schemas.
+     * @param schemaOrArr - A single schema or an array of schemas.
+     * @returns `{ valid: true }` on success, or `{ valid: false, err: ValidateError }` on failure.
+     */
     validateSchema(schemaOrArr: JsonSchema | JsonSchema[]): ValidateResponse;
 }
+/**
+ * Asynchronous throw validator — `validate()` returns `Promise<true>` or rejects.
+ * Created via `ZSchema.create({ async: true })`.
+ */
 declare class ZSchemaAsync extends ZSchemaBase {
-    /** @deprecated Use ZSchema.create() instead. */
-    private constructor();
+    /** @internal Use ZSchema.create() instead. */
+    constructor(options: ZSchemaOptions | undefined, token: symbol);
+    /**
+     * Validate JSON data against a schema asynchronously.
+     * @param json - The data to validate.
+     * @param schema - A JSON Schema object or a schema id string.
+     * @param options - Per-call options.
+     * @returns A promise that resolves to `true` if valid.
+     * @throws {@link ValidateError} if validation fails (the promise rejects).
+     */
     validate(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): Promise<true>;
+    /**
+     * Validate one or more JSON Schemas (synchronous, throws on error).
+     * @param schemaOrArr - A single schema or an array of schemas.
+     * @returns `true` if all schemas are valid.
+     * @throws {@link ValidateError} if any schema is invalid.
+     */
     validateSchema(schemaOrArr: JsonSchema | JsonSchema[]): true;
 }
+/**
+ * Asynchronous safe validator — `validate()` returns `Promise<{ valid, err? }>` (never rejects).
+ * Created via `ZSchema.create({ async: true, safe: true })`.
+ */
 declare class ZSchemaAsyncSafe extends ZSchemaBase {
-    /** @deprecated Use ZSchema.create() instead. */
-    private constructor();
+    /** @internal Use ZSchema.create() instead. */
+    constructor(options: ZSchemaOptions | undefined, token: symbol);
+    /**
+     * Validate JSON data against a schema asynchronously.
+     * The promise always resolves (never rejects).
+     * @param json - The data to validate.
+     * @param schema - A JSON Schema object or a schema id string.
+     * @param options - Per-call options.
+     * @returns A promise resolving to `{ valid: true }` or `{ valid: false, err: ValidateError }`.
+     */
     validate(json: unknown, schema: JsonSchema | string, options?: ValidateOptions): Promise<ValidateResponse>;
+    /**
+     * Validate one or more JSON Schemas.
+     * @param schemaOrArr - A single schema or an array of schemas.
+     * @returns `{ valid: true }` on success, or `{ valid: false, err: ValidateError }` on failure.
+     */
     validateSchema(schemaOrArr: JsonSchema | JsonSchema[]): ValidateResponse;
 }
 
 export { Errors, Report, ValidateError, ZSchema, ZSchemaAsync, ZSchemaAsyncSafe, ZSchemaSafe, ZSchema as default, getFormatValidators, getRegisteredFormats, getSupportedFormats, isFormatSupported, registerFormat, unregisterFormat };
-export type { ErrorCode, ErrorParam, FormatValidatorFn, FormatValidatorsOptions, JsonSchema, JsonSchemaType, SchemaErrorDetail, SchemaReader, ValidateOptions, ValidateResponse, ZSchemaOptions };
+export type { ErrorCode, ErrorParam, FormatValidatorFn, FormatValidatorsOptions, JsonSchema, JsonSchemaCommon, JsonSchemaDraft201909, JsonSchemaDraft202012, JsonSchemaDraft4, JsonSchemaDraft6, JsonSchemaDraft7, JsonSchemaType, JsonSchemaVersion, SchemaErrorDetail, SchemaReader, ValidateOptions, ValidateResponse, ZSchemaOptions };