@speclynx/apidom-reference 6.0.6 → 6.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "6.0.6",
+  "version": "6.1.1",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "keywords": [
     "apidom",
@@ -299,33 +299,33 @@
   "author": "Vladimir Gorej",
   "license": "Apache-2.0",
   "dependencies": {
-    "@babel/runtime-corejs3": "^8.0.5",
-    "@speclynx/apidom-core": "6.0.6",
-    "@speclynx/apidom-datamodel": "6.0.6",
-    "@speclynx/apidom-error": "6.0.6",
-    "@speclynx/apidom-json-pointer": "6.0.6",
-    "@speclynx/apidom-ns-arazzo-1": "6.0.6",
-    "@speclynx/apidom-ns-asyncapi-2": "6.0.6",
-    "@speclynx/apidom-ns-json-schema-2020-12": "6.0.6",
-    "@speclynx/apidom-ns-openapi-2": "6.0.6",
-    "@speclynx/apidom-ns-openapi-3-0": "6.0.6",
-    "@speclynx/apidom-ns-openapi-3-1": "6.0.6",
-    "@speclynx/apidom-ns-overlay-1": "6.0.6",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "6.0.6",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "6.0.6",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "6.0.6",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "6.0.6",
-    "@speclynx/apidom-parser-adapter-json": "6.0.6",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "6.0.6",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "6.0.6",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "6.0.6",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "6.0.6",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "6.0.6",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "6.0.6",
-    "@speclynx/apidom-parser-adapter-overlay-json-1": "6.0.6",
-    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "6.0.6",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "6.0.6",
-    "@speclynx/apidom-traverse": "6.0.6",
+    "@babel/runtime-corejs3": "^8.0.8",
+    "@speclynx/apidom-core": "6.1.1",
+    "@speclynx/apidom-datamodel": "6.1.1",
+    "@speclynx/apidom-error": "6.1.1",
+    "@speclynx/apidom-json-pointer": "6.1.1",
+    "@speclynx/apidom-ns-arazzo-1": "6.1.1",
+    "@speclynx/apidom-ns-asyncapi-2": "6.1.1",
+    "@speclynx/apidom-ns-json-schema-2020-12": "6.1.1",
+    "@speclynx/apidom-ns-openapi-2": "6.1.1",
+    "@speclynx/apidom-ns-openapi-3-0": "6.1.1",
+    "@speclynx/apidom-ns-openapi-3-1": "6.1.1",
+    "@speclynx/apidom-ns-overlay-1": "6.1.1",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "6.1.1",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "6.1.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "6.1.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "6.1.1",
+    "@speclynx/apidom-parser-adapter-json": "6.1.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "6.1.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "6.1.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "6.1.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "6.1.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "6.1.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "6.1.1",
+    "@speclynx/apidom-parser-adapter-overlay-json-1": "6.1.1",
+    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "6.1.1",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "6.1.1",
+    "@speclynx/apidom-traverse": "6.1.1",
     "@swaggerexpert/arazzo-runtime-expression": "^3.2.0",
     "axios": "^1.20.0",
     "picomatch": "^4.0.7",
@@ -346,5 +346,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "7c95b638dbcf8687d16da176d0f7aea114a7b971"
+  "gitHead": "c25778097fd33bf5f0d61de6843a6240571f94b3"
 }

package/src/bundle/strategies/asyncapi-2/visitor.cjs

@@ -345,6 +345,11 @@ class AsyncAPI2BundleVisitor {
   }
   async ReferenceElement(path) {
     const referencingElement = path.node;
+
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
     const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;

package/src/bundle/strategies/asyncapi-2/visitor.mjs

@@ -337,6 +337,11 @@ class AsyncAPI2BundleVisitor {
   }
   async ReferenceElement(path) {
     const referencingElement = path.node;
+
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!isStringElement(referencingElement.$ref)) {
+      return;
+    }
     const $ref = toValue(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;

package/src/bundle/strategies/openapi-2/visitor.cjs

@@ -313,6 +313,10 @@ class OpenAPI2BundleVisitor {
    * and refraction helpers, so the shared logic is parameterized here.
    */
   async bundleReference(path, referencingElement, isSemanticReference, isReferenceLike, refractReferenceFn, label) {
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
     const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;

package/src/bundle/strategies/openapi-2/visitor.mjs

@@ -305,6 +305,10 @@ class OpenAPI2BundleVisitor {
    * and refraction helpers, so the shared logic is parameterized here.
    */
   async bundleReference(path, referencingElement, isSemanticReference, isReferenceLike, refractReferenceFn, label) {
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!isStringElement(referencingElement.$ref)) {
+      return;
+    }
     const $ref = toValue(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;

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

@@ -324,6 +324,11 @@ class OpenAPI3_0BundleVisitor {
   }
   async ReferenceElement(path) {
     const referencingElement = path.node;
+
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
     const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;
@@ -459,98 +464,108 @@ class OpenAPI3_0BundleVisitor {
    * Path Item Object is not a Components Object field in OpenAPI 3.0
    * (unlike 3.1 which has `components.pathItems`). An external Path Item
    * reference therefore cannot be hoisted; it is inlined in place instead,
-   * after bundling its own external references.
+   * after bundling its own external references. It is inlined on leave, once
+   * the sibling fields of the referencing Path Item have been bundled, so the
+   * traversal doesn't descend into the inlined copy and inline the `$ref` left
+   * in it to break a cycle again.
    */
-  async PathItemElement(path) {
-    const pathItemElement = path.node;
-
-    // ignore Path Item Objects without a $ref field
-    if (!(0, _apidomDatamodel.isStringElement)(pathItemElement.$ref)) {
-      return;
-    }
-    const $ref = (0, _apidomCore.toValue)(pathItemElement.$ref);
-    const retrievalURI = this.toBaseURI($ref);
-    const isInternalReference = this.entryURI === retrievalURI;
-    const isExternalReference = !isInternalReference;
-    if (isInternalReference) {
-      // normalize self-references to a bare fragment so the bundled
-      // document stays transferable; bare fragments are left untouched
-      pathItemElement.set('$ref', this.normalizeSelfReference($ref));
-      return;
-    }
-
-    // honor the resolve.external switch
-    if (!this.options.resolve.external && isExternalReference) {
-      return;
-    }
-    const $refBaseURI = url.resolve(retrievalURI, $ref);
-    const jsonPointer = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
-    const canonicalKey = `${retrievalURI}#${jsonPointer}`;
+  PathItemElement = {
+    leave: async path => {
+      const pathItemElement = path.node;
 
-    // a circular external Path Item reference cannot be inlined without
-    // recursing forever; leave the $ref in place to break the cycle
-    if (this.inlineStack.has(canonicalKey)) {
-      return;
-    }
-    try {
-      // detect maximum depth of bundling
-      if (this.reference.depth >= this.options.bundle.maxDepth) {
-        throw new _MaximumBundleDepthError.default(`Maximum bundle depth of "${this.options.bundle.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
-          maxDepth: this.options.bundle.maxDepth,
-          uri: this.reference.uri
-        });
+      // ignore Path Item Objects without a $ref field
+      if (!(0, _apidomDatamodel.isStringElement)(pathItemElement.$ref)) {
+        return;
+      }
+      const $ref = (0, _apidomCore.toValue)(pathItemElement.$ref);
+      const retrievalURI = this.toBaseURI($ref);
+      const isInternalReference = this.entryURI === retrievalURI;
+      const isExternalReference = !isInternalReference;
+      if (isInternalReference) {
+        // normalize self-references to a bare fragment so the bundled
+        // document stays transferable; bare fragments are left untouched
+        pathItemElement.set('$ref', this.normalizeSelfReference($ref));
+        return;
       }
-      const reference = await this.toReference($ref);
-      let referencedElement = (0, _apidomJsonPointer.evaluate)(reference.value.result, jsonPointer);
 
-      // apply Path Item semantics to the referenced fragment
-      if (!(0, _apidomNsOpenapi.isPathItemElement)(referencedElement)) {
-        const cached = this.getRefracted(referencedElement, 'pathItem');
-        if (cached !== undefined) {
-          referencedElement = cached;
-        } else {
-          const sourceElement = referencedElement;
-          referencedElement = (0, _apidomNsOpenapi.refractPathItem)(referencedElement);
-          this.setRefracted(sourceElement, 'pathItem', referencedElement);
+      // honor the resolve.external switch
+      if (!this.options.resolve.external && isExternalReference) {
+        return;
+      }
+      const $refBaseURI = url.resolve(retrievalURI, $ref);
+      const jsonPointer = _apidomJsonPointer.URIFragmentIdentifier.fromURIReference($refBaseURI);
+      const canonicalKey = `${retrievalURI}#${jsonPointer}`;
+
+      // a circular external Path Item reference cannot be inlined without
+      // recursing forever; leave the $ref in place to break the cycle. It ends
+      // up in the entry document, so it has to resolve from there
+      if (this.inlineStack.has(canonicalKey)) {
+        const targetURI = url.resolve(this.reference.uri, $ref);
+        if (url.resolve(this.entryURI, $ref) !== targetURI) {
+          pathItemElement.set('$ref', url.relative(this.entryURI, targetURI));
         }
+        return;
       }
-
-      // own a copy and bundle the external references it contains
-      const inlinedElement = (0, _apidomDatamodel.cloneDeep)(referencedElement);
-      this.inlineStack.add(canonicalKey);
-      const visitor = new OpenAPI3_0BundleVisitor({
-        reference,
-        options: this.options,
-        assignments: this.assignments,
-        reservedNames: this.reservedNames,
-        refractCache: this.refractCache,
-        inlineStack: this.inlineStack
-      });
-      let bundledElement;
       try {
-        bundledElement = await (0, _apidomTraverse.traverseAsync)(inlinedElement, visitor, {
-          mutable: true
+        // detect maximum depth of bundling
+        if (this.reference.depth >= this.options.bundle.maxDepth) {
+          throw new _MaximumBundleDepthError.default(`Maximum bundle depth of "${this.options.bundle.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
+            maxDepth: this.options.bundle.maxDepth,
+            uri: this.reference.uri
+          });
+        }
+        const reference = await this.toReference($ref);
+        let referencedElement = (0, _apidomJsonPointer.evaluate)(reference.value.result, jsonPointer);
+
+        // apply Path Item semantics to the referenced fragment
+        if (!(0, _apidomNsOpenapi.isPathItemElement)(referencedElement)) {
+          const cached = this.getRefracted(referencedElement, 'pathItem');
+          if (cached !== undefined) {
+            referencedElement = cached;
+          } else {
+            const sourceElement = referencedElement;
+            referencedElement = (0, _apidomNsOpenapi.refractPathItem)(referencedElement);
+            this.setRefracted(sourceElement, 'pathItem', referencedElement);
+          }
+        }
+
+        // own a copy and bundle the external references it contains
+        const inlinedElement = (0, _apidomDatamodel.cloneDeep)(referencedElement);
+        this.inlineStack.add(canonicalKey);
+        const visitor = new OpenAPI3_0BundleVisitor({
+          reference,
+          options: this.options,
+          assignments: this.assignments,
+          reservedNames: this.reservedNames,
+          refractCache: this.refractCache,
+          inlineStack: this.inlineStack
         });
-      } finally {
-        this.inlineStack.delete(canonicalKey);
-      }
+        let bundledElement;
+        try {
+          bundledElement = await (0, _apidomTraverse.traverseAsync)(inlinedElement, visitor, {
+            mutable: true
+          });
+        } finally {
+          this.inlineStack.delete(canonicalKey);
+        }
 
-      // merge sibling fields from the referencing Path Item over the referenced
-      // one. The referencing `$ref` is being resolved away and is skipped; the
-      // referenced element keeps its own `$ref` if one survived (i.e. it was
-      // left in place to break a circular external Path Item chain).
-      pathItemElement.forEach((_value, keyElement, item) => {
-        const key = (0, _apidomCore.toValue)(keyElement);
-        if (key === '$ref') return;
-        bundledElement.remove(key);
-        bundledElement.content.push(item);
-      });
-      bundledElement.meta.set('ref-origin', reference.uri);
-      path.replaceWith(bundledElement);
-    } catch (error) {
-      this.handleError(`Error while bundling Path Item Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, pathItemElement, '$ref', $ref, path);
+        // merge sibling fields from the referencing Path Item over the referenced
+        // one. The referencing `$ref` is being resolved away and is skipped; the
+        // referenced element keeps its own `$ref` if one survived (i.e. it was
+        // left in place to break a circular external Path Item chain).
+        pathItemElement.forEach((_value, keyElement, item) => {
+          const key = (0, _apidomCore.toValue)(keyElement);
+          if (key === '$ref') return;
+          bundledElement.remove(key);
+          bundledElement.content.push(item);
+        });
+        bundledElement.meta.set('ref-origin', reference.uri);
+        path.replaceWith(bundledElement);
+      } catch (error) {
+        this.handleError(`Error while bundling Path Item Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, pathItemElement, '$ref', $ref, path);
+      }
     }
-  }
+  };
 
   /**
    * Example Object `externalValue` points at arbitrary external content that

package/src/bundle/strategies/openapi-3-0/visitor.mjs

@@ -316,6 +316,11 @@ class OpenAPI3_0BundleVisitor {
   }
   async ReferenceElement(path) {
     const referencingElement = path.node;
+
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!isStringElement(referencingElement.$ref)) {
+      return;
+    }
     const $ref = toValue(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;
@@ -451,98 +456,108 @@ class OpenAPI3_0BundleVisitor {
    * Path Item Object is not a Components Object field in OpenAPI 3.0
    * (unlike 3.1 which has `components.pathItems`). An external Path Item
    * reference therefore cannot be hoisted; it is inlined in place instead,
-   * after bundling its own external references.
+   * after bundling its own external references. It is inlined on leave, once
+   * the sibling fields of the referencing Path Item have been bundled, so the
+   * traversal doesn't descend into the inlined copy and inline the `$ref` left
+   * in it to break a cycle again.
    */
-  async PathItemElement(path) {
-    const pathItemElement = path.node;
-
-    // ignore Path Item Objects without a $ref field
-    if (!isStringElement(pathItemElement.$ref)) {
-      return;
-    }
-    const $ref = toValue(pathItemElement.$ref);
-    const retrievalURI = this.toBaseURI($ref);
-    const isInternalReference = this.entryURI === retrievalURI;
-    const isExternalReference = !isInternalReference;
-    if (isInternalReference) {
-      // normalize self-references to a bare fragment so the bundled
-      // document stays transferable; bare fragments are left untouched
-      pathItemElement.set('$ref', this.normalizeSelfReference($ref));
-      return;
-    }
-
-    // honor the resolve.external switch
-    if (!this.options.resolve.external && isExternalReference) {
-      return;
-    }
-    const $refBaseURI = url.resolve(retrievalURI, $ref);
-    const jsonPointer = URIFragmentIdentifier.fromURIReference($refBaseURI);
-    const canonicalKey = `${retrievalURI}#${jsonPointer}`;
+  PathItemElement = {
+    leave: async path => {
+      const pathItemElement = path.node;
 
-    // a circular external Path Item reference cannot be inlined without
-    // recursing forever; leave the $ref in place to break the cycle
-    if (this.inlineStack.has(canonicalKey)) {
-      return;
-    }
-    try {
-      // detect maximum depth of bundling
-      if (this.reference.depth >= this.options.bundle.maxDepth) {
-        throw new MaximumBundleDepthError(`Maximum bundle depth of "${this.options.bundle.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
-          maxDepth: this.options.bundle.maxDepth,
-          uri: this.reference.uri
-        });
+      // ignore Path Item Objects without a $ref field
+      if (!isStringElement(pathItemElement.$ref)) {
+        return;
+      }
+      const $ref = toValue(pathItemElement.$ref);
+      const retrievalURI = this.toBaseURI($ref);
+      const isInternalReference = this.entryURI === retrievalURI;
+      const isExternalReference = !isInternalReference;
+      if (isInternalReference) {
+        // normalize self-references to a bare fragment so the bundled
+        // document stays transferable; bare fragments are left untouched
+        pathItemElement.set('$ref', this.normalizeSelfReference($ref));
+        return;
       }
-      const reference = await this.toReference($ref);
-      let referencedElement = evaluate(reference.value.result, jsonPointer);
 
-      // apply Path Item semantics to the referenced fragment
-      if (!isPathItemElement(referencedElement)) {
-        const cached = this.getRefracted(referencedElement, 'pathItem');
-        if (cached !== undefined) {
-          referencedElement = cached;
-        } else {
-          const sourceElement = referencedElement;
-          referencedElement = refractPathItem(referencedElement);
-          this.setRefracted(sourceElement, 'pathItem', referencedElement);
+      // honor the resolve.external switch
+      if (!this.options.resolve.external && isExternalReference) {
+        return;
+      }
+      const $refBaseURI = url.resolve(retrievalURI, $ref);
+      const jsonPointer = URIFragmentIdentifier.fromURIReference($refBaseURI);
+      const canonicalKey = `${retrievalURI}#${jsonPointer}`;
+
+      // a circular external Path Item reference cannot be inlined without
+      // recursing forever; leave the $ref in place to break the cycle. It ends
+      // up in the entry document, so it has to resolve from there
+      if (this.inlineStack.has(canonicalKey)) {
+        const targetURI = url.resolve(this.reference.uri, $ref);
+        if (url.resolve(this.entryURI, $ref) !== targetURI) {
+          pathItemElement.set('$ref', url.relative(this.entryURI, targetURI));
         }
+        return;
       }
-
-      // own a copy and bundle the external references it contains
-      const inlinedElement = cloneDeep(referencedElement);
-      this.inlineStack.add(canonicalKey);
-      const visitor = new OpenAPI3_0BundleVisitor({
-        reference,
-        options: this.options,
-        assignments: this.assignments,
-        reservedNames: this.reservedNames,
-        refractCache: this.refractCache,
-        inlineStack: this.inlineStack
-      });
-      let bundledElement;
       try {
-        bundledElement = await traverseAsync(inlinedElement, visitor, {
-          mutable: true
+        // detect maximum depth of bundling
+        if (this.reference.depth >= this.options.bundle.maxDepth) {
+          throw new MaximumBundleDepthError(`Maximum bundle depth of "${this.options.bundle.maxDepth}" has been exceeded in file "${this.reference.uri}"`, {
+            maxDepth: this.options.bundle.maxDepth,
+            uri: this.reference.uri
+          });
+        }
+        const reference = await this.toReference($ref);
+        let referencedElement = evaluate(reference.value.result, jsonPointer);
+
+        // apply Path Item semantics to the referenced fragment
+        if (!isPathItemElement(referencedElement)) {
+          const cached = this.getRefracted(referencedElement, 'pathItem');
+          if (cached !== undefined) {
+            referencedElement = cached;
+          } else {
+            const sourceElement = referencedElement;
+            referencedElement = refractPathItem(referencedElement);
+            this.setRefracted(sourceElement, 'pathItem', referencedElement);
+          }
+        }
+
+        // own a copy and bundle the external references it contains
+        const inlinedElement = cloneDeep(referencedElement);
+        this.inlineStack.add(canonicalKey);
+        const visitor = new OpenAPI3_0BundleVisitor({
+          reference,
+          options: this.options,
+          assignments: this.assignments,
+          reservedNames: this.reservedNames,
+          refractCache: this.refractCache,
+          inlineStack: this.inlineStack
         });
-      } finally {
-        this.inlineStack.delete(canonicalKey);
-      }
+        let bundledElement;
+        try {
+          bundledElement = await traverseAsync(inlinedElement, visitor, {
+            mutable: true
+          });
+        } finally {
+          this.inlineStack.delete(canonicalKey);
+        }
 
-      // merge sibling fields from the referencing Path Item over the referenced
-      // one. The referencing `$ref` is being resolved away and is skipped; the
-      // referenced element keeps its own `$ref` if one survived (i.e. it was
-      // left in place to break a circular external Path Item chain).
-      pathItemElement.forEach((_value, keyElement, item) => {
-        const key = toValue(keyElement);
-        if (key === '$ref') return;
-        bundledElement.remove(key);
-        bundledElement.content.push(item);
-      });
-      bundledElement.meta.set('ref-origin', reference.uri);
-      path.replaceWith(bundledElement);
-    } catch (error) {
-      this.handleError(`Error while bundling Path Item Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, pathItemElement, '$ref', $ref, path);
+        // merge sibling fields from the referencing Path Item over the referenced
+        // one. The referencing `$ref` is being resolved away and is skipped; the
+        // referenced element keeps its own `$ref` if one survived (i.e. it was
+        // left in place to break a circular external Path Item chain).
+        pathItemElement.forEach((_value, keyElement, item) => {
+          const key = toValue(keyElement);
+          if (key === '$ref') return;
+          bundledElement.remove(key);
+          bundledElement.content.push(item);
+        });
+        bundledElement.meta.set('ref-origin', reference.uri);
+        path.replaceWith(bundledElement);
+      } catch (error) {
+        this.handleError(`Error while bundling Path Item Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, pathItemElement, '$ref', $ref, path);
+      }
     }
-  }
+  };
 
   /**
    * Example Object `externalValue` points at arbitrary external content that

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

@@ -422,6 +422,11 @@ class OpenAPI3_1BundleVisitor {
   };
   async ReferenceElement(path) {
     const referencingElement = path.node;
+
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
     const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;

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

@@ -414,6 +414,11 @@ class OpenAPI3_1BundleVisitor {
   };
   async ReferenceElement(path) {
     const referencingElement = path.node;
+
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!isStringElement(referencingElement.$ref)) {
+      return;
+    }
     const $ref = toValue(referencingElement.$ref);
     const retrievalURI = this.toBaseURI($ref);
     const isInternalReference = this.entryURI === retrievalURI;

package/src/dereference/strategies/asyncapi-2/visitor.cjs

@@ -202,6 +202,11 @@ class AsyncAPI2DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();

package/src/dereference/strategies/asyncapi-2/visitor.mjs

@@ -193,6 +193,11 @@ class AsyncAPI2DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!isStringElement(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();

package/src/dereference/strategies/openapi-2/visitor.cjs

@@ -202,6 +202,11 @@ class OpenAPI2DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();
@@ -505,6 +510,11 @@ class OpenAPI2DereferenceVisitor {
   async JSONReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();

package/src/dereference/strategies/openapi-2/visitor.mjs

@@ -193,6 +193,11 @@ class OpenAPI2DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!isStringElement(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();
@@ -496,6 +501,11 @@ class OpenAPI2DereferenceVisitor {
   async JSONReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!isStringElement(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();

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

@@ -203,6 +203,11 @@ class OpenAPI3_0DereferenceVisitor {
   async ReferenceElement(path) {
     const referencingElement = path.node;
 
+    // ignore Reference Object without a string $ref, e.g. an empty YAML value
+    if (!(0, _apidomDatamodel.isStringElement)(referencingElement.$ref)) {
+      return;
+    }
+
     // skip current referencing element as it's already been access
     if (this.indirections.includes(referencingElement)) {
       path.skip();