@speclynx/apidom-reference 3.0.0 → 3.2.0

package/package.json

@@ -1,7 +1,30 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
+  "keywords": [
+    "apidom",
+    "api",
+    "$ref",
+    "dereference",
+    "reference",
+    "resolve",
+    "resolver",
+    "bundle",
+    "openapi",
+    "swagger",
+    "oas",
+    "asyncapi",
+    "arazzo",
+    "json-schema",
+    "json",
+    "yaml",
+    "spec",
+    "specification",
+    "parse",
+    "typescript",
+    "javascript"
+  ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org",
@@ -231,29 +254,29 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "3.0.0",
-    "@speclynx/apidom-datamodel": "3.0.0",
-    "@speclynx/apidom-error": "3.0.0",
-    "@speclynx/apidom-json-pointer": "3.0.0",
-    "@speclynx/apidom-ns-arazzo-1": "3.0.0",
-    "@speclynx/apidom-ns-asyncapi-2": "3.0.0",
-    "@speclynx/apidom-ns-json-schema-2020-12": "3.0.0",
-    "@speclynx/apidom-ns-openapi-2": "3.0.0",
-    "@speclynx/apidom-ns-openapi-3-0": "3.0.0",
-    "@speclynx/apidom-ns-openapi-3-1": "3.0.0",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "3.0.0",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "3.0.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "3.0.0",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "3.0.0",
-    "@speclynx/apidom-parser-adapter-json": "3.0.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "3.0.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "3.0.0",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "3.0.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "3.0.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "3.0.0",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "3.0.0",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "3.0.0",
-    "@speclynx/apidom-traverse": "3.0.0",
+    "@speclynx/apidom-core": "3.2.0",
+    "@speclynx/apidom-datamodel": "3.2.0",
+    "@speclynx/apidom-error": "3.2.0",
+    "@speclynx/apidom-json-pointer": "3.2.0",
+    "@speclynx/apidom-ns-arazzo-1": "3.2.0",
+    "@speclynx/apidom-ns-asyncapi-2": "3.2.0",
+    "@speclynx/apidom-ns-json-schema-2020-12": "3.2.0",
+    "@speclynx/apidom-ns-openapi-2": "3.2.0",
+    "@speclynx/apidom-ns-openapi-3-0": "3.2.0",
+    "@speclynx/apidom-ns-openapi-3-1": "3.2.0",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "3.2.0",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "3.2.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "3.2.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "3.2.0",
+    "@speclynx/apidom-parser-adapter-json": "3.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "3.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "3.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "3.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "3.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "3.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "3.2.0",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "3.2.0",
+    "@speclynx/apidom-traverse": "3.2.0",
     "@swaggerexpert/arazzo-runtime-expression": "^2.0.3",
     "axios": "^1.13.5",
     "picomatch": "^4.0.3",
@@ -275,5 +298,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "cb94ec84ea789d121801065876e7a91799a363d0"
+  "gitHead": "eeb2f01cd34fb0a95617f02bc1b6683aefc028f2"
 }

package/src/dereference/index.cjs

@@ -10,6 +10,7 @@ var _File = _interopRequireDefault(require("../File.cjs"));
 var plugins = _interopRequireWildcard(require("../util/plugins.cjs"));
 var _UnmatchedDereferenceStrategyError = _interopRequireDefault(require("../errors/UnmatchedDereferenceStrategyError.cjs"));
 var _DereferenceError = _interopRequireDefault(require("../errors/DereferenceError.cjs"));
+var _UnresolvableReferenceError = _interopRequireDefault(require("../errors/UnresolvableReferenceError.cjs"));
 var _index = _interopRequireDefault(require("../parse/index.cjs"));
 var _util = require("../options/util.cjs");
 var url = _interopRequireWildcard(require("../util/url.cjs"));
@@ -46,6 +47,9 @@ const dereferenceApiDOM = async (element, options) => {
     // unwrap the element from ParseResult assuming first element is the actual result
     return surrogateWrapping ? result.get(0) : result;
   } catch (error) {
+    if (error instanceof _UnresolvableReferenceError.default) {
+      throw error;
+    }
     throw new _DereferenceError.default(`Error while dereferencing file "${file.uri}"`, {
       cause: error
     });

package/src/dereference/index.mjs

@@ -4,6 +4,7 @@ import File from "../File.mjs";
 import * as plugins from "../util/plugins.mjs";
 import UnmatchedDereferenceStrategyError from "../errors/UnmatchedDereferenceStrategyError.mjs";
 import DereferenceError from "../errors/DereferenceError.mjs";
+import UnresolvableReferenceError from "../errors/UnresolvableReferenceError.mjs";
 import parse from "../parse/index.mjs";
 import { merge as mergeOptions } from "../options/util.mjs";
 import * as url from "../util/url.mjs";
@@ -40,6 +41,9 @@ export const dereferenceApiDOM = async (element, options) => {
     // unwrap the element from ParseResult assuming first element is the actual result
     return surrogateWrapping ? result.get(0) : result;
   } catch (error) {
+    if (error instanceof UnresolvableReferenceError) {
+      throw error;
+    }
     throw new DereferenceError(`Error while dereferencing file "${file.uri}"`, {
       cause: error
     });

package/src/dereference/strategies/apidom/visitor.cjs

@@ -11,6 +11,7 @@ var _apidomCore = require("@speclynx/apidom-core");
 var _apidomTraverse = require("@speclynx/apidom-traverse");
 var _apidomJsonPointer = require("@speclynx/apidom-json-pointer");
 var _MaximumResolveDepthError = _interopRequireDefault(require("../../../errors/MaximumResolveDepthError.cjs"));
+var _UnresolvableReferenceError = _interopRequireDefault(require("../../../errors/UnresolvableReferenceError.cjs"));
 var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 var _index = _interopRequireDefault(require("../../../parse/index.cjs"));
 var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
@@ -48,7 +49,10 @@ class ApiDOMDereferenceVisitor {
   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}"`);
+      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 {
@@ -85,6 +89,72 @@ class ApiDOMDereferenceVisitor {
     }
     return mutableReference;
   }
+
+  /**
+   * Handles an error according to the continueOnError option.
+   *
+   * For new errors: wraps in UnresolvableReferenceError with structured context.
+   * 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;
+    let location;
+    (0, _apidomTraverse.traverse)(this.reference.value.result, {
+      enter(p) {
+        if (p.node === referencingElement) {
+          location = p.formatPath();
+          p.stop();
+        }
+      }
+    });
+    location ??= visitorPath.formatPath();
+    const codeFrame = (0, _apidomCore.toYAML)(referencingElement);
+    const hop = {
+      uri,
+      type,
+      refFieldName,
+      refFieldValue,
+      location,
+      codeFrame
+    };
+    let unresolvedError;
+    if (error instanceof _UnresolvableReferenceError.default) {
+      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 RefElement(path) {
     const refElement = path.node;
     const {
@@ -110,69 +180,79 @@ class ApiDOMDereferenceVisitor {
       path.skip();
       return;
     }
-    const reference = await this.toReference(refNormalizedURI);
-    const refBaseURI = url.resolve(retrievalURI, refNormalizedURI);
-    const elementID = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference(refBaseURI);
-    let referencedElement = (0, _elementId.evaluate)(elementID, reference.value.result);
-    if (!(0, _apidomDatamodel.isElement)(referencedElement)) {
-      throw new _apidomError.ApiDOMError(`Referenced element with id="${elementID}" was not found`);
-    }
-    if (refElement === referencedElement) {
-      throw new _apidomError.ApiDOMError('RefElement cannot reference itself');
-    }
-    if ((0, _apidomDatamodel.isRefElement)(referencedElement)) {
-      throw new _apidomError.ApiDOMError('RefElement cannot reference another RefElement');
-    }
-    if (isExternalReference) {
-      // dive deep into the fragment
-      const visitor = new ApiDOMDereferenceVisitor({
-        reference,
-        options: this.options
-      });
-      referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
-        mutable: true
-      });
-    }
-
-    /**
-     * When path is used, it references the given property of the referenced element.
-     * Valid paths are: 'element', 'content', 'meta', 'attributes'.
-     */
-    const referencedElementPath = (0, _apidomCore.toValue)(refElement.path);
-    if (referencedElementPath !== 'element' && (0, _apidomDatamodel.isElement)(referencedElement)) {
-      referencedElement = (0, _apidomDatamodel.refract)(referencedElement[referencedElementPath]);
-    }
+    try {
+      const reference = await this.toReference(refNormalizedURI);
+      const refBaseURI = url.resolve(retrievalURI, refNormalizedURI);
+      const elementID = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference(refBaseURI);
+      let referencedElement = (0, _elementId.evaluate)(elementID, reference.value.result);
+      if (!(0, _apidomDatamodel.isElement)(referencedElement)) {
+        throw new _apidomError.ApiDOMStructuredError(`Referenced element with id="${elementID}" was not found`, {
+          elementID
+        });
+      }
+      if (refElement === referencedElement) {
+        throw new _apidomError.ApiDOMStructuredError(`RefElement with id="${elementID}" cannot reference itself`, {
+          elementID
+        });
+      }
+      if ((0, _apidomDatamodel.isRefElement)(referencedElement)) {
+        throw new _apidomError.ApiDOMStructuredError(`RefElement with id="${elementID}" cannot reference another RefElement`, {
+          elementID
+        });
+      }
+      if (isExternalReference) {
+        // dive deep into the fragment
+        const visitor = new ApiDOMDereferenceVisitor({
+          reference,
+          options: this.options
+        });
+        referencedElement = await (0, _apidomTraverse.traverseAsync)(referencedElement, visitor, {
+          mutable: true
+        });
+      }
 
-    /**
-     * Transclusion of a Ref Element SHALL be defined in the if/else block below.
-     */
-    // ancestors[0] is the grandparent (nearest ancestor from getAncestorNodes())
-    const grandparent = ancestors[0];
-    if ((0, _apidomDatamodel.isObjectElement)(referencedElement) && (0, _apidomDatamodel.isObjectElement)(grandparent) && Array.isArray(parent) && typeof key === 'number') {
-      /**
-       * If the Ref Element is held by an Object Element and references an Object Element,
-       * its content entries SHALL be inserted in place of the Ref Element.
-       */
-      parent.splice(key, 1, ...referencedElement.content);
-    } else if ((0, _apidomDatamodel.isArrayElement)(referencedElement) && Array.isArray(parent) && typeof key === 'number') {
       /**
-       * If the Ref Element is held by an Array Element and references an Array Element,
-       * its content entries SHALL be inserted in place of the Ref Element.
+       * When path is used, it references the given property of the referenced element.
+       * Valid paths are: 'element', 'content', 'meta', 'attributes'.
        */
-      parent.splice(key, 1, ...referencedElement.content);
-    } else if ((0, _apidomDatamodel.isMemberElement)(parent)) {
-      /**
-       * The Ref Element is substituted by the Element it references.
-       */
-      parent.value = referencedElement;
-    } else if (Array.isArray(parent)) {
+      const referencedElementPath = (0, _apidomCore.toValue)(refElement.path);
+      if (referencedElementPath !== 'element' && (0, _apidomDatamodel.isElement)(referencedElement)) {
+        referencedElement = (0, _apidomDatamodel.refract)(referencedElement[referencedElementPath]);
+      }
+
       /**
-       * The Ref Element is substituted by the Element it references.
+       * Transclusion of a Ref Element SHALL be defined in the if/else block below.
        */
-      parent[key] = referencedElement;
-    }
-    if (!parent) {
-      path.replaceWith(referencedElement);
+      // ancestors[0] is the grandparent (nearest ancestor from getAncestorNodes())
+      const grandparent = ancestors[0];
+      if ((0, _apidomDatamodel.isObjectElement)(referencedElement) && (0, _apidomDatamodel.isObjectElement)(grandparent) && Array.isArray(parent) && typeof key === 'number') {
+        /**
+         * If the Ref Element is held by an Object Element and references an Object Element,
+         * its content entries SHALL be inserted in place of the Ref Element.
+         */
+        parent.splice(key, 1, ...referencedElement.content);
+      } else if ((0, _apidomDatamodel.isArrayElement)(referencedElement) && Array.isArray(parent) && typeof key === 'number') {
+        /**
+         * If the Ref Element is held by an Array Element and references an Array Element,
+         * its content entries SHALL be inserted in place of the Ref Element.
+         */
+        parent.splice(key, 1, ...referencedElement.content);
+      } else if ((0, _apidomDatamodel.isMemberElement)(parent)) {
+        /**
+         * The Ref Element is substituted by the Element it references.
+         */
+        parent.value = referencedElement;
+      } else if (Array.isArray(parent)) {
+        /**
+         * The Ref Element is substituted by the Element it references.
+         */
+        parent[key] = referencedElement;
+      }
+      if (!parent) {
+        path.replaceWith(referencedElement);
+      }
+    } catch (error) {
+      this.handleError(`Error while dereferencing Ref Element. Cannot resolve ref "${refURI}": ${error.message}`, error, refElement, null, refURI, path);
     }
   }
 }

package/src/dereference/strategies/apidom/visitor.mjs

@@ -1,10 +1,11 @@
 import { propEq } from 'ramda';
-import { ApiDOMError } from '@speclynx/apidom-error';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 import { isElement, isMemberElement, isArrayElement, isObjectElement, isRefElement, refract, cloneDeep } from '@speclynx/apidom-datamodel';
-import { toValue } from '@speclynx/apidom-core';
-import { traverseAsync } from '@speclynx/apidom-traverse';
+import { toValue, toYAML } from '@speclynx/apidom-core';
+import { traverse, traverseAsync } from '@speclynx/apidom-traverse';
 import { URIFragmentIdentifier } from '@speclynx/apidom-json-pointer';
 import MaximumResolveDepthError from "../../../errors/MaximumResolveDepthError.mjs";
+import UnresolvableReferenceError from "../../../errors/UnresolvableReferenceError.mjs";
 import * as url from "../../../util/url.mjs";
 import parse from "../../../parse/index.mjs";
 import Reference from "../../../Reference.mjs";
@@ -41,7 +42,10 @@ class ApiDOMDereferenceVisitor {
   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 {
@@ -78,6 +82,72 @@ class ApiDOMDereferenceVisitor {
     }
     return mutableReference;
   }
+
+  /**
+   * Handles an error according to the continueOnError option.
+   *
+   * For new errors: wraps in UnresolvableReferenceError with structured context.
+   * 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;
+    let location;
+    traverse(this.reference.value.result, {
+      enter(p) {
+        if (p.node === referencingElement) {
+          location = p.formatPath();
+          p.stop();
+        }
+      }
+    });
+    location ??= visitorPath.formatPath();
+    const codeFrame = toYAML(referencingElement);
+    const hop = {
+      uri,
+      type,
+      refFieldName,
+      refFieldValue,
+      location,
+      codeFrame
+    };
+    let unresolvedError;
+    if (error instanceof UnresolvableReferenceError) {
+      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 RefElement(path) {
     const refElement = path.node;
     const {
@@ -103,69 +173,79 @@ class ApiDOMDereferenceVisitor {
       path.skip();
       return;
     }
-    const reference = await this.toReference(refNormalizedURI);
-    const refBaseURI = url.resolve(retrievalURI, refNormalizedURI);
-    const elementID = URIFragmentIdentifier.fromURIReference(refBaseURI);
-    let referencedElement = evaluate(elementID, reference.value.result);
-    if (!isElement(referencedElement)) {
-      throw new ApiDOMError(`Referenced element with id="${elementID}" was not found`);
-    }
-    if (refElement === referencedElement) {
-      throw new ApiDOMError('RefElement cannot reference itself');
-    }
-    if (isRefElement(referencedElement)) {
-      throw new ApiDOMError('RefElement cannot reference another RefElement');
-    }
-    if (isExternalReference) {
-      // dive deep into the fragment
-      const visitor = new ApiDOMDereferenceVisitor({
-        reference,
-        options: this.options
-      });
-      referencedElement = await traverseAsync(referencedElement, visitor, {
-        mutable: true
-      });
-    }
-
-    /**
-     * When path is used, it references the given property of the referenced element.
-     * Valid paths are: 'element', 'content', 'meta', 'attributes'.
-     */
-    const referencedElementPath = toValue(refElement.path);
-    if (referencedElementPath !== 'element' && isElement(referencedElement)) {
-      referencedElement = refract(referencedElement[referencedElementPath]);
-    }
+    try {
+      const reference = await this.toReference(refNormalizedURI);
+      const refBaseURI = url.resolve(retrievalURI, refNormalizedURI);
+      const elementID = URIFragmentIdentifier.fromURIReference(refBaseURI);
+      let referencedElement = evaluate(elementID, reference.value.result);
+      if (!isElement(referencedElement)) {
+        throw new ApiDOMStructuredError(`Referenced element with id="${elementID}" was not found`, {
+          elementID
+        });
+      }
+      if (refElement === referencedElement) {
+        throw new ApiDOMStructuredError(`RefElement with id="${elementID}" cannot reference itself`, {
+          elementID
+        });
+      }
+      if (isRefElement(referencedElement)) {
+        throw new ApiDOMStructuredError(`RefElement with id="${elementID}" cannot reference another RefElement`, {
+          elementID
+        });
+      }
+      if (isExternalReference) {
+        // dive deep into the fragment
+        const visitor = new ApiDOMDereferenceVisitor({
+          reference,
+          options: this.options
+        });
+        referencedElement = await traverseAsync(referencedElement, visitor, {
+          mutable: true
+        });
+      }
 
-    /**
-     * Transclusion of a Ref Element SHALL be defined in the if/else block below.
-     */
-    // ancestors[0] is the grandparent (nearest ancestor from getAncestorNodes())
-    const grandparent = ancestors[0];
-    if (isObjectElement(referencedElement) && isObjectElement(grandparent) && Array.isArray(parent) && typeof key === 'number') {
-      /**
-       * If the Ref Element is held by an Object Element and references an Object Element,
-       * its content entries SHALL be inserted in place of the Ref Element.
-       */
-      parent.splice(key, 1, ...referencedElement.content);
-    } else if (isArrayElement(referencedElement) && Array.isArray(parent) && typeof key === 'number') {
       /**
-       * If the Ref Element is held by an Array Element and references an Array Element,
-       * its content entries SHALL be inserted in place of the Ref Element.
+       * When path is used, it references the given property of the referenced element.
+       * Valid paths are: 'element', 'content', 'meta', 'attributes'.
        */
-      parent.splice(key, 1, ...referencedElement.content);
-    } else if (isMemberElement(parent)) {
-      /**
-       * The Ref Element is substituted by the Element it references.
-       */
-      parent.value = referencedElement;
-    } else if (Array.isArray(parent)) {
+      const referencedElementPath = toValue(refElement.path);
+      if (referencedElementPath !== 'element' && isElement(referencedElement)) {
+        referencedElement = refract(referencedElement[referencedElementPath]);
+      }
+
       /**
-       * The Ref Element is substituted by the Element it references.
+       * Transclusion of a Ref Element SHALL be defined in the if/else block below.
        */
-      parent[key] = referencedElement;
-    }
-    if (!parent) {
-      path.replaceWith(referencedElement);
+      // ancestors[0] is the grandparent (nearest ancestor from getAncestorNodes())
+      const grandparent = ancestors[0];
+      if (isObjectElement(referencedElement) && isObjectElement(grandparent) && Array.isArray(parent) && typeof key === 'number') {
+        /**
+         * If the Ref Element is held by an Object Element and references an Object Element,
+         * its content entries SHALL be inserted in place of the Ref Element.
+         */
+        parent.splice(key, 1, ...referencedElement.content);
+      } else if (isArrayElement(referencedElement) && Array.isArray(parent) && typeof key === 'number') {
+        /**
+         * If the Ref Element is held by an Array Element and references an Array Element,
+         * its content entries SHALL be inserted in place of the Ref Element.
+         */
+        parent.splice(key, 1, ...referencedElement.content);
+      } else if (isMemberElement(parent)) {
+        /**
+         * The Ref Element is substituted by the Element it references.
+         */
+        parent.value = referencedElement;
+      } else if (Array.isArray(parent)) {
+        /**
+         * The Ref Element is substituted by the Element it references.
+         */
+        parent[key] = referencedElement;
+      }
+      if (!parent) {
+        path.replaceWith(referencedElement);
+      }
+    } catch (error) {
+      this.handleError(`Error while dereferencing Ref Element. Cannot resolve ref "${refURI}": ${error.message}`, error, refElement, null, refURI, path);
     }
   }
 }

package/src/dereference/strategies/arazzo-1/index.cjs

@@ -1,12 +1,11 @@
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
-var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 exports.__esModule = true;
 exports.resolveSchema$refField = exports.resolveSchema$idField = exports.maybeRefractToJSONSchemaElement = exports.default = void 0;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomTraverse = require("@speclynx/apidom-traverse");
-var _apidomNsArazzo = _interopRequireWildcard(require("@speclynx/apidom-ns-arazzo-1"));
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
 var _DereferenceStrategy = _interopRequireDefault(require("../DereferenceStrategy.cjs"));
 var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
 var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
@@ -42,7 +41,6 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
     return (0, _apidomNsArazzo.isArazzoSpecification1Element)(file.parseResult?.result);
   }
   async dereference(file, options) {
-    const namespace = new _apidomDatamodel.Namespace().use(_apidomNsArazzo.default);
     const immutableRefSet = options.dereference.refSet ?? new _ReferenceSet.default();
     const mutableRefSet = new _ReferenceSet.default();
     let refSet = immutableRefSet;
@@ -72,7 +70,6 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
     }
     const visitor = new _visitor.default({
       reference,
-      namespace,
       options
     });
     const dereferencedElement = await (0, _apidomTraverse.traverseAsync)(refSet.rootRef.value, visitor, {

package/src/dereference/strategies/arazzo-1/index.mjs

@@ -1,6 +1,6 @@
-import { Namespace, cloneDeep } from '@speclynx/apidom-datamodel';
+import { cloneDeep } from '@speclynx/apidom-datamodel';
 import { traverseAsync } from '@speclynx/apidom-traverse';
-import arazzo1Namespace, { isArazzoSpecification1Element, mediaTypes } from '@speclynx/apidom-ns-arazzo-1';
+import { isArazzoSpecification1Element, mediaTypes } from '@speclynx/apidom-ns-arazzo-1';
 import DereferenceStrategy from "../DereferenceStrategy.mjs";
 import Reference from "../../../Reference.mjs";
 import ReferenceSet from "../../../ReferenceSet.mjs";
@@ -29,7 +29,6 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
     return isArazzoSpecification1Element(file.parseResult?.result);
   }
   async dereference(file, options) {
-    const namespace = new Namespace().use(arazzo1Namespace);
     const immutableRefSet = options.dereference.refSet ?? new ReferenceSet();
     const mutableRefSet = new ReferenceSet();
     let refSet = immutableRefSet;
@@ -59,7 +58,6 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
     }
     const visitor = new Arazzo1DereferenceVisitor({
       reference,
-      namespace,
       options
     });
     const dereferencedElement = await traverseAsync(refSet.rootRef.value, visitor, {