@apidevtools/json-schema-ref-parser 15.3.1 → 15.3.3

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.
    */
@@ -194,11 +199,18 @@ class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOpt
    * @param options
    * @returns
    */
-  static isAllowed$Ref<S extends object = JSONSchema>(value: unknown, options?: ParserOptions<S>) {
+  static isAllowed$Ref<S extends object = JSONSchema>(
+    value: unknown,
+    options?: ParserOptions<S>,
+    allowPlainNameFragments = false,
+  ) {
     if (this.is$Ref(value)) {
       if (value.$ref.substring(0, 2) === "#/" || value.$ref === "#") {
         // It's a JSON Pointer reference, which is always allowed
         return true;
+      } else if (allowPlainNameFragments && value.$ref[0] === "#") {
+        // JSON Schema 2019-09+ allows plain-name fragments declared via $anchor/$dynamicAnchor
+        return true;
       } else if (value.$ref[0] !== "#" && (!options || options.resolve?.external)) {
         // It's an external reference, which is allowed by the options
         return true;
@@ -281,7 +293,12 @@ class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOpt
     $ref: $Ref<S, O>,
     resolvedValue: S,
     options?: O,
+    useSpecCompliantRefSiblings = false,
   ): S {
+    if ($Ref.isExtended$Ref($ref) && useSpecCompliantRefSiblings) {
+      return preserveRefSiblings($ref, resolvedValue) as S;
+    }
+
     if (resolvedValue && typeof resolvedValue === "object" && $Ref.isExtended$Ref($ref)) {
       const merged = {} as Partial<S>;
       for (const key of Object.keys($ref)) {
@@ -320,6 +337,27 @@ class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOpt
   }
 }
 
+function preserveRefSiblings<T>(refValue: Record<string, any>, resolvedValue: T): T {
+  const preserved = {} as Record<string, any>;
+  const existingAllOf = "allOf" in refValue ? refValue.allOf : undefined;
+
+  for (const key of Object.keys(refValue)) {
+    if (key !== "$ref" && key !== "allOf") {
+      preserved[key] = refValue[key];
+    }
+  }
+
+  const allOf = [resolvedValue];
+  if (Array.isArray(existingAllOf)) {
+    allOf.push(...existingAllOf);
+  } else if (existingAllOf !== undefined) {
+    allOf.push(existingAllOf);
+  }
+
+  preserved.allOf = allOf;
+  return preserved as T;
+}
+
 function deepMerge<T>(target: Partial<T>, source: Partial<T>): T {
   //return {...target, ...source};
 

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(this._exactAliases[path] || path);
   }
 
   /**
@@ -134,6 +132,32 @@ 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;
+  }
+
+  _addExactAlias(path: string, targetPath: string) {
+    if (!path || this._exactAliases[path]) {
+      return this._exactAliases[path];
+    }
+
+    this._exactAliases[path] = targetPath;
+    return targetPath;
+  }
+
   /**
    * Resolves the given JSON reference.
    *
@@ -145,14 +169,14 @@ 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 canonicalPath = this._exactAliases[absPath] || absPath;
+    const $ref = this._getRef(canonicalPath);
 
     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);
+    return $ref.resolve(canonicalPath, options, path, pathFromRoot);
   }
 
   /**
@@ -163,6 +187,10 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
    */
   _$refs: $RefsMap<S, O> = {};
 
+  _aliases: $RefsMap<S, O> = {};
+
+  _exactAliases: Record<string, string> = {};
+
   /**
    * The {@link $Ref} object that is the root of the JSON schema.
    *
@@ -180,6 +208,8 @@ export default class $Refs<S extends object = JSONSchema, O extends ParserOption
     this.circular = false;
 
     this._$refs = {};
+    this._aliases = {};
+    this._exactAliases = {};
 
     // @ts-ignore
     this._root$Ref = null;
@@ -205,6 +235,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,109 @@
+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, pointerTokens: string[]) => {
+    if (!node || typeof node !== "object" || ArrayBuffer.isView(node) || seen.has(node)) {
+      return;
+    }
+
+    seen.add(node);
+
+    const nextScopeBase = getSchemaBasePath(scopeBase, node);
+    const resourcePointerTokens = nextScopeBase === scopeBase ? pointerTokens : [];
+    if (nextScopeBase !== scopeBase) {
+      $refs._addAlias(nextScopeBase, node as S, pathType, dynamicIdScope);
+    }
+    registerAnchorAliases($refs, nextScopeBase, resourcePointerTokens, node);
+
+    for (const key of Object.keys(node)) {
+      visit((node as Record<string, unknown>)[key], nextScopeBase, [...resourcePointerTokens, key]);
+    }
+  };
+
+  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;
+}
+
+function registerAnchorAliases<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
+  $refs: $Refs<S, O>,
+  scopeBase: string,
+  pointerTokens: string[],
+  value: unknown,
+) {
+  if (!value || typeof value !== "object" || ArrayBuffer.isView(value)) {
+    return;
+  }
+
+  const resourceBase = url.stripHash(scopeBase);
+  const targetPath = pointerTokens.length > 0 ? joinPointerPath(resourceBase, pointerTokens) : `${resourceBase}#`;
+  const anchors = [
+    (value as { $anchor?: unknown }).$anchor,
+    (value as { $dynamicAnchor?: unknown }).$dynamicAnchor,
+  ];
+
+  for (const anchor of anchors) {
+    if (typeof anchor === "string" && anchor.length > 0) {
+      $refs._addExactAlias(`${resourceBase}#${anchor}`, targetPath);
+    }
+  }
+}
+
+function joinPointerPath(basePath: string, tokens: string[]) {
+  let path = `${basePath}#`;
+
+  for (const token of tokens) {
+    path += `/${token.replace(/~/g, "~0").replace(/\//g, "~1")}`;
+  }
+
+  return path;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apidevtools/json-schema-ref-parser",
-  "version": "15.3.1",
+  "version": "15.3.3",
   "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"
 }