@jarenjs/validate 0.9.2 → 0.34.2

package/src/index.js

@@ -21,6 +21,8 @@ import {
 import {
   isBoolOrObjectClass,
   hasSchemaRef,
+  hasUnevaluatedPropertiesCoverage,
+  hasUnevaluatedItemsCoverage,
   EvalLog,
 } from './tools.js';
 import { wrapUnevaluated } from './unevaluated.js';
@@ -32,6 +34,20 @@ export {
   registerFormatCompilers
 } from './format.js';
 
+import {
+  convertInternalErrors,
+} from './messages.js';
+
+export {
+  ValidationError,
+  messagesEn,
+  compileMessageTemplate,
+  compileMessageCatalog,
+  renderErrorMessage,
+  localizeErrors,
+} from './messages.js';
+
+
 export { TraverseOptions };
 
 /**
@@ -206,43 +222,6 @@ class InternalValidationError {
   }
 }
 
-/**
- * JSON Schema Validation Error
- * Represents a validation error according to the JSON Schema specification.
- * @see https://json-schema.org/draft/2020-12/json-schema-core.html#output
- */
-export class ValidationError {
-  /**
-   * @param {object} options - Error options
-   * @param {string} options.keyword - The keyword that failed validation
-   * @param {string} options.instancePath - JSON Pointer to the data location
-   * @param {string} options.schemaPath - JSON Pointer to the schema location
-   * @param {object} options.params - Keyword-specific parameters
-   * @param {string} [options.message] - Human-readable error message
-   */
-  constructor(options) {
-    this.keyword = options.keyword;
-    this.instancePath = options.instancePath || '';
-    this.schemaPath = options.schemaPath || '';
-    this.params = options.params || {};
-    this.message = options.message || '';
-  }
-
-  /**
-   * Convert error to a plain object
-   * @returns {object} Plain object representation
-   */
-  toJSON() {
-    return {
-      keyword: this.keyword,
-      instancePath: this.instancePath,
-      schemaPath: this.schemaPath,
-      params: this.params,
-      message: this.message,
-    };
-  }
-}
-
 /**
  * ValidationOptions configures the behavior of the validation process.
  * @class
@@ -257,6 +236,8 @@ export class ValidationOptions {
    * @param {number} [draftVersion=7] - The JSON Schema draft version (6, 7, 2019, or 2020)
    * @param {boolean} [vocabValidation=true] - Whether the validation vocabulary is enabled (false when the schema's metaschema omits it via $vocabulary)
    * @param {boolean|null} [formatAssertion=null] - Whether format asserts (null = auto: asserts below draft 2020-12, annotation-only from 2020-12 on)
+   * @param {boolean} [messages=true] - Whether collected errors carry rendered message text; false skips rendering (message: '', params/msgid still set)
+   * @param {'error'|'ignore'} [unknownFormats='ignore'] - What to do when an ASSERTING `format` names something no compiler is registered for: 'ignore' (the default, and what the specification requires) accepts it as an annotation; 'error' throws at COMPILE time. Never affects instance validation, and never applies where format is annotation-only anyway.
    */
   constructor(
     skipErrors = true,
@@ -265,7 +246,9 @@ export class ValidationOptions {
     contentValidation = null,
     draftVersion = 7,
     vocabValidation = true,
-    formatAssertion = null
+    formatAssertion = null,
+    messages = true,
+    unknownFormats = 'ignore'
   ) {
     /** @type {boolean} Whether to stop at first error or continue */
     this.skipErrors = skipErrors;
@@ -281,6 +264,10 @@ export class ValidationOptions {
     this.vocabValidation = vocabValidation;
     /** @type {boolean|null} Whether the format keyword asserts (null = auto by draft) */
     this.formatAssertion = formatAssertion;
+    /** @type {boolean} Whether collected errors carry rendered message text */
+    this.messages = messages;
+    /** @type {'error'|'ignore'} What an asserting `format` with no registered compiler does */
+    this.unknownFormats = unknownFormats;
   }
 }
 
@@ -343,6 +330,8 @@ export class ValidationRoot {
   #evalLog = new EvalLog();
   /** @type {object|null} The JarenValidator instance this compilation belongs to, or null when constructed standalone */
   #owner = null;
+  /** @type {Map<string, object>|null} Compiled 'errorMessage' specs by schema path; null when the schema set has none */
+  #errorMessages = null;
 
   /** Keywords whose value is a map of arbitrary names to schemas; those
    * names must not be mistaken for keywords (e.g. a metaschema declaring
@@ -352,6 +341,27 @@ export class ValidationRoot {
     '$defs', 'definitions',
   ]);
 
+  /**
+   * Whether an unevaluatedProperties/unevaluatedItems occurrence can force
+   * runtime annotation tracking. Two shapes never can (in skipErrors mode):
+   * the literal `true` form asserts nothing and only produces annotations,
+   * which matter only when a checking occurrence elsewhere consumes them;
+   * and a check whose sibling keywords already evaluate every property/item
+   * (see hasUnevaluatedPropertiesCoverage/hasUnevaluatedItemsCoverage) is
+   * unreachable, because reaching it means those siblings passed. When no
+   * occurrence forces tracking, the evaluation log has no consumers and
+   * annotation logging is skipped entirely.
+   * @param {object} node - The schema object holding the keyword
+   * @param {string} key - 'unevaluatedProperties' or 'unevaluatedItems'
+   * @returns {boolean} True when this occurrence requires annotation tracking
+   */
+  static #unevaluatedForcesTracking(node, key) {
+    if (node[key] === true) return false;
+    return key === 'unevaluatedProperties'
+      ? !hasUnevaluatedPropertiesCoverage(node)
+      : !hasUnevaluatedItemsCoverage(node);
+  }
+
   /**
    * Recursively scans a schema (sub)tree for keys that require special
    * runtime support: '$data' references and 'unevaluatedProperties'/
@@ -390,7 +400,16 @@ export class ValidationRoot {
           flags.dollarData = true;
           continue;
         }
-        else if (key === 'unevaluatedProperties' || key === 'unevaluatedItems') flags.unevaluated = true;
+        else if (key === 'errorMessage') {
+          // 'errorMessage' is report-time metadata; its value is a message
+          // spec whose map form may spell keys like '$query' that must not
+          // register as keywords of this compilation.
+          continue;
+        }
+        else if (key === 'unevaluatedProperties' || key === 'unevaluatedItems') {
+          if (!flags.canElide || ValidationRoot.#unevaluatedForcesTracking(node, key))
+            flags.unevaluated = true;
+        }
         if (ValidationRoot.#SCAN_MAP_KEYWORDS.has(key)) {
           // The value is a name->schema map: its keys are names, its values schemas.
           ValidationRoot.#scanSchemaFeatures(node[key], seen, flags, false);
@@ -429,7 +448,10 @@ export class ValidationRoot {
     // Detect $data references and unevaluated* keywords once, so fast paths
     // can skip path building / annotation logging when nothing consumes them.
     // Must run before validators are compiled below.
-    const flags = { dollarData: false, unevaluated: false };
+    // Elision of unreachable unevaluated* checks relies on validators
+    // short-circuiting at the first failure, so it only holds in
+    // skipErrors mode (see #unevaluatedForcesTracking).
+    const flags = { dollarData: false, unevaluated: false, canElide: opts.skipErrors === true };
     const seen = new Set();
     for (const value of schemas.values()) {
       ValidationRoot.#scanSchemaFeatures(value, seen, flags);
@@ -455,9 +477,6 @@ export class ValidationRoot {
       .filter(anchor => anchor.schema !== rootSchema);
   }
 
-  /** @returns {string} The root schema origin/URI */
-  get rootOrigin() { return this.#rootOrigin; }
-
   /** @returns {TraverseOptions} Schema traversal options */
   get traverse() { return this.#traverse; }
 
@@ -470,9 +489,6 @@ export class ValidationRoot {
   /** @returns {Array} Array of validation errors */
   get errors() { return this.#errors; }
 
-  /** @returns {ValidationObject} The root schema's ValidationObject */
-  get firstSchema() { return this.#firstSchema; }
-
   /** @returns {boolean} Whether any schema in this compilation contains a $data reference */
   get usesDollarData() { return this.#usesDollarData; }
 
@@ -485,6 +501,21 @@ export class ValidationRoot {
   /** @returns {object|null} The owning JarenValidator instance, or null when constructed standalone */
   get owner() { return this.#owner; }
 
+  /** @returns {Map<string, object>|null} Compiled 'errorMessage' specs by schema path, or null when the schema set has none */
+  get errorMessages() { return this.#errorMessages; }
+
+  /**
+   * Register a compiled 'errorMessage' spec for a schema location.
+   * Called at schema compile time (see compileSchemaObject); the registry
+   * is only consulted at report time, over the already-failed set.
+   * @param {string} path - The schema path (ValidationObject.path)
+   * @param {object} spec - The compiled spec (see messages.js compileErrorMessageSpec)
+   */
+  registerErrorMessage(path, spec) {
+    if (this.#errorMessages === null) this.#errorMessages = new Map();
+    this.#errorMessages.set(path, spec);
+  }
+
   /**
    * Creates a new ValidationObject for the given path and schema.
    * @param {string} path - The URI path for this schema object
@@ -510,24 +541,6 @@ export class ValidationRoot {
     return null;
   }
 
-  /**
-   * Gets the raw schema object for a given reference without compiling it.
-   * Used to check schema properties (like $recursiveAnchor) at compile time.
-   * @param {string} ref - The reference URI to resolve
-   * @param {string} path - The current path (for error messages)
-   * @param {object} schema - The schema containing the $ref
-   * @returns {{id: string, schema: object}|null} The resolved schema info or null
-   */
-  getRawSchema(ref, path, schema) {
-    try {
-      const schemas = this.#schemas;
-      const traverse = this.#traverse;
-      return resolveRefSchemaDeep(schemas, path, schema, traverse);
-    } catch (e) {
-      return null;
-    }
-  }
-
   /**
    * Gets the raw schema object by its URI/ID directly from the schemas map.
    * This performs a direct lookup without following references.
@@ -574,6 +587,30 @@ export class ValidationRoot {
     return false;
   }
 
+  /**
+   * A checkpoint in the collected-error list.
+   *
+   * A SPECULATIVE applicator - an `anyOf` branch, an `if` condition, the
+   * subschema of a `not`, a `contains` candidate - runs a validator whose
+   * failure may be entirely expected. Those failures still call `addError`,
+   * so without a checkpoint they leak into the caller's issue list and blame
+   * a document for not matching a branch it was never required to match.
+   * Marking before the probe and rolling back after is the same discipline
+   * `EvalLog` already uses for annotations.
+   * @returns {number} The mark to pass to {@link rollbackErrors}
+   */
+  errorMark() {
+    return this.#errors.length;
+  }
+
+  /**
+   * Discard every error collected since `mark`.
+   * @param {number} mark - A value from {@link errorMark}
+   */
+  rollbackErrors(mark) {
+    if (this.#errors.length > mark) this.#errors.length = mark;
+  }
+
   /**
    * Validates data against the root schema.
    * @param {unknown} data - The data to validate
@@ -624,6 +661,36 @@ export class ValidationRoot {
     return rootValidator(data, '', data);
   }
 
+  /**
+   * Returns the fastest repeated-validation entry point for this root.
+   * Error collection and root-level dynamic anchors need the per-call
+   * bookkeeping of validate(); without them the compiled root validator
+   * only needs the annotation log cleared (when tracking is on) and can
+   * otherwise be invoked directly. Dynamic anchors pushed during
+   * validation are balanced by try/finally, so the anchor map needs no
+   * per-call clearing here.
+   * @returns {(data: unknown) => boolean} The validation entry point
+   */
+  createValidateFn() {
+    if (!this.#options.skipErrors || this.#options.collectErrors
+      || this.#rootAnchorName !== null
+      || this.#rootDynamicAnchors.length !== 0) {
+      return (data) => this.validate(data);
+    }
+
+    const rootValidator = this.#rootValidator;
+    if (this.#usesUnevaluated) {
+      const evalLog = this.#evalLog;
+      return function validateRootTracked(data) {
+        evalLog.reset();
+        return rootValidator(data, '', data);
+      };
+    }
+    return function validateRoot(data) {
+      return rootValidator(data, '', data);
+    };
+  }
+
   /**
    * Get the stored validator for a dynamic anchor.
    * Used by $dynamicRef for runtime resolution.
@@ -729,7 +796,13 @@ export class ValidationObject {
 
     // In draft 2019-09+, $ref can have sibling keywords that are applied together.
     // In draft 7 and earlier, $ref overrides siblings.
-    const draftVersion = root.options.draftVersion || 7;
+    //
+    // The draft that decides this is the one declared by the schema RESOURCE
+    // holding the `$ref`, not the one the root document happens to use. A
+    // 2020-12 resource embedded in a draft-07 document has to assert its
+    // siblings, and a draft-07 resource inside a 2020-12 document must not —
+    // reading the root's draft got both backwards.
+    const draftVersion = self.declaredDraft ?? root.options.draftVersion ?? 7;
 
     // Base URI for resolving $ref:
     // - Draft 7 and earlier: $ref replaces the schema entirely, so a sibling
@@ -795,7 +868,8 @@ export class ValidationObject {
               root.pushDynamicAnchorValidator(anchorName, refValidator);
             }
             try {
-              return refValidator(data, dataPath, dataRoot) && siblingValidator(data, dataPath, dataRoot);
+              return combineRefAndSiblings(refValidator, siblingValidator, self.options.skipErrors,
+              data, dataPath, dataRoot);
             } finally {
               // Pop in reverse order
               if (hasRecAnchor || dynAnchorName) {
@@ -839,7 +913,8 @@ export class ValidationObject {
         // unevaluated* keywords must see annotations produced by the $ref
         // target, so the wrapper goes around the combined validator.
         return wrapUnevaluated(self, schema, function validateRefWithSiblings(data, dataPath, dataRoot) {
-          return refValidator(data, dataPath, dataRoot) && siblingValidator(data, dataPath, dataRoot);
+          return combineRefAndSiblings(refValidator, siblingValidator, self.options.skipErrors,
+              data, dataPath, dataRoot);
         });
       }
       
@@ -898,7 +973,8 @@ export class ValidationObject {
           try {
             // If there are sibling validators (draft 2019-09+), combine them with the ref validator
             if (boundSiblingValidator) {
-              return refValidator(data, dataPath, dataRoot) && boundSiblingValidator(data, dataPath, dataRoot);
+              return combineRefAndSiblings(refValidator, boundSiblingValidator,
+                self.options.skipErrors, data, dataPath, dataRoot);
             }
             return refValidator(data, dataPath, dataRoot);
           } finally {
@@ -908,7 +984,8 @@ export class ValidationObject {
 
         // If there are sibling validators (draft 2019-09+), combine them with the ref validator
         if (boundSiblingValidator) {
-          return refValidator(data, dataPath, dataRoot) && boundSiblingValidator(data, dataPath, dataRoot);
+          return combineRefAndSiblings(refValidator, boundSiblingValidator,
+                self.options.skipErrors, data, dataPath, dataRoot);
         }
 
         // Cache the validator directly (skipping this resolver) only when
@@ -937,8 +1014,6 @@ export class ValidationObject {
   #schema = null;
   /** @type {function|null} The compiled validator function */
   #validator = null;
-  /** @type {string} The base URI passed during construction */
-  #baseUri = null;
   /** @type {string} The effective base URI for child $ref resolution */
   #effectiveBaseUri = null;
   /** @type {number|null} Draft version declared by this schema's document ($schema), inherited by subschemas; null when never declared */
@@ -977,7 +1052,6 @@ export class ValidationObject {
       // No $id - inherit parent's base
       this.#effectiveBaseUri = baseUri;
     }
-    this.#baseUri = baseUri;
 
     this.#validator = ValidationObject.compileValidator(this, path, schema, baseUri);
   }
@@ -992,11 +1066,6 @@ export class ValidationObject {
     return this.#effectiveBaseUri;
   }
 
-  /** @returns {Array} The current validation errors from the root */
-  get errors() {
-    return this.#root.errors;
-  }
-
   /** @returns {function} The compiled validator function */
   get validate() {
     return this.#validator;
@@ -1040,13 +1109,13 @@ export class ValidationObject {
     // Just return false immediately to avoid the overhead of error creation
     if (self.#root.options.skipErrors) {
       if (!Array.isArray(key)) {
-        return function addNormalErrorFast(data, ...meta) {
+        return function addNormalErrorFast(_data, ..._meta) {
           // Just return false without creating error object
           return false;
         };
       }
       else {
-        return function addKeyedErrorFast(dataKey, data, ...meta) {
+        return function addKeyedErrorFast(_dataKey, _data, ..._meta) {
           // Just return false without creating error object
           return false;
         };
@@ -1118,6 +1187,26 @@ export class ValidationObject {
   }
 }
 
+/**
+ * Run a `$ref` and its sibling keywords, which are INDEPENDENT of each other:
+ * a document can fail the referenced schema and its siblings for unrelated
+ * reasons, and reporting only the first is the same short-circuit that used to
+ * hide half of every issue list. Boolean mode keeps the early exit.
+ * @param {Function} refValidator
+ * @param {Function} siblingValidator
+ * @param {boolean} stopAtFirst
+ * @param {any} data
+ * @param {string} dataPath
+ * @param {any} dataRoot
+ * @returns {boolean}
+ */
+function combineRefAndSiblings(refValidator, siblingValidator, stopAtFirst, data, dataPath, dataRoot) {
+  if (stopAtFirst)
+    return refValidator(data, dataPath, dataRoot) && siblingValidator(data, dataPath, dataRoot);
+  const target = refValidator(data, dataPath, dataRoot);
+  return siblingValidator(data, dataPath, dataRoot) && target;
+}
+
 /**
  * ValidatorOptions configures the JarenValidator instance.
  * Can be created with positional arguments or an options object.
@@ -1156,17 +1245,22 @@ export class ValidatorOptions {
       /** @type {object[]} Initial schemas to register */
       this.schemas = opts.schemas || [];
       // If collectErrors is passed directly, create ValidationOptions with it
-      if (opts.collectErrors != null || opts.skipErrors != null || opts.useGrapheme != null || opts.contentValidation != null || opts.draftVersion != null || opts.formatAssertion != null) {
+      if (opts.collectErrors != null || opts.skipErrors != null || opts.useGrapheme != null || opts.contentValidation != null || opts.draftVersion != null || opts.formatAssertion != null || opts.messages != null || opts.unknownFormats != null) {
         const collectErrors = opts.collectErrors ?? false;
         this.validation = new ValidationOptions(
           // collecting errors implies actually recording them
           opts.skipErrors ?? !collectErrors,
           opts.useGrapheme ?? true,
           collectErrors,
-          opts.contentValidation ?? false,
+          // null, not false: an unset option must stay unset so `compile`
+          // can apply the per-draft default. Coercing it here would make
+          // any options object silently disable content assertion.
+          opts.contentValidation ?? null,
           opts.draftVersion ?? 7,
           true,
-          opts.formatAssertion ?? null
+          opts.formatAssertion ?? null,
+          opts.messages ?? true,
+          opts.unknownFormats ?? 'ignore'
         );
       } else {
         /** @type {ValidationOptions} Validation behavior options */
@@ -1183,9 +1277,51 @@ export class ValidatorOptions {
   }
 }
 
+/**
+ * The object a compiled validator returns when `collectErrors` is enabled.
+ * @typedef {{ valid: boolean, errors: import("./messages.js").ValidationError[] }} ValidationResultObject
+ */
+
+/**
+ * A compiled validator in the default boolean mode. It is a type guard, so
+ * `T` is whatever the caller asserts the schema describes; with no `T` it
+ * behaves as an ordinary boolean predicate.
+ * @template T
+ * @typedef {(data: unknown) => data is T} CompiledPredicate
+ */
+
+/**
+ * A compiled validator in collect-errors mode.
+ * @typedef {(data: unknown) => ValidationResultObject} CompiledCollector
+ */
+
+/**
+ * The plain-object form accepted by the JarenValidator constructor, mixing
+ * validator-level settings with the ValidationOptions fields.
+ * @template {boolean} [TCollect=false]
+ * @typedef {object} ValidatorInit
+ * @property {Record<string, FormatCompiler>} [formats] - Format compilers to register
+ * @property {(JSONSchema | boolean)[]} [schemas] - Schemas to register
+ * @property {ValidationOptions} [validation] - Validation behavior options
+ * @property {TraverseOptions} [traverse] - Schema traversal options
+ * @property {TCollect} [collectErrors] - Return `{ valid, errors }` instead of a boolean
+ * @property {boolean} [skipErrors] - Stop at the first failure (defaults to `!collectErrors`)
+ * @property {boolean} [useGrapheme] - Count grapheme clusters for string length
+ * @property {boolean} [contentValidation] - Assert contentEncoding/contentMediaType
+ * @property {number} [draftVersion] - The JSON Schema draft version
+ * @property {boolean} [formatAssertion] - Assert the format keyword
+ * @property {boolean} [messages] - Render English message text on collected errors
+ * @property {'error'|'ignore'} [unknownFormats] - What an ASSERTING `format` with no registered compiler does: 'ignore' (default, per spec) accepts it as an annotation, 'error' throws at compile time
+ */
+
 /**
  * JarenValidator is the main entry point for JSON Schema validation.
  * It manages schema registration, format registration, and compilation.
+ *
+ * The `collectErrors` option decides what a compiled validator returns, and
+ * it is carried in the type parameter so the two shapes never have to be
+ * distinguished at runtime.
+ * @template {boolean} [TCollect=false]
  * @class
  * @example
  * const validator = new JarenValidator();
@@ -1205,7 +1341,7 @@ export class JarenValidator {
 
   /**
    * Creates a new JarenValidator instance.
-   * @param {ValidatorOptions} [options] - Validator options including formats, schemas, validation options, and traverse options
+   * @param {ValidatorOptions | ValidatorInit<TCollect>} [options] - Validator options including formats, schemas, validation options, and traverse options
    */
   constructor(options = new ValidatorOptions()) {
     // Accept a plain options object ({ skipErrors, collectErrors, ... })
@@ -1223,7 +1359,7 @@ export class JarenValidator {
    * Adds a format validator.
    * @param {string} name - The format name (e.g., 'email', 'uri', 'date-time')
    * @param {FormatCompiler} formatCompiler - A function that compiles format validators
-   * @returns {JarenValidator} This validator instance for chaining
+   * @returns {this} This validator instance for chaining (the polymorphic `this` keeps the collectErrors type parameter across a chain)
    * @example
    * validator.addFormat('custom', (schemaObj, schema) => {
    *   return (data) => data.startsWith('custom:');
@@ -1240,7 +1376,7 @@ export class JarenValidator {
   /**
    * Adds multiple format validators at once.
    * @param {Record<string, FormatCompiler>} formatCompilers - Object mapping format names to compiler functions
-   * @returns {JarenValidator} This validator instance for chaining
+   * @returns {this} This validator instance for chaining (the polymorphic `this` keeps the collectErrors type parameter across a chain)
    */
   addFormats(formatCompilers) {
     registerFormatCompilers(
@@ -1286,7 +1422,7 @@ export class JarenValidator {
    * Dependencies can be added in any order, and circular dependencies are supported.
    * @param {JSONSchema | boolean | (JSONSchema | boolean)[]} schema - The schema(s) to add
    * @param {string} [key] - Optional key/URI to register the schema under
-   * @returns {JarenValidator} This validator instance for chaining
+   * @returns {this} This validator instance for chaining (the polymorphic `this` keeps the collectErrors type parameter across a chain)
    * @example
    * // Add a single schema
    * validator.addSchema({ $id: 'http://example.com/user', type: 'object' });
@@ -1348,7 +1484,7 @@ export class JarenValidator {
     const newSchemas = new Map();
     try {
       storeSchemaIdsInMap(newSchemas, baseUri, schema, scopedOpts);
-    } catch (e) {
+    } catch (_e) {
       // Ignore errors for already-existing schemas at the root level
     }
 
@@ -1360,144 +1496,19 @@ export class JarenValidator {
     }
   }
 
-  /**
-   * Convert internal validation errors to public ValidationError format
-   * @param {InternalValidationError[]} internalErrors
-   * @returns {ValidationError[]}
-   */
-  static #convertErrors(internalErrors) {
-    return internalErrors.map(err => {
-      const keyword = Array.isArray(err.key) ? err.key[err.key.length - 1] : err.key;
-
-      // Build params based on error type
-      const params = {};
-      if (keyword === 'required') {
-        params.missingProperty = err.dataKey;
-      } else if (keyword === 'type') {
-        if (Array.isArray(err.expected)) {
-          params.types = err.expected;
-        } else {
-          params.type = err.expected;
-        }
-      } else if (['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'minLength', 'maxLength', 'minProperties', 'maxProperties', 'minItems', 'maxItems'].includes(keyword)) {
-        params.limit = err.expected;
-        if (keyword === 'minimum' || keyword === 'maximum') {
-          params.comparison = keyword === 'minimum' ? '>=' : '<=';
-        } else if (keyword === 'exclusiveMinimum' || keyword === 'exclusiveMaximum') {
-          params.comparison = keyword === 'exclusiveMinimum' ? '>' : '<';
-        }
-      } else if (keyword === 'multipleOf') {
-        params.multipleOf = err.expected;
-      } else if (keyword === 'pattern') {
-        params.pattern = err.expected?.source || err.expected;
-      } else if (keyword === 'additionalProperties') {
-        params.additionalProperty = err.dataKey;
-      } else if (keyword === '$query') {
-        // A '$query' runtime failure passes the JQ2xxx code and the query
-        // document pointer as extra meta arguments after the data path;
-        // a plain EBV-false failure passes neither.
-        if (err.rest != null && err.rest.length > 1) {
-          params.code = err.rest[1];
-          params.docPath = err.rest[2];
-        }
-      }
-
-      // Generate message
-      let message = `validation failed for keyword '${keyword}'`;
-      if (keyword === 'required') {
-        message = params.missingProperty
-          ? `must have required property '${params.missingProperty}'`
-          : 'must have required properties';
-      } else if (keyword === 'type') {
-        message = params.types
-          ? `must be one of the following types: ${params.types.join(', ')}`
-          : `must be ${params.type === 'integer' ? 'an' : 'a'} ${params.type}`;
-      } else if (keyword === 'minimum' || keyword === 'maximum') {
-        message = `must be ${params.comparison} ${params.limit}`;
-      } else if (keyword === 'exclusiveMinimum' || keyword === 'exclusiveMaximum') {
-        message = `must be ${params.comparison} ${params.limit}`;
-      } else if (keyword === 'multipleOf') {
-        message = `must be multiple of ${params.multipleOf}`;
-      } else if (keyword === 'minLength') {
-        message = `must NOT have fewer than ${params.limit} characters`;
-      } else if (keyword === 'maxLength') {
-        message = `must NOT have more than ${params.limit} characters`;
-      } else if (keyword === 'pattern') {
-        message = `must match pattern "${params.pattern}"`;
-      } else if (keyword === 'additionalProperties') {
-        message = params.additionalProperty
-          ? `must NOT have additional property '${params.additionalProperty}'`
-          : 'must NOT have additional properties';
-      } else if (keyword === 'minProperties') {
-        message = `must NOT have fewer than ${params.limit} properties`;
-      } else if (keyword === 'maxProperties') {
-        message = `must NOT have more than ${params.limit} properties`;
-      } else if (keyword === 'minItems') {
-        message = `must NOT have fewer than ${params.limit} items`;
-      } else if (keyword === 'maxItems') {
-        message = `must NOT have more than ${params.limit} items`;
-      } else if (keyword === 'uniqueItems') {
-        message = 'must NOT have duplicate items';
-      } else if (keyword === 'contains') {
-        message = 'must contain at least one valid item';
-      } else if (keyword === 'items') {
-        message = 'array items are invalid';
-      } else if (keyword === 'allOf') {
-        message = 'must match all of the subschemas';
-      } else if (keyword === 'anyOf') {
-        message = 'must match a subschema in anyOf';
-      } else if (keyword === 'oneOf') {
-        message = 'must match exactly one subschema in oneOf';
-      } else if (keyword === 'not') {
-        message = 'must NOT match the subschema';
-      } else if (keyword === 'format') {
-        const formatName = err.expected || err.value;
-        params.format = formatName;
-        message = `must match format "${formatName}"`;
-      } else if (keyword === 'if') {
-        message = 'must match "if" schema';
-      } else if (keyword === 'then') {
-        message = 'must match "then" schema';
-      } else if (keyword === 'else') {
-        message = 'must match "else" schema';
-      } else if (keyword === 'false schema') {
-        message = 'boolean schema false is always invalid';
-      } else if (keyword === '$query') {
-        message = params.code
-          ? `'$query' assertion raised ${params.code} at '${params.docPath}'`
-          : "must satisfy the '$query' assertion";
-      }
-
-      // Validators pass the data path as the first meta argument to the
-      // error handler; use it when it looks like a JSON pointer.
-      const meta0 = err.rest?.[0];
-      const instancePath = (typeof meta0 === 'string' && (meta0 === '' || meta0.charCodeAt(0) === 0x2f))
-        ? meta0
-        : '';
-
-      return new ValidationError({
-        keyword,
-        instancePath,
-        schemaPath: err.object?.path || '',
-        params,
-        message,
-      });
-    });
-  }
-
   /**
    *
    * @param {JarenValidator} self
    * @param {string} origin
    * @param {Map} schemas
-   * @returns {(data) => boolean | {valid: boolean, errors: ValidationError[]}}
+   * @returns {(data) => boolean | {valid: boolean, errors: import("./messages.js").ValidationError[]}}
    */
-  static #compileSchema(self, origin, schemas) {
+  static #compileSchema(self, origin, schemas, validation = self.#options.validation) {
     const root = new ValidationRoot(
       origin,
       schemas,
       self.#formats,
-      self.#options.validation,
+      validation,
       self.#options.traverse,
       self);
 
@@ -1508,16 +1519,12 @@ export class JarenValidator {
       if (collectErrors) {
         return {
           valid,
-          errors: valid ? [] : JarenValidator.#convertErrors(root.errors)
+          errors: valid ? [] : convertInternalErrors(root.errors)
         };
       }
       return valid;
     }
 
-    Object.defineProperty(jarenValidateSchema, "errors", {
-      get: function () { return root.errors }
-    })
-
     return jarenValidateSchema;
   }
 
@@ -1527,20 +1534,25 @@ export class JarenValidator {
    * @param {string} origin
    * @param {Map} schemas
    * @param {ValidationRoot} root - Pre-created root with pre-compiled refs
-   * @returns {(data) => boolean | {valid: boolean, errors: ValidationError[]}}
+   * @returns {(data) => boolean | {valid: boolean, errors: import("./messages.js").ValidationError[]}}
    */
   static #compileSchemaWithRoot(self, origin, schemas, root) {
     const collectErrors = self.#options.validation?.collectErrors || false;
 
+    if (!collectErrors) {
+      const jarenValidateSchema = root.createValidateFn();
+      Object.defineProperty(jarenValidateSchema, "errors", {
+        get: function () { return root.errors }
+      })
+      return jarenValidateSchema;
+    }
+
     function jarenValidateSchema(data) {
       const valid = root.validate(data);
-      if (collectErrors) {
-        return {
-          valid,
-          errors: valid ? [] : JarenValidator.#convertErrors(root.errors)
-        };
-      }
-      return valid;
+      return {
+        valid,
+        errors: valid ? [] : convertInternalErrors(root.errors)
+      };
     }
 
     Object.defineProperty(jarenValidateSchema, "errors", {
@@ -1559,28 +1571,45 @@ export class JarenValidator {
    * Meta-schemas are schemas that describe the structure of valid JSON schemas.
    * @param {JSONSchema | boolean | (JSONSchema | boolean)[]} schema - The meta-schema(s) to add
    * @param {string} [key] - Optional key/URI for the meta-schema
-   * @returns {JarenValidator} This validator instance for chaining
+   * @returns {this} This validator instance for chaining (the polymorphic `this` keeps the collectErrors type parameter across a chain)
    * @example
    * validator.addMetaSchema(draft7MetaSchema, 'http://json-schema.org/draft-07/schema');
    */
   addMetaSchema(schema, key = undefined) {
     key = JarenValidator.normalizeUriKey(key)
+    // A meta-schema is infrastructure, not something the caller authored:
+    // every JSON Schema meta-schema declares `format: "uri-reference"` on
+    // `$id`/`$ref`, and nobody registers formats in order to check that a
+    // SCHEMA is well-formed. The unknownFormats guard protects an author
+    // from a keyword of their own that silently checks nothing, so it does
+    // not apply here — otherwise merely registering draft-07 would throw.
+    const validation = JarenValidator.#withOption(this.#options.validation,
+      'unknownFormats', 'ignore');
     if (Array.isArray(schema)) {
       const first = schema.shift();
       const { origin, map } = JarenValidator.#traverseSchema(first, schema, undefined, new TraverseOptions(key));
-      const compiled = JarenValidator.#compileSchema(this, origin, map);
+      const compiled = JarenValidator.#compileSchema(this, origin, map, validation);
       this.#metaSchemas.set(origin, compiled);
       mergeMap(this.#schemas, map);
     }
     else if (isBoolOrObjectClass(schema)) {
       const { origin, map } = JarenValidator.#traverseSchema(schema, undefined, undefined, new TraverseOptions(key));
-      const compiled = JarenValidator.#compileSchema(this, origin, map);
+      const compiled = JarenValidator.#compileSchema(this, origin, map, validation);
       this.#metaSchemas.set(origin, compiled);
       mergeMap(this.#schemas, map);
     }
     return this;
   }
 
+  /** A ValidationOptions with one member replaced, leaving the original
+   * untouched (the validator's own options must not drift). */
+  static #withOption(validation, name, value) {
+    const next = new ValidationOptions();
+    Object.assign(next, validation ?? new ValidationOptions());
+    next[name] = value;
+    return next;
+  }
+
   /**
    * Retrieves a registered schema by its key/URI.
    * @param {string} key - The schema URI/key
@@ -1645,7 +1674,7 @@ export class JarenValidator {
         // This is a canonical $id path - create with origin as base
         try {
           root.createObject(id, schema, origin);
-        } catch (e) {
+        } catch (_e) {
           // May fail if dependencies not resolved yet
         }
       }
@@ -1751,7 +1780,7 @@ export class JarenValidator {
                 baseUri = candidateBase;
                 break;
               }
-            } catch (e) {
+            } catch (_e) {
               // Invalid URL, skip this candidate
             }
           }
@@ -1760,7 +1789,7 @@ export class JarenValidator {
 
       try {
         root.createObject(id, schema, baseUri);
-      } catch (e) {
+      } catch (_e) {
         // Ref may not be resolvable yet, that's ok
       }
     }
@@ -1770,9 +1799,16 @@ export class JarenValidator {
    * Compiles a schema into a validation function.
    * This is the main method for creating validators. It resolves all $ref references,
    * compiles the schema structure, and returns a function that validates data.
+   * The return type follows the instance's `collectErrors` setting: a type
+   * guard over `unknown` by default, or a function producing
+   * `{ valid, errors }` when errors are collected. Jaren does not infer `T`
+   * from the schema — the caller asserts what the schema describes, which is
+   * what a checked contract wrapper wants; pair it with a schema-to-type
+   * generator if you need the shape derived mechanically.
+   * @template [T=unknown]
    * @param {JSONSchema | boolean} schema - The schema to compile
    * @param {(JSONSchema | boolean)[]} [schemas] - Additional schemas to reference during compilation
-   * @returns {(data: any) => boolean | {valid: boolean, errors: ValidationError[]}} A validation function
+   * @returns {TCollect extends true ? CompiledCollector : CompiledPredicate<T>} A validation function
    * @example
    * const validate = validator.compile({
    *   type: 'object',
@@ -1784,9 +1820,13 @@ export class JarenValidator {
    * const valid = validate({ name: 'John' }); // true
    * const invalid = validate({ name: 123 }); // false
    *
+   * // Narrowing to a caller-asserted type
+   * const isUser = validator.compile<{ name: string }>(userSchema);
+   * if (isUser(input)) input.name; // input is { name: string } here
+   *
    * // With error collection
-   * validator = new JarenValidator({ collectErrors: true });
-   * const result = validate({ name: 123 });
+   * const collecting = new JarenValidator({ collectErrors: true });
+   * const result = collecting.compile(schema)({ name: 123 });
    * // result = { valid: false, errors: [...] }
    */
   compile(schema, schemas = undefined) {
@@ -1831,7 +1871,9 @@ export class JarenValidator {
       existingValidation.contentValidation ?? contentValidationDefault,
       draftVersion,
       vocabValidation,
-      formatAssertion
+      formatAssertion,
+      existingValidation.messages ?? true,
+      existingValidation.unknownFormats ?? 'ignore'
     );
 
     // Pre-compile all refs before returning the validator