@speclynx/apidom-reference 3.0.0 → 3.1.0

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

@@ -1,53 +1,59 @@
 import { propEq, none } from 'ramda';
 import { isUndefined } from 'ramda-adjunct';
-import { isElement, isPrimitiveElement, isStringElement, isObjectElement, RefElement, cloneShallow, cloneDeep } from '@speclynx/apidom-datamodel';
-import { IdentityManager, toValue, fixedFields } from '@speclynx/apidom-core';
-import { ApiDOMError } from '@speclynx/apidom-error';
-import { traverseAsync, find } from '@speclynx/apidom-traverse';
+import { isElement, isStringElement, isObjectElement, 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 MaximumDereferenceDepthError from "../../../errors/MaximumDereferenceDepthError.mjs";
 import MaximumResolveDepthError from "../../../errors/MaximumResolveDepthError.mjs";
+import UnresolvableReferenceError from "../../../errors/UnresolvableReferenceError.mjs";
+import EvaluationJsonSchemaUriError from "../../../errors/EvaluationJsonSchemaUriError.mjs";
 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 { AncestorLineage } from "../../util.mjs";
-import EvaluationJsonSchemaUriError from "../../../errors/EvaluationJsonSchemaUriError.mjs";
-// initialize element identity manager
-const identityManager = new IdentityManager();
-
 /**
  * @public
  */
-
 /**
  * @public
  */
 class OpenAPI3_1DereferenceVisitor {
   indirections;
-  namespace;
   reference;
   options;
-  ancestors;
   refractCache;
+
+  /**
+   * Tracks element ancestors across dive-deep traversal boundaries.
+   * Used for cycle detection: if a referenced element is found in
+   * the ancestor lineage, a circular reference is detected.
+   */
+  ancestors;
   constructor({
     reference,
-    namespace,
     options,
     indirections = [],
-    ancestors = new AncestorLineage(),
-    refractCache = new Map()
+    refractCache = new WeakMap(),
+    ancestors = new AncestorLineage()
   }) {
     this.indirections = indirections;
-    this.namespace = namespace;
     this.reference = reference;
     this.options = options;
-    this.ancestors = new AncestorLineage(...ancestors);
     this.refractCache = refractCache;
+    this.ancestors = new AncestorLineage(...ancestors);
+  }
+  toAncestorLineage(path) {
+    const ancestorNodes = path.getAncestorNodes();
+    const directAncestors = new Set(ancestorNodes.filter(isElement));
+    const ancestorsLineage = new AncestorLineage(...this.ancestors, directAncestors);
+    return [ancestorsLineage, directAncestors];
   }
   toBaseURI(uri) {
     return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
@@ -55,7 +61,10 @@ class OpenAPI3_1DereferenceVisitor {
   async toReference(uri) {
     // detect maximum depth of resolution
     if (this.reference.depth >= this.options.resolve.maxDepth) {
-      throw new MaximumResolveDepthError(`Maximum resolution depth of ${this.options.resolve.maxDepth} has been exceeded by file "${this.reference.uri}"`);
+      throw new MaximumResolveDepthError(`Maximum resolution depth of ${this.options.resolve.maxDepth} has been exceeded by file "${this.reference.uri}"`, {
+        maxDepth: this.options.resolve.maxDepth,
+        uri: this.reference.uri
+      });
     }
     const baseURI = this.toBaseURI(uri);
     const {
@@ -75,14 +84,28 @@ class OpenAPI3_1DereferenceVisitor {
     });
 
     // register new mutable reference with a refSet
+    //
+    // NOTE(known limitation): the mutable reference is mutated in place during traversal
+    // (via `{ mutable: true }`). When an external document evaluates a JSON pointer back
+    // into this document, it may receive an already-resolved element instead of the original
+    // $ref. That resolved element was produced using the entry document's resolution context
+    // (ancestors, indirections), which may differ from the external document's context.
+    // This can affect cycle detection in rare cross-document circular reference patterns.
+    //
+    // Remediation: evaluate JSON pointers against the immutable (original) parse tree
+    // instead of the mutable working copy. The `immutable://` reference below preserves
+    // the original tree and could be used for pointer evaluation, ensuring every resolution
+    // context always sees raw, unresolved elements and processes them with its own
+    // ancestors/indirections. The trade-off is that elements referenced by multiple
+    // documents would be resolved once per context instead of being reused.
     const mutableReference = new Reference({
       uri: baseURI,
-      value: cloneDeep(parseResult),
+      value: this.options.dereference.immutable ? cloneDeep(parseResult) : parseResult,
       depth: this.reference.depth + 1
     });
     refSet.add(mutableReference);
     if (this.options.dereference.immutable) {
-      // register new immutable reference with a refSet
+      // register new immutable reference with original parseResult
       const immutableReference = new Reference({
         uri: `immutable://${baseURI}`,
         value: parseResult,
@@ -92,25 +115,86 @@ class OpenAPI3_1DereferenceVisitor {
     }
     return mutableReference;
   }
-  toAncestorLineage(path) {
-    /**
-     * Compute full ancestors lineage.
-     * Ancestors are flatten to unwrap all Element instances.
-     */
-    const ancestorNodes = path.getAncestorNodes();
-    const directAncestors = new Set(ancestorNodes.filter(isElement));
-    const ancestorsLineage = new AncestorLineage(...this.ancestors, directAncestors);
-    return [ancestorsLineage, directAncestors];
+
+  /**
+   * Handles an error according to the continueOnError option.
+   *
+   * For new errors: wraps in UnresolvableReferenceError with structured context
+   * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
+   * For errors already wrapped by a nested visitor: prepends the current hop to the trace.
+   *
+   * Inner/intermediate visitors always throw to let the trace accumulate.
+   * Only the entry document visitor respects continueOnError (callback/swallow/throw).
+   */
+  handleError(message, error, referencingElement, refFieldName, refFieldValue, visitorPath) {
+    const {
+      continueOnError
+    } = this.options.dereference;
+    const isEntryDocument = url.stripHash(this.reference.refSet?.rootRef?.uri ?? '') === this.reference.uri;
+    const uri = this.reference.uri;
+    const type = referencingElement.element;
+    const codeFrame = toYAML(referencingElement);
+
+    // find element location: tree search for entry documents, visitor path for external
+    let location;
+    traverse(this.reference.value.result, {
+      enter: p => {
+        if (p.node === referencingElement || this.refractCache.get(p.node) === referencingElement) {
+          location = p.formatPath();
+          p.stop();
+        }
+      }
+    });
+    location ??= visitorPath.formatPath();
+    const hop = {
+      uri,
+      type,
+      refFieldName,
+      refFieldValue,
+      location,
+      codeFrame
+    };
+
+    // enrich existing error from nested visitor or create new one
+    let unresolvedError;
+    if (error instanceof UnresolvableReferenceError) {
+      // prefix relative locations for entries belonging to the referenced document
+      const refBaseURI = this.toBaseURI(refFieldValue);
+      const fragment = URIFragmentIdentifier.fromURIReference(refFieldValue);
+      if (fragment) {
+        if (refBaseURI === error.uri && error.location) {
+          error.location = fragment + error.location;
+        }
+        for (const h of error.trace) {
+          if (h.uri === refBaseURI && h.location) h.location = fragment + h.location;
+        }
+      }
+      // @ts-ignore
+      error.trace = [hop, ...error.trace];
+      unresolvedError = error;
+    } else {
+      unresolvedError = new UnresolvableReferenceError(message, {
+        cause: error,
+        type,
+        uri,
+        location,
+        codeFrame,
+        refFieldName,
+        refFieldValue,
+        trace: []
+      });
+    }
+    if (!isEntryDocument || continueOnError === false) throw unresolvedError;
+    if (typeof continueOnError === 'function') continueOnError(unresolvedError);
   }
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
-    // skip current referencing element as it's already been access
+    // skip current referencing element as it's already been accessed
     if (this.indirections.includes(referencingElement)) {
       path.skip();
       return;
     }
-    const [ancestorsLineage, directAncestors] = this.toAncestorLineage(path);
     const retrievalURI = this.toBaseURI(toValue(referencingElement.$ref));
     const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
     const isExternalReference = !isInternalReference;
@@ -127,133 +211,140 @@ class OpenAPI3_1DereferenceVisitor {
       path.skip();
       return;
     }
-    const reference = await this.toReference(toValue(referencingElement.$ref));
     const $refBaseURI = url.resolve(retrievalURI, toValue(referencingElement.$ref));
-    this.indirections.push(referencingElement);
-    const jsonPointer = URIFragmentIdentifier.fromURIReference($refBaseURI);
+    const indirectionsSize = this.indirections.length;
+    try {
+      const reference = await this.toReference(toValue(referencingElement.$ref));
+      this.indirections.push(referencingElement);
+      const jsonPointer = URIFragmentIdentifier.fromURIReference($refBaseURI);
 
-    // possibly non-semantic fragment
-    let referencedElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
-    referencedElement.id = identityManager.identify(referencedElement);
+      // possibly non-semantic fragment
+      let referencedElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
 
-    // applying semantics to a fragment
-    if (isPrimitiveElement(referencedElement)) {
+      // applying semantics to a fragment
       const referencedElementType = referencingElement.meta.get('referenced-element');
-      const cacheKey = `${referencedElementType}-${identityManager.identify(referencedElement)}`;
-      if (this.refractCache.has(cacheKey)) {
-        referencedElement = this.refractCache.get(cacheKey);
-      } else if (isReferenceLikeElement(referencedElement)) {
-        // handling indirect references
-        referencedElement = refractReference(referencedElement);
-        referencedElement.meta.set('referenced-element', referencedElementType);
-        this.refractCache.set(cacheKey, referencedElement);
-      } else {
-        // handling direct references
-        referencedElement = refract(referencedElement, {
-          element: referencedElementType
+      if (referencedElement.element !== referencedElementType && !isReferenceElement(referencedElement)) {
+        if (this.refractCache.has(referencedElement)) {
+          referencedElement = this.refractCache.get(referencedElement);
+        } else if (isReferenceLikeElement(referencedElement)) {
+          // handling generic indirect references
+          const sourceElement = referencedElement;
+          referencedElement = refractReference(referencedElement);
+          referencedElement.meta.set('referenced-element', referencedElementType);
+          this.refractCache.set(sourceElement, referencedElement);
+        } else {
+          // handling direct references
+          const sourceElement = referencedElement;
+          referencedElement = refract(referencedElement, {
+            element: referencedElementType
+          });
+          this.refractCache.set(sourceElement, referencedElement);
+        }
+      }
+
+      // detect direct or indirect reference
+      if (referencingElement === referencedElement) {
+        throw new ApiDOMStructuredError('Recursive Reference Object detected', {
+          $ref: toValue(referencingElement.$ref)
         });
-        this.refractCache.set(cacheKey, referencedElement);
       }
-    }
 
-    // detect direct or indirect reference
-    if (referencingElement === referencedElement) {
-      throw new ApiDOMError('Recursive Reference Object detected');
-    }
+      // detect maximum depth of dereferencing
+      if (this.indirections.length > this.options.dereference.maxDepth) {
+        throw new MaximumDereferenceDepthError(`Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
+          maxDepth: this.options.dereference.maxDepth,
+          uri: this.reference.uri
+        });
+      }
 
-    // detect maximum depth of dereferencing
-    if (this.indirections.length > this.options.dereference.maxDepth) {
-      throw new MaximumDereferenceDepthError(`Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`);
-    }
+      // detect cross-boundary cycle
+      const [ancestorsLineage, directAncestors] = this.toAncestorLineage(path);
+      if (ancestorsLineage.includes(referencedElement)) {
+        reference.refSet.circular = true;
+        if (this.options.dereference.circular === 'error') {
+          throw new ApiDOMStructuredError('Circular reference detected', {
+            $ref: toValue(referencingElement.$ref)
+          });
+        } else if (this.options.dereference.circular === 'replace') {
+          const refElement = new RefElement($refBaseURI, {
+            type: referencingElement.element,
+            uri: reference.uri,
+            $ref: toValue(referencingElement.$ref)
+          });
+          const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
+          const replacement = replacer(refElement);
+          path.replaceWith(replacement);
+          return;
+        }
+      }
 
-    // detect second deep dive into the same fragment and avoid it
-    if (ancestorsLineage.includes(referencedElement)) {
-      reference.refSet.circular = true;
-      if (this.options.dereference.circular === 'error') {
-        throw new ApiDOMError('Circular reference detected');
-      } else if (this.options.dereference.circular === 'replace') {
-        const refElement = new RefElement(referencedElement.id, {
-          type: 'reference',
-          uri: reference.uri,
-          $ref: toValue(referencingElement.$ref)
+      /**
+       * Dive deep into the fragment.
+       *
+       * Cases to consider:
+       *  1. We're crossing document boundary
+       *  2. Fragment is from non-entry document
+       *  3. Fragment is a Reference Object. We need to follow it to get the eventual value
+       *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
+       */
+      const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
+      const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
+      if ((isExternalReference || isNonEntryDocument || isReferenceElement(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+        directAncestors.add(referencingElement);
+        const visitor = new OpenAPI3_1DereferenceVisitor({
+          reference,
+          indirections: [...this.indirections],
+          options: this.options,
+          refractCache: this.refractCache,
+          ancestors: ancestorsLineage
         });
-        const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
-        const replacement = replacer(refElement);
-        this.indirections.pop();
-        path.replaceWith(replacement);
-        return;
+        referencedElement = await traverseAsync(referencedElement, visitor, {
+          mutable: true
+        });
+        directAncestors.delete(referencingElement);
       }
-    }
 
-    /**
-     * Dive deep into the fragment.
-     *
-     * Cases to consider:
-     *  1. We're crossing document boundary
-     *  2. Fragment is from non-root document
-     *  3. Fragment is a Reference Object. We need to follow it to get the eventual value
-     *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
-     */
-    const isNonRootDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
-    const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-    if ((isExternalReference || isNonRootDocument || isReferenceElement(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
-      // append referencing reference to ancestors lineage
-      directAncestors.add(referencingElement);
-      const visitor = new OpenAPI3_1DereferenceVisitor({
-        reference,
-        namespace: this.namespace,
-        indirections: [...this.indirections],
-        options: this.options,
-        refractCache: this.refractCache,
-        ancestors: ancestorsLineage
-      });
-      referencedElement = await traverseAsync(referencedElement, visitor, {
-        mutable: true
+      /**
+       * Creating a new version of referenced element to avoid modifying the original one.
+       */
+      const mergedElement = cloneShallow(referencedElement);
+      // annotate fragment with info about original Reference element
+      mergedElement.meta.set('ref-fields', {
+        $ref: toValue(referencingElement.$ref),
+        // @ts-ignore
+        description: toValue(referencingElement.description),
+        // @ts-ignore
+        summary: toValue(referencingElement.summary)
       });
+      // annotate fragment with info about origin and type
+      mergedElement.meta.set('ref-origin', reference.uri);
+      mergedElement.meta.set('ref-type', referencingElement.element);
 
-      // remove referencing reference from ancestors lineage
-      directAncestors.delete(referencingElement);
-    }
-    this.indirections.pop();
-
-    /**
-     * Creating a new version of referenced element to avoid modifying the original one.
-     */
-    const mergedElement = cloneShallow(referencedElement);
-    // assign unique id to merged element
-    mergedElement.meta.set('id', identityManager.generateId());
-    // annotate fragment with info about original Reference element
-    mergedElement.meta.set('ref-fields', {
-      $ref: toValue(referencingElement.$ref),
-      // @ts-ignore
-      description: toValue(referencingElement.description),
-      // @ts-ignore
-      summary: toValue(referencingElement.summary)
-    });
-    // annotate fragment with info about origin
-    mergedElement.meta.set('ref-origin', reference.uri);
-    // annotate fragment with info about referencing element
-    mergedElement.meta.set('ref-referencing-element-id', identityManager.identify(referencingElement));
-
-    // override description and summary (outer has higher priority then inner)
-    if (isObjectElement(referencedElement) && isObjectElement(mergedElement)) {
-      const fields = fixedFields(referencedElement, {
-        indexed: true
-      });
-      if (referencingElement.hasKey('description') && Object.hasOwn(fields, 'description')) {
-        mergedElement.remove('description');
-        mergedElement.set('description', referencingElement.get('description'));
-      }
-      if (referencingElement.hasKey('summary') && Object.hasOwn(fields, 'summary')) {
-        mergedElement.remove('summary');
-        mergedElement.set('summary', referencingElement.get('summary'));
+      // override description and summary (outer has higher priority then inner)
+      if (isObjectElement(referencedElement) && isObjectElement(mergedElement)) {
+        const fields = fixedFields(referencedElement, {
+          indexed: true
+        });
+        if (referencingElement.hasKey('description') && Object.hasOwn(fields, 'description')) {
+          mergedElement.remove('description');
+          mergedElement.set('description', referencingElement.get('description'));
+        }
+        if (referencingElement.hasKey('summary') && Object.hasOwn(fields, 'summary')) {
+          mergedElement.remove('summary');
+          mergedElement.set('summary', referencingElement.get('summary'));
+        }
       }
-    }
 
-    /**
-     * Transclude referencing element with merged referenced element.
-     */
-    path.replaceWith(mergedElement);
+      /**
+       * Transclude referencing element with merged referenced element.
+       */
+      path.replaceWith(mergedElement);
+    } catch (error) {
+      const $ref = toValue(referencingElement.$ref);
+      this.handleError(`Error while dereferencing Reference Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
+    }
   }
   async PathItemElement(path) {
     const referencingElement = path.node;
@@ -263,12 +354,11 @@ class OpenAPI3_1DereferenceVisitor {
       return;
     }
 
-    // skip current referencing element as it's already been access
+    // skip current referencing element as it's already been accessed
     if (this.indirections.includes(referencingElement)) {
       path.skip();
       return;
     }
-    const [ancestorsLineage, directAncestors] = this.toAncestorLineage(path);
     const retrievalURI = this.toBaseURI(toValue(referencingElement.$ref));
     const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
     const isExternalReference = !isInternalReference;
@@ -283,117 +373,121 @@ class OpenAPI3_1DereferenceVisitor {
       // skip traversing this Path Item element but traverse all it's child elements
       return;
     }
-    const reference = await this.toReference(toValue(referencingElement.$ref));
     const $refBaseURI = url.resolve(retrievalURI, toValue(referencingElement.$ref));
-    this.indirections.push(referencingElement);
-    const jsonPointer = URIFragmentIdentifier.fromURIReference($refBaseURI);
-
-    // possibly non-semantic referenced element
-    let referencedElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
-    referencedElement.id = identityManager.identify(referencedElement);
-
-    /**
-     * Applying semantics to a referenced element if semantics are missing.
-     */
-    if (isPrimitiveElement(referencedElement)) {
-      const cacheKey = `path-item-${identityManager.identify(referencedElement)}`;
-      if (this.refractCache.has(cacheKey)) {
-        referencedElement = this.refractCache.get(cacheKey);
-      } else {
-        referencedElement = refractPathItem(referencedElement);
-        this.refractCache.set(cacheKey, referencedElement);
-      }
-    }
+    const indirectionsSize = this.indirections.length;
+    try {
+      const reference = await this.toReference(toValue(referencingElement.$ref));
+      this.indirections.push(referencingElement);
+      const jsonPointer = URIFragmentIdentifier.fromURIReference($refBaseURI);
 
-    // detect direct or indirect reference
-    if (referencingElement === referencedElement) {
-      throw new ApiDOMError('Recursive Path Item Object reference detected');
-    }
+      // possibly non-semantic referenced element
+      let referencedElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
 
-    // detect maximum depth of dereferencing
-    if (this.indirections.length > this.options.dereference.maxDepth) {
-      throw new MaximumDereferenceDepthError(`Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`);
-    }
+      // applying semantics to a referenced element
+      if (!isPathItemElement(referencedElement)) {
+        if (this.refractCache.has(referencedElement)) {
+          referencedElement = this.refractCache.get(referencedElement);
+        } else {
+          const sourceElement = referencedElement;
+          referencedElement = refractPathItem(referencedElement);
+          this.refractCache.set(sourceElement, referencedElement);
+        }
+      }
 
-    // detect second deep dive into the same fragment and avoid it
-    if (ancestorsLineage.includes(referencedElement)) {
-      reference.refSet.circular = true;
-      if (this.options.dereference.circular === 'error') {
-        throw new ApiDOMError('Circular reference detected');
-      } else if (this.options.dereference.circular === 'replace') {
-        const refElement = new RefElement(referencedElement.id, {
-          type: 'path-item',
-          uri: reference.uri,
+      // detect direct or indirect reference
+      if (referencingElement === referencedElement) {
+        throw new ApiDOMStructuredError('Recursive Path Item Object reference detected', {
           $ref: toValue(referencingElement.$ref)
         });
-        const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
-        const replacement = replacer(refElement);
-        this.indirections.pop();
-        path.replaceWith(replacement);
-        return;
       }
-    }
 
-    /**
-     * Dive deep into the fragment.
-     *
-     * Cases to consider:
-     *  1. We're crossing document boundary
-     *  2. Fragment is from non-root document
-     *  3. Fragment is a Path Item Object with $ref field. We need to follow it to get the eventual value
-     *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
-     */
-    const isNonRootDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
-    const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-    if ((isExternalReference || isNonRootDocument || isPathItemElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
-      // append referencing reference to ancestors lineage
-      directAncestors.add(referencingElement);
-      const visitor = new OpenAPI3_1DereferenceVisitor({
-        reference,
-        namespace: this.namespace,
-        indirections: [...this.indirections],
-        options: this.options,
-        refractCache: this.refractCache,
-        ancestors: ancestorsLineage
-      });
-      referencedElement = await traverseAsync(referencedElement, visitor, {
-        mutable: true
-      });
+      // detect maximum depth of dereferencing
+      if (this.indirections.length > this.options.dereference.maxDepth) {
+        throw new MaximumDereferenceDepthError(`Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
+          maxDepth: this.options.dereference.maxDepth,
+          uri: this.reference.uri
+        });
+      }
 
-      // remove referencing reference from ancestors lineage
-      directAncestors.delete(referencingElement);
-    }
-    this.indirections.pop();
+      // detect cross-boundary cycle
+      const [ancestorsLineage, directAncestors] = this.toAncestorLineage(path);
+      if (ancestorsLineage.includes(referencedElement)) {
+        reference.refSet.circular = true;
+        if (this.options.dereference.circular === 'error') {
+          throw new ApiDOMStructuredError('Circular reference detected', {
+            $ref: toValue(referencingElement.$ref)
+          });
+        } else if (this.options.dereference.circular === 'replace') {
+          const refElement = new RefElement($refBaseURI, {
+            type: referencingElement.element,
+            uri: reference.uri,
+            $ref: toValue(referencingElement.$ref)
+          });
+          const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
+          const replacement = replacer(refElement);
+          path.replaceWith(replacement);
+          return;
+        }
+      }
 
-    /**
-     * Creating a new version of Path Item by merging fields from referenced Path Item with referencing one.
-     */
-    if (isPathItemElement(referencedElement)) {
-      const mergedElement = cloneShallow(referencedElement);
-      // assign unique id to merged element
-      mergedElement.meta.set('id', identityManager.generateId());
-      // existing keywords from referencing PathItemElement overrides ones from referenced element
-      referencingElement.forEach((value, keyElement, item) => {
-        mergedElement.remove(toValue(keyElement));
-        mergedElement.content.push(item);
-      });
-      mergedElement.remove('$ref');
+      /**
+       * Dive deep into the fragment.
+       *
+       * Cases to consider:
+       *  1. We're crossing document boundary
+       *  2. Fragment is from non-entry document
+       *  3. Fragment is a Path Item Object with $ref field. We need to follow it to get the eventual value
+       *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
+       */
+      const isNonEntryDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
+      const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
+      if ((isExternalReference || isNonEntryDocument || isPathItemElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+        directAncestors.add(referencingElement);
+        const visitor = new OpenAPI3_1DereferenceVisitor({
+          reference,
+          indirections: [...this.indirections],
+          options: this.options,
+          refractCache: this.refractCache,
+          ancestors: ancestorsLineage
+        });
+        referencedElement = await traverseAsync(referencedElement, visitor, {
+          mutable: true
+        });
+        directAncestors.delete(referencingElement);
+      }
 
-      // annotate referenced element with info about original referencing element
-      mergedElement.meta.set('ref-fields', {
-        $ref: toValue(referencingElement.$ref)
-      });
-      // annotate referenced element with info about origin
-      mergedElement.meta.set('ref-origin', reference.uri);
-      // annotate fragment with info about referencing element
-      mergedElement.meta.set('ref-referencing-element-id', identityManager.identify(referencingElement));
-      referencedElement = mergedElement;
-    }
+      /**
+       * Creating a new version of Path Item by merging fields from referenced Path Item with referencing one.
+       */
+      if (isPathItemElement(referencedElement)) {
+        const mergedElement = cloneShallow(referencedElement);
+        // existing keywords from referencing PathItemElement overrides ones from referenced element
+        referencingElement.forEach((value, keyElement, item) => {
+          mergedElement.remove(toValue(keyElement));
+          mergedElement.content.push(item);
+        });
+        mergedElement.remove('$ref');
+
+        // annotate referenced element with info about original referencing element
+        mergedElement.meta.set('ref-fields', {
+          $ref: toValue(referencingElement.$ref)
+        });
+        // annotate referenced element with info about origin and type
+        mergedElement.meta.set('ref-origin', reference.uri);
+        mergedElement.meta.set('ref-type', referencingElement.element);
+        referencedElement = mergedElement;
+      }
 
-    /**
-     * Transclude referencing element with merged referenced element.
-     */
-    path.replaceWith(referencedElement);
+      /**
+       * Transclude referencing element with merged referenced element.
+       */
+      path.replaceWith(referencedElement);
+    } catch (error) {
+      const $ref = toValue(referencingElement.$ref);
+      this.handleError(`Error while dereferencing Path Item Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
+    }
   }
   async LinkElement(path) {
     const linkElement = path.node;
@@ -405,66 +499,78 @@ class OpenAPI3_1DereferenceVisitor {
 
     // operationRef and operationId fields are mutually exclusive
     if (isStringElement(linkElement.operationRef) && isStringElement(linkElement.operationId)) {
-      throw new ApiDOMError('LinkElement operationRef and operationId fields are mutually exclusive');
+      throw new ApiDOMStructuredError('LinkElement operationRef and operationId fields are mutually exclusive', {
+        operationRef: toValue(linkElement.operationRef),
+        operationId: toValue(linkElement.operationId)
+      });
     }
-    let operationElement;
-    if (isStringElement(linkElement.operationRef)) {
-      // possibly non-semantic referenced element
-      const jsonPointer = URIFragmentIdentifier.fromURIReference(toValue(linkElement.operationRef));
-      const retrievalURI = this.toBaseURI(toValue(linkElement.operationRef));
-      const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
-      const isExternalReference = !isInternalReference;
-
-      // ignore resolving internal Operation Object reference
-      if (!this.options.resolve.internal && isInternalReference) {
-        // skip traversing this Link element but traverse all it's child elements
-        return;
-      }
-      // ignore resolving external Operation Object reference
-      if (!this.options.resolve.external && isExternalReference) {
-        // skip traversing this Link element but traverse all it's child elements
+    try {
+      let operationElement;
+      if (isStringElement(linkElement.operationRef)) {
+        // possibly non-semantic referenced element
+        const jsonPointer = URIFragmentIdentifier.fromURIReference(toValue(linkElement.operationRef));
+        const retrievalURI = this.toBaseURI(toValue(linkElement.operationRef));
+        const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+        const isExternalReference = !isInternalReference;
+
+        // ignore resolving internal Operation Object reference
+        if (!this.options.resolve.internal && isInternalReference) {
+          // skip traversing this Link element but traverse all it's child elements
+          return;
+        }
+        // ignore resolving external Operation Object reference
+        if (!this.options.resolve.external && isExternalReference) {
+          // skip traversing this Link element but traverse all it's child elements
+          return;
+        }
+        const reference = await this.toReference(toValue(linkElement.operationRef));
+        operationElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
+        // applying semantics to a referenced element
+        if (!isOperationElement(operationElement)) {
+          if (this.refractCache.has(operationElement)) {
+            operationElement = this.refractCache.get(operationElement);
+          } else {
+            const sourceElement = operationElement;
+            operationElement = refractOperation(operationElement);
+            this.refractCache.set(sourceElement, operationElement);
+          }
+        }
+        // create shallow clone to be able to annotate with metadata
+        operationElement = cloneShallow(operationElement);
+        // annotate operation element with info about origin and type
+        operationElement.meta.set('ref-origin', reference.uri);
+        operationElement.meta.set('ref-type', linkElement.element);
+        const linkElementCopy = cloneShallow(linkElement);
+        linkElementCopy.operationRef?.meta.set('operation', operationElement);
+
+        /**
+         * Transclude Link Object containing Operation Object in its meta.
+         */
+        path.replaceWith(linkElementCopy);
         return;
       }
-      const reference = await this.toReference(toValue(linkElement.operationRef));
-      operationElement = jsonPointerEvaluate(reference.value.result, jsonPointer);
-      // applying semantics to a referenced element
-      if (isPrimitiveElement(operationElement)) {
-        const cacheKey = `operation-${identityManager.identify(operationElement)}`;
-        if (this.refractCache.has(cacheKey)) {
-          operationElement = this.refractCache.get(cacheKey);
-        } else {
-          operationElement = refractOperation(operationElement);
-          this.refractCache.set(cacheKey, operationElement);
+      if (isStringElement(linkElement.operationId)) {
+        const operationId = toValue(linkElement.operationId);
+        const reference = await this.toReference(url.unsanitize(this.reference.uri));
+        operationElement = find(reference.value.result, e => isOperationElement(e) && isElement(e.operationId) && e.operationId.equals(operationId));
+        // OperationElement not found by its operationId
+        if (isUndefined(operationElement)) {
+          throw new ApiDOMStructuredError(`OperationElement(operationId=${operationId}) not found`, {
+            operationId
+          });
         }
-      }
-      // create shallow clone to be able to annotate with metadata
-      operationElement = cloneShallow(operationElement);
-      // annotate operation element with info about origin
-      operationElement.meta.set('ref-origin', reference.uri);
-      const linkElementCopy = cloneShallow(linkElement);
-      linkElementCopy.operationRef?.meta.set('operation', operationElement);
+        const linkElementCopy = cloneShallow(linkElement);
+        linkElementCopy.operationId?.meta.set('operation', operationElement);
 
-      /**
-       * Transclude Link Object containing Operation Object in its meta.
-       */
-      path.replaceWith(linkElementCopy);
-      return;
-    }
-    if (isStringElement(linkElement.operationId)) {
-      const operationId = toValue(linkElement.operationId);
-      const reference = await this.toReference(url.unsanitize(this.reference.uri));
-      operationElement = find(reference.value.result, e => isOperationElement(e) && isElement(e.operationId) && e.operationId.equals(operationId));
-      // OperationElement not found by its operationId
-      if (isUndefined(operationElement)) {
-        throw new ApiDOMError(`OperationElement(operationId=${operationId}) not found`);
+        /**
+         * Transclude Link Object containing Operation Object in its meta.
+         */
+        path.replaceWith(linkElementCopy);
       }
-      const linkElementCopy = cloneShallow(linkElement);
-      linkElementCopy.operationId?.meta.set('operation', operationElement);
-
-      /**
-       * Transclude Link Object containing Operation Object in its meta.
-       */
-      path.replaceWith(linkElementCopy);
+    } catch (error) {
+      const refFieldName = isStringElement(linkElement.operationRef) ? 'operationRef' : 'operationId';
+      const refFieldValue = isStringElement(linkElement.operationRef) ? toValue(linkElement.operationRef) : toValue(linkElement.operationId);
+      this.handleError(`Error while dereferencing Link Object. Cannot resolve ${refFieldName} "${refFieldValue}": ${error.message}`, error, linkElement, refFieldName, refFieldValue, path);
     }
   }
   async ExampleElement(path) {
@@ -477,7 +583,10 @@ class OpenAPI3_1DereferenceVisitor {
 
     // value and externalValue fields are mutually exclusive
     if (exampleElement.hasKey('value') && isStringElement(exampleElement.externalValue)) {
-      throw new ApiDOMError('ExampleElement value and externalValue fields are mutually exclusive');
+      throw new ApiDOMStructuredError('ExampleElement value and externalValue fields are mutually exclusive', {
+        value: toValue(exampleElement.value),
+        externalValue: toValue(exampleElement.externalValue)
+      });
     }
     const retrievalURI = this.toBaseURI(toValue(exampleElement.externalValue));
     const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
@@ -493,19 +602,25 @@ class OpenAPI3_1DereferenceVisitor {
       // skip traversing this Example element but traverse all it's child elements
       return;
     }
-    const reference = await this.toReference(toValue(exampleElement.externalValue));
-
-    // shallow clone of the referenced element
-    const valueElement = cloneShallow(reference.value.result);
-    // annotate operation element with info about origin
-    valueElement.meta.set('ref-origin', reference.uri);
-    const exampleElementCopy = cloneShallow(exampleElement);
-    exampleElementCopy.value = valueElement;
-
-    /**
-     * Transclude Example Object containing external value.
-     */
-    path.replaceWith(exampleElementCopy);
+    try {
+      const reference = await this.toReference(toValue(exampleElement.externalValue));
+
+      // shallow clone of the referenced element
+      const valueElement = cloneShallow(reference.value.result);
+      // annotate element with info about origin and type
+      valueElement.meta.set('ref-origin', reference.uri);
+      valueElement.meta.set('ref-type', exampleElement.element);
+      const exampleElementCopy = cloneShallow(exampleElement);
+      exampleElementCopy.value = valueElement;
+
+      /**
+       * Transclude Example Object containing external value.
+       */
+      path.replaceWith(exampleElementCopy);
+    } catch (error) {
+      const externalValue = toValue(exampleElement.externalValue);
+      this.handleError(`Error while dereferencing Example Object. Cannot resolve externalValue "${externalValue}": ${error.message}`, error, exampleElement, 'externalValue', externalValue, path);
+    }
   }
   async SchemaElement(path) {
     const referencingElement = path.node;
@@ -515,83 +630,38 @@ class OpenAPI3_1DereferenceVisitor {
       return;
     }
 
-    // skip current referencing element as it's already been access
+    // skip current referencing element as it's already been accessed
     if (this.indirections.includes(referencingElement)) {
       path.skip();
       return;
     }
-    const [ancestorsLineage, directAncestors] = this.toAncestorLineage(path);
-
-    // compute baseURI using rules around $id and $ref keywords
-    let reference = await this.toReference(url.unsanitize(this.reference.uri));
-    let {
-      uri: retrievalURI
-    } = reference;
-    const $refBaseURI = resolveSchema$refField(retrievalURI, referencingElement);
-    const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
-    const file = new File({
-      uri: $refBaseURIStrippedHash
-    });
-    const isUnknownURI = none(r => r.canRead(file), this.options.resolve.resolvers);
-    const isURL = !isUnknownURI;
-    let isInternalReference = url.stripHash(this.reference.uri) === $refBaseURI;
-    let isExternalReference = !isInternalReference;
-
-    // determining reference, proper evaluation and selection mechanism
-    let referencedElement;
+    const indirectionsSize = this.indirections.length;
     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);
-        referencedElement = maybeRefractToSchemaElement(referencedElement);
-        referencedElement.id = identityManager.identify(referencedElement);
-
-        // ignore resolving internal Schema Objects
-        if (!this.options.resolve.internal && isInternalReference) {
-          // skip traversing this schema element but traverse all it's child elements
-          return;
-        }
-        // ignore resolving external Schema Objects
-        if (!this.options.resolve.external && isExternalReference) {
-          // skip traversing this schema element but traverse all it's child elements
-          return;
-        }
-      } else {
-        // we're assuming here that we're dealing with JSON Pointer here
-        retrievalURI = this.toBaseURI($refBaseURI);
-        isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
-        isExternalReference = !isInternalReference;
-
-        // ignore resolving internal Schema Objects
-        if (!this.options.resolve.internal && isInternalReference) {
-          // skip traversing this schema element but traverse all it's child elements
-          return;
-        }
-        // ignore resolving external Schema Objects
-        if (!this.options.resolve.external && isExternalReference) {
-          // skip traversing this schema element but traverse all it's child elements
-          return;
-        }
-        reference = await this.toReference(url.unsanitize($refBaseURI));
-        const selector = URIFragmentIdentifier.fromURIReference($refBaseURI);
-        const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
-        referencedElement = jsonPointerEvaluate(referenceAsSchema, selector);
-        referencedElement = maybeRefractToSchemaElement(referencedElement);
-        referencedElement.id = identityManager.identify(referencedElement);
-      }
-    } catch (error) {
-      /**
-       * SchemaElement($id=URL) was not found, so we're going to try to resolve
-       * the URL and assume the returned response is a JSON Schema.
-       */
-      if (isURL && error instanceof EvaluationJsonSchemaUriError) {
-        if (isAnchor(uriToAnchor($refBaseURI))) {
-          // we're dealing with JSON Schema $anchor here
-          isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
-          isExternalReference = !isInternalReference;
+      // compute baseURI using rules around $id and $ref keywords
+      let reference = await this.toReference(url.unsanitize(this.reference.uri));
+      let {
+        uri: retrievalURI
+      } = reference;
+      const $refBaseURI = resolveSchema$refField(retrievalURI, referencingElement);
+      const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
+      const file = new File({
+        uri: $refBaseURIStrippedHash
+      });
+      const isUnknownURI = none(r => r.canRead(file), this.options.resolve.resolvers);
+      const isURL = !isUnknownURI;
+      let isInternalReference = url.stripHash(this.reference.uri) === $refBaseURI;
+      let isExternalReference = !isInternalReference;
+
+      // determining reference, proper evaluation and selection mechanism
+      let referencedElement;
+      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);
+          referencedElement = maybeRefractToSchemaElement(referencedElement);
 
           // ignore resolving internal Schema Objects
           if (!this.options.resolve.internal && isInternalReference) {
@@ -603,12 +673,6 @@ class OpenAPI3_1DereferenceVisitor {
             // skip traversing this schema element but traverse all it's child elements
             return;
           }
-          reference = await this.toReference(url.unsanitize($refBaseURI));
-          const selector = uriToAnchor($refBaseURI);
-          const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
-          referencedElement = $anchorEvaluate(selector, referenceAsSchema);
-          referencedElement = maybeRefractToSchemaElement(referencedElement);
-          referencedElement.id = identityManager.identify(referencedElement);
         } else {
           // we're assuming here that we're dealing with JSON Pointer here
           retrievalURI = this.toBaseURI($refBaseURI);
@@ -630,118 +694,167 @@ class OpenAPI3_1DereferenceVisitor {
           const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
           referencedElement = jsonPointerEvaluate(referenceAsSchema, selector);
           referencedElement = maybeRefractToSchemaElement(referencedElement);
-          referencedElement.id = identityManager.identify(referencedElement);
         }
-      } else {
-        throw error;
+      } catch (error) {
+        /**
+         * SchemaElement($id=URL) was not found, so we're going to try to resolve
+         * the URL and assume the returned response is a JSON Schema.
+         */
+        if (isURL && error instanceof EvaluationJsonSchemaUriError) {
+          if (isAnchor(uriToAnchor($refBaseURI))) {
+            // we're dealing with JSON Schema $anchor here
+            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+            isExternalReference = !isInternalReference;
+
+            // ignore resolving internal Schema Objects
+            if (!this.options.resolve.internal && isInternalReference) {
+              // skip traversing this schema element but traverse all it's child elements
+              return;
+            }
+            // ignore resolving external Schema Objects
+            if (!this.options.resolve.external && isExternalReference) {
+              // skip traversing this schema element but traverse all it's child elements
+              return;
+            }
+            reference = await this.toReference(url.unsanitize($refBaseURI));
+            const selector = uriToAnchor($refBaseURI);
+            const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
+            referencedElement = $anchorEvaluate(selector, referenceAsSchema);
+            referencedElement = maybeRefractToSchemaElement(referencedElement);
+          } else {
+            // we're assuming here that we're dealing with JSON Pointer here
+            retrievalURI = this.toBaseURI($refBaseURI);
+            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+            isExternalReference = !isInternalReference;
+
+            // ignore resolving internal Schema Objects
+            if (!this.options.resolve.internal && isInternalReference) {
+              // skip traversing this schema element but traverse all it's child elements
+              return;
+            }
+            // ignore resolving external Schema Objects
+            if (!this.options.resolve.external && isExternalReference) {
+              // skip traversing this schema element but traverse all it's child elements
+              return;
+            }
+            reference = await this.toReference(url.unsanitize($refBaseURI));
+            const selector = URIFragmentIdentifier.fromURIReference($refBaseURI);
+            const referenceAsSchema = maybeRefractToSchemaElement(reference.value.result);
+            referencedElement = jsonPointerEvaluate(referenceAsSchema, selector);
+            referencedElement = maybeRefractToSchemaElement(referencedElement);
+          }
+        } else {
+          throw error;
+        }
       }
-    }
-    this.indirections.push(referencingElement);
+      this.indirections.push(referencingElement);
 
-    // detect direct or indirect reference
-    if (referencingElement === referencedElement) {
-      throw new ApiDOMError('Recursive Schema Object reference detected');
-    }
+      // detect direct or indirect reference
+      if (referencingElement === referencedElement) {
+        throw new ApiDOMStructuredError('Recursive Schema Object reference detected', {
+          $ref: toValue(referencingElement.$ref)
+        });
+      }
 
-    // detect maximum depth of dereferencing
-    if (this.indirections.length > this.options.dereference.maxDepth) {
-      throw new MaximumDereferenceDepthError(`Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`);
-    }
+      // detect maximum depth of dereferencing
+      if (this.indirections.length > this.options.dereference.maxDepth) {
+        throw new MaximumDereferenceDepthError(`Maximum dereference depth of "${this.options.dereference.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
+          maxDepth: this.options.dereference.maxDepth,
+          uri: this.reference.uri
+        });
+      }
+
+      // detect cross-boundary cycle
+      const [ancestorsLineage, directAncestors] = this.toAncestorLineage(path);
+      if (ancestorsLineage.includes(referencedElement)) {
+        reference.refSet.circular = true;
+        if (this.options.dereference.circular === 'error') {
+          throw new ApiDOMStructuredError('Circular reference detected', {
+            $ref: toValue(referencingElement.$ref)
+          });
+        } else if (this.options.dereference.circular === 'replace') {
+          const refElement = new RefElement($refBaseURI, {
+            type: referencingElement.element,
+            uri: reference.uri,
+            $ref: toValue(referencingElement.$ref)
+          });
+          const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
+          const replacement = replacer(refElement);
+          path.replaceWith(replacement);
+          return;
+        }
+      }
+
+      /**
+       * Dive deep into the fragment.
+       *
+       * Cases to consider:
+       *  1. We're crossing document boundary
+       *  2. Fragment is from non-entry document
+       *  3. Fragment is a Schema Object with $ref field. We need to follow it to get the eventual value
+       *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
+       */
+      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) && !ancestorsLineage.includesCycle(referencedElement)) {
+        directAncestors.add(referencingElement);
+        const visitor = new OpenAPI3_1DereferenceVisitor({
+          reference,
+          indirections: [...this.indirections],
+          options: this.options,
+          refractCache: this.refractCache,
+          ancestors: ancestorsLineage
+        });
+        referencedElement = await traverseAsync(referencedElement, visitor, {
+          mutable: true
+        });
+        directAncestors.delete(referencingElement);
+      }
 
-    // detect second deep dive into the same fragment and avoid it
-    if (ancestorsLineage.includes(referencedElement)) {
-      reference.refSet.circular = true;
-      if (this.options.dereference.circular === 'error') {
-        throw new ApiDOMError('Circular reference detected');
-      } else if (this.options.dereference.circular === 'replace') {
-        const refElement = new RefElement(referencedElement.id, {
-          type: 'json-schema',
-          uri: reference.uri,
+      // Boolean JSON Schemas
+      if (isBooleanJSONSchemaElement(referencedElement)) {
+        const booleanJsonSchemaElement = cloneDeep(referencedElement);
+        // annotate referenced element with info about original referencing element
+        booleanJsonSchemaElement.meta.set('ref-fields', {
           $ref: toValue(referencingElement.$ref)
         });
-        const replacer = this.options.dereference.strategyOpts['openapi-3-1']?.circularReplacer ?? this.options.dereference.circularReplacer;
-        const replacement = replacer(refElement);
-        this.indirections.pop();
-        path.replaceWith(replacement);
+        // annotate referenced element with info about origin and type
+        booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
+        booleanJsonSchemaElement.meta.set('ref-type', referencingElement.element);
+        path.replaceWith(booleanJsonSchemaElement);
         return;
       }
-    }
-
-    /**
-     * Dive deep into the fragment.
-     *
-     * Cases to consider:
-     *  1. We're crossing document boundary
-     *  2. Fragment is from non-root document
-     *  3. Fragment is a Schema Object with $ref field. We need to follow it to get the eventual value
-     *  4. We are dereferencing the fragment lazily/eagerly depending on circular mode
-     */
-    const isNonRootDocument = url.stripHash(reference.refSet.rootRef.uri) !== reference.uri;
-    const shouldDetectCircular = ['error', 'replace'].includes(this.options.dereference.circular);
-    if ((isExternalReference || isNonRootDocument || isSchemaElement(referencedElement) && isStringElement(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
-      // append referencing reference to ancestors lineage
-      directAncestors.add(referencingElement);
-      const visitor = new OpenAPI3_1DereferenceVisitor({
-        reference,
-        namespace: this.namespace,
-        indirections: [...this.indirections],
-        options: this.options,
-        refractCache: this.refractCache,
-        ancestors: ancestorsLineage
-      });
-      referencedElement = await traverseAsync(referencedElement, visitor, {
-        mutable: true
-      });
 
-      // remove referencing reference from ancestors lineage
-      directAncestors.delete(referencingElement);
-    }
-    this.indirections.pop();
-
-    // Boolean JSON Schemas
-    if (isBooleanJSONSchemaElement(referencedElement)) {
-      const booleanJsonSchemaElement = cloneDeep(referencedElement);
-      // assign unique id to merged element
-      booleanJsonSchemaElement.meta.set('id', identityManager.generateId());
-      // annotate referenced element with info about original referencing element
-      booleanJsonSchemaElement.meta.set('ref-fields', {
-        $ref: toValue(referencingElement.$ref)
-      });
-      // annotate referenced element with info about origin
-      booleanJsonSchemaElement.meta.set('ref-origin', reference.uri);
-      // annotate fragment with info about referencing element
-      booleanJsonSchemaElement.meta.set('ref-referencing-element-id', identityManager.identify(referencingElement));
-      path.replaceWith(booleanJsonSchemaElement);
-      return;
-    }
-
-    /**
-     * Creating a new version of Schema Object by merging fields from referenced Schema Object with referencing one.
-     */
-    if (isSchemaElement(referencedElement)) {
-      const mergedElement = cloneShallow(referencedElement);
-      // assign unique id to merged element
-      mergedElement.meta.set('id', identityManager.generateId());
-      // existing keywords from referencing schema overrides ones from referenced schema
-      referencingElement.forEach((value, keyElement, item) => {
-        mergedElement.remove(toValue(keyElement));
-        mergedElement.content.push(item);
-      });
-      mergedElement.remove('$ref');
-      // annotate referenced element with info about original referencing element
-      mergedElement.meta.set('ref-fields', {
-        $ref: toValue(referencingElement.$ref)
-      });
-      // annotate fragment with info about origin
-      mergedElement.meta.set('ref-origin', reference.uri);
-      // annotate fragment with info about referencing element
-      mergedElement.meta.set('ref-referencing-element-id', identityManager.identify(referencingElement));
-      referencedElement = mergedElement;
+      /**
+       * Creating a new version of Schema Object by merging fields from referenced Schema Object with referencing one.
+       */
+      if (isSchemaElement(referencedElement)) {
+        const mergedElement = cloneShallow(referencedElement);
+        // existing keywords from referencing schema overrides ones from referenced schema
+        referencingElement.forEach((value, keyElement, item) => {
+          mergedElement.remove(toValue(keyElement));
+          mergedElement.content.push(item);
+        });
+        mergedElement.remove('$ref');
+        // annotate referenced element with info about original referencing element
+        mergedElement.meta.set('ref-fields', {
+          $ref: toValue(referencingElement.$ref)
+        });
+        // annotate fragment with info about origin and type
+        mergedElement.meta.set('ref-origin', reference.uri);
+        mergedElement.meta.set('ref-type', referencingElement.element);
+        referencedElement = mergedElement;
+      }
+      /**
+       * Transclude referencing element with merged referenced element.
+       */
+      path.replaceWith(referencedElement);
+    } catch (error) {
+      const $ref = toValue(referencingElement.$ref);
+      this.handleError(`Error while dereferencing Schema Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);
+    } finally {
+      if (this.indirections.length > indirectionsSize) this.indirections.pop();
     }
-    /**
-     * Transclude referencing element with merged referenced element.
-     */
-    path.replaceWith(referencedElement);
   }
 }
 export default OpenAPI3_1DereferenceVisitor;