@jentic/arazzo-resolver 1.0.0-alpha.3 → 1.0.0-alpha.30

package/CHANGELOG.md

@@ -0,0 +1,153 @@
+# Change Log
+
+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.30](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.29...v1.0.0-alpha.30) (2026-04-04)
+
+**Note:** Version bump only for package @jentic/arazzo-resolver
+
+# [1.0.0-alpha.29](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.28...v1.0.0-alpha.29) (2026-03-19)
+
+**Note:** Version bump only for package @jentic/arazzo-resolver
+
+# [1.0.0-alpha.28](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.27...v1.0.0-alpha.28) (2026-03-19)
+
+**Note:** Version bump only for package @jentic/arazzo-resolver
+
+# [1.0.0-alpha.27](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.26...v1.0.0-alpha.27) (2026-03-12)
+
+### Bug Fixes
+
+- **release:** override minimatch 10.2.3 to fix glob pattern regression in lerna publish ([#143](https://github.com/jentic/jentic-arazzo-tools/issues/143)) ([829f1cf](https://github.com/jentic/jentic-arazzo-tools/commit/829f1cf3d4376b407e4ef2391e155f8e60e1a7d4)), closes [lerna/lerna#4305](https://github.com/lerna/lerna/issues/4305) [isaacs/minimatch#284](https://github.com/isaacs/minimatch/issues/284)
+
+# [1.0.0-alpha.26](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.25...v1.0.0-alpha.26) (2026-03-11)
+
+### Bug Fixes
+
+- **parser:** add consistent naming for exported options ([#134](https://github.com/jentic/jentic-arazzo-tools/issues/134)) ([cfa2a54](https://github.com/jentic/jentic-arazzo-tools/commit/cfa2a54fad0189da7d26ca4c76b63bfcc3c60eec))
+
+# [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
+
+# [1.0.0-alpha.23](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.22...v1.0.0-alpha.23) (2026-03-11)
+
+### Features
+
+- **resolver:** reuse configuration from parser ([#130](https://github.com/jentic/jentic-arazzo-tools/issues/130)) ([e135be7](https://github.com/jentic/jentic-arazzo-tools/commit/e135be78133ad3957a31716dabd540333d57c0a4))
+
+# [1.0.0-alpha.22](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.21...v1.0.0-alpha.22) (2026-03-10)
+
+### Performance Improvements
+
+- address memory issues with SpecLynx data model ([#124](https://github.com/jentic/jentic-arazzo-tools/issues/124)) ([90ee10d](https://github.com/jentic/jentic-arazzo-tools/commit/90ee10d52dbe7314d7dc2e48e0e656fd74a97cff))
+
+# [1.0.0-alpha.21](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.20...v1.0.0-alpha.21) (2026-02-24)
+
+### Bug Fixes
+
+- **parser:** parse YAML document larger than 32768 lines ([#111](https://github.com/jentic/jentic-arazzo-tools/issues/111)) ([b155660](https://github.com/jentic/jentic-arazzo-tools/commit/b155660a608f4f5a0614cb5b3496bcd28a27a447))
+
+# [1.0.0-alpha.20](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.19...v1.0.0-alpha.20) (2026-02-24)
+
+### Bug Fixes
+
+- loosen parsing constraints to parse URIs without extensions ([#108](https://github.com/jentic/jentic-arazzo-tools/issues/108)) ([3720140](https://github.com/jentic/jentic-arazzo-tools/commit/372014060b7feae9a98e220277c2a5888132bad2))
+
+# [1.0.0-alpha.19](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.18...v1.0.0-alpha.19) (2026-02-23)
+
+### Features
+
+- **arazzo-ui:** add CLI for opening any URL from command cli ([#103](https://github.com/jentic/jentic-arazzo-tools/issues/103)) ([6923e7b](https://github.com/jentic/jentic-arazzo-tools/commit/6923e7bdcb62e86266789e18ef6af5dc27459110)), closes [#96](https://github.com/jentic/jentic-arazzo-tools/issues/96)
+
+# [1.0.0-alpha.18](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.17...v1.0.0-alpha.18) (2026-02-20)
+
+### Features
+
+- **parser:** add support for lossless roundtrips ([#91](https://github.com/jentic/jentic-arazzo-tools/issues/91)) ([2cffe4f](https://github.com/jentic/jentic-arazzo-tools/commit/2cffe4f142c4a541126a3f5f2e3634195c906f75))
+
+# [1.0.0-alpha.17](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.16...v1.0.0-alpha.17) (2026-02-20)
+
+### Bug Fixes
+
+- **deps:** use caret ranges for @speclynx/\* dependencies ([#90](https://github.com/jentic/jentic-arazzo-tools/issues/90)) ([2be9f0b](https://github.com/jentic/jentic-arazzo-tools/commit/2be9f0b06a38ee28d3b2ee344ff9a764d2ed3de4))
+
+# [1.0.0-alpha.16](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.15...v1.0.0-alpha.16) (2026-02-20)
+
+### Bug Fixes
+
+- **security:** fix security vulnerability in minimatch ([#89](https://github.com/jentic/jentic-arazzo-tools/issues/89)) ([7e16a0f](https://github.com/jentic/jentic-arazzo-tools/commit/7e16a0ff16aa4e87d09e149dd1bd6cfcf7f23e23))
+
+# [1.0.0-alpha.15](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.14...v1.0.0-alpha.15) (2026-02-20)
+
+**Note:** Version bump only for package @jentic/arazzo-resolver
+
+# [1.0.0-alpha.14](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.13...v1.0.0-alpha.14) (2026-02-20)
+
+**Note:** Version bump only for package @jentic/arazzo-resolver
+
+# [1.0.0-alpha.13](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.12...v1.0.0-alpha.13) (2026-02-11)
+
+**Note:** Version bump only for package @jentic/arazzo-resolver
+
+# [1.0.0-alpha.12](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.11...v1.0.0-alpha.12) (2026-02-11)
+
+**Note:** Version bump only for package @jentic/arazzo-resolver
+
+# [1.0.0-alpha.11](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.10...v1.0.0-alpha.11) (2026-02-10)
+
+### Features
+
+- add initial validator implementation ([#60](https://github.com/jentic/jentic-arazzo-tools/issues/60)) ([4e9a73d](https://github.com/jentic/jentic-arazzo-tools/commit/4e9a73dd5ca2b2b48ebc32de6b02c93524fabccf))
+
+# [1.0.0-alpha.10](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.9...v1.0.0-alpha.10) (2026-02-08)
+
+### Bug Fixes
+
+- **resolver:** add doc for accessing parse result via SourceDescription ([13d43e4](https://github.com/jentic/jentic-arazzo-tools/commit/13d43e45ed3bb02d5771b3adc7a6fb1e5571a393))
+
+# [1.0.0-alpha.9](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.8...v1.0.0-alpha.9) (2026-02-05)
+
+### Features
+
+- **resolver:** add dereferencing support for Arazzo Source Descriptions ([#43](https://github.com/jentic/jentic-arazzo-tools/issues/43)) ([091610b](https://github.com/jentic/jentic-arazzo-tools/commit/091610be81b32540845c7f1cb60dd68348ee282b))
+
+# [1.0.0-alpha.8](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.7...v1.0.0-alpha.8) (2026-02-05)
+
+### Features
+
+- **resolver:** add dereferencing support for OpenAPI Documents & fragments ([#42](https://github.com/jentic/jentic-arazzo-tools/issues/42)) ([7687c9e](https://github.com/jentic/jentic-arazzo-tools/commit/7687c9eecc50aab508e67ba5d639b31e25154eff))
+- **resolver:** improve API consistency and validation ([#36](https://github.com/jentic/jentic-arazzo-tools/issues/36)) ([aa095cb](https://github.com/jentic/jentic-arazzo-tools/commit/aa095cb19a1543cd675bfa94a6de1651d21a58b5))
+
+# [1.0.0-alpha.7](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.6...v1.0.0-alpha.7) (2026-02-04)
+
+### Features
+
+- **parser:** add support for parsing OpenAPI Documents ([#35](https://github.com/jentic/jentic-arazzo-tools/issues/35)) ([4c2615e](https://github.com/jentic/jentic-arazzo-tools/commit/4c2615e07c3b74ea7fe74b91b977c8c7123a2188))
+
+# [1.0.0-alpha.6](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.5...v1.0.0-alpha.6) (2026-02-04)
+
+### Features
+
+- **parser:** add support for parsing entire Arazzo Description ([#34](https://github.com/jentic/jentic-arazzo-tools/issues/34)) ([44b2bda](https://github.com/jentic/jentic-arazzo-tools/commit/44b2bda1c7449e1db8145af1dea457f2e09a465b))
+
+# [1.0.0-alpha.5](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.4...v1.0.0-alpha.5) (2026-01-31)
+
+### Bug Fixes
+
+- **resolver:** provide documentation in README ([74cabc1](https://github.com/jentic/jentic-arazzo-tools/commit/74cabc102c56eb3cc2640500a513449a64ca52ad))
+
+# [1.0.0-alpha.4](https://github.com/jentic/jentic-arazzo-tools/compare/v1.0.0-alpha.3...v1.0.0-alpha.4) (2026-01-31)
+
+### Features
+
+- **parser:** add unified options interface & retrievalURI meta ([#16](https://github.com/jentic/jentic-arazzo-tools/issues/16)) ([2d6c3b3](https://github.com/jentic/jentic-arazzo-tools/commit/2d6c3b37f3246bc5ad775c30b508607119c9eb50))
+- **resolver:** add dereferencing support for Arazzo Document fragments ([#21](https://github.com/jentic/jentic-arazzo-tools/issues/21)) ([868dc43](https://github.com/jentic/jentic-arazzo-tools/commit/868dc434b51f6247ca102fae7422a85a0e545d09))
+- **resolver:** add dereferencing support for entry Arazzo Document ([#15](https://github.com/jentic/jentic-arazzo-tools/issues/15)) ([cf016ed](https://github.com/jentic/jentic-arazzo-tools/commit/cf016ed9130f08aac87bbb94b0e45e80c27f8fc3))

package/NOTICE

@@ -2,3 +2,11 @@ Jentic Arazzo Tools
 Copyright (c) 2026 Jentic
 Jentic Arazzo Tools is licensed under Apache 2.0 license.
 Copy of the Apache 2.0 license can be found in `LICENSE` file.
+
+swagger-js/swagger-client
+Copyright 2020-2021 SmartBear Software Inc.
+swagger-client is being pre-processed by our build process
+and swagger-client build artifact is included in npm distribution.
+It's not dynamically linked via npm dependency management.
+swagger-client is licensed under Apache 2.0 license.
+Copy of the Apache 2.0 license can be found in `LICENSE` file.

package/README.md

@@ -1,3 +1,498 @@
 # @jentic/arazzo-resolver
 
-`@jentic/arazzo-resolver` is a resolver for [Arazzo Specification](https://spec.openapis.org/arazzo/latest.html) documents.
+`@jentic/arazzo-resolver` is a resolver for [Arazzo Specification](https://spec.openapis.org/arazzo/latest.html) and [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) documents.
+It produces [SpecLynx ApiDOM](https://github.com/speclynx/apidom) data models using the appropriate namespace ([Arazzo 1.x](https://github.com/speclynx/apidom/tree/main/packages/apidom-ns-arazzo-1#readme), [OpenAPI 2.0](https://github.com/speclynx/apidom/tree/main/packages/apidom-ns-openapi-2#readme), [OpenAPI 3.0.x](https://github.com/speclynx/apidom/tree/main/packages/apidom-ns-openapi-3-0#readme), [OpenAPI 3.1.x](https://github.com/speclynx/apidom/tree/main/packages/apidom-ns-openapi-3-1#readme)).
+
+**Supported Arazzo versions:**
+- [Arazzo 1.0.0](https://spec.openapis.org/arazzo/v1.0.0)
+- [Arazzo 1.0.1](https://spec.openapis.org/arazzo/v1.0.1)
+
+**Supported OpenAPI versions (for source descriptions):**
+- [OpenAPI 2.0](https://spec.openapis.org/oas/v2.0)
+- [OpenAPI 3.0.x](https://spec.openapis.org/oas/v3.0.4)
+- [OpenAPI 3.1.x](https://spec.openapis.org/oas/v3.1.2)
+
+## Installation
+
+You can install this package via [npm](https://npmjs.org/) CLI by running the following command:
+
+```sh
+npm install @jentic/arazzo-resolver
+```
+
+## Dereferencing
+
+Dereferencing is the process of replacing references with the actual content they point to.
+
+**In Arazzo Documents**, this includes:
+
+- **JSON Schemas** - resolves references within schemas
+- **Reusable Object references** (`$components.*`) - references to reusable components like parameters and actions
+
+**In OpenAPI Documents**, this includes:
+
+- **Reference Objects** (`$ref`) - resolves references to components, external files, and URLs
+- **JSON Schemas** - resolves references within schemas
+- **Path Item Object** - resolves references to path items
+- and others
+
+After dereferencing, all references are resolved inline, making the document self-contained and easier to process programmatically.
+
+### Functions
+
+**Arazzo:**
+- **`dereferenceArazzo(uri)`** - Dereferences from a file system path or HTTP(S) URL
+- **`dereferenceArazzoElement(element)`** - Dereferences a SpecLynx ApiDOM element
+
+**OpenAPI:**
+- **`dereferenceOpenAPI(uri)`** - Dereferences from a file system path or HTTP(S) URL
+- **`dereferenceOpenAPIElement(element)`** - Dereferences a SpecLynx ApiDOM element
+
+### Arazzo Documents
+
+#### From file
+
+```js
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
+
+const parseResult = await dereferenceArazzo('/path/to/arazzo.json');
+// parseResult is ParseResultElement with all references resolved
+```
+
+#### From URL
+
+```js
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
+
+const parseResult = await dereferenceArazzo('https://example.com/arazzo.yaml');
+```
+
+#### From ApiDOM element
+
+When you already have a parsed Arazzo Document (e.g., from `@jentic/arazzo-parser`), you can dereference the element directly:
+
+```js
+import { parseArazzo } from '@jentic/arazzo-parser';
+import { dereferenceArazzoElement } from '@jentic/arazzo-resolver';
+
+// Parse first, then dereference
+const parseResult = await parseArazzo('/path/to/arazzo.json');
+const dereferenced = await dereferenceArazzoElement(parseResult);
+```
+
+##### Without retrievalURI
+
+When dereferencing a ParseResultElement that was parsed from inline content (string or object), you must provide a `baseURI`:
+
+```js
+import { parseArazzo } from '@jentic/arazzo-parser';
+import { dereferenceArazzoElement } from '@jentic/arazzo-resolver';
+
+const parseResult = await parseArazzo({ arazzo: '1.0.1', ... });
+const dereferenced = await dereferenceArazzoElement(parseResult, {
+  resolve: { baseURI: 'https://example.com/arazzo.json' },
+});
+```
+
+##### Child elements
+
+You can dereference individual child elements (e.g., a specific workflow) by providing the parent parseResult in options:
+
+```js
+import { parseArazzo } from '@jentic/arazzo-parser';
+import { dereferenceArazzoElement } from '@jentic/arazzo-resolver';
+
+const parseResult = await parseArazzo('/path/to/arazzo.json');
+const workflow = parseResult.api.workflows.get(0);
+
+const dereferencedWorkflow = await dereferenceArazzoElement(workflow, {
+  dereference: { strategyOpts: { parseResult } },
+});
+```
+
+##### Source descriptions
+
+Source descriptions referenced in the Arazzo Document can optionally be dereferenced using strategy options.
+
+The following options can be passed via `dereference.strategyOpts` (globally) or `dereference.strategyOpts['arazzo-1']` (strategy-specific).
+Strategy-specific options take precedence over global options.
+
+- **sourceDescriptions** - Controls which external source descriptions are dereferenced and included in the result.
+  - `true` - dereference all source descriptions
+  - `string[]` - dereference only source descriptions with matching names (e.g., `['petStore', 'paymentApi']`)
+
+  Each dereferenced source description is added with a `'source-description'` class and metadata (`name`, `type`, `retrievalURI`).
+  Only [OpenAPI 2.0](https://spec.openapis.org/oas/v2.0), [OpenAPI 3.0.x](https://spec.openapis.org/oas/v3.0.4), [OpenAPI 3.1.x](https://spec.openapis.org/oas/v3.1.2), and [Arazzo 1.x](https://spec.openapis.org/arazzo/v1.0.1) documents are accepted as source descriptions.
+- **sourceDescriptionsMaxDepth** - Maximum recursion depth for dereferencing nested Arazzo source descriptions.
+  Defaults to `+Infinity`. Circular references are automatically detected and skipped.
+
+###### Error handling
+
+The source descriptions dereferencing uses annotations instead of throwing errors, allowing dereferencing to continue
+even when individual source descriptions fail. Errors are reported as `AnnotationElement` instances
+with an `'error'` class within the result:
+
+- **Max depth exceeded** - When `sourceDescriptionsMaxDepth` is reached, an error annotation is returned
+  instead of the nested source descriptions
+- **Dereference failures** - If a source description file cannot be dereferenced (e.g., file not found, invalid syntax),
+  an error annotation is returned for that specific source description while other source descriptions
+  continue to be processed
+- **Validation warnings** - Warning annotations (with `'warning'` class) are returned when the dereferenced document
+  is not an OpenAPI or Arazzo specification
+
+```js
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
+
+// Dereference all source descriptions
+const result = await dereferenceArazzo('/path/to/arazzo.json', {
+  dereference: {
+    strategyOpts: {
+      sourceDescriptions: true,
+      sourceDescriptionsMaxDepth: 10,
+    },
+  },
+});
+
+// Dereference only specific source descriptions by name
+const resultFiltered = await dereferenceArazzo('/path/to/arazzo.json', {
+  dereference: {
+    strategyOpts: {
+      'arazzo-1': {
+        sourceDescriptions: ['petStore', 'paymentApi'],
+      },
+    },
+  },
+});
+```
+
+### OpenAPI Documents
+
+Supports [OpenAPI 2.0 (Swagger)](https://spec.openapis.org/oas/v2.0), [OpenAPI 3.0.x](https://spec.openapis.org/oas/v3.0.4), and [OpenAPI 3.1.x](https://spec.openapis.org/oas/v3.1.2).
+
+#### From file
+
+```js
+import { dereferenceOpenAPI } from '@jentic/arazzo-resolver';
+
+const parseResult = await dereferenceOpenAPI('/path/to/openapi.json');
+// parseResult is ParseResultElement with all references resolved
+```
+
+#### From URL
+
+```js
+import { dereferenceOpenAPI } from '@jentic/arazzo-resolver';
+
+const parseResult = await dereferenceOpenAPI('https://example.com/openapi.yaml');
+```
+
+#### From ApiDOM element
+
+When you already have a parsed OpenAPI Document (e.g., from `@jentic/arazzo-parser`), you can dereference the element directly:
+
+```js
+import { parseOpenAPI } from '@jentic/arazzo-parser';
+import { dereferenceOpenAPIElement } from '@jentic/arazzo-resolver';
+
+// Parse first, then dereference
+const parseResult = await parseOpenAPI('/path/to/openapi.json');
+const dereferenced = await dereferenceOpenAPIElement(parseResult);
+```
+
+##### Without retrievalURI
+
+When dereferencing a ParseResultElement that was parsed from inline content (string or object), you must provide a `baseURI`:
+
+```js
+import { parseOpenAPI } from '@jentic/arazzo-parser';
+import { dereferenceOpenAPIElement } from '@jentic/arazzo-resolver';
+
+const parseResult = await parseOpenAPI({ openapi: '3.1.0', ... });
+const dereferenced = await dereferenceOpenAPIElement(parseResult, {
+  resolve: { baseURI: 'https://example.com/openapi.json' },
+});
+```
+
+##### Child elements
+
+You can dereference individual child elements (e.g., a specific Operation Object) by providing the parent parseResult in options:
+
+```js
+import { parseOpenAPI } from '@jentic/arazzo-parser';
+import { dereferenceOpenAPIElement } from '@jentic/arazzo-resolver';
+
+const parseResult = await parseOpenAPI('/path/to/openapi.json');
+const operation = parseResult.api.paths.get('/users').get;
+
+const dereferencedOperation = await dereferenceOpenAPIElement(operation, {
+  dereference: { strategyOpts: { parseResult } },
+});
+```
+
+### Options
+
+All dereference functions accept an optional options argument compatible with [SpecLynx ApiDOM Reference Options](https://github.com/speclynx/apidom/blob/main/packages/apidom-reference/src/options/index.ts):
+
+```js
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
+
+const parseResult = await dereferenceArazzo('/path/to/arazzo.json', {
+  resolve: {
+    baseURI: 'https://example.com/',  // Base URI for relative references
+  },
+  parse: {
+    parserOpts: {
+      strict: false,    // Required for sourceMap and style (default: true)
+      sourceMap: true,  // Include source maps in parsed documents
+      style: true,      // Capture format-specific style information for round-trip preservation
+    },
+  },
+});
+```
+
+#### Default options
+
+You can import and inspect the default options:
+
+```js
+import {
+  defaultDereferenceArazzoOptions,
+  defaultDereferenceOpenAPIOptions,
+} from '@jentic/arazzo-resolver';
+
+console.log(defaultDereferenceArazzoOptions);
+// {
+//   resolve: {
+//     resolvers: [FileResolver, HTTPResolverAxios],
+//   },
+//   parse: {
+//     parsers: [
+//       ArazzoJSON1Parser, ArazzoYAML1Parser,
+//       OpenApiJSON2Parser, OpenApiYAML2Parser,
+//       OpenApiJSON3_0Parser, OpenApiYAML3_0Parser,
+//       OpenApiJSON3_1Parser, OpenApiYAML3_1Parser,
+//       JSONParser, YAMLParser, BinaryParser
+//     ],
+//   },
+//   dereference: {
+//     strategies: [
+//       Arazzo1DereferenceStrategy,
+//       OpenAPI2DereferenceStrategy, OpenAPI3_0DereferenceStrategy, OpenAPI3_1DereferenceStrategy
+//     ],
+//     strategyOpts: {
+//       sourceDescriptions: false,
+//     },
+//   },
+// }
+
+console.log(defaultDereferenceOpenAPIOptions);
+// {
+//   resolve: {
+//     resolvers: [FileResolver, HTTPResolverAxios],
+//   },
+//   parse: {
+//     parsers: [
+//       OpenApiJSON2Parser, OpenApiYAML2Parser,
+//       OpenApiJSON3_0Parser, OpenApiYAML3_0Parser,
+//       OpenApiJSON3_1Parser, OpenApiYAML3_1Parser,
+//       JSONParser, YAMLParser, BinaryParser
+//     ],
+//   },
+//   dereference: {
+//     strategies: [OpenAPI2DereferenceStrategy, OpenAPI3_0DereferenceStrategy, OpenAPI3_1DereferenceStrategy],
+//   },
+// }
+```
+
+### Error handling
+
+When dereferencing fails, a `DereferenceError` is thrown. The original error is available via the `cause` property:
+
+```js
+import { dereferenceArazzo, dereferenceOpenAPI, DereferenceError } from '@jentic/arazzo-resolver';
+
+try {
+  await dereferenceArazzo('/path/to/arazzo.json');
+} catch (error) {
+  if (error instanceof DereferenceError) {
+    console.error(error.message);  // 'Failed to dereference Arazzo Document at "/path/to/arazzo.json"'
+    console.error(error.cause);    // Original error from underlying resolver
+  }
+}
+
+try {
+  await dereferenceOpenAPI('/path/to/openapi.json');
+} catch (error) {
+  if (error instanceof DereferenceError) {
+    console.error(error.message);  // 'Failed to dereference OpenAPI Document at "/path/to/openapi.json"'
+    console.error(error.cause);    // Original error from underlying resolver
+  }
+}
+```
+
+### Working with the result
+
+Both `dereferenceArazzo` and `dereferenceOpenAPI` functions return a [ParseResultElement](https://github.com/speclynx/apidom/blob/main/packages/apidom-datamodel/README.md#parseresultelement) with all references resolved inline.
+
+```js
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
+
+const parseResult = await dereferenceArazzo('/path/to/arazzo.json');
+
+// Access the main Arazzo specification element
+const arazzoSpec = parseResult.api;
+
+// Check if parsing produced any errors
+const hasErrors = parseResult.errors.length > 0;
+
+// Check if parseResult is empty
+const isEmpty = parseResult.isEmpty;
+
+// All references are now resolved inline
+const firstWorkflow = arazzoSpec.workflows.get(0);
+const firstStep = firstWorkflow.steps.get(0);
+```
+
+#### Retrieval URI metadata
+
+Both `dereferenceArazzo` and `dereferenceOpenAPI` functions automatically set `retrievalURI` metadata on the parse result:
+
+```js
+import { dereferenceArazzo, dereferenceOpenAPI } from '@jentic/arazzo-resolver';
+
+const arazzoResult = await dereferenceArazzo('https://example.com/arazzo.yaml');
+const arazzoUri = arazzoResult.meta.get('retrievalURI');
+// 'https://example.com/arazzo.yaml'
+
+const openapiResult = await dereferenceOpenAPI('https://example.com/openapi.yaml');
+const openapiUri = openapiResult.meta.get('retrievalURI');
+// 'https://example.com/openapi.yaml'
+```
+
+Note: `dereferenceArazzoElement` and `dereferenceOpenAPIElement` do not set `retrievalURI` - they preserve whatever metadata was on the original element.
+
+#### Source descriptions
+
+When dereferencing with `sourceDescriptions` enabled, the result contains the entry Arazzo Document at index 0, followed by any dereferenced source descriptions.
+Each source description is a `ParseResultElement` with `'source-description'` class and metadata.
+
+```js
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
+
+const result = await dereferenceArazzo('/path/to/arazzo.json', {
+  dereference: { strategyOpts: { sourceDescriptions: true } },
+});
+
+// Access entry Arazzo Document
+const entryArazzo = result.api; // ArazzoSpecification1Element
+
+// Iterate over source descriptions (starting at index 1)
+for (let i = 1; i < result.length; i++) {
+  const sdParseResult = result.get(i);
+
+  // Check if it's a source description
+  if (sdParseResult.classes.includes('source-description')) {
+    const name = sdParseResult.meta.get('name');
+    const type = sdParseResult.meta.get('type'); // 'openapi' or 'arazzo'
+    const retrievalURI = sdParseResult.meta.get('retrievalURI');
+
+    // Access the dereferenced API element
+    const api = sdParseResult.api; // OpenApi3_1Element, SwaggerElement, ArazzoSpecification1Element, etc.
+    console.log(`Source "${name}" (${type}) from ${retrievalURI}:`, api?.element);
+  }
+}
+```
+
+##### Accessing via SourceDescriptionElement
+
+An alternative way to access dereferenced source descriptions is through the `SourceDescriptionElement` metadata.
+When source descriptions are dereferenced, a `ParseResultElement` is attached to each `SourceDescriptionElement`'s metadata under the key `'parseResult'`.
+
+```js
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
+
+const result = await dereferenceArazzo('/path/to/arazzo.json', {
+  dereference: { strategyOpts: { sourceDescriptions: true } },
+});
+
+const arazzoSpec = result.api;
+
+// Access dereferenced document via SourceDescriptionElement
+const sourceDesc = arazzoSpec.sourceDescriptions.get(0);
+const sdParseResult = sourceDesc.meta.get('parseResult');
+
+// Check for errors before using
+if (sdParseResult.errors.length === 0) {
+  // Access the dereferenced API
+  const api = sdParseResult.api;
+  console.log(`API type: ${api.element}`); // e.g., 'openApi3_1'
+
+  // Get the retrieval URI
+  const retrievalURI = sdParseResult.meta.get('retrievalURI');
+  console.log(`Loaded from: ${retrievalURI}`);
+}
+```
+
+This approach is useful when you need to:
+- Access a specific source description by its position in the `sourceDescriptions` array
+- Get the `retrievalURI` metadata indicating where the document was fetched from
+- Correlate dereferenced documents with their source description definitions
+
+**Note:** When the `ParseResultElement` already contains parsed source descriptions (from parsing with `sourceDescriptions: true`), the dereferencer reuses them instead of re-fetching. This makes the parse-then-dereference workflow efficient.
+
+## SpecLynx ApiDOM tooling
+
+Since `@jentic/arazzo-resolver` produces a SpecLynx ApiDOM data model, you have access to the full suite of ApiDOM tools for manipulating, traversing, and transforming the dereferenced document.
+
+### Core utilities
+
+The [@speclynx/apidom-core](https://github.com/speclynx/apidom/tree/main/packages/apidom-core) package provides essential utilities for working with ApiDOM elements. Here are just a few examples:
+
+```js
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
+import { cloneDeep, cloneShallow } from '@speclynx/apidom-datamodel';
+import { toValue, toJSON, toYAML, sexprs } from '@speclynx/apidom-core';
+
+const parseResult = await dereferenceArazzo('/path/to/arazzo.json');
+const arazzoSpec = parseResult.api;
+
+// Convert to plain JavaScript object
+const obj = toValue(arazzoSpec);
+
+// Serialize to JSON string
+const json = toJSON(arazzoSpec);
+
+// Serialize to YAML string
+const yaml = toYAML(arazzoSpec);
+
+// Clone the element
+const clonedShallow = cloneShallow(arazzoSpec);
+const clonedDeep = cloneDeep(arazzoSpec);
+
+// Get S-expression representation (useful for debugging)
+const sexpr = sexprs(arazzoSpec);
+```
+
+### Traversal
+
+The [@speclynx/apidom-traverse](https://github.com/speclynx/apidom/tree/main/packages/apidom-traverse) package provides powerful traversal capabilities. Here is a basic example:
+
+```js
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
+import { traverse } from '@speclynx/apidom-traverse';
+
+const parseResult = await dereferenceArazzo('/path/to/arazzo.json');
+
+// Traverse and collect steps using semantic visitor hook
+const steps = [];
+traverse(parseResult.api, {
+  StepElement(path) {
+    steps.push(path.node);
+    if (steps.length >= 10) {
+      path.stop(); // Stop traversal after collecting 10 steps
+    }
+  },
+});
+```
+
+For more information about available utilities, see the [SpecLynx ApiDOM documentation](https://github.com/speclynx/apidom).