@jentic/arazzo-resolver 1.0.0-alpha.24 → 1.0.0-alpha.25

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.25](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.24...v1.0.0-alpha.25) (2026-03-11)
+
+### Bug Fixes
+
+- **release:** fix issue in lerna not publishing _.cjs|_.mjs files ([8982184](https://github.com/jentic/jentic-arazzo-tools/commit/8982184ddae167b6f2a772114f9a9321f3b67d14))
+
 # [1.0.0-alpha.24](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.23...v1.0.0-alpha.24) (2026-03-11)
 
 **Note:** Version bump only for package @jentic/arazzo-resolver

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jentic/arazzo-resolver",
-  "version": "1.0.0-alpha.24",
+  "version": "1.0.0-alpha.25",
   "description": "Resolver for Arazzo Documents.",
   "keywords": [
     "arazzo",
@@ -49,7 +49,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@jentic/arazzo-parser": "1.0.0-alpha.24",
+    "@jentic/arazzo-parser": "1.0.0-alpha.25",
     "@speclynx/apidom-datamodel": "^4.0.3",
     "@speclynx/apidom-error": "^4.0.3",
     "@speclynx/apidom-ns-arazzo-1": "^4.0.3",
@@ -63,8 +63,7 @@
     "@speclynx/apidom-core": "^4.0.3"
   },
   "files": [
-    "src/**/*.mjs",
-    "src/**/*.cjs",
+    "src/",
     "dist/",
     "types/arazzo-resolver.d.ts",
     "LICENSE",
@@ -72,5 +71,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "4d69c9a6c690d8fac8938c7032f57258948d76ce"
+  "gitHead": "b9a3213b0561fc58e0491c7e638d6a96383befff"
 }

package/src/dereference/arazzo.cjs

@@ -0,0 +1,231 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.defaultOptions = void 0;
+exports.dereference = dereference;
+exports.dereferenceElement = dereferenceElement;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _arazzo = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/arazzo-1"));
+var _openapi = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-2"));
+var _openapi2 = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-3-0"));
+var _openapi3 = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-3-1"));
+var _json = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/json"));
+var _yaml = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/yaml-1-2"));
+var _binary = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/binary"));
+var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _arazzoParser = require("@jentic/arazzo-parser");
+var _DereferenceError = _interopRequireDefault(require("../errors/DereferenceError.cjs"));
+/**
+ * Options for dereferencing Arazzo Documents.
+ * @public
+ */
+
+/**
+ * Default reference options for dereferencing Arazzo Documents.
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {
+  resolve: {
+    resolvers: [..._arazzoParser.defaultArazzoOptions.resolve.resolvers]
+  },
+  parse: {
+    parsers: [..._arazzoParser.defaultArazzoOptions.parse.parsers, new _json.default({
+      allowEmpty: false
+    }), new _yaml.default({
+      allowEmpty: false
+    }), new _binary.default({
+      allowEmpty: false
+    })],
+    parserOpts: {
+      ..._arazzoParser.defaultArazzoOptions.parse.parserOpts
+    }
+  },
+  dereference: {
+    strategies: [new _arazzo.default(), new _openapi.default(), new _openapi2.default(), new _openapi3.default()],
+    strategyOpts: {
+      sourceDescriptions: false
+    }
+  }
+};
+
+/**
+ * Dereferences an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function resolves all JSON References ($ref) and Reusable Object references
+ * ($components.*) in the Arazzo Document.
+ *
+ * Source descriptions can optionally be dereferenced using strategy options:
+ * - `sourceDescriptions`: `true` (all) or `['name1', 'name2']` (specific names only)
+ * - `sourceDescriptionsMaxDepth`: Maximum recursion depth for nested Arazzo source descriptions (default: `+Infinity`)
+ *
+ * Options can be passed globally via `strategyOpts` or strategy-specific via `strategyOpts['arazzo-1']`.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the Arazzo Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced Arazzo Document as ApiDOM element
+ * @throws DereferenceError - When dereferencing fails or document is not an Arazzo specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Dereference from file
+ * const result = await dereferenceArazzo('/path/to/arazzo.json');
+ *
+ * @example
+ * // Dereference from URL
+ * const result = await dereferenceArazzo('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * Dereference with source descriptions
+ * ```typescript
+ * const result = await dereferenceArazzo('/path/to/arazzo.json', {
+ *   dereference: { strategyOpts: { sourceDescriptions: true } },
+ * });
+ * ```
+ *
+ * @example
+ * // Dereference with custom options
+ * const result = await dereferenceArazzo('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+async function dereference(uri, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+  try {
+    const parseResult = await (0, _empty.dereference)(uri, mergedOptions);
+
+    // validate that the dereferenced document is an Arazzo specification
+    if (!(0, _apidomNsArazzo.isArazzoSpecification1Element)(parseResult.api)) {
+      throw new _empty.UnmatchedDereferenceStrategyError(`Could not find a dereference strategy that can dereference "${uri}" as an Arazzo specification`);
+    }
+    parseResult.meta.set('retrievalURI', uri);
+    return parseResult;
+  } catch (error) {
+    throw new _DereferenceError.default(`Failed to dereference Arazzo Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Dereferences an ApiDOM element representing an Arazzo Document.
+ *
+ * This function resolves all JSON References ($ref) and Reusable Object references
+ * ($components.*) in the Arazzo Document element.
+ *
+ * Supported scenarios:
+ * - ParseResultElement with retrievalURI metadata: baseURI derived automatically
+ * - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
+ * - Child element (e.g., WorkflowElement) with parseResult in strategyOpts:
+ *   requires `options.dereference.strategyOpts.parseResult` for component resolution,
+ *   and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
+ *
+ * Source descriptions can optionally be dereferenced using strategy options:
+ * - `sourceDescriptions`: `true` (all) or `['name1', 'name2']` (specific names only)
+ * - `sourceDescriptionsMaxDepth`: Maximum recursion depth for nested Arazzo source descriptions (default: `+Infinity`)
+ *
+ * Options can be passed globally via `strategyOpts` or strategy-specific via `strategyOpts['arazzo-1']`.
+ *
+ * @param element - An ApiDOM element (ParseResultElement or child element like WorkflowElement)
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced element
+ * @throws DereferenceError - When baseURI is required but not provided, or when dereferencing fails
+ *
+ * @example
+ * Dereference ParseResultElement with retrievalURI (from file parsing)
+ * ```typescript
+ * import { parseArazzo } from '@jentic/arazzo-parser';
+ *
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const dereferenced = await dereferenceArazzoElement(parseResult);
+ * ```
+ *
+ * @example
+ * Dereference ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parseArazzo({ arazzo: '1.0.1', ... });
+ * const dereferenced = await dereferenceArazzoElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/arazzo.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference child element (e.g., WorkflowElement)
+ * ```typescript
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const workflow = parseResult.api.workflows.get(0);
+ * const dereferenced = await dereferenceArazzoElement(workflow, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference with source descriptions
+ * ```typescript
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const dereferenced = await dereferenceArazzoElement(parseResult, {
+ *   dereference: { strategyOpts: { sourceDescriptions: true } },
+ * });
+ * ```
+ * @public
+ */
+async function dereferenceElement(element, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+  const refSet = mergedOptions.dereference?.refSet ?? new _empty.ReferenceSet();
+  let baseURI = mergedOptions.resolve?.baseURI;
+  let mediaType = 'text/plain';
+  if (refSet.size === 0) {
+    if ((0, _apidomDatamodel.isParseResultElement)(element)) {
+      if ((0, _apidomNsArazzo.isArazzoSpecification1Element)(element.api)) {
+        mediaType = _apidomNsArazzo.mediaTypes.latest();
+      }
+      if (element.hasMetaProperty('retrievalURI')) {
+        baseURI = element.meta.get('retrievalURI');
+      } else if (!baseURI) {
+        throw new _DereferenceError.default('baseURI option is required when dereferencing a ParseResultElement without retrievalURI metadata');
+      }
+    } else if ((0, _apidomDatamodel.isParseResultElement)(mergedOptions.dereference?.strategyOpts?.parseResult)) {
+      // dereferencing child element requires refSet for component resolution
+      const {
+        parseResult
+      } = mergedOptions.dereference.strategyOpts;
+      let rootURI;
+      if ((0, _apidomNsArazzo.isArazzoSpecification1Element)(parseResult.api)) {
+        mediaType = _apidomNsArazzo.mediaTypes.latest();
+      }
+      if (parseResult.hasMetaProperty('retrievalURI')) {
+        rootURI = parseResult.meta.get('retrievalURI');
+      } else if (baseURI) {
+        rootURI = baseURI;
+      } else {
+        throw new _DereferenceError.default('baseURI option is required when dereferencing a child element without retrievalURI metadata');
+      }
+      const elementReference = new _empty.Reference({
+        uri: `${rootURI}#fragment`,
+        value: new _apidomDatamodel.ParseResultElement([element])
+      });
+      const rootReference = new _empty.Reference({
+        uri: rootURI,
+        value: parseResult
+      });
+      refSet.add(elementReference).add(rootReference);
+      baseURI = rootURI;
+    }
+  }
+  try {
+    return await (0, _empty.dereferenceApiDOM)(element, (0, _empty.mergeOptions)(mergedOptions, {
+      resolve: {
+        baseURI
+      },
+      parse: {
+        mediaType
+      },
+      dereference: {
+        refSet
+      }
+    }));
+  } catch (error) {
+    throw new _DereferenceError.default('Failed to dereference Arazzo Document', {
+      cause: error
+    });
+  }
+}

package/src/dereference/arazzo.mjs

@@ -0,0 +1,223 @@
+import { isParseResultElement, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { dereference as dereferenceURI, dereferenceApiDOM as dereferenceApiDOMElement, mergeOptions, ReferenceSet, Reference, UnmatchedDereferenceStrategyError } from '@speclynx/apidom-reference/configuration/empty';
+import Arazzo1DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/arazzo-1';
+import OpenAPI2DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-2';
+import OpenAPI30DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-3-0';
+import OpenAPI31DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-3-1';
+import JSONParser from '@speclynx/apidom-reference/parse/parsers/json';
+import YAMLParser from '@speclynx/apidom-reference/parse/parsers/yaml-1-2';
+import BinaryParser from '@speclynx/apidom-reference/parse/parsers/binary';
+import { isArazzoSpecification1Element, mediaTypes } from '@speclynx/apidom-ns-arazzo-1';
+import { defaultArazzoOptions as parserDefaultOptions } from '@jentic/arazzo-parser';
+import DereferenceError from "../errors/DereferenceError.mjs";
+/**
+ * Options for dereferencing Arazzo Documents.
+ * @public
+ */
+/**
+ * Default reference options for dereferencing Arazzo Documents.
+ * @public
+ */
+export const defaultOptions = {
+  resolve: {
+    resolvers: [...parserDefaultOptions.resolve.resolvers]
+  },
+  parse: {
+    parsers: [...parserDefaultOptions.parse.parsers, new JSONParser({
+      allowEmpty: false
+    }), new YAMLParser({
+      allowEmpty: false
+    }), new BinaryParser({
+      allowEmpty: false
+    })],
+    parserOpts: {
+      ...parserDefaultOptions.parse.parserOpts
+    }
+  },
+  dereference: {
+    strategies: [new Arazzo1DereferenceStrategy(), new OpenAPI2DereferenceStrategy(), new OpenAPI30DereferenceStrategy(), new OpenAPI31DereferenceStrategy()],
+    strategyOpts: {
+      sourceDescriptions: false
+    }
+  }
+};
+
+/**
+ * Dereferences an Arazzo Document from a file system path or HTTP(S) URL.
+ *
+ * This function resolves all JSON References ($ref) and Reusable Object references
+ * ($components.*) in the Arazzo Document.
+ *
+ * Source descriptions can optionally be dereferenced using strategy options:
+ * - `sourceDescriptions`: `true` (all) or `['name1', 'name2']` (specific names only)
+ * - `sourceDescriptionsMaxDepth`: Maximum recursion depth for nested Arazzo source descriptions (default: `+Infinity`)
+ *
+ * Options can be passed globally via `strategyOpts` or strategy-specific via `strategyOpts['arazzo-1']`.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the Arazzo Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced Arazzo Document as ApiDOM element
+ * @throws DereferenceError - When dereferencing fails or document is not an Arazzo specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Dereference from file
+ * const result = await dereferenceArazzo('/path/to/arazzo.json');
+ *
+ * @example
+ * // Dereference from URL
+ * const result = await dereferenceArazzo('https://example.com/arazzo.yaml');
+ *
+ * @example
+ * Dereference with source descriptions
+ * ```typescript
+ * const result = await dereferenceArazzo('/path/to/arazzo.json', {
+ *   dereference: { strategyOpts: { sourceDescriptions: true } },
+ * });
+ * ```
+ *
+ * @example
+ * // Dereference with custom options
+ * const result = await dereferenceArazzo('/path/to/arazzo.json', customReferenceOptions);
+ * @public
+ */
+export async function dereference(uri, options = {}) {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  try {
+    const parseResult = await dereferenceURI(uri, mergedOptions);
+
+    // validate that the dereferenced document is an Arazzo specification
+    if (!isArazzoSpecification1Element(parseResult.api)) {
+      throw new UnmatchedDereferenceStrategyError(`Could not find a dereference strategy that can dereference "${uri}" as an Arazzo specification`);
+    }
+    parseResult.meta.set('retrievalURI', uri);
+    return parseResult;
+  } catch (error) {
+    throw new DereferenceError(`Failed to dereference Arazzo Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Dereferences an ApiDOM element representing an Arazzo Document.
+ *
+ * This function resolves all JSON References ($ref) and Reusable Object references
+ * ($components.*) in the Arazzo Document element.
+ *
+ * Supported scenarios:
+ * - ParseResultElement with retrievalURI metadata: baseURI derived automatically
+ * - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
+ * - Child element (e.g., WorkflowElement) with parseResult in strategyOpts:
+ *   requires `options.dereference.strategyOpts.parseResult` for component resolution,
+ *   and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
+ *
+ * Source descriptions can optionally be dereferenced using strategy options:
+ * - `sourceDescriptions`: `true` (all) or `['name1', 'name2']` (specific names only)
+ * - `sourceDescriptionsMaxDepth`: Maximum recursion depth for nested Arazzo source descriptions (default: `+Infinity`)
+ *
+ * Options can be passed globally via `strategyOpts` or strategy-specific via `strategyOpts['arazzo-1']`.
+ *
+ * @param element - An ApiDOM element (ParseResultElement or child element like WorkflowElement)
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced element
+ * @throws DereferenceError - When baseURI is required but not provided, or when dereferencing fails
+ *
+ * @example
+ * Dereference ParseResultElement with retrievalURI (from file parsing)
+ * ```typescript
+ * import { parseArazzo } from '@jentic/arazzo-parser';
+ *
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const dereferenced = await dereferenceArazzoElement(parseResult);
+ * ```
+ *
+ * @example
+ * Dereference ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parseArazzo({ arazzo: '1.0.1', ... });
+ * const dereferenced = await dereferenceArazzoElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/arazzo.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference child element (e.g., WorkflowElement)
+ * ```typescript
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const workflow = parseResult.api.workflows.get(0);
+ * const dereferenced = await dereferenceArazzoElement(workflow, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference with source descriptions
+ * ```typescript
+ * const parseResult = await parseArazzo('/path/to/arazzo.json');
+ * const dereferenced = await dereferenceArazzoElement(parseResult, {
+ *   dereference: { strategyOpts: { sourceDescriptions: true } },
+ * });
+ * ```
+ * @public
+ */
+export async function dereferenceElement(element, options = {}) {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  const refSet = mergedOptions.dereference?.refSet ?? new ReferenceSet();
+  let baseURI = mergedOptions.resolve?.baseURI;
+  let mediaType = 'text/plain';
+  if (refSet.size === 0) {
+    if (isParseResultElement(element)) {
+      if (isArazzoSpecification1Element(element.api)) {
+        mediaType = mediaTypes.latest();
+      }
+      if (element.hasMetaProperty('retrievalURI')) {
+        baseURI = element.meta.get('retrievalURI');
+      } else if (!baseURI) {
+        throw new DereferenceError('baseURI option is required when dereferencing a ParseResultElement without retrievalURI metadata');
+      }
+    } else if (isParseResultElement(mergedOptions.dereference?.strategyOpts?.parseResult)) {
+      // dereferencing child element requires refSet for component resolution
+      const {
+        parseResult
+      } = mergedOptions.dereference.strategyOpts;
+      let rootURI;
+      if (isArazzoSpecification1Element(parseResult.api)) {
+        mediaType = mediaTypes.latest();
+      }
+      if (parseResult.hasMetaProperty('retrievalURI')) {
+        rootURI = parseResult.meta.get('retrievalURI');
+      } else if (baseURI) {
+        rootURI = baseURI;
+      } else {
+        throw new DereferenceError('baseURI option is required when dereferencing a child element without retrievalURI metadata');
+      }
+      const elementReference = new Reference({
+        uri: `${rootURI}#fragment`,
+        value: new ParseResultElement([element])
+      });
+      const rootReference = new Reference({
+        uri: rootURI,
+        value: parseResult
+      });
+      refSet.add(elementReference).add(rootReference);
+      baseURI = rootURI;
+    }
+  }
+  try {
+    return await dereferenceApiDOMElement(element, mergeOptions(mergedOptions, {
+      resolve: {
+        baseURI
+      },
+      parse: {
+        mediaType
+      },
+      dereference: {
+        refSet
+      }
+    }));
+  } catch (error) {
+    throw new DereferenceError('Failed to dereference Arazzo Document', {
+      cause: error
+    });
+  }
+}

package/src/dereference/openapi.cjs

@@ -0,0 +1,224 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.defaultOptions = void 0;
+exports.dereference = dereference;
+exports.dereferenceElement = dereferenceElement;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _empty = require("@speclynx/apidom-reference/configuration/empty");
+var _openapi = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-2"));
+var _openapi2 = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-3-0"));
+var _openapi3 = _interopRequireDefault(require("@speclynx/apidom-reference/dereference/strategies/openapi-3-1"));
+var _json = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/json"));
+var _yaml = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/yaml-1-2"));
+var _binary = _interopRequireDefault(require("@speclynx/apidom-reference/parse/parsers/binary"));
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
+var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
+var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
+var _arazzoParser = require("@jentic/arazzo-parser");
+var _DereferenceError = _interopRequireDefault(require("../errors/DereferenceError.cjs"));
+/**
+ * Options for dereferencing OpenAPI Documents.
+ * @public
+ */
+
+/**
+ * Default reference options for dereferencing OpenAPI Documents.
+ * @public
+ */
+const defaultOptions = exports.defaultOptions = {
+  resolve: {
+    resolvers: [..._arazzoParser.defaultOpenAPIOptions.resolve.resolvers]
+  },
+  parse: {
+    parsers: [..._arazzoParser.defaultOpenAPIOptions.parse.parsers, new _json.default({
+      allowEmpty: false
+    }), new _yaml.default({
+      allowEmpty: false
+    }), new _binary.default({
+      allowEmpty: false
+    })],
+    parserOpts: {
+      ..._arazzoParser.defaultOpenAPIOptions.parse.parserOpts
+    }
+  },
+  dereference: {
+    strategies: [new _openapi.default(), new _openapi2.default(), new _openapi3.default()],
+    strategyOpts: {}
+  }
+};
+
+/**
+ * Dereferences an OpenAPI Document from a file system path or HTTP(S) URL.
+ *
+ * This function resolves all JSON References ($ref) in the OpenAPI Document.
+ *
+ * Supports OpenAPI 2.0 (Swagger), OpenAPI 3.0.x, and OpenAPI 3.1.x.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the OpenAPI Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced OpenAPI Document as ApiDOM element
+ * @throws DereferenceError - When dereferencing fails or document is not an OpenAPI specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Dereference from file
+ * const result = await dereferenceOpenAPI('/path/to/openapi.json');
+ *
+ * @example
+ * // Dereference from URL
+ * const result = await dereferenceOpenAPI('https://example.com/openapi.yaml');
+ *
+ * @example
+ * // Dereference with custom options
+ * const result = await dereferenceOpenAPI('/path/to/openapi.json', customReferenceOptions);
+ * @public
+ */
+async function dereference(uri, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+  try {
+    const parseResult = await (0, _empty.dereference)(uri, mergedOptions);
+
+    // validate that the dereferenced document is an OpenAPI specification
+    if (!isOpenApiElement(parseResult.api)) {
+      throw new _empty.UnmatchedDereferenceStrategyError(`Could not find a dereference strategy that can dereference "${uri}" as an OpenAPI specification`);
+    }
+    parseResult.meta.set('retrievalURI', uri);
+    return parseResult;
+  } catch (error) {
+    throw new _DereferenceError.default(`Failed to dereference OpenAPI Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Dereferences an ApiDOM element representing an OpenAPI Document.
+ *
+ * This function resolves all JSON References ($ref) in the OpenAPI Document element.
+ *
+ * Supported scenarios:
+ * - ParseResultElement with retrievalURI metadata: baseURI derived automatically
+ * - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
+ * - Child element (e.g., PathItemElement) with parseResult in strategyOpts:
+ *   requires `options.dereference.strategyOpts.parseResult` for component resolution,
+ *   and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
+ *
+ * @param element - An ApiDOM element (ParseResultElement or child element like PathItemElement)
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced element
+ * @throws DereferenceError - When baseURI is required but not provided, or when dereferencing fails
+ *
+ * @example
+ * Dereference ParseResultElement with retrievalURI (from file parsing)
+ * ```typescript
+ * import { parseOpenAPI } from '@jentic/arazzo-parser';
+ *
+ * const parseResult = await parseOpenAPI('/path/to/openapi.json');
+ * const dereferenced = await dereferenceOpenAPIElement(parseResult);
+ * ```
+ *
+ * @example
+ * Dereference ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parseOpenAPI({ openapi: '3.1.0', ... });
+ * const dereferenced = await dereferenceOpenAPIElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/openapi.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference child element (e.g., PathItemElement)
+ * ```typescript
+ * const parseResult = await parseOpenAPI('/path/to/openapi.json');
+ * const pathItem = parseResult.api.paths.get('/users');
+ * const dereferenced = await dereferenceOpenAPIElement(pathItem, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ * @public
+ */
+async function dereferenceElement(element, options = {}) {
+  const mergedOptions = (0, _empty.mergeOptions)(defaultOptions, options);
+  const refSet = mergedOptions.dereference?.refSet ?? new _empty.ReferenceSet();
+  let baseURI = mergedOptions.resolve?.baseURI;
+  let mediaType = 'text/plain';
+  if (refSet.size === 0) {
+    if ((0, _apidomDatamodel.isParseResultElement)(element)) {
+      if (isOpenApiElement(element.api)) {
+        mediaType = inferOpenApiMediaType(element.api);
+      }
+      if (element.hasMetaProperty('retrievalURI')) {
+        baseURI = element.meta.get('retrievalURI');
+      } else if (!baseURI) {
+        throw new _DereferenceError.default('baseURI option is required when dereferencing a ParseResultElement without retrievalURI metadata');
+      }
+    } else if ((0, _apidomDatamodel.isParseResultElement)(mergedOptions.dereference?.strategyOpts?.parseResult)) {
+      // dereferencing child element requires refSet for component resolution
+      const {
+        parseResult
+      } = mergedOptions.dereference.strategyOpts;
+      let rootURI;
+      if (isOpenApiElement(parseResult.api)) {
+        mediaType = inferOpenApiMediaType(parseResult.api);
+      }
+      if (parseResult.hasMetaProperty('retrievalURI')) {
+        rootURI = parseResult.meta.get('retrievalURI');
+      } else if (baseURI) {
+        rootURI = baseURI;
+      } else {
+        throw new _DereferenceError.default('baseURI option is required when dereferencing a child element without retrievalURI metadata');
+      }
+      const elementReference = new _empty.Reference({
+        uri: `${rootURI}#fragment`,
+        value: new _apidomDatamodel.ParseResultElement([element])
+      });
+      const rootReference = new _empty.Reference({
+        uri: rootURI,
+        value: parseResult
+      });
+      refSet.add(elementReference).add(rootReference);
+      baseURI = rootURI;
+    }
+  }
+  try {
+    return await (0, _empty.dereferenceApiDOM)(element, (0, _empty.mergeOptions)(mergedOptions, {
+      resolve: {
+        baseURI
+      },
+      parse: {
+        mediaType
+      },
+      dereference: {
+        refSet
+      }
+    }));
+  } catch (error) {
+    throw new _DereferenceError.default('Failed to dereference OpenAPI Document', {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Checks if the element is a valid OpenAPI specification element.
+ */
+function isOpenApiElement(element) {
+  return (0, _apidomNsOpenapi.isSwaggerElement)(element) || (0, _apidomNsOpenapi2.isOpenApi3_0Element)(element) || (0, _apidomNsOpenapi3.isOpenApi3_1Element)(element);
+}
+
+/**
+ * Gets the appropriate mediaType for an OpenAPI element.
+ */
+function inferOpenApiMediaType(element) {
+  if ((0, _apidomNsOpenapi.isSwaggerElement)(element)) {
+    return _apidomNsOpenapi.mediaTypes.latest();
+  }
+  if ((0, _apidomNsOpenapi2.isOpenApi3_0Element)(element)) {
+    return _apidomNsOpenapi2.mediaTypes.latest();
+  }
+  if ((0, _apidomNsOpenapi3.isOpenApi3_1Element)(element)) {
+    return _apidomNsOpenapi3.mediaTypes.latest();
+  }
+  return 'text/plain';
+}

package/src/dereference/openapi.mjs

@@ -0,0 +1,216 @@
+import { isParseResultElement, ParseResultElement } from '@speclynx/apidom-datamodel';
+import { dereference as dereferenceURI, dereferenceApiDOM as dereferenceApiDOMElement, mergeOptions, ReferenceSet, Reference, UnmatchedDereferenceStrategyError } from '@speclynx/apidom-reference/configuration/empty';
+import OpenAPI2DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-2';
+import OpenAPI3_0DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-3-0';
+import OpenAPI3_1DereferenceStrategy from '@speclynx/apidom-reference/dereference/strategies/openapi-3-1';
+import JSONParser from '@speclynx/apidom-reference/parse/parsers/json';
+import YAMLParser from '@speclynx/apidom-reference/parse/parsers/yaml-1-2';
+import BinaryParser from '@speclynx/apidom-reference/parse/parsers/binary';
+import { isSwaggerElement, mediaTypes as openApi2MediaTypes } from '@speclynx/apidom-ns-openapi-2';
+import { isOpenApi3_0Element, mediaTypes as openApi3_0MediaTypes } from '@speclynx/apidom-ns-openapi-3-0';
+import { isOpenApi3_1Element, mediaTypes as openApi3_1MediaTypes } from '@speclynx/apidom-ns-openapi-3-1';
+import { defaultOpenAPIOptions as parserDefaultOptions } from '@jentic/arazzo-parser';
+import DereferenceError from "../errors/DereferenceError.mjs";
+/**
+ * Options for dereferencing OpenAPI Documents.
+ * @public
+ */
+/**
+ * Default reference options for dereferencing OpenAPI Documents.
+ * @public
+ */
+export const defaultOptions = {
+  resolve: {
+    resolvers: [...parserDefaultOptions.resolve.resolvers]
+  },
+  parse: {
+    parsers: [...parserDefaultOptions.parse.parsers, new JSONParser({
+      allowEmpty: false
+    }), new YAMLParser({
+      allowEmpty: false
+    }), new BinaryParser({
+      allowEmpty: false
+    })],
+    parserOpts: {
+      ...parserDefaultOptions.parse.parserOpts
+    }
+  },
+  dereference: {
+    strategies: [new OpenAPI2DereferenceStrategy(), new OpenAPI3_0DereferenceStrategy(), new OpenAPI3_1DereferenceStrategy()],
+    strategyOpts: {}
+  }
+};
+
+/**
+ * Dereferences an OpenAPI Document from a file system path or HTTP(S) URL.
+ *
+ * This function resolves all JSON References ($ref) in the OpenAPI Document.
+ *
+ * Supports OpenAPI 2.0 (Swagger), OpenAPI 3.0.x, and OpenAPI 3.1.x.
+ *
+ * @param uri - A file system path or HTTP(S) URL to the OpenAPI Document
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced OpenAPI Document as ApiDOM element
+ * @throws DereferenceError - When dereferencing fails or document is not an OpenAPI specification. The original error is available via the `cause` property.
+ *
+ * @example
+ * // Dereference from file
+ * const result = await dereferenceOpenAPI('/path/to/openapi.json');
+ *
+ * @example
+ * // Dereference from URL
+ * const result = await dereferenceOpenAPI('https://example.com/openapi.yaml');
+ *
+ * @example
+ * // Dereference with custom options
+ * const result = await dereferenceOpenAPI('/path/to/openapi.json', customReferenceOptions);
+ * @public
+ */
+export async function dereference(uri, options = {}) {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  try {
+    const parseResult = await dereferenceURI(uri, mergedOptions);
+
+    // validate that the dereferenced document is an OpenAPI specification
+    if (!isOpenApiElement(parseResult.api)) {
+      throw new UnmatchedDereferenceStrategyError(`Could not find a dereference strategy that can dereference "${uri}" as an OpenAPI specification`);
+    }
+    parseResult.meta.set('retrievalURI', uri);
+    return parseResult;
+  } catch (error) {
+    throw new DereferenceError(`Failed to dereference OpenAPI Document at "${uri}"`, {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Dereferences an ApiDOM element representing an OpenAPI Document.
+ *
+ * This function resolves all JSON References ($ref) in the OpenAPI Document element.
+ *
+ * Supported scenarios:
+ * - ParseResultElement with retrievalURI metadata: baseURI derived automatically
+ * - ParseResultElement without retrievalURI: requires `options.resolve.baseURI`
+ * - Child element (e.g., PathItemElement) with parseResult in strategyOpts:
+ *   requires `options.dereference.strategyOpts.parseResult` for component resolution,
+ *   and `options.resolve.baseURI` if parseResult lacks retrievalURI metadata
+ *
+ * @param element - An ApiDOM element (ParseResultElement or child element like PathItemElement)
+ * @param options - Reference options (uses defaultOptions when not provided)
+ * @returns A promise that resolves to the dereferenced element
+ * @throws DereferenceError - When baseURI is required but not provided, or when dereferencing fails
+ *
+ * @example
+ * Dereference ParseResultElement with retrievalURI (from file parsing)
+ * ```typescript
+ * import { parseOpenAPI } from '@jentic/arazzo-parser';
+ *
+ * const parseResult = await parseOpenAPI('/path/to/openapi.json');
+ * const dereferenced = await dereferenceOpenAPIElement(parseResult);
+ * ```
+ *
+ * @example
+ * Dereference ParseResultElement without retrievalURI (from inline parsing)
+ * ```typescript
+ * const parseResult = await parseOpenAPI({ openapi: '3.1.0', ... });
+ * const dereferenced = await dereferenceOpenAPIElement(parseResult, {
+ *   resolve: { baseURI: 'https://example.com/openapi.json' },
+ * });
+ * ```
+ *
+ * @example
+ * Dereference child element (e.g., PathItemElement)
+ * ```typescript
+ * const parseResult = await parseOpenAPI('/path/to/openapi.json');
+ * const pathItem = parseResult.api.paths.get('/users');
+ * const dereferenced = await dereferenceOpenAPIElement(pathItem, {
+ *   dereference: { strategyOpts: { parseResult } },
+ * });
+ * ```
+ * @public
+ */
+export async function dereferenceElement(element, options = {}) {
+  const mergedOptions = mergeOptions(defaultOptions, options);
+  const refSet = mergedOptions.dereference?.refSet ?? new ReferenceSet();
+  let baseURI = mergedOptions.resolve?.baseURI;
+  let mediaType = 'text/plain';
+  if (refSet.size === 0) {
+    if (isParseResultElement(element)) {
+      if (isOpenApiElement(element.api)) {
+        mediaType = inferOpenApiMediaType(element.api);
+      }
+      if (element.hasMetaProperty('retrievalURI')) {
+        baseURI = element.meta.get('retrievalURI');
+      } else if (!baseURI) {
+        throw new DereferenceError('baseURI option is required when dereferencing a ParseResultElement without retrievalURI metadata');
+      }
+    } else if (isParseResultElement(mergedOptions.dereference?.strategyOpts?.parseResult)) {
+      // dereferencing child element requires refSet for component resolution
+      const {
+        parseResult
+      } = mergedOptions.dereference.strategyOpts;
+      let rootURI;
+      if (isOpenApiElement(parseResult.api)) {
+        mediaType = inferOpenApiMediaType(parseResult.api);
+      }
+      if (parseResult.hasMetaProperty('retrievalURI')) {
+        rootURI = parseResult.meta.get('retrievalURI');
+      } else if (baseURI) {
+        rootURI = baseURI;
+      } else {
+        throw new DereferenceError('baseURI option is required when dereferencing a child element without retrievalURI metadata');
+      }
+      const elementReference = new Reference({
+        uri: `${rootURI}#fragment`,
+        value: new ParseResultElement([element])
+      });
+      const rootReference = new Reference({
+        uri: rootURI,
+        value: parseResult
+      });
+      refSet.add(elementReference).add(rootReference);
+      baseURI = rootURI;
+    }
+  }
+  try {
+    return await dereferenceApiDOMElement(element, mergeOptions(mergedOptions, {
+      resolve: {
+        baseURI
+      },
+      parse: {
+        mediaType
+      },
+      dereference: {
+        refSet
+      }
+    }));
+  } catch (error) {
+    throw new DereferenceError('Failed to dereference OpenAPI Document', {
+      cause: error
+    });
+  }
+}
+
+/**
+ * Checks if the element is a valid OpenAPI specification element.
+ */
+function isOpenApiElement(element) {
+  return isSwaggerElement(element) || isOpenApi3_0Element(element) || isOpenApi3_1Element(element);
+}
+
+/**
+ * Gets the appropriate mediaType for an OpenAPI element.
+ */
+function inferOpenApiMediaType(element) {
+  if (isSwaggerElement(element)) {
+    return openApi2MediaTypes.latest();
+  }
+  if (isOpenApi3_0Element(element)) {
+    return openApi3_0MediaTypes.latest();
+  }
+  if (isOpenApi3_1Element(element)) {
+    return openApi3_1MediaTypes.latest();
+  }
+  return 'text/plain';
+}

package/src/errors/DereferenceError.cjs

@@ -0,0 +1,15 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomError = require("@speclynx/apidom-error");
+/**
+ * Error thrown when dereferencing an Arazzo document or element fails.
+ * @public
+ */
+class DereferenceError extends _apidomError.ApiDOMError {
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+var _default = exports.default = DereferenceError;

package/src/errors/DereferenceError.mjs

@@ -0,0 +1,12 @@
+import { ApiDOMError } from '@speclynx/apidom-error';
+
+/**
+ * Error thrown when dereferencing an Arazzo document or element fails.
+ * @public
+ */
+class DereferenceError extends ApiDOMError {
+  constructor(message, options) {
+    super(message, options);
+  }
+}
+export default DereferenceError;

package/src/index.cjs

@@ -0,0 +1,15 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.dereferenceOpenAPIElement = exports.dereferenceOpenAPI = exports.dereferenceArazzoElement = exports.dereferenceArazzo = exports.defaultDereferenceOpenAPIOptions = exports.defaultDereferenceArazzoOptions = exports.DereferenceError = void 0;
+var _arazzo = require("./dereference/arazzo.cjs");
+exports.defaultDereferenceArazzoOptions = _arazzo.defaultOptions;
+exports.dereferenceArazzo = _arazzo.dereference;
+exports.dereferenceArazzoElement = _arazzo.dereferenceElement;
+var _openapi = require("./dereference/openapi.cjs");
+exports.defaultDereferenceOpenAPIOptions = _openapi.defaultOptions;
+exports.dereferenceOpenAPI = _openapi.dereference;
+exports.dereferenceOpenAPIElement = _openapi.dereferenceElement;
+var _DereferenceError = _interopRequireDefault(require("./errors/DereferenceError.cjs"));
+exports.DereferenceError = _DereferenceError.default;

package/src/index.mjs

@@ -0,0 +1,3 @@
+export { defaultOptions as defaultDereferenceArazzoOptions, dereference as dereferenceArazzo, dereferenceElement as dereferenceArazzoElement } from "./dereference/arazzo.mjs";
+export { defaultOptions as defaultDereferenceOpenAPIOptions, dereference as dereferenceOpenAPI, dereferenceElement as dereferenceOpenAPIElement } from "./dereference/openapi.mjs";
+export { default as DereferenceError } from "./errors/DereferenceError.mjs";