@speclynx/apidom-reference 5.1.1 → 5.2.2

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.2.2](https://github.com/speclynx/apidom/compare/v5.2.1...v5.2.2) (2026-09-03)
+
+### Bug Fixes
+
+- **reference:** distinguish shared source descriptions from cycles ([#518](https://github.com/speclynx/apidom/issues/518)) ([b66bac4](https://github.com/speclynx/apidom/commit/b66bac4f5f8f91f5cc1010fb8dd12aed399d5dfa)), closes [usearazzo/arazzo-toolkit#139](https://github.com/usearazzo/arazzo-toolkit/issues/139)
+
+## [5.2.1](https://github.com/speclynx/apidom/compare/v5.2.0...v5.2.1) (2026-08-29)
+
+**Note:** Version bump only for package @speclynx/apidom-reference
+
+# [5.2.0](https://github.com/speclynx/apidom/compare/v5.1.1...v5.2.0) (2026-08-29)
+
+### Features
+
+- **reference:** add support for Arazzo 1.1.0 ([#504](https://github.com/speclynx/apidom/issues/504)) ([1bad06a](https://github.com/speclynx/apidom/commit/1bad06a2a4a7ea7ef57223d4d08a8f60d17eddf2)), closes [#297](https://github.com/speclynx/apidom/issues/297)
+
 ## [5.1.1](https://github.com/speclynx/apidom/compare/v5.1.0...v5.1.1) (2026-08-19)
 
 **Note:** Version bump only for package @speclynx/apidom-reference

package/README.md

@@ -289,6 +289,8 @@ Supported media types are:
   'application/vnd.oai.workflows+json;version=1.0.0',
   'application/vnd.oai.workflows;version=1.0.1',
   'application/vnd.oai.workflows+json;version=1.0.1',
+  'application/vnd.oai.workflows;version=1.1.0',
+  'application/vnd.oai.workflows+json;version=1.1.0',
 ]
 ```
 
@@ -303,9 +305,16 @@ Parser-specific options take precedence over global options.
 
   Each parsed source description is added with a `'source-description'` class and metadata (`name`, `type`, `retrievalURI`).
   Only OpenAPI 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x, and Arazzo 1.x documents are accepted as source descriptions.
+  Source description URLs are resolved against the Arazzo document's base URI (its `$self` field when present, otherwise its retrieval URI).
 - **sourceDescriptionsMaxDepth** - Maximum recursion depth for parsing nested Arazzo source descriptions.
   Defaults to `+Infinity`. Circular references are automatically detected and skipped.
 
+  A document referenced from more than one place (e.g., one OpenAPI description shared by several Arazzo documents)
+  is parsed only once. Every later source description referencing it gets its own `ParseResultElement` with the usual
+  metadata, an `'info'` annotation, and a `'parseResult'` meta pointing at the `ParseResultElement` where the document was parsed.
+  The `SourceDescriptionElement`'s `'parseResult'` meta points at that same `ParseResultElement`, so the parsed
+  document is reachable from every source description that references it.
+
 ##### Error handling
 
 The source descriptions parsing uses annotations instead of throwing errors, allowing parsing to continue
@@ -442,6 +451,8 @@ Supported media types are:
   'application/vnd.oai.workflows+yaml;version=1.0.0',
   'application/vnd.oai.workflows;version=1.0.1',
   'application/vnd.oai.workflows+yaml;version=1.0.1',
+  'application/vnd.oai.workflows;version=1.1.0',
+  'application/vnd.oai.workflows+yaml;version=1.1.0',
 ]
 ```
 
@@ -456,9 +467,16 @@ Parser-specific options take precedence over global options. See [arazzo-json-1]
 
   Each parsed source description is added with a `'source-description'` class and metadata (`name`, `type`, `retrievalURI`).
   Only OpenAPI 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x, and Arazzo 1.x documents are accepted as source descriptions.
+  Source description URLs are resolved against the Arazzo document's base URI (its `$self` field when present, otherwise its retrieval URI).
 - **sourceDescriptionsMaxDepth** - Maximum recursion depth for parsing nested Arazzo source descriptions.
   Defaults to `+Infinity`. Circular references are automatically detected and skipped.
 
+  A document referenced from more than one place (e.g., one OpenAPI description shared by several Arazzo documents)
+  is parsed only once. Every later source description referencing it gets its own `ParseResultElement` with the usual
+  metadata, an `'info'` annotation, and a `'parseResult'` meta pointing at the `ParseResultElement` where the document was parsed.
+  The `SourceDescriptionElement`'s `'parseResult'` meta points at that same `ParseResultElement`, so the parsed
+  document is reachable from every source description that references it.
+
 ##### Error handling
 
 See [arazzo-json-1 Error handling](#error-handling) - the behavior is identical for both JSON and YAML parsers.
@@ -1607,6 +1625,9 @@ Supported media types:
   'application/vnd.oai.workflows;version=1.0.1',
   'application/vnd.oai.workflows+json;version=1.0.1',
   'application/vnd.oai.workflows+yaml;version=1.0.1',
+  'application/vnd.oai.workflows;version=1.1.0',
+  'application/vnd.oai.workflows+json;version=1.1.0',
+  'application/vnd.oai.workflows+yaml;version=1.1.0',
 ]
 ```
 
@@ -2008,6 +2029,11 @@ Supported media types:
 
 Dereference strategy for dereferencing [Arazzo 1.x](https://spec.openapis.org/arazzo/latest.html) definitions.
 
+Relative references (JSON Schema `$ref` keywords and Source Description URLs) are resolved against the document's
+base URI. Per Arazzo 1.1.0, the base URI is the Arazzo Object's `$self` field when present (itself resolved
+against the retrieval URI when relative), otherwise the retrieval URI. A reference whose URI matches the `$self`
+of an already loaded Arazzo document resolves to that document by identity, without fetching it again.
+
 Supported media types:
 
 ```js
@@ -2018,6 +2044,9 @@ Supported media types:
   'application/vnd.oai.workflows;version=1.0.1',
   'application/vnd.oai.workflows+json;version=1.0.1',
   'application/vnd.oai.workflows+yaml;version=1.0.1',
+  'application/vnd.oai.workflows;version=1.1.0',
+  'application/vnd.oai.workflows+json;version=1.1.0',
+  'application/vnd.oai.workflows+yaml;version=1.1.0',
 ]
 ```
 
@@ -2032,9 +2061,16 @@ Strategy-specific options take precedence over global options.
 
   Each dereferenced source description is added with a `'source-description'` class and metadata (`name`, `type`, `retrievalURI`).
   Only OpenAPI 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x, and Arazzo 1.x documents are accepted as source descriptions.
+  Source description URLs are resolved against the Arazzo document's base URI (its `$self` field when present, otherwise its retrieval URI).
 - **sourceDescriptionsMaxDepth** - Maximum recursion depth for dereferencing nested Arazzo source descriptions.
   Defaults to `+Infinity`. Circular references are automatically detected and skipped.
 
+  A document referenced from more than one place (e.g., one OpenAPI description shared by several Arazzo documents)
+  is dereferenced only once. Every later source description referencing it gets its own `ParseResultElement` with the usual
+  metadata, an `'info'` annotation, and a `'parseResult'` meta pointing at the `ParseResultElement` where the document was dereferenced.
+  The `SourceDescriptionElement`'s `'parseResult'` meta points at that same `ParseResultElement`, so the dereferenced
+  document is reachable from every source description that references it.
+
 ###### Error handling
 
 The source descriptions dereferencing uses annotations instead of throwing errors, allowing dereferencing to continue
@@ -2940,6 +2976,9 @@ rules, exactly as in the `openapi-3-1` strategy: the external schema **resource*
 resource is embedded once, keyed by its `$id`; references (including `$anchor`, `$dynamicRef`, and
 `$dynamicAnchor`) are never rewritten. Nested external schema resources are embedded flat into the top-level
 `components.inputs`, deduplicated by resource URI. Internal Schema Object references are preserved untouched.
+Schema Object `$ref`s are resolved against the document's base URI — the Arazzo Object's `$self` field when
+present (Arazzo 1.1.0), otherwise the retrieval URI — and references resolving into the entry document
+(including by its `$self` identity) are treated as internal.
 
 Supported media types:
 
@@ -2950,7 +2989,10 @@ Supported media types:
   'application/vnd.oai.workflows+yaml;version=1.0.0',
   'application/vnd.oai.workflows;version=1.0.1',
   'application/vnd.oai.workflows+json;version=1.0.1',
-  'application/vnd.oai.workflows+yaml;version=1.0.1'
+  'application/vnd.oai.workflows+yaml;version=1.0.1',
+  'application/vnd.oai.workflows;version=1.1.0',
+  'application/vnd.oai.workflows+json;version=1.1.0',
+  'application/vnd.oai.workflows+yaml;version=1.1.0',
 ]
 ```
 
@@ -2963,7 +3005,7 @@ import { bundle } from '@speclynx/apidom-reference';
 
 await bundle('/home/user/arazzo.json', {
   parse: {
-    mediaType: 'application/vnd.oai.workflows+json;version=1.0.1',
+    mediaType: 'application/vnd.oai.workflows+json;version=1.1.0',
   },
   bundle: {
     strategyOpts: {