@speclynx/apidom-reference 5.2.4 → 5.2.6

package/src/dereference/strategies/openapi-3-1/util.cjs

@@ -4,39 +4,100 @@ var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopReq
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.resolveSchema$refField = exports.resolveSchema$idField = exports.refractToSchemaElement = exports.maybeRefractToSchemaElement = void 0;
+exports.schema$idsOf = exports.resolveSchemaBaseURI = exports.resolveSchema$refField = exports.resolveSchema$ids = exports.resolveSchema$idField = exports.refractToSchemaElement = exports.maybeRefractToSchemaElement = exports.isJSONSchemaElementWith$id = exports.detachedRootSchema$ids = exports.collectSchema$ids = void 0;
 var _ramda = require("ramda");
+var _ramdaAdjunct = require("ramda-adjunct");
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomCore = require("@speclynx/apidom-core");
+var _apidomNsJsonSchema = require("@speclynx/apidom-ns-json-schema-2020-12");
 var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-3-1");
 var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 /**
+ * A schema located within a document, together with the `$id`s of the JSON Schema
+ * elements enclosing it (outermost first; the located schema's own `$id` excluded).
  * @public
  */
-const resolveSchema$refField = (retrievalURI, schemaElement) => {
-  if (typeof schemaElement.$ref === 'undefined') {
+
+/**
+ * Whether the element is a JSON Schema element declaring a `$id`.
+ */
+const isJSONSchemaElementWith$id = element => (0, _apidomNsJsonSchema.isJSONSchemaElement)(element) && (0, _apidomDatamodel.isStringElement)(element.$id);
+
+/**
+ * `$id`s declared by the JSON Schema elements among `nodes`, in order.
+ */
+exports.isJSONSchemaElementWith$id = isJSONSchemaElementWith$id;
+const schema$idsOf = nodes => nodes.filter(isJSONSchemaElementWith$id).map(node => (0, _apidomCore.toValue)(node.$id));
+
+/**
+ * `$id`s of the JSON Schema elements on `path` (outermost first, the node itself
+ * included). The `$id`s are read from the elements themselves rather than from
+ * refraction-time metadata, so a `$id` assigned after refraction (e.g. by the
+ * bundler) is honored.
+ */
+exports.schema$idsOf = schema$idsOf;
+const collectSchema$ids = path => schema$idsOf([...path.getAncestorNodes().reverse(), path.node]);
+
+/**
+ * `$id`s of the schemas enclosing a traversal root that is a fragment detached
+ * from its document, read from the `ancestorsSchemaIdentifiers` meta the JSON
+ * Schema refractors record. The meta also carries the root's own `$id`, which
+ * the ancestor walk contributes itself, so it is dropped. A detached fragment
+ * has no live ancestors, so the meta is the only carrier of its lexical
+ * context; this is the one reader of it the refractors must keep serving.
+ */
+exports.collectSchema$ids = collectSchema$ids;
+const detachedRootSchema$ids = root => {
+  const meta = root?.meta.get('ancestorsSchemaIdentifiers');
+  const $ids = Array.isArray(meta) ? meta.filter(_ramdaAdjunct.isString) : [];
+  const own$id = isJSONSchemaElementWith$id(root) ? (0, _apidomCore.toValue)(root.$id) : undefined;
+  return $ids.length > 0 && $ids.at(-1) === own$id ? $ids.slice(0, -1) : $ids;
+};
+
+/**
+ * Resolves a chain of `$id`s (outermost first) against `baseURI`, each `$id`
+ * refining the base the next one resolves against.
+ */
+exports.detachedRootSchema$ids = detachedRootSchema$ids;
+const resolveSchema$ids = (baseURI, $ids) => (0, _ramda.reduce)((acc, $id) => url.resolve(acc, url.sanitize(url.stripHash($id))), baseURI, $ids);
+
+/**
+ * Resolves the base URI of the schema at `path`: `baseURI` (the base URI in
+ * effect at the traversal root) refined by each `$id` on the schema's ancestor
+ * chain in turn, the schema's own `$id` included.
+ */
+exports.resolveSchema$ids = resolveSchema$ids;
+const resolveSchemaBaseURI = (baseURI, path) => resolveSchema$ids(baseURI, collectSchema$ids(path));
+
+/**
+ * Resolves the `$ref` of the schema against its base URI (see
+ * `resolveSchemaBaseURI`), or returns `undefined` when the schema has no string `$ref`.
+ *
+ * @public
+ */
+exports.resolveSchemaBaseURI = resolveSchemaBaseURI;
+const resolveSchema$refField = (schemaBaseURI, schemaElement) => {
+  if (!(0, _apidomDatamodel.isStringElement)(schemaElement.$ref)) {
     return undefined;
   }
-  const hash = url.getHash((0, _apidomCore.toValue)(schemaElement.$ref));
-  const ancestorsSchemaIdentifiers = schemaElement.meta.get('ancestorsSchemaIdentifiers');
-  const $refBaseURI = (0, _ramda.reduce)((acc, uri) => {
-    return url.resolve(acc, url.sanitize(url.stripHash(uri)));
-  }, retrievalURI, [...ancestorsSchemaIdentifiers, (0, _apidomCore.toValue)(schemaElement.$ref)]);
+  const $ref = (0, _apidomCore.toValue)(schemaElement.$ref);
+  const hash = url.getHash($ref);
+  const $refBaseURI = resolveSchema$ids(schemaBaseURI, [$ref]);
   return `${$refBaseURI}${hash === '#' ? '' : hash}`;
 };
 
 /**
+ * Resolves the `$id` of the schema against `baseURI`, the base URI in effect
+ * where the schema sits, or returns `undefined` when the schema declares no string `$id`.
+ *
  * @public
  */
 exports.resolveSchema$refField = resolveSchema$refField;
-const resolveSchema$idField = (retrievalURI, schemaElement) => {
-  if (typeof schemaElement.$id === 'undefined') {
+const resolveSchema$idField = (baseURI, schemaElement) => {
+  if (!(0, _apidomDatamodel.isStringElement)(schemaElement.$id)) {
     return undefined;
   }
-  const ancestorsSchemaIdentifiers = schemaElement.meta.get('ancestorsSchemaIdentifiers');
-  return (0, _ramda.reduce)((acc, $id) => {
-    return url.resolve(acc, url.sanitize(url.stripHash($id)));
-  }, retrievalURI, ancestorsSchemaIdentifiers);
+  return resolveSchema$ids(baseURI, [(0, _apidomCore.toValue)(schemaElement.$id)]);
 };
 
 /**

package/src/dereference/strategies/openapi-3-1/util.mjs

@@ -1,34 +1,88 @@
 import { reduce } from 'ramda';
-import { isPrimitiveElement } from '@speclynx/apidom-datamodel';
+import { isString } from 'ramda-adjunct';
+import { isPrimitiveElement, isStringElement } from '@speclynx/apidom-datamodel';
 import { toValue } from '@speclynx/apidom-core';
+import { isJSONSchemaElement } from '@speclynx/apidom-ns-json-schema-2020-12';
 import { refractSchema } from '@speclynx/apidom-ns-openapi-3-1';
 import * as url from "../../../util/url.mjs";
 /**
+ * A schema located within a document, together with the `$id`s of the JSON Schema
+ * elements enclosing it (outermost first; the located schema's own `$id` excluded).
  * @public
  */
-export const resolveSchema$refField = (retrievalURI, schemaElement) => {
-  if (typeof schemaElement.$ref === 'undefined') {
+/**
+ * Whether the element is a JSON Schema element declaring a `$id`.
+ */
+export const isJSONSchemaElementWith$id = element => isJSONSchemaElement(element) && isStringElement(element.$id);
+
+/**
+ * `$id`s declared by the JSON Schema elements among `nodes`, in order.
+ */
+export const schema$idsOf = nodes => nodes.filter(isJSONSchemaElementWith$id).map(node => toValue(node.$id));
+
+/**
+ * `$id`s of the JSON Schema elements on `path` (outermost first, the node itself
+ * included). The `$id`s are read from the elements themselves rather than from
+ * refraction-time metadata, so a `$id` assigned after refraction (e.g. by the
+ * bundler) is honored.
+ */
+export const collectSchema$ids = path => schema$idsOf([...path.getAncestorNodes().reverse(), path.node]);
+
+/**
+ * `$id`s of the schemas enclosing a traversal root that is a fragment detached
+ * from its document, read from the `ancestorsSchemaIdentifiers` meta the JSON
+ * Schema refractors record. The meta also carries the root's own `$id`, which
+ * the ancestor walk contributes itself, so it is dropped. A detached fragment
+ * has no live ancestors, so the meta is the only carrier of its lexical
+ * context; this is the one reader of it the refractors must keep serving.
+ */
+export const detachedRootSchema$ids = root => {
+  const meta = root?.meta.get('ancestorsSchemaIdentifiers');
+  const $ids = Array.isArray(meta) ? meta.filter(isString) : [];
+  const own$id = isJSONSchemaElementWith$id(root) ? toValue(root.$id) : undefined;
+  return $ids.length > 0 && $ids.at(-1) === own$id ? $ids.slice(0, -1) : $ids;
+};
+
+/**
+ * Resolves a chain of `$id`s (outermost first) against `baseURI`, each `$id`
+ * refining the base the next one resolves against.
+ */
+export const resolveSchema$ids = (baseURI, $ids) => reduce((acc, $id) => url.resolve(acc, url.sanitize(url.stripHash($id))), baseURI, $ids);
+
+/**
+ * Resolves the base URI of the schema at `path`: `baseURI` (the base URI in
+ * effect at the traversal root) refined by each `$id` on the schema's ancestor
+ * chain in turn, the schema's own `$id` included.
+ */
+export const resolveSchemaBaseURI = (baseURI, path) => resolveSchema$ids(baseURI, collectSchema$ids(path));
+
+/**
+ * Resolves the `$ref` of the schema against its base URI (see
+ * `resolveSchemaBaseURI`), or returns `undefined` when the schema has no string `$ref`.
+ *
+ * @public
+ */
+export const resolveSchema$refField = (schemaBaseURI, schemaElement) => {
+  if (!isStringElement(schemaElement.$ref)) {
     return undefined;
   }
-  const hash = url.getHash(toValue(schemaElement.$ref));
-  const ancestorsSchemaIdentifiers = schemaElement.meta.get('ancestorsSchemaIdentifiers');
-  const $refBaseURI = reduce((acc, uri) => {
-    return url.resolve(acc, url.sanitize(url.stripHash(uri)));
-  }, retrievalURI, [...ancestorsSchemaIdentifiers, toValue(schemaElement.$ref)]);
+  const $ref = toValue(schemaElement.$ref);
+  const hash = url.getHash($ref);
+  const $refBaseURI = resolveSchema$ids(schemaBaseURI, [$ref]);
   return `${$refBaseURI}${hash === '#' ? '' : hash}`;
 };
 
 /**
+ * Resolves the `$id` of the schema against `baseURI`, the base URI in effect
+ * where the schema sits, or returns `undefined` when the schema declares no string `$id`.
+ *
  * @public
  */
-export const resolveSchema$idField = (retrievalURI, schemaElement) => {
-  if (typeof schemaElement.$id === 'undefined') {
+export const resolveSchema$idField = (baseURI, schemaElement) => {
+  if (!isStringElement(schemaElement.$id)) {
     return undefined;
   }
-  const ancestorsSchemaIdentifiers = schemaElement.meta.get('ancestorsSchemaIdentifiers');
-  return reduce((acc, $id) => {
-    return url.resolve(acc, url.sanitize(url.stripHash($id)));
-  }, retrievalURI, ancestorsSchemaIdentifiers);
+  return resolveSchema$ids(baseURI, [toValue(schemaElement.$id)]);
 };
 
 /**

package/src/dereference/strategies/openapi-3-1/visitor.cjs

@@ -16,6 +16,7 @@ var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
 var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-3-1");
 var _$anchor = require("./selectors/$anchor.cjs");
 var _uri = require("./selectors/uri.cjs");
+var _jsonPointer = require("./selectors/json-pointer.cjs");
 var _MaximumDereferenceDepthError = _interopRequireDefault(require("../../../errors/MaximumDereferenceDepthError.cjs"));
 var _MaximumResolveDepthError = _interopRequireDefault(require("../../../errors/MaximumResolveDepthError.cjs"));
 var _UnresolvableReferenceError = _interopRequireDefault(require("../../../errors/UnresolvableReferenceError.cjs"));
@@ -38,8 +39,23 @@ class OpenAPI3_1DereferenceVisitor {
   reference;
   options;
   refractCache;
+
+  /**
+   * Index of `$id`-bearing schemas per document, shared across nested visitors
+   * of a single dereference run so it never outlives mutations of the documents.
+   */
+  schema$idIndex;
   visited;
 
+  /**
+   * `$id`s of the JSON Schema elements enclosing the traversal root within its
+   * document (outermost first). Empty when the root is the document itself; a
+   * nested visitor traversing a fragment is seeded with the `$id`s of the
+   * schemas the fragment sits under, so the `$ref`s and `$id`s within resolve
+   * against the same base as they would from the document root.
+   */
+  ancestorSchema$ids;
+
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
    * Used for cycle detection: if a referenced element is found in
@@ -51,15 +67,19 @@ class OpenAPI3_1DereferenceVisitor {
     options,
     indirections = [],
     refractCache = new WeakMap(),
+    schema$idIndex = new WeakMap(),
     ancestors = new _util2.AncestorLineage(),
-    visited = new WeakSet()
+    visited = new WeakSet(),
+    ancestorSchema$ids = []
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.refractCache = refractCache;
+    this.schema$idIndex = schema$idIndex;
     this.ancestors = new _util2.AncestorLineage(...ancestors);
     this.visited = visited;
+    this.ancestorSchema$ids = ancestorSchema$ids;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -318,6 +338,7 @@ class OpenAPI3_1DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          schema$idIndex: this.schema$idIndex,
           visited: this.visited,
           ancestors: ancestorsLineage
         });
@@ -476,6 +497,7 @@ class OpenAPI3_1DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          schema$idIndex: this.schema$idIndex,
           visited: this.visited,
           ancestors: ancestorsLineage
         });
@@ -673,7 +695,11 @@ class OpenAPI3_1DereferenceVisitor {
       let {
         uri: retrievalURI
       } = reference;
-      const $refBaseURI = (0, _util.resolveSchema$refField)(retrievalURI, referencingElement);
+      // base URI in effect at the traversal root: the document base refined by
+      // the $ids of the schemas enclosing the root when the root is a fragment
+      const rootBaseURI = (0, _util.resolveSchema$ids)(retrievalURI, this.ancestorSchema$ids);
+      const schemaBaseURI = (0, _util.resolveSchemaBaseURI)(rootBaseURI, path);
+      const $refBaseURI = (0, _util.resolveSchema$refField)(schemaBaseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new _File.default({
         uri: $refBaseURIStrippedHash
@@ -685,13 +711,48 @@ class OpenAPI3_1DereferenceVisitor {
 
       // determining reference, proper evaluation and selection mechanism
       let referencedElement;
+      // $ids of the schemas enclosing the referenced element within its document
+      let ancestorSchema$ids;
       try {
         if (isUnknownURI || isURL) {
           // we're dealing with canonical URI or URL with possible fragment
           retrievalURI = this.toBaseURI($refBaseURI);
           const selector = $refBaseURI;
-          const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(reference.value.result);
-          referencedElement = (0, _uri.evaluate)(selector, referenceAsSchema);
+          // the fragment being traversed is searched before the whole document: a
+          // fragment referenced from another document (a Response, Parameter, Path
+          // Item, ...) is refracted with its own semantics, so the Schema Objects it
+          // contains are indexed, whereas the referenced document as a whole is
+          // parsed generically and refracted as a bare JSON Schema, which leaves
+          // those Schema Objects (under `content`, `schema`, ...) unrecognized and
+          // their `$id`s out of the index
+          const documentElement = reference.value.result;
+          const rootNode = path.getAncestorNodes().at(-1) ?? path.node;
+          const fragmentElement = (0, _apidomDatamodel.isParseResultElement)(rootNode) ? rootNode.result : rootNode;
+          try {
+            // the fragment's $ids resolve against the base its enclosing chain
+            // leaves in effect, which then also prefixes the located schema's chain
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = (0, _uri.locate)(selector, (0, _util.maybeRefractToSchemaElement)(fragmentElement), {
+              baseURI: rootBaseURI,
+              index: this.schema$idIndex
+            }));
+            ancestorSchema$ids = [...this.ancestorSchema$ids, ...ancestorSchema$ids];
+          } catch (error) {
+            if (!(error instanceof _EvaluationJsonSchemaUriError.default) || fragmentElement === documentElement) {
+              throw error;
+            }
+            // the document index is rooted at the document, so the located chain
+            // is already document-relative and takes no prefix
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = (0, _uri.locate)(selector, (0, _util.maybeRefractToSchemaElement)(documentElement), {
+              baseURI: reference.uri,
+              index: this.schema$idIndex
+            }));
+          }
           referencedElement = (0, _util.maybeRefractToSchemaElement)(referencedElement);
 
           // ignore resolving internal Schema Objects
@@ -723,7 +784,10 @@ class OpenAPI3_1DereferenceVisitor {
           reference = await this.toReference(url.unsanitize($refBaseURI));
           const selector = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
           const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(reference.value.result);
-          referencedElement = (0, _apidomJsonPointer.evaluate)(referenceAsSchema, selector);
+          ({
+            element: referencedElement,
+            ancestorSchema$ids
+          } = (0, _jsonPointer.locate)(referenceAsSchema, selector));
           referencedElement = (0, _util.maybeRefractToSchemaElement)(referencedElement);
         }
       } catch (error) {
@@ -750,7 +814,10 @@ class OpenAPI3_1DereferenceVisitor {
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = (0, _$anchor.uriToAnchor)($refBaseURI);
             const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(reference.value.result);
-            referencedElement = (0, _$anchor.evaluate)(selector, referenceAsSchema);
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = (0, _$anchor.locate)(selector, referenceAsSchema));
             referencedElement = (0, _util.maybeRefractToSchemaElement)(referencedElement);
           } else {
             // we're assuming here that we're dealing with JSON Pointer here
@@ -771,7 +838,10 @@ class OpenAPI3_1DereferenceVisitor {
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
             const referenceAsSchema = (0, _util.maybeRefractToSchemaElement)(reference.value.result);
-            referencedElement = (0, _apidomJsonPointer.evaluate)(referenceAsSchema, selector);
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = (0, _jsonPointer.locate)(referenceAsSchema, selector));
             referencedElement = (0, _util.maybeRefractToSchemaElement)(referencedElement);
           }
         } else {
@@ -828,7 +898,11 @@ class OpenAPI3_1DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || (0, _apidomNsOpenapi.isSchemaElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+      // content transplanted into the referencing site is traversed under that
+      // site's $id chain; a fragment enclosed by a different chain has its own
+      // $refs resolved in place first, by a nested visitor seeded with that chain
+      const hasDifferentEnclosingBase = (0, _util.resolveSchema$ids)(reference.uri, ancestorSchema$ids) !== (0, _util.resolveSchema$ids)(rootBaseURI, (0, _util.schema$idsOf)(path.getAncestorNodes().reverse()));
+      if ((isExternalReference || isNonEntryDocument || hasDifferentEnclosingBase || (0, _apidomNsOpenapi.isSchemaElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
         if (shouldDetectCircular) {
           this.visited.add(referencedElement);
         }
@@ -838,8 +912,10 @@ class OpenAPI3_1DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          schema$idIndex: this.schema$idIndex,
           visited: this.visited,
-          ancestors: ancestorsLineage
+          ancestors: ancestorsLineage,
+          ancestorSchema$ids
         });
         referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
           mutable: true,

package/src/dereference/strategies/openapi-3-1/visitor.mjs

@@ -1,13 +1,14 @@
 import { propEq, none } from 'ramda';
 import { isUndefined } from 'ramda-adjunct';
-import { isElement, isStringElement, isObjectElement, RefElement, cloneShallow, cloneDeep } from '@speclynx/apidom-datamodel';
+import { isElement, isStringElement, isObjectElement, isParseResultElement, RefElement, cloneShallow, cloneDeep } from '@speclynx/apidom-datamodel';
 import { toValue, fixedFields, toYAML } from '@speclynx/apidom-core';
 import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 import { traverse, traverseAsync, find } from '@speclynx/apidom-traverse';
 import { evaluate as jsonPointerEvaluate, URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
 import { isReferenceLikeElement, isPathItemElement, isReferenceElement, isSchemaElement, isOperationElement, isBooleanJSONSchemaElement, refract, refractReference, refractPathItem, refractOperation } from '@speclynx/apidom-ns-openapi-3-1';
-import { isAnchor, uriToAnchor, evaluate as $anchorEvaluate } from "./selectors/$anchor.mjs";
-import { evaluate as uriEvaluate } from "./selectors/uri.mjs";
+import { isAnchor, uriToAnchor, locate as $anchorLocate } from "./selectors/$anchor.mjs";
+import { locate as uriLocate } from "./selectors/uri.mjs";
+import { locate as jsonPointerLocate } from "./selectors/json-pointer.mjs";
 import MaximumDereferenceDepthError from "../../../errors/MaximumDereferenceDepthError.mjs";
 import MaximumResolveDepthError from "../../../errors/MaximumResolveDepthError.mjs";
 import UnresolvableReferenceError from "../../../errors/UnresolvableReferenceError.mjs";
@@ -16,7 +17,7 @@ import * as url from "../../../util/url.mjs";
 import parse from "../../../parse/index.mjs";
 import Reference from "../../../Reference.mjs";
 import File from "../../../File.mjs";
-import { resolveSchema$refField, maybeRefractToSchemaElement } from "./util.mjs";
+import { schema$idsOf, resolveSchema$ids, resolveSchemaBaseURI, resolveSchema$refField, maybeRefractToSchemaElement } from "./util.mjs";
 import { AncestorLineage } from "../../util.mjs";
 /**
  * @public
@@ -29,8 +30,23 @@ class OpenAPI3_1DereferenceVisitor {
   reference;
   options;
   refractCache;
+
+  /**
+   * Index of `$id`-bearing schemas per document, shared across nested visitors
+   * of a single dereference run so it never outlives mutations of the documents.
+   */
+  schema$idIndex;
   visited;
 
+  /**
+   * `$id`s of the JSON Schema elements enclosing the traversal root within its
+   * document (outermost first). Empty when the root is the document itself; a
+   * nested visitor traversing a fragment is seeded with the `$id`s of the
+   * schemas the fragment sits under, so the `$ref`s and `$id`s within resolve
+   * against the same base as they would from the document root.
+   */
+  ancestorSchema$ids;
+
   /**
    * Tracks element ancestors across dive-deep traversal boundaries.
    * Used for cycle detection: if a referenced element is found in
@@ -42,15 +58,19 @@ class OpenAPI3_1DereferenceVisitor {
     options,
     indirections = [],
     refractCache = new WeakMap(),
+    schema$idIndex = new WeakMap(),
     ancestors = new AncestorLineage(),
-    visited = new WeakSet()
+    visited = new WeakSet(),
+    ancestorSchema$ids = []
   }) {
     this.indirections = indirections;
     this.reference = reference;
     this.options = options;
     this.refractCache = refractCache;
+    this.schema$idIndex = schema$idIndex;
     this.ancestors = new AncestorLineage(...ancestors);
     this.visited = visited;
+    this.ancestorSchema$ids = ancestorSchema$ids;
   }
   toAncestorLineage(path) {
     const ancestorNodes = path.getAncestorNodes();
@@ -309,6 +329,7 @@ class OpenAPI3_1DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          schema$idIndex: this.schema$idIndex,
           visited: this.visited,
           ancestors: ancestorsLineage
         });
@@ -467,6 +488,7 @@ class OpenAPI3_1DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          schema$idIndex: this.schema$idIndex,
           visited: this.visited,
           ancestors: ancestorsLineage
         });
@@ -664,7 +686,11 @@ class OpenAPI3_1DereferenceVisitor {
       let {
         uri: retrievalURI
       } = reference;
-      const $refBaseURI = resolveSchema$refField(retrievalURI, referencingElement);
+      // base URI in effect at the traversal root: the document base refined by
+      // the $ids of the schemas enclosing the root when the root is a fragment
+      const rootBaseURI = resolveSchema$ids(retrievalURI, this.ancestorSchema$ids);
+      const schemaBaseURI = resolveSchemaBaseURI(rootBaseURI, path);
+      const $refBaseURI = resolveSchema$refField(schemaBaseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new File({
         uri: $refBaseURIStrippedHash
@@ -676,13 +702,48 @@ class OpenAPI3_1DereferenceVisitor {
 
       // determining reference, proper evaluation and selection mechanism
       let referencedElement;
+      // $ids of the schemas enclosing the referenced element within its document
+      let ancestorSchema$ids;
       try {
         if (isUnknownURI || isURL) {
           // we're dealing with canonical URI or URL with possible fragment
           retrievalURI = this.toBaseURI($refBaseURI);
           const selector = $refBaseURI;
-          const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
-          referencedElement = uriEvaluate(selector, referenceAsSchema);
+          // the fragment being traversed is searched before the whole document: a
+          // fragment referenced from another document (a Response, Parameter, Path
+          // Item, ...) is refracted with its own semantics, so the Schema Objects it
+          // contains are indexed, whereas the referenced document as a whole is
+          // parsed generically and refracted as a bare JSON Schema, which leaves
+          // those Schema Objects (under `content`, `schema`, ...) unrecognized and
+          // their `$id`s out of the index
+          const documentElement = reference.value.result;
+          const rootNode = path.getAncestorNodes().at(-1) ?? path.node;
+          const fragmentElement = isParseResultElement(rootNode) ? rootNode.result : rootNode;
+          try {
+            // the fragment's $ids resolve against the base its enclosing chain
+            // leaves in effect, which then also prefixes the located schema's chain
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = uriLocate(selector, maybeRefractToSchemaElement(fragmentElement), {
+              baseURI: rootBaseURI,
+              index: this.schema$idIndex
+            }));
+            ancestorSchema$ids = [...this.ancestorSchema$ids, ...ancestorSchema$ids];
+          } catch (error) {
+            if (!(error instanceof EvaluationJsonSchemaUriError) || fragmentElement === documentElement) {
+              throw error;
+            }
+            // the document index is rooted at the document, so the located chain
+            // is already document-relative and takes no prefix
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = uriLocate(selector, maybeRefractToSchemaElement(documentElement), {
+              baseURI: reference.uri,
+              index: this.schema$idIndex
+            }));
+          }
           referencedElement = maybeRefractToSchemaElement(referencedElement);
 
           // ignore resolving internal Schema Objects
@@ -714,7 +775,10 @@ class OpenAPI3_1DereferenceVisitor {
           reference = await this.toReference(url.unsanitize($refBaseURI));
           const selector = URIFragmentIdentifier.fromURIReference($refBaseURI);
           const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
-          referencedElement = jsonPointerEvaluate(referenceAsSchema, selector);
+          ({
+            element: referencedElement,
+            ancestorSchema$ids
+          } = jsonPointerLocate(referenceAsSchema, selector));
           referencedElement = maybeRefractToSchemaElement(referencedElement);
         }
       } catch (error) {
@@ -741,7 +805,10 @@ class OpenAPI3_1DereferenceVisitor {
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = uriToAnchor($refBaseURI);
             const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
-            referencedElement = $anchorEvaluate(selector, referenceAsSchema);
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = $anchorLocate(selector, referenceAsSchema));
             referencedElement = maybeRefractToSchemaElement(referencedElement);
           } else {
             // we're assuming here that we're dealing with JSON Pointer here
@@ -762,7 +829,10 @@ class OpenAPI3_1DereferenceVisitor {
             reference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = URIFragmentIdentifier.fromURIReference($refBaseURI);
             const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
-            referencedElement = jsonPointerEvaluate(referenceAsSchema, selector);
+            ({
+              element: referencedElement,
+              ancestorSchema$ids
+            } = jsonPointerLocate(referenceAsSchema, selector));
             referencedElement = maybeRefractToSchemaElement(referencedElement);
           }
         } else {
@@ -819,7 +889,11 @@ class OpenAPI3_1DereferenceVisitor {
        */
       const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
       const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-      if ((isExternalReference || isNonEntryDocument || isSchemaElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
+      // content transplanted into the referencing site is traversed under that
+      // site's $id chain; a fragment enclosed by a different chain has its own
+      // $refs resolved in place first, by a nested visitor seeded with that chain
+      const hasDifferentEnclosingBase = resolveSchema$ids(reference.uri, ancestorSchema$ids) !== resolveSchema$ids(rootBaseURI, schema$idsOf(path.getAncestorNodes().reverse()));
+      if ((isExternalReference || isNonEntryDocument || hasDifferentEnclosingBase || isSchemaElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular && !this.visited.has(referencedElement)) && !ancestorsLineage.includesCycle(referencedElement)) {
         if (shouldDetectCircular) {
           this.visited.add(referencedElement);
         }
@@ -829,8 +903,10 @@ class OpenAPI3_1DereferenceVisitor {
           indirections: [...this.indirections],
           options: this.options,
           refractCache: this.refractCache,
+          schema$idIndex: this.schema$idIndex,
           visited: this.visited,
-          ancestors: ancestorsLineage
+          ancestors: ancestorsLineage,
+          ancestorSchema$ids
         });
         referencedElement = await traverseAsync(referencedElement, visitor, {
           mutable: true,