z-schema 10.0.0 → 12.0.0

package/dist/types/json-schema-versions.d.ts

@@ -1,23 +1,142 @@
 import type { JsonSchemaCommon, ZSchemaInternalProperties } from './json-schema.js';
-export type JsonSchemaVersion = 'draft-04' | 'draft-06';
+export type JsonSchemaVersion = 'draft-04' | 'draft-06' | 'draft-07' | 'draft2019-09' | 'draft2020-12';
 export declare const CURRENT_DEFAULT_SCHEMA_VERSION: JsonSchemaVersion;
 export declare const VERSION_SCHEMA_URL_MAPPING: Record<JsonSchemaVersion, string>;
-export type JsonSchema = JsonSchemaDraft4 | JsonSchemaDraft6;
-export type JsonSchemaAll = JsonSchemaDraft4 & JsonSchemaDraft6;
-export type JsonSchemaInternal = JsonSchema & ZSchemaInternalProperties;
+/** Union of all draft-specific schema interfaces — the public API type. */
+export 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.
+ */
+export 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.
+ */
+export type JsonSchemaInternal = JsonSchemaAll & ZSchemaInternalProperties;
+/** @deprecated Use `JsonSchemaInternal` — they are now equivalent. */
 export type JsonSchemaInternalAll = JsonSchemaAll & ZSchemaInternalProperties;
 export type JsonSchemaInternalD4 = JsonSchemaDraft4 & ZSchemaInternalProperties;
 export type JsonSchemaInternalD6 = JsonSchemaDraft6 & ZSchemaInternalProperties;
+export type JsonSchemaInternalD7 = JsonSchemaDraft7 & ZSchemaInternalProperties;
+export type JsonSchemaInternalD201909 = JsonSchemaDraft201909 & ZSchemaInternalProperties;
+export type JsonSchemaInternalD202012 = JsonSchemaDraft202012 & 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
+ */
 export 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
+ */
 export interface JsonSchemaDraft6 extends JsonSchemaCommon {
     $id?: string;
-    examples?: unknown[];
     const?: unknown;
     contains?: JsonSchema;
     propertyNames?: JsonSchema;
-    exclusiveMaximum?: number;
-    exclusiveMinimum?: number;
+    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
+ */
+export interface JsonSchemaDraft7 extends JsonSchemaDraft6 {
+    if?: JsonSchema | boolean;
+    then?: JsonSchema | boolean;
+    else?: JsonSchema | boolean;
+    contentEncoding?: string;
+    contentMediaType?: string;
+}
+/**
+ * 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
+ */
+export 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
+ */
+export interface JsonSchemaDraft202012 extends JsonSchemaDraft201909 {
+    $dynamicAnchor?: string;
+    $dynamicRef?: string;
+    prefixItems?: Array<JsonSchema | boolean>;
 }

package/dist/types/json-schema.d.ts

@@ -1,49 +1,66 @@
 import type { JsonSchema, JsonSchemaInternal } from './json-schema-versions.js';
 import type { Reference } from './schema-compiler.js';
 import type { ZSchemaOptions } from './z-schema-options.js';
+/**
+ * Keywords whose values are not JSON Schema sub-schemas and must not be
+ * traversed during schema walking (id collection, reference collection, etc.).
+ */
+export declare const NON_SCHEMA_KEYWORDS: readonly ["enum", "const", "default", "examples"];
+/** Returns true if the key is an internal z-schema property (prefixed with `__$`). */
+export declare const isInternalKey: (key: string) => boolean;
+/**
+ * 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`.
+ */
 export 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>;
-    patternProperties?: Record<string, JsonSchema>;
+    enum?: Array<unknown>;
+    format?: string;
     multipleOf?: number;
     minimum?: 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;
+    items?: JsonSchema | boolean | Array<JsonSchema | boolean>;
     additionalItems?: boolean | JsonSchema;
-    items?: JsonSchema | 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;
+    definitions?: Record<string, JsonSchema>;
 }
 export type JsonSchemaType = 'array' | 'boolean' | 'integer' | 'null' | 'number' | 'object' | 'string';
 export interface ZSchemaInternalProperties {
     __$compiled?: unknown;
     __$missingReferences?: Reference[];
     __$refResolved?: JsonSchema;
+    __$dynamicRefResolved?: JsonSchema;
+    __$recursiveRefResolved?: JsonSchema;
+    __$resourceRoot?: JsonSchemaInternal;
     __$schemaResolved?: unknown;
     __$validated?: boolean;
     __$validationOptions?: ZSchemaOptions;
-    __$visited?: boolean;
 }
 export declare const getId: (schema: JsonSchemaInternal) => string | undefined;
-export declare const findId: (schema: JsonSchemaInternal, id: string) => JsonSchemaInternal | undefined;
+export declare const findId: (schema: JsonSchemaInternal, id: string, targetBaseUri?: string, currentBaseUri?: string, maxDepth?: number, _depth?: number) => JsonSchemaInternal | undefined;

package/dist/types/json-validation.d.ts

@@ -1,7 +1,6 @@
-import type { JsonSchema, JsonSchemaAll, JsonSchemaInternal } from './json-schema-versions.js';
+import type { JsonSchemaAll, JsonSchemaInternal } from './json-schema-versions.js';
 import type { ZSchemaBase } from './z-schema-base.js';
 import { Report } from './report.js';
-type JsonValidatorFn = (this: ZSchemaBase, report: Report, schema: JsonSchema, json: unknown) => void;
+import { type JsonValidatorFn } from './validation/shared.js';
 export declare const JsonValidators: Record<keyof JsonSchemaAll, JsonValidatorFn>;
 export declare function validate(this: ZSchemaBase, report: Report, schema: boolean | JsonSchemaInternal, json: unknown): boolean;
-export {};

package/dist/types/report.d.ts

@@ -1,5 +1,5 @@
 import type { ErrorCode, ErrorParam } from './errors.js';
-import type { JsonSchema, JsonSchemaInternal } from './json-schema-versions.js';
+import type { JsonSchema, JsonSchemaAll, JsonSchemaInternal } from './json-schema-versions.js';
 import type { ValidateCallback, ValidateOptions } from './z-schema-base.js';
 import type { ZSchemaOptions } from './z-schema-options.js';
 export interface SchemaErrorDetail {
@@ -44,7 +44,7 @@ export interface SchemaErrorDetail {
      * The schema keyword that caused this validation error.
      * Example: "required", "type", "minLength"
      */
-    keyword?: keyof JsonSchema;
+    keyword?: keyof JsonSchemaAll;
 }
 export interface ReportOptions {
     maxErrors?: number;
@@ -57,6 +57,9 @@ type AsyncTask = [TaskFn, TaskFnArgs, TaskProcessFn];
 export 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>;
@@ -71,14 +74,21 @@ export 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;
 }
 export {};

package/dist/types/schema-cache.d.ts

@@ -1,8 +1,15 @@
 import type { JsonSchema, JsonSchemaInternal } from './json-schema-versions.js';
 import type { ZSchemaBase } from './z-schema-base.js';
+import type { ZSchemaOptions } from './z-schema-options.js';
 import { Report } from './report.js';
 export type SchemaCacheStorage = Record<string, JsonSchemaInternal>;
 export type ReferenceSchemaCacheStorage = Array<[JsonSchemaInternal, JsonSchemaInternal]>;
+/**
+ * Shared logic for registering a remote reference schema.
+ * Used by both the static `ZSchema.setRemoteReference()` (global cache) and
+ * the instance `validator.setRemoteReference()` (instance cache).
+ */
+export declare function prepareRemoteSchema(schema: string | JsonSchema, uri: string, validationOptions?: ZSchemaOptions, maxCloneDepth?: number): JsonSchemaInternal;
 export declare class SchemaCache {
     private validator;
     static global_cache: SchemaCacheStorage;

package/dist/types/schema-compiler.d.ts

@@ -8,14 +8,16 @@ interface Id {
     absoluteParent?: Id;
     absoluteUri?: string;
 }
-export declare const collectIds: (obj: JsonSchemaInternal) => Id[];
+export declare const collectIds: (obj: JsonSchemaInternal, maxDepth?: number) => Id[];
 export interface Reference {
     ref: string;
-    key: '$ref' | '$schema';
+    key: '$ref' | '$schema' | '$recursiveRef' | '$dynamicRef';
     obj: JsonSchemaInternal;
     path: Array<string | number>;
 }
-export declare const collectReferences: (obj: JsonSchemaInternal, results?: Reference[], scope?: string[], path?: Reference["path"]) => Reference[];
+export declare const collectReferences: (obj: JsonSchemaInternal, results?: Reference[], scope?: string[], path?: Reference["path"], options?: {
+    useRefObjectScope?: boolean;
+}, maxDepth?: number, _depth?: number) => Reference[];
 export declare class SchemaCompiler {
     private validator;
     constructor(validator: ZSchemaBase);

package/dist/types/schema-validator.d.ts

@@ -5,6 +5,6 @@ export declare class SchemaValidator {
     private validator;
     constructor(validator: ZSchemaBase);
     get options(): import("./z-schema-options.js").ZSchemaOptions;
-    validateArrayOfSchemas(report: Report, arr: JsonSchemaInternal[]): boolean;
-    validateSchema(report: Report, schema: JsonSchemaInternal | JsonSchemaInternal[]): boolean;
+    validateArrayOfSchemas(report: Report, arr: Array<JsonSchemaInternal | boolean>): boolean;
+    validateSchema(report: Report, schema: JsonSchemaInternal | boolean | Array<JsonSchemaInternal | boolean>): boolean;
 }

package/dist/types/utils/array.d.ts

@@ -1,2 +1,9 @@
-export declare const isUniqueArray: <T>(arr: T[], indexes?: number[]) => boolean;
+/**
+ * Check if all elements in an array are unique.
+ *
+ * Uses a Set-based fast path for arrays of pure primitives (O(n)).
+ * Falls back to pairwise deep comparison (O(n²)) when the array contains
+ * objects or arrays that need structural equality checks.
+ */
+export declare const isUniqueArray: <T>(arr: T[], indexes?: number[], maxDepth?: number) => boolean;
 export declare const difference: (bigSet: any[], subSet: any[]) => any[];

package/dist/types/utils/base64.d.ts

@@ -0,0 +1,2 @@
+export declare const isValidBase64: (value: string) => boolean;
+export declare const decodeBase64: (value: string) => string | undefined;

package/dist/types/utils/clone.d.ts

@@ -1,2 +1,2 @@
 export declare const shallowClone: <T>(src: T) => T;
-export declare const deepClone: <T>(src: T) => T;
+export declare const deepClone: <T>(src: T, maxDepth?: number) => T;

package/dist/types/utils/date.d.ts

@@ -0,0 +1 @@
+export declare const isValidRfc3339Date: (year: number, month: number, day: number) => boolean;

package/dist/types/utils/hostname.d.ts

@@ -0,0 +1,2 @@
+export declare const isValidHostname: (hostname: string) => boolean;
+export declare const isValidIdnHostname: (hostname: string) => boolean;

package/dist/types/utils/json.d.ts

@@ -1,7 +1,8 @@
 interface AreEqualOptions {
     caseInsensitiveComparison?: boolean;
+    maxDepth?: number;
 }
-export declare const areEqual: (json1: unknown, json2: unknown, options?: AreEqualOptions) => boolean;
+export declare const areEqual: (json1: unknown, json2: unknown, options?: AreEqualOptions, _depth?: number) => boolean;
 export declare const decodeJSONPointer: (str: string) => string;
 export declare const sortedKeys: (obj: Record<string, unknown>) => string[];
 export declare const get: (obj: any, path: string | Array<string | number>) => any;

package/dist/types/utils/properties.d.ts

@@ -1,2 +1 @@
-export declare function hasOwn(obj: object, key: PropertyKey): boolean;
 export declare function copyProp(from: object, to: object, key: string | number | symbol, fn?: <T>(obj: T) => T): void;

package/dist/types/utils/time.d.ts

@@ -0,0 +1,12 @@
+export declare const toUtcTime: (hour: number, minute: number, offsetSign: "+" | "-", offsetHour: number, offsetMinute: number) => {
+    hour: number;
+    minute: number;
+};
+export interface ParsedRfc3339Time {
+    hour: number;
+    minute: number;
+    second: number;
+    utcHour: number;
+    utcMinute: number;
+}
+export declare const parseRfc3339Time: (time: string) => ParsedRfc3339Time | null;

package/dist/types/utils/unicode.d.ts

@@ -1,14 +1,5 @@
 /**
- * Creates an array containing the numeric code points of each Unicode
- * character in the string. While JavaScript uses UCS-2 internally,
- * this function will convert a pair of surrogate halves (each of which
- * UCS-2 exposes as separate characters) into a single code point,
- * matching UTF-16.
- * @see `punycode.ucs2.encode`
- * @see <https://mathiasbynens.be/notes/javascript-encoding>
- * @memberOf punycode.ucs2
- * @name decode
- * @param {String} string The Unicode input string (UCS-2).
- * @returns {Array} The new array of code points.
+ * Returns the number of Unicode code points in the string.
+ * Uses the built-in string iterator which correctly handles surrogate pairs.
  */
-export declare function ucs2decode(string: string): number[];
+export declare function unicodeLength(str: string): number;

package/dist/types/validation/array.d.ts

@@ -0,0 +1,12 @@
+import type { JsonSchemaInternal } from '../json-schema-versions.js';
+import type { Report } from '../report.js';
+import type { ZSchemaBase } from '../z-schema-base.js';
+export declare function additionalItemsValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function itemsValidator(): void;
+export declare function prefixItemsValidator(): void;
+export declare function maxItemsValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function minItemsValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function uniqueItemsValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function containsValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function maxContainsValidator(): void;
+export declare function minContainsValidator(): void;

package/dist/types/validation/combinators.d.ts

@@ -0,0 +1,10 @@
+import type { JsonSchemaInternal } from '../json-schema-versions.js';
+import type { ZSchemaBase } from '../z-schema-base.js';
+import { Report } from '../report.js';
+export declare function allOfValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function anyOfValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function oneOfValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function notValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function ifValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function thenValidator(): void;
+export declare function elseValidator(): void;

package/dist/types/validation/numeric.d.ts

@@ -0,0 +1,8 @@
+import type { JsonSchemaInternal } from '../json-schema-versions.js';
+import type { Report } from '../report.js';
+import type { ZSchemaBase } from '../z-schema-base.js';
+export declare function multipleOfValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function maximumValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function exclusiveMaximumValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function minimumValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function exclusiveMinimumValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;

package/dist/types/validation/object.d.ts

@@ -0,0 +1,13 @@
+import type { JsonSchemaInternal } from '../json-schema-versions.js';
+import type { Report } from '../report.js';
+import type { ZSchemaBase } from '../z-schema-base.js';
+export declare function maxPropertiesValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function minPropertiesValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function requiredValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function additionalPropertiesValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function patternPropertiesValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function propertiesValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function dependenciesValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function dependentSchemasValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function dependentRequiredValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function propertyNamesValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;

package/dist/types/validation/ref.d.ts

@@ -0,0 +1,11 @@
+import type { JsonSchemaInternal } from '../json-schema-versions.js';
+export declare const getDynamicRefAnchorName: (dynamicRef: string) => string | undefined;
+export declare const findDynamicAnchorInScope: (scopeSchema: JsonSchemaInternal, anchorName: string) => JsonSchemaInternal | undefined;
+/**
+ * Resolves the effective target for a $recursiveRef, walking the recursive anchor stack.
+ */
+export declare const resolveRecursiveRef: (schema: JsonSchemaInternal, recursiveAnchorStack: JsonSchemaInternal[]) => JsonSchemaInternal | undefined;
+/**
+ * Resolves the effective target for a $dynamicRef, walking the dynamic scope stack.
+ */
+export declare const resolveDynamicRef: (schema: JsonSchemaInternal, dynamicScopeStack: JsonSchemaInternal[]) => JsonSchemaInternal | boolean | undefined;

package/dist/types/validation/shared.d.ts

@@ -0,0 +1,26 @@
+import type { JsonSchema, JsonSchemaAll, JsonSchemaInternal, JsonSchemaVersion } from '../json-schema-versions.js';
+import type { Report } from '../report.js';
+import type { ValidateOptions, ZSchemaBase } from '../z-schema-base.js';
+export type JsonValidatorFn = (this: ZSchemaBase, report: Report, schema: JsonSchema, json: unknown) => void;
+export declare const shouldSkipValidate: (options: ValidateOptions, errors: any) => boolean;
+export declare const supportsDependentKeywords: (schema: JsonSchemaInternal, version: JsonSchemaVersion | "none" | undefined) => boolean;
+export declare const VALIDATION_VOCAB_KEYWORDS: Set<keyof JsonSchemaAll>;
+export declare const isValidationVocabularyEnabled: (schema: JsonSchemaInternal, report: Report, version: JsonSchemaVersion | "none" | undefined) => boolean;
+/**
+ * Checks whether the format-assertion vocabulary is enabled in the meta-schema.
+ * For draft 2019-09: checks if the format vocabulary is set to true.
+ * For draft 2020-12: checks if the format-assertion vocabulary is present and true.
+ * Returns true for older drafts (format was always an assertion).
+ */
+export declare const isFormatAssertionVocabEnabled: (schema: JsonSchemaInternal, report: Report, version: JsonSchemaVersion | "none" | undefined) => boolean;
+export declare function cacheValidationResult(report: Report, schema: unknown, json: unknown, passed: boolean): void;
+export declare function getCachedValidationResult(report: Report, schema: unknown, json: unknown): boolean | undefined;
+/**
+ * Shared async-task aggregation pattern.
+ *
+ * 1. Collects async tasks from `subReports` into `report`.
+ * 2. If new async tasks were added, defers `decisionFn` via `report.addAsyncTask`
+ *    with proper path save/restore so error paths are correct.
+ * 3. Otherwise, runs `decisionFn` synchronously.
+ */
+export declare function deferOrRunSync(report: Report, subReports: Report[], decisionFn: () => void): void;

package/dist/types/validation/string.d.ts

@@ -0,0 +1,9 @@
+import type { JsonSchemaInternal } from '../json-schema-versions.js';
+import type { Report } from '../report.js';
+import type { ZSchemaBase } from '../z-schema-base.js';
+export declare function minLengthValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function maxLengthValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function patternValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function formatValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function contentEncodingValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function contentMediaTypeValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;

package/dist/types/validation/type.d.ts

@@ -0,0 +1,6 @@
+import type { JsonSchemaInternal } from '../json-schema-versions.js';
+import type { Report } from '../report.js';
+import type { ZSchemaBase } from '../z-schema-base.js';
+export declare function typeValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function enumValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;
+export declare function constValidator(this: ZSchemaBase, report: Report, schema: JsonSchemaInternal, json: unknown): void;

package/dist/types/z-schema-base.d.ts

@@ -16,25 +16,63 @@ export type ValidateResponse = {
     err?: ValidateError;
 };
 export type ValidateCallback = (err: ValidateResponse['err'], valid: ValidateResponse['valid']) => void;
+/**
+ * Module-private symbol used by `ZSchema.create()` to authorise construction.
+ * Not exported — external code cannot instantiate ZSchema variants directly.
+ */
+export declare const FACTORY_TOKEN: unique symbol;
 export declare class ZSchemaBase {
     scache: SchemaCache;
     sc: SchemaCompiler;
     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;
 }

package/dist/types/z-schema-options.d.ts

@@ -1,6 +1,7 @@
 import type { FormatValidatorFn } from './format-validators.js';
 import type { Report } from './report.js';
 import { type JsonSchemaVersion } from './json-schema-versions.js';
+export declare const DEFAULT_MAX_RECURSION_DEPTH = 100;
 export interface ZSchemaOptions {
     version?: JsonSchemaVersion | 'none';
     asyncTimeout?: number;
@@ -24,8 +25,10 @@ export 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;
 }
 export declare const defaultOptions: ZSchemaOptions;
 export declare const normalizeOptions: (options?: ZSchemaOptions) => ZSchemaOptions;