@speclynx/apidom-reference 5.2.1 → 5.2.2

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.
 
+## [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

package/README.md

@@ -309,6 +309,12 @@ Parser-specific options take precedence over global options.
 - **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
@@ -465,6 +471,12 @@ Parser-specific options take precedence over global options. See [arazzo-json-1]
 - **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.
@@ -2053,6 +2065,12 @@ Strategy-specific options take precedence over global options.
 - **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