@jarenjs/validate 0.34.2 → 0.43.3

package/ARCHITECTURE.md

@@ -955,7 +955,7 @@ Map<string, ValidationObject> {
 
 When schemas have `$id` that changes the base URI:
 
-```json
+```jsonc
 {
   "$id": "http://example.com/schema",
   "$defs": {

package/README.md

@@ -1,6 +1,6 @@
 # @jarenjs/validate
 
-The JSON Schema validating compiler at the heart of [Jaren](https://github.com/jklarenbeek/jarenjs). It compiles JSON Schemas into optimized validation functions and fully supports `draft-06`, `draft-07`, `draft 2019-09` and `draft 2020-12` — passing 100% of the official [JSON-Schema-Test-Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite) for draft-07, 2019-09 and 2020-12.
+The JSON Schema validating compiler at the heart of [Jaren](https://github.com/jklarenbeek/jarenjs). It compiles JSON Schemas into optimized validation functions and fully supports `draft-06`, `draft-07`, `draft 2019-09` and `draft 2020-12` — passing the official [JSON-Schema-Test-Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite) for draft-07 and 2019-09 in full, and all of 2020-12 except the `$dynamicRef` cases the repository's roadmap names.
 
 ## Usage
 

package/dist/types/index.d.ts

@@ -330,6 +330,7 @@ export type JSONSchemaKeywords = {
     data?: DataKeywordSchema;
 };
 export type JSONSchema = JSONSchemaKeywords & Record<string, unknown>;
+export type JSONSchemaLike = JSONSchema | Record<string, unknown>;
 export type FormatCompiler = (schemaObj: ValidationObject, jsonSchema: JSONSchema & {
     format?: string;
 }) => ((data: unknown, dataPath?: string) => boolean) | undefined;
@@ -447,6 +448,18 @@ export type FormatCompiler = (schemaObj: ValidationObject, jsonSchema: JSONSchem
  * forms accept everything (`true`) or nothing (`false`).
  * @typedef {JSONSchemaKeywords & Record<string, unknown>} JSONSchema
  */
+/**
+ * A schema as a validator boundary ACCEPTS it. {@link JSONSchema}
+ * documents what a schema IS — typed keywords, open for extensions —
+ * but a schema held as a plain `Record<string, unknown>` map (the
+ * natural type for a document that crossed a wire or a package
+ * boundary) does not assign to that keyword intersection under strict
+ * TypeScript, and forcing the consumer to cast at every `compile` and
+ * `addSchema` call site teaches them to cast, which is worse than the
+ * looser parameter. The boundary methods accept this union; both arms
+ * are treated identically at runtime, which was always true.
+ * @typedef {JSONSchema | Record<string, unknown>} JSONSchemaLike
+ */
 /**
  * A format compiler function.
  * Called once per schema location at compile time with the compiling
@@ -893,7 +906,7 @@ export declare class JarenValidator<TCollect extends boolean = false> {
      * Adds schema(s) to the validator instance.
      * This method does not compile schemas - it only registers them for reference.
      * Dependencies can be added in any order, and circular dependencies are supported.
-     * @param {JSONSchema | boolean | (JSONSchema | boolean)[]} schema - The schema(s) to add
+     * @param {JSONSchemaLike | boolean | (JSONSchemaLike | boolean)[]} schema - The schema(s) to add
      * @param {string} [key] - Optional key/URI to register the schema under
      * @returns {this} This validator instance for chaining (the polymorphic `this` keeps the collectErrors type parameter across a chain)
      * @example
@@ -906,18 +919,18 @@ export declare class JarenValidator<TCollect extends boolean = false> {
      * // Add with explicit key
      * validator.addSchema({ type: 'string' }, 'http://example.com/name');
      */
-    addSchema(schema: JSONSchema | boolean | (JSONSchema | boolean)[], key?: string): this;
+    addSchema(schema: JSONSchemaLike | boolean | (JSONSchemaLike | boolean)[], key?: string): this;
     static normalizeUriKey(key: any): any;
     /**
      * Adds meta-schema(s) that can be used to validate schemas.
      * 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 {JSONSchemaLike | boolean | (JSONSchemaLike | boolean)[]} schema - The meta-schema(s) to add
      * @param {string} [key] - Optional key/URI for the meta-schema
      * @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: JSONSchema | boolean | (JSONSchema | boolean)[], key?: string): this;
+    addMetaSchema(schema: JSONSchemaLike | boolean | (JSONSchemaLike | boolean)[], key?: string): this;
     /**
      * Retrieves a registered schema by its key/URI.
      * @param {string} key - The schema URI/key
@@ -927,13 +940,13 @@ export declare class JarenValidator<TCollect extends boolean = false> {
     /**
      * Validates a schema against a registered meta-schema.
      * This is used to ensure schemas are valid according to the JSON Schema specification.
-     * @param {JSONSchema | boolean} schema - The schema to validate
+     * @param {JSONSchemaLike | boolean} schema - The schema to validate
      * @returns {boolean} True if the schema is valid
      * @example
      * validator.addMetaSchema(draft7MetaSchema);
      * const isValid = validator.validateSchema({ type: 'string' }); // true
      */
-    validateSchema(schema: JSONSchema | boolean): boolean;
+    validateSchema(schema: JSONSchemaLike | boolean): boolean;
     /**
      * Compiles a schema into a validation function.
      * This is the main method for creating validators. It resolves all $ref references,
@@ -945,8 +958,8 @@ export declare class JarenValidator<TCollect extends boolean = false> {
      * 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
+     * @param {JSONSchemaLike | boolean} schema - The schema to compile
+     * @param {(JSONSchemaLike | boolean)[]} [schemas] - Additional schemas to reference during compilation
      * @returns {TCollect extends true ? CompiledCollector : CompiledPredicate<T>} A validation function
      * @example
      * const validate = validator.compile({
@@ -968,5 +981,5 @@ export declare class JarenValidator<TCollect extends boolean = false> {
      * const result = collecting.compile(schema)({ name: 123 });
      * // result = { valid: false, errors: [...] }
      */
-    compile<T = unknown>(schema: JSONSchema | boolean, schemas?: (JSONSchema | boolean)[]): TCollect extends true ? CompiledCollector : CompiledPredicate<T>;
+    compile<T = unknown>(schema: JSONSchemaLike | boolean, schemas?: (JSONSchemaLike | boolean)[]): TCollect extends true ? CompiledCollector : CompiledPredicate<T>;
 }

package/dist/types/tools.d.ts

@@ -14,6 +14,22 @@ export declare function isOfSchemaType(schema: any, type: any): boolean;
 export declare function hasSchemaRef(schema: any): boolean;
 export declare function hasSchemaRecursiveRef(schema: any): boolean;
 export declare function hasSchemaDynamicRef(schema: any): boolean;
+/**
+ * The keywords that assert something beside a `$ref`: the siblings draft
+ * 2019-09+ applies alongside the reference and draft-07 ignores.
+ * Membership-only (order-insensitive): the shared constraint groups plus
+ * the applicators and extras. One list, read by the schema compiler (does
+ * this `$ref` carry siblings to compile?) and by the reference resolver
+ * (may this hop of a `$ref` chain be flattened away?).
+ */
+export declare const REF_SIBLING_KEYWORDS: readonly string[];
+/**
+ * Whether a schema carrying a `$ref` also carries a keyword of
+ * {@link REF_SIBLING_KEYWORDS}.
+ * @param {object} schema
+ * @returns {boolean}
+ */
+export declare function hasRefSiblings(schema: object): boolean;
 /**
  * Whether a sibling keyword of unevaluatedProperties already evaluates every
  * property of the instance. additionalProperties (boolean or schema) applies

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/validate",
   "private": false,
-  "version": "0.34.2",
+  "version": "0.43.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -55,7 +55,7 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.34.2",
-    "@jarenjs/json": "^0.34.2"
+    "@jarenjs/core": "^0.43.3",
+    "@jarenjs/json": "^0.43.3"
   }
 }

package/src/index.js

@@ -168,6 +168,19 @@ export { TraverseOptions };
  * @typedef {JSONSchemaKeywords & Record<string, unknown>} JSONSchema
  */
 
+/**
+ * A schema as a validator boundary ACCEPTS it. {@link JSONSchema}
+ * documents what a schema IS — typed keywords, open for extensions —
+ * but a schema held as a plain `Record<string, unknown>` map (the
+ * natural type for a document that crossed a wire or a package
+ * boundary) does not assign to that keyword intersection under strict
+ * TypeScript, and forcing the consumer to cast at every `compile` and
+ * `addSchema` call site teaches them to cast, which is worse than the
+ * looser parameter. The boundary methods accept this union; both arms
+ * are treated identically at runtime, which was always true.
+ * @typedef {JSONSchema | Record<string, unknown>} JSONSchemaLike
+ */
+
 /**
  * A format compiler function.
  * Called once per schema location at compile time with the compiling
@@ -1420,7 +1433,7 @@ export class JarenValidator {
    * Adds schema(s) to the validator instance.
    * This method does not compile schemas - it only registers them for reference.
    * Dependencies can be added in any order, and circular dependencies are supported.
-   * @param {JSONSchema | boolean | (JSONSchema | boolean)[]} schema - The schema(s) to add
+   * @param {JSONSchemaLike | boolean | (JSONSchemaLike | boolean)[]} schema - The schema(s) to add
    * @param {string} [key] - Optional key/URI to register the schema under
    * @returns {this} This validator instance for chaining (the polymorphic `this` keeps the collectErrors type parameter across a chain)
    * @example
@@ -1569,7 +1582,7 @@ export class JarenValidator {
   /**
    * Adds meta-schema(s) that can be used to validate schemas.
    * 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 {JSONSchemaLike | boolean | (JSONSchemaLike | boolean)[]} schema - The meta-schema(s) to add
    * @param {string} [key] - Optional key/URI for the meta-schema
    * @returns {this} This validator instance for chaining (the polymorphic `this` keeps the collectErrors type parameter across a chain)
    * @example
@@ -1623,7 +1636,7 @@ export class JarenValidator {
   /**
    * Validates a schema against a registered meta-schema.
    * This is used to ensure schemas are valid according to the JSON Schema specification.
-   * @param {JSONSchema | boolean} schema - The schema to validate
+   * @param {JSONSchemaLike | boolean} schema - The schema to validate
    * @returns {boolean} True if the schema is valid
    * @example
    * validator.addMetaSchema(draft7MetaSchema);
@@ -1806,8 +1819,8 @@ export class JarenValidator {
    * 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
+   * @param {JSONSchemaLike | boolean} schema - The schema to compile
+   * @param {(JSONSchemaLike | boolean)[]} [schemas] - Additional schemas to reference during compilation
    * @returns {TCollect extends true ? CompiledCollector : CompiledPredicate<T>} A validation function
    * @example
    * const validate = validator.compile({

package/src/schema.js

@@ -5,10 +5,6 @@ import {
   getStringType,
   isObjectClass,
 } from '@jarenjs/core';
-import {
-  NUMERIC_CONSTRAINTS, STRING_CONSTRAINTS,
-  ARRAY_CONSTRAINTS, OBJECT_CONSTRAINTS,
-} from '@jarenjs/core/schema';
 
 import {
   getUniqueArray,
@@ -29,6 +25,7 @@ import {
   hasSchemaRef,
   hasSchemaRecursiveRef,
   hasSchemaDynamicRef,
+  hasRefSiblings,
 } from './tools.js';
 
 import {
@@ -453,18 +450,10 @@ export function compileSchemaObject(schemaObj, jsonSchema) {
   let refWithSiblings = false;
   if (hasSchemaRef(jsonSchema) && !hasSchemaRecursiveRef(jsonSchema)) {
     // Check if there are any validation-related sibling keywords
-    // In draft 2019-09+, if there are validation siblings, we process
-    // them together. Membership-only (order-insensitive): the shared
-    // constraint groups plus the applicators and extras.
-    const validationKeywords = ['type', 'const', 'enum',
-      ...NUMERIC_CONSTRAINTS, ...STRING_CONSTRAINTS,
-      ...ARRAY_CONSTRAINTS, 'maxContains', 'minContains',
-      ...OBJECT_CONSTRAINTS, 'required',
-      'dependentRequired', 'properties', 'patternProperties', 'additionalProperties', 'items',
-      'prefixItems', 'additionalItems', 'contains', 'allOf', 'anyOf', 'oneOf', 'not', 'if',
-      'then', 'else', 'propertyNames', 'contentEncoding', 'contentMediaType',
-      'unevaluatedProperties', 'unevaluatedItems', '$query'];
-    const hasValidationSiblings = keys.some(k => validationKeywords.includes(k));
+    // (REF_SIBLING_KEYWORDS — the one list the reference resolver reads
+    // too). In draft 2019-09+, if there are validation siblings, we
+    // process them together.
+    const hasValidationSiblings = hasRefSiblings(jsonSchema);
     // In draft 7 and earlier, $ref always overrides siblings regardless
     // In draft 2019-09+, $ref can have validation siblings
     if (!hasValidationSiblings || draftVersion < 2019) {

package/src/tools.js

@@ -31,6 +31,11 @@ import {
   JSONPOINTER_NOTHING,
 } from '@jarenjs/json';
 
+import {
+  NUMERIC_CONSTRAINTS, STRING_CONSTRAINTS,
+  ARRAY_CONSTRAINTS, OBJECT_CONSTRAINTS,
+} from '@jarenjs/core/schema';
+
 //#region Object
 export function isBoolOrObjectClass(obj) {
   return isBooleanType(obj)
@@ -85,6 +90,37 @@ export function hasSchemaDynamicRef(schema) {
     && !isStringWhiteSpace(schema.$dynamicRef);
 }
 
+/**
+ * The keywords that assert something beside a `$ref`: the siblings draft
+ * 2019-09+ applies alongside the reference and draft-07 ignores.
+ * Membership-only (order-insensitive): the shared constraint groups plus
+ * the applicators and extras. One list, read by the schema compiler (does
+ * this `$ref` carry siblings to compile?) and by the reference resolver
+ * (may this hop of a `$ref` chain be flattened away?).
+ */
+export const REF_SIBLING_KEYWORDS = Object.freeze(['type', 'const', 'enum',
+  ...NUMERIC_CONSTRAINTS, ...STRING_CONSTRAINTS,
+  ...ARRAY_CONSTRAINTS, 'maxContains', 'minContains',
+  ...OBJECT_CONSTRAINTS, 'required',
+  'dependentRequired', 'properties', 'patternProperties', 'additionalProperties', 'items',
+  'prefixItems', 'additionalItems', 'contains', 'allOf', 'anyOf', 'oneOf', 'not', 'if',
+  'then', 'else', 'propertyNames', 'contentEncoding', 'contentMediaType',
+  'unevaluatedProperties', 'unevaluatedItems', '$query']);
+
+/**
+ * Whether a schema carrying a `$ref` also carries a keyword of
+ * {@link REF_SIBLING_KEYWORDS}.
+ * @param {object} schema
+ * @returns {boolean}
+ */
+export function hasRefSiblings(schema) {
+  const keys = Object.keys(schema);
+  for (let i = 0; i < keys.length; i++) {
+    if (REF_SIBLING_KEYWORDS.includes(keys[i])) return true;
+  }
+  return false;
+}
+
 /**
  * Whether a sibling keyword of unevaluatedProperties already evaluates every
  * property of the instance. additionalProperties (boolean or schema) applies

package/src/traverse.js

@@ -1,6 +1,7 @@
 import {
   isBoolOrObjectClass,
   hasSchemaRef,
+  hasRefSiblings,
 } from './tools.js';
 
 import {
@@ -416,10 +417,18 @@ export function resolveRefSchemaDeep(schemas, baseUri, refschema, opts = new Tra
     if (!isObjectClass(item))
       return { id: base, schema: item };
 
-    // In draft 7 and earlier, $ref completely replaces the schema
-    // and all sibling keywords must be ignored. We only keep the $ref
-    // to resolve it, discarding all other keywords from this item.
+    // A pure `$ref` hop is flattened away: only the `$ref` is kept to
+    // resolve it, the other (annotation) keywords of this item are
+    // discarded. A target reached THROUGH the chain that asserts
+    // keywords beside its `$ref` is the end of what may be flattened:
+    // draft 2019-09+ applies those siblings alongside the reference, so
+    // collapsing the chain past them would drop assertions (an OpenAPI
+    // document schema is nothing but such hops). The item is kept as
+    // written and compiled as a schema object, where the resource's
+    // draft decides whether its siblings assert (draft-07 ignores them).
     if (hasSchemaRef(item)) {
+      if (item !== refschema && hasRefSiblings(item))
+        return { id: base, schema: item };
       const ref = item.$ref;
       const { id, schema } = resolveRefSchemaShallow(schemas, ref, base, opts);