@apidevtools/json-schema-ref-parser 15.3.0 → 15.3.2

package/lib/pointer.ts

@@ -3,6 +3,7 @@ import type { ParserOptions } from "./options.js";
 import $Ref from "./ref.js";
 import * as url from "./util/url.js";
 import { JSONParserError, InvalidPointerError, MissingPointerError, isHandledError } from "./util/errors.js";
+import { getSchemaBasePath } from "./util/schema-resources.js";
 import type { JSONSchema } from "./index.js";
 import type { JSONSchema4Type, JSONSchema6Type, JSONSchema7Type } from "json-schema";
 
@@ -38,6 +39,11 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
    */
   originalPath: string;
 
+  /**
+   * The current base URI used to resolve nested $ref pointers while walking this pointer.
+   */
+  scopeBase: string;
+
   /**
    * The value of the JSON pointer.
    * Can be any JSON type, not just objects. Unknown file types are represented as Buffers (byte arrays).
@@ -61,6 +67,8 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
 
     this.originalPath = friendlyPath || path;
 
+    this.scopeBase = $ref.path || url.stripHash(path);
+
     this.value = undefined;
 
     this.circular = false;
@@ -87,6 +95,9 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
 
     // Crawl the object, one token at a time
     this.value = unwrapOrThrow(obj);
+    if (this.$ref.dynamicIdScope) {
+      this.scopeBase = getSchemaBasePath(this.scopeBase, this.value);
+    }
 
     for (let i = 0; i < tokens.length; i++) {
       // During token walking, if the current value is an extended $ref (has sibling keys
@@ -149,10 +160,14 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
       }
 
       found.push(token);
+      if (this.$ref.dynamicIdScope) {
+        this.scopeBase = getSchemaBasePath(this.scopeBase, this.value);
+      }
     }
 
     // Resolve the final value
-    if (!this.value || (this.value.$ref && url.resolve(this.path, this.value.$ref) !== pathFromRoot)) {
+    const finalResolutionBase = this.$ref.dynamicIdScope ? this.scopeBase : this.path;
+    if (!this.value || (this.value.$ref && url.resolve(finalResolutionBase, this.value.$ref) !== pathFromRoot)) {
       resolveIf$Ref(this, options, pathFromRoot);
     }
 
@@ -181,6 +196,9 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
 
     // Crawl the object, one token at a time
     this.value = unwrapOrThrow(obj);
+    if (this.$ref.dynamicIdScope) {
+      this.scopeBase = getSchemaBasePath(this.scopeBase, this.value);
+    }
 
     for (let i = 0; i < tokens.length - 1; i++) {
       resolveIf$Ref(this, options);
@@ -193,6 +211,10 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
         // The token doesn't exist, so create it
         this.value = setValue(this, token, {});
       }
+
+      if (this.$ref.dynamicIdScope) {
+        this.scopeBase = getSchemaBasePath(this.scopeBase, this.value);
+      }
     }
 
     // Set the value of the final token
@@ -287,7 +309,8 @@ function resolveIf$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
   // Is the value a JSON reference? (and allowed?)
 
   if ($Ref.isAllowed$Ref(pointer.value, options)) {
-    const $refPath = url.resolve(pointer.path, pointer.value.$ref);
+    const resolutionBase = pointer.$ref.dynamicIdScope ? pointer.scopeBase : pointer.path;
+    const $refPath = url.resolve(resolutionBase, pointer.value.$ref);
 
     if ($refPath === pointer.path && !isRootPath(pathFromRoot)) {
       // The value is a reference to itself, so there's nothing to do.
@@ -304,12 +327,18 @@ function resolveIf$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
         // This JSON reference "extends" the resolved value, rather than simply pointing to it.
         // So the resolved path does NOT change.  Just the value does.
         pointer.value = $Ref.dereference(pointer.value, resolved.value, options);
+        if (pointer.$ref.dynamicIdScope) {
+          pointer.scopeBase = getSchemaBasePath(pointer.scopeBase, pointer.value);
+        }
         return false;
       } else {
         // Resolve the reference
         pointer.$ref = resolved.$ref;
         pointer.path = resolved.path;
         pointer.value = resolved.value;
+        pointer.scopeBase = pointer.$ref.dynamicIdScope
+          ? getSchemaBasePath(pointer.$ref.path!, pointer.value)
+          : pointer.$ref.path!;
       }
 
       return true;

package/lib/ref.ts

@@ -47,6 +47,11 @@ class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOpt
    */
   pathType: string | unknown;
 
+  /**
+   * Whether this document/resource should use JSON Schema 2019-09+ nested $id scope semantics.
+   */
+  dynamicIdScope = false;
+
   /**
    * List of all errors. Undefined if no errors.
    */

package/lib/refs.ts

@@ -95,11 +95,10 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    */
   set(path: string, value: JSONSchema4Type | JSONSchema6Type | JSONSchema7Type) {
     const absPath = url.resolve(this._root$Ref.path!, path);
-    const withoutHash = url.stripHash(absPath);
-    const $ref = this._$refs[withoutHash];
+    const $ref = this._getRef(absPath);
 
     if (!$ref) {
-      throw new Error(`Error resolving $ref pointer "${path}". \n"${withoutHash}" not found.`);
+      throw new Error(`Error resolving $ref pointer "${path}". \n"${url.stripHash(absPath)}" not found.`);
     }
 
     $ref.set(absPath, value);
@@ -113,8 +112,7 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    */
   _get$Ref(path: string) {
     path = url.resolve(this._root$Ref.path!, path);
-    const withoutHash = url.stripHash(path);
-    return this._$refs[withoutHash];
+    return this._getRef(path);
   }
 
   /**
@@ -134,6 +132,23 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
     return $ref;
   }
 
+  _addAlias(path: string, value: S, pathType?: string | unknown, dynamicIdScope = false) {
+    const withoutHash = url.stripHash(path);
+
+    if (!withoutHash || this._$refs[withoutHash] || this._aliases[withoutHash]) {
+      return this._$refs[withoutHash] || this._aliases[withoutHash];
+    }
+
+    const $ref = new $Ref<S, O>(this);
+    $ref.path = withoutHash;
+    $ref.pathType = pathType;
+    $ref.value = value;
+    $ref.dynamicIdScope = dynamicIdScope;
+
+    this._aliases[withoutHash] = $ref;
+    return $ref;
+  }
+
   /**
    * Resolves the given JSON reference.
    *
@@ -145,11 +160,10 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    */
   _resolve(path: string, pathFromRoot: string, options?: O) {
     const absPath = url.resolve(this._root$Ref.path!, path);
-    const withoutHash = url.stripHash(absPath);
-    const $ref = this._$refs[withoutHash];
+    const $ref = this._getRef(absPath);
 
     if (!$ref) {
-      throw new Error(`Error resolving $ref pointer "${path}". \n"${withoutHash}" not found.`);
+      throw new Error(`Error resolving $ref pointer "${path}". \n"${url.stripHash(absPath)}" not found.`);
     }
 
     return $ref.resolve(absPath, options, path, pathFromRoot);
@@ -163,6 +177,8 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    */
   _$refs: $RefsMap<S, O> = {};
 
+  _aliases: $RefsMap<S, O> = {};
+
   /**
    * The {@link $Ref} object that is the root of the JSON schema.
    *
@@ -180,6 +196,7 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
     this.circular = false;
 
     this._$refs = {};
+    this._aliases = {};
 
     // @ts-ignore
     this._root$Ref = null;
@@ -205,6 +222,11 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    * @returns {object}
    */
   toJSON = this.values;
+
+  private _getRef(path: string) {
+    const withoutHash = url.stripHash(path);
+    return this._$refs[withoutHash] || this._aliases[withoutHash];
+  }
 }
 
 /**

package/lib/resolve-external.ts

@@ -3,6 +3,7 @@ import Pointer from "./pointer.js";
 import parse from "./parse.js";
 import * as url from "./util/url.js";
 import { isHandledError } from "./util/errors.js";
+import { getSchemaBasePath } from "./util/schema-resources.js";
 import type $Refs from "./refs.js";
 import type { ParserOptions } from "./options.js";
 import type { JSONSchema } from "./types/index.js";
@@ -29,7 +30,14 @@ function resolveExternal<S extends object = JSONSchema, O extends ParserOptions<
 
   try {
     // console.log('Resolving $ref pointers in %s', parser.$refs._root$Ref.path);
-    const promises = crawl(parser.schema, parser.$refs._root$Ref.path + "#", parser.$refs, options);
+    const promises = crawl(
+      parser.schema,
+      parser.$refs._root$Ref.path + "#",
+      parser.$refs._root$Ref.path!,
+      parser.$refs._root$Ref.dynamicIdScope,
+      parser.$refs,
+      options,
+    );
     return Promise.all(promises);
   } catch (e) {
     return Promise.reject(e);
@@ -55,6 +63,8 @@ function resolveExternal<S extends object = JSONSchema, O extends ParserOptions<
 function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
   obj: string | Buffer | S | undefined | null,
   path: string,
+  scopeBase: string,
+  dynamicIdScope: boolean,
   $refs: $Refs<S, O>,
   options: O,
   seen?: Set<any>,
@@ -65,15 +75,18 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
 
   if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !seen.has(obj)) {
     seen.add(obj); // Track previously seen objects to avoid infinite recursion
+    const currentScopeBase = dynamicIdScope ? getSchemaBasePath(scopeBase, obj) : scopeBase;
     if ($Ref.isExternal$Ref(obj)) {
-      promises.push(resolve$Ref<S, O>(obj, path, $refs, options));
+      promises.push(resolve$Ref<S, O>(obj, path, currentScopeBase, dynamicIdScope, $refs, options));
     }
 
     const keys = Object.keys(obj) as string[];
     for (const key of keys) {
       const keyPath = Pointer.join(path, key);
       const value = obj[key as keyof typeof obj] as string | JSONSchema | Buffer | undefined;
-      promises = promises.concat(crawl(value, keyPath, $refs, options, seen, external));
+      const childScopeBase =
+        dynamicIdScope && $Ref.isExternal$Ref(value) ? getSchemaBasePath(currentScopeBase, value) : currentScopeBase;
+      promises = promises.concat(crawl(value, keyPath, childScopeBase, dynamicIdScope, $refs, options, seen, external));
     }
   }
 
@@ -95,17 +108,20 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
 async function resolve$Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
   $ref: S,
   path: string,
+  scopeBase: string,
+  dynamicIdScope: boolean,
   $refs: $Refs<S, O>,
   options: O,
 ) {
   const shouldResolveOnCwd = options.dereference?.externalReferenceResolution === "root";
-  const resolvedPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, ($ref as JSONSchema).$ref!);
+  const resolutionBase = shouldResolveOnCwd ? url.cwd() : dynamicIdScope ? scopeBase : path;
+  const resolvedPath = url.resolve(resolutionBase, ($ref as JSONSchema).$ref!);
   const withoutHash = url.stripHash(resolvedPath);
 
   // $ref.$ref = url.relative($refs._root$Ref.path, resolvedPath);
 
   // Do we already have this $ref?
-  const ref = $refs._$refs[withoutHash];
+  const ref = $refs._get$Ref(withoutHash);
   if (ref) {
     // We've already parsed this $ref, so use the existing value
     return Promise.resolve(ref.value);
@@ -113,11 +129,33 @@ async function resolve$Ref<S extends object = JSONSchema, O extends ParserOption
 
   // Parse the $referenced file/url
   try {
-    const result = await parse(resolvedPath, $refs, options);
+    const reference = ($ref as JSONSchema).$ref;
+    const parseTarget: { url: string; baseUrl: string; reference?: string } = {
+      url: resolvedPath,
+      baseUrl: resolutionBase,
+    };
+    if (typeof reference === "string") {
+      parseTarget.reference = reference;
+    }
+    const result = await parse(
+      parseTarget,
+      $refs,
+      options,
+    );
 
     // Crawl the parsed value
     // console.log('Resolving $ref pointers in %s', withoutHash);
-    const promises = crawl(result, withoutHash + "#", $refs, options, new Set(), true);
+    const parsedRef = $refs._get$Ref(withoutHash);
+    const promises = crawl(
+      result,
+      withoutHash + "#",
+      withoutHash,
+      parsedRef?.dynamicIdScope ?? false,
+      $refs,
+      options,
+      new Set(),
+      true,
+    );
 
     return Promise.all(promises);
   } catch (err) {

package/lib/types/index.ts

@@ -139,6 +139,19 @@ export interface FileInfo {
    */
   url: string;
 
+  /**
+   * The unresolved `$ref` value exactly as it appeared in the parent schema, without the hash.
+   * This is useful for custom resolvers that need to preserve relative reference semantics instead
+   * of relying on the already-resolved `url`.
+   */
+  reference?: string;
+
+  /**
+   * The URL that `reference` was resolved against to produce `url`.
+   * This may include a JSON Pointer fragment when the reference originated from a nested location.
+   */
+  baseUrl?: string;
+
   /**
    * The hash (URL fragment) of the file URL, including the # symbol. If the URL doesn't have a hash, then this will be an empty string.
    */

package/lib/util/schema-resources.ts

@@ -0,0 +1,73 @@
+import * as url from "./url.js";
+import type { ParserOptions } from "../options.js";
+import type { JSONSchema } from "../index.js";
+import type $Refs from "../refs.js";
+
+export function getSchemaBasePath(basePath: string, value: unknown) {
+  const schemaId = getSchemaId(value);
+  return schemaId ? url.resolve(basePath, schemaId) : basePath;
+}
+
+export function usesDynamicIdScope(value: unknown) {
+  if (!value || typeof value !== "object" || ArrayBuffer.isView(value)) {
+    return false;
+  }
+
+  const schema = (value as { $schema?: unknown }).$schema;
+  if (
+    typeof schema === "string" &&
+    (schema.includes("draft/2019-09/") || schema.includes("draft/2020-12/") || schema.includes("oas/3.1/"))
+  ) {
+    return true;
+  }
+
+  const openapi = (value as { openapi?: unknown }).openapi;
+  return typeof openapi === "string" && /^3\.1(?:\.|$)/.test(openapi);
+}
+
+export function registerSchemaResources<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
+  $refs: $Refs<S, O>,
+  basePath: string,
+  value: unknown,
+  pathType?: string | unknown,
+  dynamicIdScope = false,
+) {
+  if (!dynamicIdScope) {
+    return;
+  }
+
+  const seen = new Set<object>();
+
+  const visit = (node: unknown, scopeBase: string) => {
+    if (!node || typeof node !== "object" || ArrayBuffer.isView(node) || seen.has(node)) {
+      return;
+    }
+
+    seen.add(node);
+
+    const nextScopeBase = getSchemaBasePath(scopeBase, node);
+    if (nextScopeBase !== scopeBase) {
+      $refs._addAlias(nextScopeBase, node as S, pathType, dynamicIdScope);
+    }
+
+    for (const key of Object.keys(node)) {
+      visit((node as Record<string, unknown>)[key], nextScopeBase);
+    }
+  };
+
+  visit(value, basePath);
+}
+
+function getSchemaId(value: unknown): string | undefined {
+  if (
+    value &&
+    typeof value === "object" &&
+    "$id" in value &&
+    typeof (value as { $id?: unknown }).$id === "string" &&
+    (value as { $id: string }).$id.length > 0
+  ) {
+    return (value as { $id: string }).$id;
+  }
+
+  return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apidevtools/json-schema-ref-parser",
-  "version": "15.3.0",
+  "version": "15.3.2",
   "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
   "type": "module",
   "types": "dist/lib/index.d.ts",
@@ -75,29 +75,29 @@
     "js-yaml": "^4.1.1"
   },
   "devDependencies": {
-    "@eslint/compat": "^2.0.2",
+    "@eslint/compat": "^2.0.3",
     "@eslint/js": "^10.0.1",
     "@types/eslint": "^9.6.1",
     "@types/js-yaml": "^4.0.9",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^25",
-    "@typescript-eslint/eslint-plugin": "^8.56.1",
-    "@typescript-eslint/parser": "^8.56.1",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
+    "@vitest/coverage-v8": "^4.1.1",
     "cross-env": "^10.1.0",
-    "eslint": "^10.0.2",
+    "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-promise": "^7.2.1",
     "eslint-plugin-unused-imports": "^4.4.1",
-    "globals": "^17.3.0",
-    "jsdom": "^28.1.0",
+    "globals": "^17.4.0",
+    "jsdom": "^29.0.1",
     "prettier": "^3.8.1",
     "rimraf": "^6.1.3",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1",
-    "vitest": "^4.0.18"
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.57.2",
+    "vitest": "^4.1.1"
   },
   "release": {
     "branches": [
@@ -110,5 +110,5 @@
       "@semantic-release/github"
     ]
   },
-  "packageManager": "yarn@4.12.0"
+  "packageManager": "yarn@4.13.0"
 }