z-schema 10.0.0 → 12.0.0

package/src/z-schema-options.ts

@@ -4,6 +4,8 @@ import type { Report } from './report.js';
 import { CURRENT_DEFAULT_SCHEMA_VERSION, type JsonSchemaVersion } from './json-schema-versions.js';
 import { shallowClone } from './utils/clone.js';
 
+export const DEFAULT_MAX_RECURSION_DEPTH = 100;
+
 export interface ZSchemaOptions {
   version?: JsonSchemaVersion | 'none';
   asyncTimeout?: number;
@@ -27,8 +29,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 const defaultOptions: ZSchemaOptions = {
@@ -54,7 +58,7 @@ export const defaultOptions: ZSchemaOptions = {
   forceMaxLength: false,
   // force properties or patternProperties to be defined on "object" types
   forceProperties: false,
-  // ignore references that cannot be resolved (remote schemas) // TODO: make sure this is only for remote schemas, not local ones
+  // ignore references that cannot be resolved (remote schemas)
   ignoreUnresolvableReferences: false,
   // disallow usage of keywords that this validator can't handle
   noExtraKeywords: false,
@@ -76,8 +80,16 @@ export const defaultOptions: ZSchemaOptions = {
   pedanticCheck: false,
   // ignore unknown formats (do not report them as an error)
   ignoreUnknownFormats: false,
+  // control format assertion behavior:
+  //   true  - respect vocabulary: for draft 2019-09/2020-12, check meta-schema $vocabulary
+  //           to determine if format is assertion or annotation-only
+  //   false - format is always annotation-only (never asserts)
+  //   null  - legacy behavior: always assert format validation
+  formatAssertions: null,
   // function to be called on every schema
   customValidator: null as unknown as undefined,
+  // maximum recursion depth for deeply nested schema/data traversal (prevents stack overflow)
+  maxRecursionDepth: DEFAULT_MAX_RECURSION_DEPTH,
 };
 
 export const normalizeOptions = (options?: ZSchemaOptions) => {
@@ -86,12 +98,9 @@ export const normalizeOptions = (options?: ZSchemaOptions) => {
   // options
   if (typeof options === 'object') {
     let keys = Object.keys(options) as Array<keyof ZSchemaOptions>;
-    let idx = keys.length;
-    let key;
 
     // check that the options are correctly configured
-    while (idx--) {
-      key = keys[idx];
+    for (const key of keys) {
       if (defaultOptions[key] === undefined) {
         throw new Error('Unexpected option passed to constructor: ' + key);
       }
@@ -99,9 +108,7 @@ export const normalizeOptions = (options?: ZSchemaOptions) => {
 
     // copy the default options into passed options
     keys = Object.keys(defaultOptions) as Array<keyof ZSchemaOptions>;
-    idx = keys.length;
-    while (idx--) {
-      key = keys[idx];
+    for (const key of keys) {
       if (options[key] === undefined) {
         (options as any)[key] = shallowClone(defaultOptions[key]);
       }

package/src/z-schema-versions.ts

@@ -1,21 +1,67 @@
 // import schemas so they don't have to be downloaded for validation purposes
-import type { JsonSchema, JsonSchemaInternal } from './json-schema-versions.js';
+import type {
+  JsonSchema,
+  JsonSchemaDraft4,
+  JsonSchemaDraft6,
+  JsonSchemaDraft7,
+  JsonSchemaDraft201909,
+  JsonSchemaDraft202012,
+  JsonSchemaInternal,
+} from './json-schema-versions.js';
 import type { ZSchemaOptions } from './z-schema-options.js';
 
 import { SchemaCache } from './schema-cache.js';
 import { normalizeOptions } from './z-schema-options.js';
 
-import _Draft4HyperSchema from './schemas/draft-04-hyper-schema.json' with { type: 'json' };
+// draft-04
 import _Draft4Schema from './schemas/draft-04-schema.json' with { type: 'json' };
-import _Draft6HyperSchema from './schemas/draft-06-hyper-schema.json' with { type: 'json' };
-import _Draft6Links from './schemas/draft-06-links.json' with { type: 'json' };
+// draft-06
 import _Draft6Schema from './schemas/draft-06-schema.json' with { type: 'json' };
+// draft-07
+import _Draft7Schema from './schemas/draft-07-schema.json' with { type: 'json' };
+// draft2019-09
+import _Draft201909MetaApplicator from './schemas/draft-2019-09-meta-applicator.json' with { type: 'json' };
+import _Draft201909MetaContent from './schemas/draft-2019-09-meta-content.json' with { type: 'json' };
+import _Draft201909MetaCore from './schemas/draft-2019-09-meta-core.json' with { type: 'json' };
+import _Draft201909MetaFormat from './schemas/draft-2019-09-meta-format.json' with { type: 'json' };
+import _Draft201909MetaMetaData from './schemas/draft-2019-09-meta-meta-data.json' with { type: 'json' };
+import _Draft201909MetaValidation from './schemas/draft-2019-09-meta-validation.json' with { type: 'json' };
+import _Draft201909Schema from './schemas/draft-2019-09-schema.json' with { type: 'json' };
+// draft2020-12
+import _Draft202012MetaApplicator from './schemas/draft-2020-12-meta-applicator.json' with { type: 'json' };
+import _Draft202012MetaContent from './schemas/draft-2020-12-meta-content.json' with { type: 'json' };
+import _Draft202012MetaCore from './schemas/draft-2020-12-meta-core.json' with { type: 'json' };
+import _Draft202012MetaFormatAnnotation from './schemas/draft-2020-12-meta-format-annotation.json' with { type: 'json' };
+import _Draft202012MetaFormatAssertion from './schemas/draft-2020-12-meta-format-assertion.json' with { type: 'json' };
+import _Draft202012MetaMetaData from './schemas/draft-2020-12-meta-meta-data.json' with { type: 'json' };
+import _Draft202012MetaUnevaluated from './schemas/draft-2020-12-meta-unevaluated.json' with { type: 'json' };
+import _Draft202012MetaValidation from './schemas/draft-2020-12-meta-validation.json' with { type: 'json' };
+import _Draft202012Schema from './schemas/draft-2020-12-schema.json' with { type: 'json' };
 
-const Draft4Schema: JsonSchema = _Draft4Schema;
-const Draft4HyperSchema: JsonSchema = _Draft4HyperSchema;
-const Draft6Schema: JsonSchema = _Draft6Schema;
-const Draft6HyperSchema: JsonSchema = _Draft6HyperSchema;
-const Draft6Links: JsonSchema = _Draft6Links;
+// draft-04
+const Draft4Schema: JsonSchemaDraft4 = _Draft4Schema;
+// draft-06
+const Draft6Schema: JsonSchemaDraft6 = _Draft6Schema;
+// draft-07
+const Draft7Schema: JsonSchemaDraft7 = _Draft7Schema;
+// draft2019-09
+const Draft201909Schema: JsonSchemaDraft201909 = _Draft201909Schema;
+const Draft201909MetaApplicator: JsonSchemaDraft201909 = _Draft201909MetaApplicator;
+const Draft201909MetaContent: JsonSchemaDraft201909 = _Draft201909MetaContent;
+const Draft201909MetaCore: JsonSchemaDraft201909 = _Draft201909MetaCore;
+const Draft201909MetaFormat: JsonSchemaDraft201909 = _Draft201909MetaFormat;
+const Draft201909MetaMetaData: JsonSchemaDraft201909 = _Draft201909MetaMetaData;
+const Draft201909MetaValidation: JsonSchemaDraft201909 = _Draft201909MetaValidation;
+// draft2020-12
+const Draft202012Schema: JsonSchemaDraft202012 = _Draft202012Schema;
+const Draft202012MetaApplicator: JsonSchemaDraft202012 = _Draft202012MetaApplicator;
+const Draft202012MetaContent: JsonSchemaDraft202012 = _Draft202012MetaContent;
+const Draft202012MetaCore: JsonSchemaDraft202012 = _Draft202012MetaCore;
+const Draft202012MetaFormatAnnotation: JsonSchemaDraft202012 = _Draft202012MetaFormatAnnotation;
+const Draft202012MetaFormatAssertion: JsonSchemaDraft202012 = _Draft202012MetaFormatAssertion;
+const Draft202012MetaMetaData: JsonSchemaDraft202012 = _Draft202012MetaMetaData;
+const Draft202012MetaUnevaluated: JsonSchemaDraft202012 = _Draft202012MetaUnevaluated;
+const Draft202012MetaValidation: JsonSchemaDraft202012 = _Draft202012MetaValidation;
 
 const registerRemoteReference = (uri: string, schema: JsonSchema, validationOptions?: ZSchemaOptions) => {
   const preparedSchema = schema as JsonSchemaInternal;
@@ -31,8 +77,57 @@ const registerRemoteReference = (uri: string, schema: JsonSchema, validationOpti
   SchemaCache.cacheSchemaByUri(uri, preparedSchema);
 };
 
+// draft-04
 registerRemoteReference('http://json-schema.org/draft-04/schema', Draft4Schema, { version: 'none' });
-registerRemoteReference('http://json-schema.org/draft-04/hyper-schema', Draft4HyperSchema, { version: 'none' });
+// draft-06
 registerRemoteReference('http://json-schema.org/draft-06/schema', Draft6Schema, { version: 'none' });
-registerRemoteReference('http://json-schema.org/draft-06/hyper-schema', Draft6HyperSchema, { version: 'none' });
-registerRemoteReference('http://json-schema.org/draft-06/links', Draft6Links, { version: 'none' });
+// draft-07
+registerRemoteReference('http://json-schema.org/draft-07/schema', Draft7Schema, { version: 'none' });
+// draft2019-09
+registerRemoteReference('https://json-schema.org/draft/2019-09/schema', Draft201909Schema, { version: 'none' });
+registerRemoteReference('https://json-schema.org/draft/2019-09/meta/applicator', Draft201909MetaApplicator, {
+  version: 'none',
+});
+registerRemoteReference('https://json-schema.org/draft/2019-09/meta/content', Draft201909MetaContent, {
+  version: 'none',
+});
+registerRemoteReference('https://json-schema.org/draft/2019-09/meta/core', Draft201909MetaCore, {
+  version: 'none',
+});
+registerRemoteReference('https://json-schema.org/draft/2019-09/meta/format', Draft201909MetaFormat, {
+  version: 'none',
+});
+registerRemoteReference('https://json-schema.org/draft/2019-09/meta/meta-data', Draft201909MetaMetaData, {
+  version: 'none',
+});
+registerRemoteReference('https://json-schema.org/draft/2019-09/meta/validation', Draft201909MetaValidation, {
+  version: 'none',
+});
+// draft2020-12
+registerRemoteReference('https://json-schema.org/draft/2020-12/schema', Draft202012Schema, { version: 'none' });
+registerRemoteReference('https://json-schema.org/draft/2020-12/meta/applicator', Draft202012MetaApplicator, {
+  version: 'none',
+});
+registerRemoteReference('https://json-schema.org/draft/2020-12/meta/content', Draft202012MetaContent, {
+  version: 'none',
+});
+registerRemoteReference('https://json-schema.org/draft/2020-12/meta/core', Draft202012MetaCore, {
+  version: 'none',
+});
+registerRemoteReference(
+  'https://json-schema.org/draft/2020-12/meta/format-annotation',
+  Draft202012MetaFormatAnnotation,
+  { version: 'none' }
+);
+registerRemoteReference('https://json-schema.org/draft/2020-12/meta/format-assertion', Draft202012MetaFormatAssertion, {
+  version: 'none',
+});
+registerRemoteReference('https://json-schema.org/draft/2020-12/meta/meta-data', Draft202012MetaMetaData, {
+  version: 'none',
+});
+registerRemoteReference('https://json-schema.org/draft/2020-12/meta/unevaluated', Draft202012MetaUnevaluated, {
+  version: 'none',
+});
+registerRemoteReference('https://json-schema.org/draft/2020-12/meta/validation', Draft202012MetaValidation, {
+  version: 'none',
+});

package/src/z-schema.ts

@@ -1,6 +1,6 @@
 import type { ValidateError } from './errors.js';
 import type { FormatValidatorFn } from './format-validators.js';
-import type { JsonSchema, JsonSchemaInternal } from './json-schema-versions.js';
+import type { JsonSchema } from './json-schema-versions.js';
 import type { ValidateOptions, ValidateResponse } from './z-schema-base.js';
 import type { ZSchemaOptions } from './z-schema-options.js';
 import type { SchemaReader } from './z-schema-reader.js';
@@ -8,63 +8,70 @@ import type { SchemaReader } from './z-schema-reader.js';
 import './z-schema-versions.js';
 
 import { getRegisteredFormats, registerFormat, unregisterFormat } from './format-validators.js';
-import { SchemaCache } from './schema-cache.js';
+import { prepareRemoteSchema, SchemaCache } from './schema-cache.js';
 import { deepClone } from './utils/clone.js';
 import { jsonSymbol, schemaSymbol } from './utils/symbols.js';
-import { ZSchemaBase } from './z-schema-base.js';
-import { defaultOptions, normalizeOptions } from './z-schema-options.js';
+import { FACTORY_TOKEN, ZSchemaBase } from './z-schema-base.js';
+import { defaultOptions } from './z-schema-options.js';
 import { getSchemaReader, setSchemaReader } from './z-schema-reader.js';
 
 export class ZSchema extends ZSchemaBase {
-  /** @deprecated Use ZSchema.create() instead. */
-  private constructor(options?: ZSchemaOptions) {
-    super(options);
+  /** @internal Use ZSchema.create() instead. */
+  constructor(options: ZSchemaOptions | undefined, token: symbol) {
+    super(options, token);
   }
 
   // ----- static methods start -----
 
   // class scoped format functions
+
+  /**
+   * 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>`.
+   */
   public static registerFormat(name: string, validatorFunction: FormatValidatorFn): void {
     return registerFormat(name, validatorFunction);
   }
 
+  /**
+   * Remove a globally registered format validator.
+   * @param name - The format name to unregister.
+   */
   public static unregisterFormat(name: string): void {
     return unregisterFormat(name);
   }
 
+  /** Returns the names of all globally registered format validators. */
   public static getRegisteredFormats(): string[] {
     return getRegisteredFormats();
   }
 
-  // default options for validator instance
+  /** Returns a deep clone of the default options. */
   public static getDefaultOptions(): ZSchemaOptions {
     return deepClone(defaultOptions);
   }
 
+  /**
+   * 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.
+   */
   public static setRemoteReference(uri: string, schema: string | JsonSchema, validationOptions?: ZSchemaOptions) {
-    let _schema: JsonSchemaInternal;
-
-    if (typeof schema === 'string') {
-      _schema = JSON.parse(schema);
-    } else {
-      _schema = deepClone(schema);
-    }
-
-    if (!_schema.id) {
-      _schema.id = uri;
-    }
-
-    if (validationOptions) {
-      _schema.__$validationOptions = normalizeOptions(validationOptions);
-    }
-
+    const _schema = prepareRemoteSchema(schema, uri, validationOptions);
     SchemaCache.cacheSchemaByUri(uri, _schema);
   }
 
+  /** Returns the current global schema reader, or `undefined` if none is set. */
   public static getSchemaReader() {
     return getSchemaReader();
   }
 
+  /**
+   * Set a global schema reader function used to resolve remote `$ref` URIs.
+   * @param schemaReader - A function `(uri: string) => JsonSchema | undefined`, or `undefined` to clear.
+   */
   public static setSchemaReader(schemaReader: SchemaReader | undefined) {
     return setSchemaReader(schemaReader);
   }
@@ -75,6 +82,27 @@ export class ZSchema extends ZSchemaBase {
 
   // ----- static methods end -----
 
+  /**
+   * 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? }
+   * ```
+   */
   public static create(options: ZSchemaOptions & { async: true; safe: true }): ZSchemaAsyncSafe;
   public static create(options: ZSchemaOptions & { async: true }): ZSchemaAsync;
   public static create(options: ZSchemaOptions & { safe: true }): ZSchemaSafe;
@@ -86,27 +114,37 @@ export class ZSchema extends ZSchemaBase {
     const isSafe = options.safe;
     delete options.async;
     delete options.safe;
-    (options as any).__called_from_factory__ = true;
     if (isAsync && isSafe) {
-      // @ts-expect-error Factory can use private/deprecated constructor
-      return new ZSchemaAsyncSafe(options);
+      return new ZSchemaAsyncSafe(options, FACTORY_TOKEN);
     }
     if (isAsync) {
-      // @ts-expect-error Factory can use private/deprecated constructor
-      return new ZSchemaAsync(options);
+      return new ZSchemaAsync(options, FACTORY_TOKEN);
     }
     if (isSafe) {
-      // @ts-expect-error Factory can use private/deprecated constructor
-      return new ZSchemaSafe(options);
+      return new ZSchemaSafe(options, FACTORY_TOKEN);
     }
-    // Factory can use private/deprecated constructor
-    return new ZSchema(options);
+    return new ZSchema(options, FACTORY_TOKEN);
   }
 
+  /**
+   * 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 {
     return this._validate(json, schema, options);
   }
 
+  /**
+   * 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 {
     try {
       this._validate(json, schema, options ?? {});
@@ -116,6 +154,14 @@ export class ZSchema extends ZSchemaBase {
     }
   }
 
+  /**
+   * 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> {
     return new Promise((resolve, reject) => {
       try {
@@ -128,6 +174,14 @@ export class ZSchema extends ZSchemaBase {
     });
   }
 
+  /**
+   * 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> {
     return new Promise((resolve) => {
       try {
@@ -140,10 +194,21 @@ export class ZSchema extends ZSchemaBase {
     });
   }
 
+  /**
+   * 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 {
     return this._validateSchema(schemaOrArr);
   }
 
+  /**
+   * 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 {
     try {
       this._validateSchema(schemaOrArr);
@@ -154,12 +219,23 @@ export class ZSchema extends ZSchemaBase {
   }
 }
 
+/**
+ * Synchronous safe validator — `validate()` returns `{ valid, err? }` instead of throwing.
+ * Created via `ZSchema.create({ safe: true })`.
+ */
 export class ZSchemaSafe extends ZSchemaBase {
-  /** @deprecated Use ZSchema.create() instead. */
-  private constructor(options?: ZSchemaOptions) {
-    super(options);
+  /** @internal Use ZSchema.create() instead. */
+  constructor(options: ZSchemaOptions | undefined, token: symbol) {
+    super(options, token);
   }
 
+  /**
+   * 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 {
     try {
       this._validate(json, schema, options);
@@ -169,6 +245,11 @@ export class ZSchemaSafe extends ZSchemaBase {
     }
   }
 
+  /**
+   * 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 {
     try {
       this._validateSchema(schemaOrArr);
@@ -179,12 +260,24 @@ export class ZSchemaSafe extends ZSchemaBase {
   }
 }
 
+/**
+ * Asynchronous throw validator — `validate()` returns `Promise<true>` or rejects.
+ * Created via `ZSchema.create({ async: true })`.
+ */
 export class ZSchemaAsync extends ZSchemaBase {
-  /** @deprecated Use ZSchema.create() instead. */
-  private constructor(options?: ZSchemaOptions) {
-    super(options);
+  /** @internal Use ZSchema.create() instead. */
+  constructor(options: ZSchemaOptions | undefined, token: symbol) {
+    super(options, token);
   }
 
+  /**
+   * 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> {
     return new Promise((resolve, reject) => {
       try {
@@ -195,17 +288,35 @@ export class ZSchemaAsync extends ZSchemaBase {
     });
   }
 
+  /**
+   * 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 {
     return this._validateSchema(schemaOrArr);
   }
 }
 
+/**
+ * Asynchronous safe validator — `validate()` returns `Promise<{ valid, err? }>` (never rejects).
+ * Created via `ZSchema.create({ async: true, safe: true })`.
+ */
 export class ZSchemaAsyncSafe extends ZSchemaBase {
-  /** @deprecated Use ZSchema.create() instead. */
-  private constructor(options?: ZSchemaOptions) {
-    super(options);
+  /** @internal Use ZSchema.create() instead. */
+  constructor(options: ZSchemaOptions | undefined, token: symbol) {
+    super(options, token);
   }
 
+  /**
+   * 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> {
     return new Promise((resolve) => {
       try {
@@ -218,6 +329,11 @@ export class ZSchemaAsyncSafe extends ZSchemaBase {
     });
   }
 
+  /**
+   * 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 {
     try {
       this._validateSchema(schemaOrArr);