@speclynx/apidom-reference 5.2.4 → 5.2.5

package/src/dereference/strategies/openapi-3-1/selectors/uri.mjs

@@ -1,42 +1,66 @@
 import { isUndefined } from 'ramda-adjunct';
 import { filter } from '@speclynx/apidom-traverse';
-import { isJSONSchemaElement } from '@speclynx/apidom-ns-json-schema-2020-12';
-import { URIFragmentIdentifier, evaluate as jsonPointerEvaluate } from '@speclynx/apidom-json-pointer';
+import { URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
 import * as url from "../../../../util/url.mjs";
 import EvaluationJsonSchemaUriError from "../../../../errors/EvaluationJsonSchemaUriError.mjs";
-import { isAnchor, uriToAnchor, evaluate as $anchorEvaluate } from "./$anchor.mjs";
-import { resolveSchema$idField } from "../util.mjs";
+import { isJSONSchemaElementWith$id, collectSchema$ids, resolveSchema$ids } from "../util.mjs";
+import { isAnchor, uriToAnchor, locate as $anchorLocate } from "./$anchor.mjs";
+import { locate as jsonPointerLocate } from "./json-pointer.mjs";
 /**
- * Evaluates JSON Schema $ref containing unknown URI against ApiDOM fragment.
+ * Index of `$id`-bearing schemas per indexed element (a document root, or the
+ * fragment a visitor traverses). Each entry pairs a schema with the `$id`s of its
+ * enclosing schema resources (outermost first, including its own). The index is
+ * populated once per element and never refreshed, so callers scope it
+ * to a single dereference/bundle run instead of sharing it globally. Within a run the
+ * `$id` graph of an indexed document is stable: the bundle strategies mutate deep
+ * clones and place components only after the entry traversal ends, and the
+ * dereference strategies only replace `$ref`-bearing schemas.
  * @public
  */
-export const evaluate = (uri, element) => {
-  const {
-    cache
-  } = evaluate;
-  const uriStrippedHash = url.stripHash(uri);
-  const isJSONSchemaElementWith$id = path => isJSONSchemaElement(path.node) && typeof path.node.$id !== 'undefined';
+/**
+ * @public
+ */
+const indexSchema$ids = element => filter(element, path => isJSONSchemaElementWith$id(path.node)).map(path => ({
+  schema: path.node,
+  $ids: collectSchema$ids(path)
+}));
 
-  // warm the cache
-  if (!cache.has(element)) {
-    const schemaObjectPaths = filter(element, isJSONSchemaElementWith$id);
-    cache.set(element, schemaObjectPaths.map(path => path.node));
+/**
+ * Locates the schema addressed by JSON Schema $ref containing unknown URI within
+ * ApiDOM fragment, along with the `$id`s of the schemas enclosing it.
+ * @public
+ */
+export const locate = (uri, element, options = {}) => {
+  const uriStrippedHash = url.stripHash(uri);
+  const {
+    baseURI = uriStrippedHash,
+    index = new WeakMap()
+  } = options;
+  if (!index.has(element)) {
+    index.set(element, indexSchema$ids(element));
   }
 
-  // search for the matching schema
-  const result = cache.get(element).find(e => {
-    const $idBaseURI = resolveSchema$idField(uriStrippedHash, e);
-    return $idBaseURI === uriStrippedHash;
-  });
-  if (isUndefined(result)) {
+  // search for the schema whose canonical URI matches
+  const entry = index.get(element).find(({
+    $ids
+  }) => resolveSchema$ids(baseURI, $ids) === uriStrippedHash);
+  if (isUndefined(entry)) {
     throw new EvaluationJsonSchemaUriError(`Evaluation failed on URI: "${uri}"`);
   }
-  if (isAnchor(uriToAnchor(uri))) {
-    // we're dealing with JSON Schema $anchor here
-    return $anchorEvaluate(uriToAnchor(uri), result);
-  }
-  return jsonPointerEvaluate(result, URIFragmentIdentifier.fromURIReference(uri));
+
+  // the fragment is resolved within the matched schema, whose own $id is the
+  // last of its chain; the fragment walk contributes it again when descending
+  const fragmentLocation = isAnchor(uriToAnchor(uri)) ? $anchorLocate(uriToAnchor(uri), entry.schema) : jsonPointerLocate(entry.schema, URIFragmentIdentifier.fromURIReference(uri));
+  return {
+    element: fragmentLocation.element,
+    ancestorSchema$ids: [...entry.$ids.slice(0, -1), ...fragmentLocation.ancestorSchema$ids]
+  };
 };
-evaluate.cache = new WeakMap();
+
+/**
+ * Evaluates JSON Schema $ref containing unknown URI against ApiDOM fragment.
+ * @public
+ */
+export const evaluate = (uri, element, options = {}) => locate(uri, element, options).element;
 export { EvaluationJsonSchemaUriError };
 export { default as JsonSchemaUriError } from "../../../../errors/JsonSchemaUriError.mjs";

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,