@jarenjs/validate 0.9.2 → 0.34.0

package/src/dollar-data.js

@@ -36,8 +36,6 @@
 import {
   isObjectClass,
   isStringType,
-  isNumberType,
-  isArrayClass,
   isObjectType,
 } from '@jarenjs/core';
 
@@ -46,21 +44,34 @@ import {
 } from '@jarenjs/core/object';
 
 import {
-  compileRelativeJSONPointer,
+  NUMERIC_CONSTRAINTS, STRING_CONSTRAINTS,
+  ARRAY_CONSTRAINTS, OBJECT_CONSTRAINTS,
+} from '@jarenjs/core/schema';
+
+import {
+  compileDataRef,
   JSONPOINTER_NOTHING,
 } from '@jarenjs/json';
 
-// A ref that fails the strict compile keeps the lax keyword semantics:
-// it resolves as not-found and the keyword asserts nothing.
-const resolveNothing = () => JSONPOINTER_NOTHING;
+import {
+  createDataRefCompilers,
+} from './tools.js';
 
+/**
+ * Resolve a `$data` reference.
+ *
+ * Ajv's `$data` takes the same three forms the `data` keyword does — empty for
+ * the root, a Relative JSON Pointer, or an absolute JSON Pointer — and this
+ * used to compile only the relative form. An absolute `$data: '/limit'` threw,
+ * was swallowed by the catch, and became `resolveNothing`: the constraint
+ * silently never asserted, so a document that should have failed passed. A
+ * disabled constraint is worse than a rejected schema, which is why an
+ * uncompilable reference is now a compile-time error.
+ * @param {string} ref
+ * @returns {(dataRoot: any, dataPath: string) => any}
+ */
 function compileRefResolver(ref) {
-  try {
-    return compileRelativeJSONPointer(ref);
-  }
-  catch {
-    return resolveNothing;
-  }
+  return compileDataRef(ref);
 }
 
 /**
@@ -72,260 +83,12 @@ function isDollarDataRef(value) {
   return isObjectClass(value) && isStringType(value.$data);
 }
 
+// The fifteen keyword validators are shared with the `data` keyword;
+// only `compileRefResolver` above differs (see tools.js). uniqueItems
+// and required below are $data-only and stay local.
+const KEYWORD_COMPILERS = createDataRefCompilers(compileRefResolver);
 
-//#region Number Validators
-
-/**
- * Compile $data reference for minimum constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataMinimum(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'minimum');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataMinimum(data, dataPath, dataRoot) {
-    if (!isNumberType(data)) return true;
-
-    const minValue = resolveRef(dataRoot, dataPath);
-    if (minValue === JSONPOINTER_NOTHING || !isNumberType(minValue)) return true;
-
-    return data >= minValue || addError(minValue, data, dataPath);
-  };
-}
-
-/**
- * Compile $data reference for maximum constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataMaximum(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'maximum');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataMaximum(data, dataPath, dataRoot) {
-    if (!isNumberType(data)) return true;
-
-    const maxValue = resolveRef(dataRoot, dataPath);
-    if (maxValue === JSONPOINTER_NOTHING || !isNumberType(maxValue)) return true;
-
-    return data <= maxValue || addError(maxValue, data, dataPath);
-  };
-}
-
-/**
- * Compile $data reference for exclusiveMinimum constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataExclusiveMinimum(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'exclusiveMinimum');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataExclusiveMinimum(data, dataPath, dataRoot) {
-    if (!isNumberType(data)) return true;
-
-    const minValue = resolveRef(dataRoot, dataPath);
-    if (minValue === JSONPOINTER_NOTHING || !isNumberType(minValue)) return true;
-
-    return data > minValue || addError(minValue, data, dataPath);
-  };
-}
-
-/**
- * Compile $data reference for exclusiveMaximum constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataExclusiveMaximum(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'exclusiveMaximum');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataExclusiveMaximum(data, dataPath, dataRoot) {
-    if (!isNumberType(data)) return true;
-
-    const maxValue = resolveRef(dataRoot, dataPath);
-    if (maxValue === JSONPOINTER_NOTHING || !isNumberType(maxValue)) return true;
-
-    return data < maxValue || addError(maxValue, data, dataPath);
-  };
-}
-
-/**
- * Compile $data reference for multipleOf constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataMultipleOf(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'multipleOf');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataMultipleOf(data, dataPath, dataRoot) {
-    if (!isNumberType(data)) return true;
-
-    const multipleOf = resolveRef(dataRoot, dataPath);
-    if (multipleOf === JSONPOINTER_NOTHING || !isNumberType(multipleOf)) return true;
-
-    const q = data / multipleOf;
-    return Math.abs(q - Math.round(q)) < 1e-6 || addError(multipleOf, data, dataPath);
-  };
-}
-
-//#endregion
-
-//#region String Validators
-
-/**
- * Compile $data reference for minLength constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataMinLength(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'minLength');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataMinLength(data, dataPath, dataRoot) {
-    if (typeof data !== 'string') return true;
-
-    const minLen = resolveRef(dataRoot, dataPath);
-    if (minLen === JSONPOINTER_NOTHING || !isNumberType(minLen)) return true;
-
-    return data.length >= minLen || addError(minLen, data, dataPath);
-  };
-}
-
-/**
- * Compile $data reference for maxLength constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataMaxLength(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'maxLength');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataMaxLength(data, dataPath, dataRoot) {
-    if (typeof data !== 'string') return true;
-
-    const maxLen = resolveRef(dataRoot, dataPath);
-    if (maxLen === JSONPOINTER_NOTHING || !isNumberType(maxLen)) return true;
-
-    return data.length <= maxLen || addError(maxLen, data, dataPath);
-  };
-}
-
-/**
- * Compile $data reference for pattern constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataPattern(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'pattern');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataPattern(data, dataPath, dataRoot) {
-    if (typeof data !== 'string') return true;
-
-    const pattern = resolveRef(dataRoot, dataPath);
-    if (pattern === JSONPOINTER_NOTHING || !isStringType(pattern)) return true;
-
-    const regex = new RegExp(pattern, 'u');
-    return regex.test(data) || addError(pattern, data, dataPath);
-  };
-}
-
-/**
- * Compile $data reference for format constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataFormat(schemaObj, ref) {
-  const formats = schemaObj.formats;
-  if (!formats) return undefined;
-
-  const addError = schemaObj.createErrorHandler(ref, 'format');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataFormat(data, dataPath, dataRoot) {
-    if (typeof data !== 'string') return true;
-
-    const formatName = resolveRef(dataRoot, dataPath);
-    if (formatName === JSONPOINTER_NOTHING || !isStringType(formatName)) return true;
-
-    const formatCompiler = formats[formatName];
-    if (!formatCompiler) return true;
-
-    // The format compiler needs to be called to create the validator
-    // We pass a mock schemaObj that only has createErrorHandler
-    const mockSchemaObj = {
-      createErrorHandler: () => () => false,
-      options: { skipErrors: true }
-    };
-
-    try {
-      // Get the validator function from the compiler
-      const validator = formatCompiler(mockSchemaObj, { format: formatName });
-      if (typeof validator !== 'function') return true;
-
-      return validator(data, dataPath) || addError(formatName, data, dataPath);
-    } catch (e) {
-      // If compilation fails, skip validation
-      return true;
-    }
-  };
-}
-
-//#endregion
-
-//#region Array Validators
-
-/**
- * Compile $data reference for minItems constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataMinItems(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'minItems');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataMinItems(data, dataPath, dataRoot) {
-    if (!Array.isArray(data)) return true;
-
-    const minItems = resolveRef(dataRoot, dataPath);
-    if (minItems === JSONPOINTER_NOTHING || !isNumberType(minItems)) return true;
-
-    return data.length >= minItems || addError(minItems, data, dataPath);
-  };
-}
-
-/**
- * Compile $data reference for maxItems constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataMaxItems(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'maxItems');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataMaxItems(data, dataPath, dataRoot) {
-    if (!Array.isArray(data)) return true;
-
-    const maxItems = resolveRef(dataRoot, dataPath);
-    if (maxItems === JSONPOINTER_NOTHING || !isNumberType(maxItems)) return true;
-
-    return data.length <= maxItems || addError(maxItems, data, dataPath);
-  };
-}
+//#region $data-only Validators
 
 /**
  * Compile $data reference for uniqueItems constraint
@@ -347,7 +110,7 @@ function compileDollarDataUniqueItems(schemaObj, ref) {
     for (let i = 0; i < data.length; i++) {
       for (let j = i + 1; j < data.length; j++) {
         if (equalsDeep(data[i], data[j])) {
-          return addError(true, data, dataPath);
+          return addError(data, dataPath);
         }
       }
     }
@@ -355,52 +118,6 @@ function compileDollarDataUniqueItems(schemaObj, ref) {
   };
 }
 
-//#endregion
-
-//#region Object Validators
-
-/**
- * Compile $data reference for minProperties constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataMinProperties(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'minProperties');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataMinProperties(data, dataPath, dataRoot) {
-    if (typeof data !== 'object' || data === null || Array.isArray(data)) return true;
-
-    const minProps = resolveRef(dataRoot, dataPath);
-    if (minProps === JSONPOINTER_NOTHING || !isNumberType(minProps)) return true;
-
-    const propCount = Object.keys(data).length;
-    return propCount >= minProps || addError(minProps, data, dataPath);
-  };
-}
-
-/**
- * Compile $data reference for maxProperties constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataMaxProperties(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'maxProperties');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataMaxProperties(data, dataPath, dataRoot) {
-    if (typeof data !== 'object' || data === null || Array.isArray(data)) return true;
-
-    const maxProps = resolveRef(dataRoot, dataPath);
-    if (maxProps === JSONPOINTER_NOTHING || !isNumberType(maxProps)) return true;
-
-    const propCount = Object.keys(data).length;
-    return propCount <= maxProps || addError(maxProps, data, dataPath);
-  };
-}
-
 /**
  * Compile $data reference for required constraint
  * @param {object} schemaObj - The validation object
@@ -408,7 +125,9 @@ function compileDollarDataMaxProperties(schemaObj, ref) {
  * @returns {function|undefined} The compiled validator function
  */
 function compileDollarDataRequired(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'required');
+  // Keyed handler: the missing property name travels as the dataKey, so
+  // error conversion extracts params.missingProperty like static required.
+  const addError = schemaObj.createErrorHandler(ref, ['required']);
   const resolveRef = compileRefResolver(ref);
 
   return function validateDollarDataRequired(data, dataPath, dataRoot) {
@@ -428,52 +147,26 @@ function compileDollarDataRequired(schemaObj, ref) {
 
 //#endregion
 
-//#region Enum/Const Validators
-
-/**
- * Compile $data reference for enum constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataEnum(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'enum');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataEnum(data, dataPath, dataRoot) {
-    if (data === undefined) return true;
-
-    const enumValues = resolveRef(dataRoot, dataPath);
-    if (enumValues === JSONPOINTER_NOTHING || !Array.isArray(enumValues)) return true;
-
-    return enumValues.includes(data) || addError(enumValues, data, dataPath);
-  };
-}
-
-/**
- * Compile $data reference for const constraint
- * @param {object} schemaObj - The validation object
- * @param {string} ref - The $data reference (relative JSON Pointer)
- * @returns {function|undefined} The compiled validator function
- */
-function compileDollarDataConst(schemaObj, ref) {
-  const addError = schemaObj.createErrorHandler(ref, 'const');
-  const resolveRef = compileRefResolver(ref);
-
-  return function validateDollarDataConst(data, dataPath, dataRoot) {
-    if (data === undefined) return true;
-
-    const constValue = resolveRef(dataRoot, dataPath);
-    if (constValue === JSONPOINTER_NOTHING) return true;
-
-    return data === constValue || addError(constValue, data, dataPath);
-  };
-}
-
-//#endregion
-
 //#region Main Compilation
 
+/** Application order of the $data-capable keywords (error order is part
+ * of the observable behavior; the shared groups' internal order IS the
+ * historical per-keyword dispatch sequence — `@jarenjs/core/schema`
+ * documents that order as contract). */
+const DOLLAR_KEYWORD_ORDER = [
+  ...NUMERIC_CONSTRAINTS,
+  ...STRING_CONSTRAINTS,
+  ...ARRAY_CONSTRAINTS,
+  ...OBJECT_CONSTRAINTS, 'required',
+  'enum', 'const',
+];
+
+const DOLLAR_ONLY_COMPILERS = {
+  __proto__: null,
+  uniqueItems: compileDollarDataUniqueItems,
+  required: compileDollarDataRequired,
+};
+
 /**
  * Compile $data keyword validators for a schema object
  * This detects when keyword values are { $data: "..." } objects and creates
@@ -486,93 +179,12 @@ function compileDollarDataConst(schemaObj, ref) {
 export function compileDollarDataSchema(schemaObj, jsonSchema) {
   const validators = [];
 
-  // Number constraints
-  if (isDollarDataRef(jsonSchema.minimum)) {
-    const validator = compileDollarDataMinimum(schemaObj, jsonSchema.minimum.$data);
-    if (validator) validators.push(validator);
-  }
-
-  if (isDollarDataRef(jsonSchema.maximum)) {
-    const validator = compileDollarDataMaximum(schemaObj, jsonSchema.maximum.$data);
-    if (validator) validators.push(validator);
-  }
-
-  if (isDollarDataRef(jsonSchema.exclusiveMinimum)) {
-    const validator = compileDollarDataExclusiveMinimum(schemaObj, jsonSchema.exclusiveMinimum.$data);
-    if (validator) validators.push(validator);
-  }
-
-  if (isDollarDataRef(jsonSchema.exclusiveMaximum)) {
-    const validator = compileDollarDataExclusiveMaximum(schemaObj, jsonSchema.exclusiveMaximum.$data);
-    if (validator) validators.push(validator);
-  }
-
-  if (isDollarDataRef(jsonSchema.multipleOf)) {
-    const validator = compileDollarDataMultipleOf(schemaObj, jsonSchema.multipleOf.$data);
-    if (validator) validators.push(validator);
-  }
-
-  // String constraints
-  if (isDollarDataRef(jsonSchema.minLength)) {
-    const validator = compileDollarDataMinLength(schemaObj, jsonSchema.minLength.$data);
-    if (validator) validators.push(validator);
-  }
-
-  if (isDollarDataRef(jsonSchema.maxLength)) {
-    const validator = compileDollarDataMaxLength(schemaObj, jsonSchema.maxLength.$data);
-    if (validator) validators.push(validator);
-  }
-
-  if (isDollarDataRef(jsonSchema.pattern)) {
-    const validator = compileDollarDataPattern(schemaObj, jsonSchema.pattern.$data);
-    if (validator) validators.push(validator);
-  }
-
-  if (isDollarDataRef(jsonSchema.format)) {
-    const validator = compileDollarDataFormat(schemaObj, jsonSchema.format.$data);
-    if (validator) validators.push(validator);
-  }
-
-  // Array constraints
-  if (isDollarDataRef(jsonSchema.minItems)) {
-    const validator = compileDollarDataMinItems(schemaObj, jsonSchema.minItems.$data);
-    if (validator) validators.push(validator);
-  }
-
-  if (isDollarDataRef(jsonSchema.maxItems)) {
-    const validator = compileDollarDataMaxItems(schemaObj, jsonSchema.maxItems.$data);
-    if (validator) validators.push(validator);
-  }
-
-  if (isDollarDataRef(jsonSchema.uniqueItems)) {
-    const validator = compileDollarDataUniqueItems(schemaObj, jsonSchema.uniqueItems.$data);
-    if (validator) validators.push(validator);
-  }
-
-  // Object constraints
-  if (isDollarDataRef(jsonSchema.minProperties)) {
-    const validator = compileDollarDataMinProperties(schemaObj, jsonSchema.minProperties.$data);
-    if (validator) validators.push(validator);
-  }
-
-  if (isDollarDataRef(jsonSchema.maxProperties)) {
-    const validator = compileDollarDataMaxProperties(schemaObj, jsonSchema.maxProperties.$data);
-    if (validator) validators.push(validator);
-  }
+  for (const keyword of DOLLAR_KEYWORD_ORDER) {
+    const value = jsonSchema[keyword];
+    if (!isDollarDataRef(value)) continue;
 
-  if (isDollarDataRef(jsonSchema.required)) {
-    const validator = compileDollarDataRequired(schemaObj, jsonSchema.required.$data);
-    if (validator) validators.push(validator);
-  }
-
-  // Enum/Const constraints
-  if (isDollarDataRef(jsonSchema.enum)) {
-    const validator = compileDollarDataEnum(schemaObj, jsonSchema.enum.$data);
-    if (validator) validators.push(validator);
-  }
-
-  if (isDollarDataRef(jsonSchema.const)) {
-    const validator = compileDollarDataConst(schemaObj, jsonSchema.const.$data);
+    const compileKeyword = KEYWORD_COMPILERS[keyword] ?? DOLLAR_ONLY_COMPILERS[keyword];
+    const validator = compileKeyword(schemaObj, value.$data);
     if (validator) validators.push(validator);
   }
 
@@ -594,35 +206,6 @@ export function compileDollarDataSchema(schemaObj, jsonSchema) {
   };
 }
 
-/**
- * Check if the schema has any $data references
- * This is used to determine if we should use the $data-aware compilation path
- * or the standard static compilation path.
- *
- * @param {object} jsonSchema - The JSON schema to check
- * @returns {boolean} True if the schema has any $data references
- */
-export function hasDollarDataReferences(jsonSchema) {
-  if (!isObjectType(jsonSchema)) return false;
-
-  // Keywords that can have $data values
-  const keywords = [
-    'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf',
-    'minLength', 'maxLength', 'pattern', 'format',
-    'minItems', 'maxItems', 'uniqueItems',
-    'minProperties', 'maxProperties', 'required',
-    'enum', 'const'
-  ];
-
-  for (const keyword of keywords) {
-    if (isDollarDataRef(jsonSchema[keyword])) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
 export function isDollarDataReference(jsonSchema) {
   return (jsonSchema !== null && (isObjectType(jsonSchema) && jsonSchema.$data));
 }

package/src/enum.js

@@ -1,7 +1,6 @@
 //@ts-check
 
 import {
-  isObjectType,
   isScalarType,
 } from '@jarenjs/core';
 

package/src/format.js

@@ -40,6 +40,11 @@ export function registerFormatCompilers(registered, formatCompilers) {
   return registered;
 }
 
+/** Named once: both wrong-shape paths end at the same mistake. */
+const WRONG_SHAPE_HINT = 'Register the format COMPILERS (stringFormats, dateTimeFormats, '
+  + 'numberFormats, jsonFormats, geoFormats) rather than the raw testers (formatTesters) — '
+  + 'both are objects full of functions, and only the compilers take (schemaObj, jsonSchema).';
+
 export function getSchemaFormatCompiler(registered, name) {
   if (isStringType(name))
     return registered[name];
@@ -53,14 +58,51 @@ export function compileFormatBasic(schemaObj, jsonSchema) {
 
   // From draft 2020-12 on, format is annotation-only unless assertion is
   // enabled (formatAssertion option or format-assertion vocabulary).
+  // Nothing is lost by an unregistered name here — the keyword would not
+  // have asserted even with a compiler — so the unknownFormats check
+  // below deliberately does not run in this branch. Complaining here
+  // would be complaining about the spec.
   if (schemaObj.options.formatAssertion === false)
     return undefined;
   const compiler = getSchemaFormatCompiler(
     schemaObj.formats,
     jsonSchema.format);
 
-  if (compiler)
-    return compiler(schemaObj, jsonSchema);
-  else
-    return undefined;
+  // An unregistered name with assertion ON is the silent failure this
+  // check exists to end: the author asked for the value to be checked,
+  // the registry has nothing to check it with, and without this the
+  // schema compiles to a validator that accepts everything. Raising it
+  // at COMPILE time keeps instance validation spec-exact — no data is
+  // ever invalidated by an unknown format, the schema's AUTHOR is told.
+  if (compiler == null) {
+    if (schemaObj.options.unknownFormats === 'ignore')
+      return undefined;
+    throw new Error(`Unknown format '${jsonSchema.format}': no compiler is registered for it, `
+      + 'so this schema would accept every value for that keyword. Register one '
+      + '(addFormats(dateTimeFormats) etc. from @jarenjs/formats, or addFormat(name, compiler) '
+      + "for your own), or pass { unknownFormats: 'ignore' } to accept it as an annotation.");
+  }
+
+  // A format COMPILER is called once per schema location and returns the
+  // per-value validator. Handing it a bare tester — `formatTesters`
+  // instead of `dateTimeFormats`, an easy mistake since both are objects
+  // full of functions — either returns a boolean (which the caller
+  // silently drops, so the format checks nothing again) or throws deep
+  // inside the tester on an argument it never expected. Both become one
+  // legible complaint here.
+  let validator;
+  try {
+    validator = compiler(schemaObj, jsonSchema);
+  }
+  catch (err) {
+    throw new Error(`Format '${jsonSchema.format}' failed to compile: ${err?.message ?? err}. `
+      + `${WRONG_SHAPE_HINT}`, { cause: err });
+  }
+  // Nullish stays legal: a compiler may decline a schema it cannot serve.
+  if (validator != null && !isFn(validator) && !Array.isArray(validator)) {
+    throw new Error(`Format '${jsonSchema.format}' is registered with something that is not a `
+      + `format compiler: calling it returned ${typeof validator}, not a validator function. `
+      + `${WRONG_SHAPE_HINT}`);
+  }
+  return validator;
 }