@speclynx/apidom-reference 4.0.2 → 4.0.3

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

@@ -0,0 +1,622 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _ramda = require("ramda");
+var _ramdaAdjunct = require("ramda-adjunct");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomError = require("@speclynx/apidom-error");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-3-0");
+var _UnresolvableReferenceError = _interopRequireDefault(require("../../../errors/UnresolvableReferenceError.cjs"));
+var _MaximumDereferenceDepthError = _interopRequireDefault(require("../../../errors/MaximumDereferenceDepthError.cjs"));
+var _MaximumResolveDepthError = _interopRequireDefault(require("../../../errors/MaximumResolveDepthError.cjs"));
+var url = _interopRequireWildcard(require("../../../util/url.cjs"));
+var _index = _interopRequireDefault(require("../../../parse/index.cjs"));
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _util = require("../../util.cjs");
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class OpenAPI3_0DereferenceVisitor {
+  indirections;
+  reference;
+  options;
+  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,
+    options,
+    indirections = [],
+    ancestors = new _util.AncestorLineage(),
+    refractCache = new WeakMap()
+  }) {
+    this.indirections = indirections;
+    this.reference = reference;
+    this.options = options;
+    this.ancestors = new _util.AncestorLineage(...ancestors);
+    this.refractCache = refractCache;
+  }
+  toAncestorLineage(path) {
+    const ancestorNodes = path.getAncestorNodes();
+    const directAncestors = new Set(ancestorNodes.filter(_apidomDatamodel.isElement));
+    const ancestorsLineage = new _util.AncestorLineage(...this.ancestors, directAncestors);
+    return [ancestorsLineage, directAncestors];
+  }
+  toBaseURI(uri) {
+    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+  }
+  async toReference(uri) {
+    // detect maximum depth of resolution
+    if (this.reference.depth >= this.options.resolve.maxDepth) {
+      throw new _MaximumResolveDepthError.default(`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 {
+      refSet
+    } = this.reference;
+
+    // we've already processed this Reference in past
+    if (refSet.has(baseURI)) {
+      return refSet.find((0, _ramda.propEq)(baseURI, 'uri'));
+    }
+    const parseResult = await (0, _index.default)(url.unsanitize(baseURI), {
+      ...this.options,
+      parse: {
+        ...this.options.parse,
+        mediaType: 'text/plain'
+      }
+    });
+
+    // 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.default({
+      uri: baseURI,
+      value: this.options.dereference.immutable ? (0, _apidomDatamodel.cloneDeep)(parseResult) : parseResult,
+      depth: this.reference.depth + 1
+    });
+    refSet.add(mutableReference);
+    if (this.options.dereference.immutable) {
+      // register new immutable reference with a refSet
+      const immutableReference = new _Reference.default({
+        uri: `immutable://${baseURI}`,
+        value: parseResult,
+        depth: this.reference.depth + 1
+      });
+      refSet.add(immutableReference);
+    }
+    return mutableReference;
+  }
+
+  /**
+   * 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 = (0, _apidomCore.toYAML)(referencingElement);
+
+    // find element location by identity in the document tree.
+    // guarded: this.reference.value may not be a ParseResultElement or may lack a result.
+    // falls back to visitorPath which may produce an incomplete path when
+    // dereferenceApiDOM is called with a fragment (cloneShallow creates a new root identity).
+    let location;
+    const root = this.reference.value.result;
+    if ((0, _apidomDatamodel.isElement)(root)) {
+      (0, _apidomTraverse.traverse)(root, {
+        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.default) {
+      // prefix relative locations for entries belonging to the referenced document
+      const refBaseURI = this.toBaseURI(refFieldValue);
+      const fragment = _apidomJsonPointer.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.default(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
+    if (this.indirections.includes(referencingElement)) {
+      path.skip();
+      return;
+    }
+    const retrievalURI = this.toBaseURI((0, _apidomCore.toValue)(referencingElement.$ref));
+    const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+    const isExternalReference = !isInternalReference;
+
+    // ignore resolving internal Reference Objects
+    if (!this.options.resolve.internal && isInternalReference) {
+      // skip traversing this reference element and all it's child elements
+      path.skip();
+      return;
+    }
+    // ignore resolving external Reference Objects
+    if (!this.options.resolve.external && isExternalReference) {
+      // skip traversing this reference element and all it's child elements
+      path.skip();
+      return;
+    }
+    const $refBaseURI = url.resolve(retrievalURI, (0, _apidomCore.toValue)(referencingElement.$ref));
+    const indirectionsSize = this.indirections.length;
+    try {
+      const reference = await this.toReference((0, _apidomCore.toValue)(referencingElement.$ref));
+      this.indirections.push(referencingElement);
+      const jsonPointer = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
+
+      // possibly non-semantic fragment
+      let referencedElement = (0, _apidomJsonPointer.evaluate)(reference.value.result, jsonPointer);
+
+      // applying semantics to a fragment
+      const referencedElementType = referencingElement.meta.get('referenced-element');
+      if (referencedElement.element !== referencedElementType && !(0, _apidomNsOpenapi.isReferenceElement)(referencedElement)) {
+        if (this.refractCache.has(referencedElement)) {
+          referencedElement = this.refractCache.get(referencedElement);
+        } else if ((0, _apidomNsOpenapi.isReferenceLikeElement)(referencedElement)) {
+          // handling generic indirect references
+          const sourceElement = referencedElement;
+          referencedElement = (0, _apidomNsOpenapi.refractReference)(referencedElement);
+          referencedElement.meta.set('referenced-element', referencedElementType);
+          this.refractCache.set(sourceElement, referencedElement);
+        } else {
+          // handling direct references
+          const sourceElement = referencedElement;
+          referencedElement = (0, _apidomNsOpenapi.refract)(referencedElement, {
+            element: referencedElementType
+          });
+          this.refractCache.set(sourceElement, referencedElement);
+        }
+      }
+
+      // detect direct or indirect reference
+      if (referencingElement === referencedElement) {
+        throw new _apidomError.ApiDOMStructuredError('Recursive Reference Object detected', {
+          $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
+        });
+      }
+
+      // detect maximum depth of dereferencing
+      if (this.indirections.length > this.options.dereference.maxDepth) {
+        throw new _MaximumDereferenceDepthError.default(`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 second deep dive into the same fragment and avoid it
+      const [ancestorsLineage, directAncestors] = this.toAncestorLineage(path);
+      if (ancestorsLineage.includes(referencedElement)) {
+        reference.refSet.circular = true;
+        if (this.options.dereference.circular === 'error') {
+          throw new _apidomError.ApiDOMStructuredError('Circular reference detected', {
+            $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
+          });
+        } else if (this.options.dereference.circular === 'replace') {
+          const refElement = new _apidomDatamodel.RefElement($refBaseURI, {
+            type: referencingElement.element,
+            uri: reference.uri,
+            $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
+          });
+          const replacer = this.options.dereference.strategyOpts['openapi-3-0']?.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 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 || (0, _apidomNsOpenapi.isReferenceElement)(referencedElement) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+        // append referencing reference to ancestors lineage
+        directAncestors.add(referencingElement);
+        const visitor = new OpenAPI3_0DereferenceVisitor({
+          reference,
+          indirections: [...this.indirections],
+          options: this.options,
+          refractCache: this.refractCache,
+          ancestors: ancestorsLineage
+        });
+        referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
+          mutable: true
+        });
+
+        // remove referencing reference from ancestors lineage
+        directAncestors.delete(referencingElement);
+      }
+
+      /**
+       * Creating a new version of referenced element to avoid modifying the original one.
+       */
+      const mergedElement = (0, _apidomDatamodel.cloneShallow)(referencedElement);
+      // annotate referenced element with info about original referencing element
+      mergedElement.meta.set('ref-fields', {
+        $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
+      });
+      // annotate fragment with info about origin
+      mergedElement.meta.set('ref-origin', reference.uri);
+      mergedElement.meta.set('ref-type', referencingElement.element);
+
+      /**
+       * Transclude referencing element with merged referenced element.
+       */
+      path.replaceWith(mergedElement);
+    } catch (error) {
+      const $ref = (0, _apidomCore.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;
+
+    // ignore PathItemElement without $ref field
+    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+
+    // skip current referencing element as it's already been access
+    if (this.indirections.includes(referencingElement)) {
+      path.skip();
+      return;
+    }
+    const retrievalURI = this.toBaseURI((0, _apidomCore.toValue)(referencingElement.$ref));
+    const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+    const isExternalReference = !isInternalReference;
+
+    // ignore resolving internal Path Item Objects
+    if (!this.options.resolve.internal && isInternalReference) {
+      // skip traversing this Path Item element but traverse all it's child elements
+      return;
+    }
+    // ignore resolving external Path Item Objects
+    if (!this.options.resolve.external && isExternalReference) {
+      // skip traversing this Path Item element but traverse all it's child elements
+      return;
+    }
+    const $refBaseURI = url.resolve(retrievalURI, (0, _apidomCore.toValue)(referencingElement.$ref));
+    const indirectionsSize = this.indirections.length;
+    try {
+      const reference = await this.toReference((0, _apidomCore.toValue)(referencingElement.$ref));
+      this.indirections.push(referencingElement);
+      const jsonPointer = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
+
+      // possibly non-semantic referenced element
+      let referencedElement = (0, _apidomJsonPointer.evaluate)(reference.value.result, jsonPointer);
+
+      // applying semantics to a referenced element
+      if (!(0, _apidomNsOpenapi.isPathItemElement)(referencedElement)) {
+        if (this.refractCache.has(referencedElement)) {
+          referencedElement = this.refractCache.get(referencedElement);
+        } else {
+          const sourceElement = referencedElement;
+          referencedElement = (0, _apidomNsOpenapi.refractPathItem)(referencedElement);
+          this.refractCache.set(sourceElement, referencedElement);
+        }
+      }
+
+      // detect direct or indirect reference
+      if (referencingElement === referencedElement) {
+        throw new _apidomError.ApiDOMStructuredError('Recursive Path Item Object reference detected', {
+          $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
+        });
+      }
+
+      // detect maximum depth of dereferencing
+      if (this.indirections.length > this.options.dereference.maxDepth) {
+        throw new _MaximumDereferenceDepthError.default(`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 _apidomError.ApiDOMStructuredError('Circular reference detected', {
+            $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
+          });
+        } else if (this.options.dereference.circular === 'replace') {
+          const refElement = new _apidomDatamodel.RefElement($refBaseURI, {
+            type: referencingElement.element,
+            uri: reference.uri,
+            $ref: (0, _apidomCore.toValue)(referencingElement.$ref)
+          });
+          const replacer = this.options.dereference.strategyOpts['openapi-3-0']?.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 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 || (0, _apidomNsOpenapi.isPathItemElement)(referencedElement) && (0, _apidomDatamodel.isStringElement)(referencedElement.$ref) || shouldDetectCircular) && !ancestorsLineage.includesCycle(referencedElement)) {
+        // append referencing reference to ancestors lineage
+        directAncestors.add(referencingElement);
+        const visitor = new OpenAPI3_0DereferenceVisitor({
+          reference,
+          indirections: [...this.indirections],
+          options: this.options,
+          refractCache: this.refractCache,
+          ancestors: ancestorsLineage
+        });
+        referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
+          mutable: true
+        });
+
+        // remove referencing reference from ancestors lineage
+        directAncestors.delete(referencingElement);
+      }
+
+      /**
+       * Creating a new version of Path Item by merging fields from referenced Path Item with referencing one.
+       */
+      if ((0, _apidomNsOpenapi.isPathItemElement)(referencedElement)) {
+        const mergedElement = (0, _apidomDatamodel.cloneShallow)(referencedElement);
+        // existing keywords from referencing PathItemElement overrides ones from referenced element
+        referencingElement.forEach((value, keyElement, item) => {
+          mergedElement.remove((0, _apidomCore.toValue)(keyElement));
+          mergedElement.content.push(item);
+        });
+        mergedElement.remove('$ref');
+
+        // annotate referenced element with info about original referencing element
+        mergedElement.meta.set('ref-fields', {
+          $ref: (0, _apidomCore.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);
+    } catch (error) {
+      const $ref = (0, _apidomCore.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;
+
+    // ignore LinkElement without operationRef or operationId field
+    if (!(0, _apidomDatamodel.isStringElement)(linkElement.operationRef) && !(0, _apidomDatamodel.isStringElement)(linkElement.operationId)) {
+      return;
+    }
+
+    // operationRef and operationId fields are mutually exclusive
+    if ((0, _apidomDatamodel.isStringElement)(linkElement.operationRef) && (0, _apidomDatamodel.isStringElement)(linkElement.operationId)) {
+      throw new _apidomError.ApiDOMStructuredError('LinkElement operationRef and operationId fields are mutually exclusive', {
+        operationRef: (0, _apidomCore.toValue)(linkElement.operationRef),
+        operationId: (0, _apidomCore.toValue)(linkElement.operationId)
+      });
+    }
+    try {
+      let operationElement;
+      if ((0, _apidomDatamodel.isStringElement)(linkElement.operationRef)) {
+        // possibly non-semantic referenced element
+        const jsonPointer = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference((0, _apidomCore.toValue)(linkElement.operationRef));
+        const retrievalURI = this.toBaseURI((0, _apidomCore.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((0, _apidomCore.toValue)(linkElement.operationRef));
+        operationElement = (0, _apidomJsonPointer.evaluate)(reference.value.result, jsonPointer);
+        // applying semantics to a referenced element
+        if (!(0, _apidomNsOpenapi.isOperationElement)(operationElement)) {
+          if (this.refractCache.has(operationElement)) {
+            operationElement = this.refractCache.get(operationElement);
+          } else {
+            const sourceElement = operationElement;
+            operationElement = (0, _apidomNsOpenapi.refractOperation)(operationElement);
+            this.refractCache.set(sourceElement, operationElement);
+          }
+        }
+        // create shallow clone to be able to annotate with metadata
+        operationElement = (0, _apidomDatamodel.cloneShallow)(operationElement);
+        // annotate operation element with info about origin
+        operationElement.meta.set('ref-origin', reference.uri);
+        operationElement.meta.set('ref-type', linkElement.element);
+        const linkElementCopy = (0, _apidomDatamodel.cloneShallow)(linkElement);
+        linkElementCopy.operationRef?.meta.set('operation', operationElement);
+
+        /**
+         * Transclude Link Object containing Operation Object in its meta.
+         */
+        path.replaceWith(linkElementCopy);
+        return;
+      }
+      if ((0, _apidomDatamodel.isStringElement)(linkElement.operationId)) {
+        const operationId = (0, _apidomCore.toValue)(linkElement.operationId);
+        const reference = await this.toReference(url.unsanitize(this.reference.uri));
+        const operationPath = (0, _apidomTraverse.find)(reference.value.result, path => (0, _apidomNsOpenapi.isOperationElement)(path.node) && (0, _apidomDatamodel.isElement)(path.node.operationId) && path.node.operationId.equals(operationId));
+        operationElement = operationPath?.node;
+        // OperationElement not found by its operationId
+        if ((0, _ramdaAdjunct.isUndefined)(operationElement)) {
+          throw new _apidomError.ApiDOMStructuredError(`OperationElement(operationId=${operationId}) not found`, {
+            operationId
+          });
+        }
+        const linkElementCopy = (0, _apidomDatamodel.cloneShallow)(linkElement);
+        linkElementCopy.operationId?.meta.set('operation', operationElement);
+
+        /**
+         * Transclude Link Object containing Operation Object in its meta.
+         */
+        path.replaceWith(linkElementCopy);
+      }
+    } catch (error) {
+      const refFieldName = (0, _apidomDatamodel.isStringElement)(linkElement.operationRef) ? 'operationRef' : 'operationId';
+      const refFieldValue = (0, _apidomDatamodel.isStringElement)(linkElement.operationRef) ? (0, _apidomCore.toValue)(linkElement.operationRef) : (0, _apidomCore.toValue)(linkElement.operationId);
+      this.handleError(`Error while dereferencing Link Object. Cannot resolve ${refFieldName} "${refFieldValue}": ${error.message}`, error, linkElement, refFieldName, refFieldValue, path);
+    }
+  }
+  async ExampleElement(path) {
+    const exampleElement = path.node;
+
+    // ignore ExampleElement without externalValue field
+    if (!(0, _apidomDatamodel.isStringElement)(exampleElement.externalValue)) {
+      return;
+    }
+
+    // value and externalValue fields are mutually exclusive
+    if (exampleElement.hasKey('value') && (0, _apidomDatamodel.isStringElement)(exampleElement.externalValue)) {
+      throw new _apidomError.ApiDOMStructuredError('ExampleElement value and externalValue fields are mutually exclusive', {
+        value: (0, _apidomCore.toValue)(exampleElement.value),
+        externalValue: (0, _apidomCore.toValue)(exampleElement.externalValue)
+      });
+    }
+    const retrievalURI = this.toBaseURI((0, _apidomCore.toValue)(exampleElement.externalValue));
+    const isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+    const isExternalReference = !isInternalReference;
+
+    // ignore resolving external Example Objects
+    if (!this.options.resolve.internal && isInternalReference) {
+      // skip traversing this Example element but traverse all it's child elements
+      return;
+    }
+    // ignore resolving external Example Objects
+    if (!this.options.resolve.external && isExternalReference) {
+      // skip traversing this Example element but traverse all it's child elements
+      return;
+    }
+    try {
+      const reference = await this.toReference((0, _apidomCore.toValue)(exampleElement.externalValue));
+
+      // shallow clone of the referenced element
+      const valueElement = (0, _apidomDatamodel.cloneShallow)(reference.value.result);
+      // annotate operation element with info about origin
+      valueElement.meta.set('ref-origin', reference.uri);
+      valueElement.meta.set('ref-type', exampleElement.element);
+      const exampleElementCopy = (0, _apidomDatamodel.cloneShallow)(exampleElement);
+      exampleElementCopy.value = valueElement;
+
+      /**
+       * Transclude Example Object containing external value.
+       */
+      path.replaceWith(exampleElementCopy);
+    } catch (error) {
+      const externalValue = (0, _apidomCore.toValue)(exampleElement.externalValue);
+      this.handleError(`Error while dereferencing Example Object. Cannot resolve externalValue "${externalValue}": ${error.message}`, error, exampleElement, 'externalValue', externalValue, path);
+    }
+  }
+}
+var _default = exports.default = OpenAPI3_0DereferenceVisitor;