@jentic/arazzo-resolver 1.0.0-alpha.7 → 1.0.0-alpha.9

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 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.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

package/README.md

@@ -1,18 +1,7 @@
 # @jentic/arazzo-resolver
 
-`@jentic/arazzo-resolver` is a resolver for [Arazzo Specification](https://spec.openapis.org/arazzo/latest.html) documents.
-It produces [SpecLynx ApiDOM](https://github.com/speclynx/apidom) data model using the [Arazzo 1.x namespace](https://github.com/speclynx/apidom/tree/main/packages/apidom-ns-arazzo-1#readme).
-
-## What is dereferencing?
-
-Dereferencing is the process of replacing references with the actual content they point to. In Arazzo Documents, this includes:
-
-- **JSON Schemas** - resolves all referencing mechanisms (`$ref`, `$anchor`, etc.) within schemas
-- **Reusable Object references** (`$components.*`) - references to reusable components like inputs, parameters, and success actions
-
-After dereferencing, all references are resolved inline, making the document self-contained and easier to process programmatically.
-
-**Current limitation:** The resolver only processes the entry Arazzo Document. Referenced OpenAPI/AsyncAPI source descriptions are not resolved.
+`@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)).
 
 ## Installation
 
@@ -22,81 +11,223 @@ You can install this package via [npm](https://npmjs.org/) CLI by running the fo
 npm install @jentic/arazzo-resolver
 ```
 
-## Usage
+## 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.
 
-`@jentic/arazzo-resolver` provides two main functions for dereferencing Arazzo Documents:
+### Functions
 
-1. **`dereference(uri)`** - Dereferences from a file system path or HTTP(S) URL
-2. **`dereferenceElement(element)`** - Dereferences an ApiDOM element
+**Arazzo:**
+- **`dereferenceArazzo(uri)`** - Dereferences from a file system path or HTTP(S) URL
+- **`dereferenceArazzoElement(element)`** - Dereferences a SpecLynx ApiDOM element
 
-### Dereferencing from file
+**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 { dereference } from '@jentic/arazzo-resolver';
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
 
-const parseResult = await dereference('/path/to/arazzo.json');
+const parseResult = await dereferenceArazzo('/path/to/arazzo.json');
 // parseResult is ParseResultElement with all references resolved
 ```
 
-### Dereferencing from URL
+#### From URL
 
 ```js
-import { dereference } from '@jentic/arazzo-resolver';
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
 
-const parseResult = await dereference('https://example.com/arazzo.yaml');
+const parseResult = await dereferenceArazzo('https://example.com/arazzo.yaml');
 ```
 
-### Dereferencing an ApiDOM element
+#### 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 { dereferenceElement } from '@jentic/arazzo-resolver';
+import { dereferenceArazzoElement } from '@jentic/arazzo-resolver';
 
 // Parse first, then dereference
 const parseResult = await parseArazzo('/path/to/arazzo.json');
-const dereferenced = await dereferenceElement(parseResult);
+const dereferenced = await dereferenceArazzoElement(parseResult);
 ```
 
-#### Dereferencing elements without retrievalURI
+##### 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 { dereferenceElement } from '@jentic/arazzo-resolver';
+import { dereferenceArazzoElement } from '@jentic/arazzo-resolver';
 
 const parseResult = await parseArazzo({ arazzo: '1.0.1', ... });
-const dereferenced = await dereferenceElement(parseResult, {
+const dereferenced = await dereferenceArazzoElement(parseResult, {
   resolve: { baseURI: 'https://example.com/arazzo.json' },
 });
 ```
 
-#### Dereferencing child elements
+##### 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 { dereferenceElement } from '@jentic/arazzo-resolver';
+import { dereferenceArazzoElement } from '@jentic/arazzo-resolver';
 
 const parseResult = await parseArazzo('/path/to/arazzo.json');
 const workflow = parseResult.api.workflows.get(0);
 
-const dereferencedWorkflow = await dereferenceElement(workflow, {
+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`).
+  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 } },
 });
 ```
 
-## Dereference options
+### Options
 
-Both `dereference` and `dereferenceElement` 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):
+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 { dereference } from '@jentic/arazzo-resolver';
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
 
-const parseResult = await dereference('/path/to/arazzo.json', {
+const parseResult = await dereferenceArazzo('/path/to/arazzo.json', {
   resolve: {
     baseURI: 'https://example.com/',  // Base URI for relative references
   },
@@ -108,53 +239,94 @@ const parseResult = await dereference('/path/to/arazzo.json', {
 });
 ```
 
-### Default options
+#### Default options
 
 You can import and inspect the default options:
 
 ```js
-import { defaultDereferenceOptions } from '@jentic/arazzo-resolver';
+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(defaultDereferenceOptions);
+console.log(defaultDereferenceOpenAPIOptions);
 // {
 //   resolve: {
 //     resolvers: [FileResolver, HTTPResolverAxios],
 //   },
 //   parse: {
-//     mediaType: 'application/vnd.oai.arazzo;version=1.0.1',
-//     parsers: [ArazzoJSON1Parser, ArazzoYAML1Parser, JSONParser, YAMLParser, BinaryParser],
+//     parsers: [
+//       OpenApiJSON2Parser, OpenApiYAML2Parser,
+//       OpenApiJSON3_0Parser, OpenApiYAML3_0Parser,
+//       OpenApiJSON3_1Parser, OpenApiYAML3_1Parser,
+//       JSONParser, YAMLParser, BinaryParser
+//     ],
 //   },
 //   dereference: {
-//     strategies: [Arazzo1, OpenAPI2, OpenAPI3_0, OpenAPI3_1],
+//     strategies: [OpenAPI2DereferenceStrategy, OpenAPI3_0DereferenceStrategy, OpenAPI3_1DereferenceStrategy],
 //   },
 // }
 ```
 
-## Error handling
+### Error handling
 
 When dereferencing fails, a `DereferenceError` is thrown. The original error is available via the `cause` property:
 
 ```js
-import { dereference, DereferenceError } from '@jentic/arazzo-resolver';
+import { dereferenceArazzo, dereferenceOpenAPI, DereferenceError } from '@jentic/arazzo-resolver';
 
 try {
-  await dereference('/path/to/arazzo.json');
+  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
+### Working with the result
 
-The `dereference` function returns a [ParseResultElement](https://github.com/speclynx/apidom/blob/main/packages/apidom-datamodel/README.md#parseresultelement) with all references resolved inline.
+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 { dereference } from '@jentic/arazzo-resolver';
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
 
-const parseResult = await dereference('/path/to/arazzo.json');
+const parseResult = await dereferenceArazzo('/path/to/arazzo.json');
 
 // Access the main Arazzo specification element
 const arazzoSpec = parseResult.api;
@@ -170,31 +342,56 @@ const firstWorkflow = arazzoSpec.workflows.get(0);
 const firstStep = firstWorkflow.steps.get(0);
 ```
 
-### Retrieval URI metadata
+#### Retrieval URI metadata
 
-The `dereference` function automatically sets `retrievalURI` metadata on the parse result:
+Both `dereferenceArazzo` and `dereferenceOpenAPI` functions automatically set `retrievalURI` metadata on the parse result:
 
 ```js
-import { dereference } from '@jentic/arazzo-resolver';
+import { dereferenceArazzo, dereferenceOpenAPI } from '@jentic/arazzo-resolver';
 import { toValue } from '@speclynx/apidom-core';
 
-const parseResult = await dereference('https://example.com/arazzo.yaml');
-
-const uri = toValue(parseResult.meta.get('retrievalURI'));
+const arazzoResult = await dereferenceArazzo('https://example.com/arazzo.yaml');
+const arazzoUri = toValue(arazzoResult.meta.get('retrievalURI'));
 // 'https://example.com/arazzo.yaml'
+
+const openapiResult = await dereferenceOpenAPI('https://example.com/openapi.yaml');
+const openapiUri = toValue(openapiResult.meta.get('retrievalURI'));
+// 'https://example.com/openapi.yaml'
 ```
 
-Note: `dereferenceElement` does not set `retrievalURI` - it preserves whatever metadata was on the original element.
+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';
+import { toValue } from '@speclynx/apidom-core';
+
+const result = await dereferenceArazzo('/path/to/arazzo.json', {
+  dereference: { strategyOpts: { sourceDescriptions: true } },
+});
+
+// Access entry Arazzo Document
+const entryArazzo = result.api; // ArazzoSpecification1Element
 
-## Function aliases
+// Iterate over source descriptions (starting at index 1)
+for (let i = 1; i < result.length; i++) {
+  const sdParseResult = result.get(i);
 
-For consistency with future OpenAPI/AsyncAPI support, the following aliases are available:
+  // Check if it's a source description
+  if (sdParseResult.classes.includes('source-description')) {
+    const name = toValue(sdParseResult.meta.get('name'));
+    const type = toValue(sdParseResult.meta.get('type')); // 'openapi' or 'arazzo'
 
-| Function | Alias |
-|----------|-------|
-| `dereference` | `dereferenceArazzo` |
-| `dereferenceElement` | `dereferenceArazzoElement` |
-| `defaultDereferenceOptions` | `defaultDereferenceArazzoOptions` |
+    // Access the dereferenced API element
+    const api = sdParseResult.api; // OpenApi3_1Element, SwaggerElement, ArazzoSpecification1Element, etc.
+    console.log(`Source "${name}" (${type}):`, api?.element);
+  }
+}
+```
 
 ## SpecLynx ApiDOM tooling
 
@@ -205,11 +402,11 @@ Since `@jentic/arazzo-resolver` produces a SpecLynx ApiDOM data model, you have
 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 { dereference } from '@jentic/arazzo-resolver';
+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 dereference('/path/to/arazzo.json');
+const parseResult = await dereferenceArazzo('/path/to/arazzo.json');
 const arazzoSpec = parseResult.api;
 
 // Convert to plain JavaScript object
@@ -234,10 +431,10 @@ const sexpr = sexprs(arazzoSpec);
 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 { dereference } from '@jentic/arazzo-resolver';
+import { dereferenceArazzo } from '@jentic/arazzo-resolver';
 import { traverse } from '@speclynx/apidom-traverse';
 
-const parseResult = await dereference('/path/to/arazzo.json');
+const parseResult = await dereferenceArazzo('/path/to/arazzo.json');
 
 // Traverse and collect steps using semantic visitor hook
 const steps = [];