@speclynx/apidom-reference 5.2.4 → 5.2.6

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.2.6](https://github.com/speclynx/apidom/compare/v5.2.5...v5.2.6) (2026-09-19)
+
+### Bug Fixes
+
+- **reference:** honour continueOnError for Arazzo Reusable Objects ([#552](https://github.com/speclynx/apidom/issues/552)) ([2bcd675](https://github.com/speclynx/apidom/commit/2bcd675d16fc1bf3fc5079fdee37419c1d84017c)), closes [#550](https://github.com/speclynx/apidom/issues/550)
+- **reference:** isolate refSet of Arazzo source descriptions ([#553](https://github.com/speclynx/apidom/issues/553)) ([ac21c16](https://github.com/speclynx/apidom/commit/ac21c165104e604aa59f027a8d78645c8bd9ca66)), closes [#551](https://github.com/speclynx/apidom/issues/551)
+
+## [5.2.5](https://github.com/speclynx/apidom/compare/v5.2.4...v5.2.5) (2026-09-17)
+
+### Bug Fixes
+
+- **reference:** assign relative $id to embedded schema resources ([#543](https://github.com/speclynx/apidom/issues/543)) ([3ba02e8](https://github.com/speclynx/apidom/commit/3ba02e82ea22a93b40d04c43ec190810a0f4b177)), closes [#531](https://github.com/speclynx/apidom/issues/531)
+- **reference:** defer bundle placement until entry traversal ends ([#538](https://github.com/speclynx/apidom/issues/538)) ([e70f735](https://github.com/speclynx/apidom/commit/e70f73503f21074dda67928d223842df1bdf43f9)), closes [#535](https://github.com/speclynx/apidom/issues/535)
+- **reference:** embed sibling $id schemas of hoisted OAS 3.1 content ([#547](https://github.com/speclynx/apidom/issues/547)) ([65d0998](https://github.com/speclynx/apidom/commit/65d09986191ea5dfb12ee63b78a56bba8ca18057)), closes [#546](https://github.com/speclynx/apidom/issues/546)
+- **reference:** rebase schema $ref onto embedded resource $id ([#532](https://github.com/speclynx/apidom/issues/532)) ([840c89c](https://github.com/speclynx/apidom/commit/840c89cdddab270ac6cdc389fc27c8be24e4a857)), closes [#530](https://github.com/speclynx/apidom/issues/530) [#531](https://github.com/speclynx/apidom/issues/531) [usearazzo/arazzo-toolkit#158](https://github.com/usearazzo/arazzo-toolkit/issues/158)
+- **reference:** relocate schema $refs in hoisted OAS 3.1 components ([#542](https://github.com/speclynx/apidom/issues/542)) ([71e067b](https://github.com/speclynx/apidom/commit/71e067b019f809f37a08cb185d61a75d9d07715b)), closes [#537](https://github.com/speclynx/apidom/issues/537)
+- **reference:** resolve schema $id lookups against document base URI ([#539](https://github.com/speclynx/apidom/issues/539)) ([e4763fa](https://github.com/speclynx/apidom/commit/e4763fada3b569c5811b1a8f02014017ef1d2679)), closes [#536](https://github.com/speclynx/apidom/issues/536)
+- **reference:** resolve schema $id within referenced OAS 3.1 fragments ([#545](https://github.com/speclynx/apidom/issues/545)) ([c69ab53](https://github.com/speclynx/apidom/commit/c69ab531bde79a10bdd7406d9c8f56ea7536436b)), closes [#541](https://github.com/speclynx/apidom/issues/541)
+
 ## [5.2.4](https://github.com/speclynx/apidom/compare/v5.2.3...v5.2.4) (2026-09-15)
 
 **Note:** Version bump only for package @speclynx/apidom-reference

package/README.md

@@ -2071,6 +2071,10 @@ Strategy-specific options take precedence over global options.
   The `SourceDescriptionElement`'s `'parseResult'` meta points at that same `ParseResultElement`, so the dereferenced
   document is reachable from every source description that references it.
 
+  When `dereference.refSet` is provided, source descriptions reuse the documents it already contains,
+  and every document reached through a source description is added to it.
+  This is also how resolving with `sourceDescriptions` enabled reports the documents behind source descriptions.
+
 ###### Error handling
 
 The source descriptions dereferencing uses annotations instead of throwing errors, allowing dereferencing to continue
@@ -2496,16 +2500,16 @@ await dereference('/home/user/oas.json', {
 // errors is an array of UnresolvableReferenceError instances
 ```
 
-Each `UnresolvableReferenceError` (extends `DereferenceError`) carries structured context:
+Each `UnresolvableReferenceError` (extends `ResolveError`) carries structured context:
 
 | Property | Type | Description |
 |---|---|---|
 | `message` | `string` | Contextual description (e.g., "Error while dereferencing Reference Object. Cannot resolve $ref ...") |
-| `type` | `string` | Element type that failed (e.g., `"reference"`, `"pathItem"`, `"schema"`, `"link"`, `"example"`) |
+| `type` | `string` | Element type that failed (e.g., `"reference"`, `"pathItem"`, `"schema"`, `"link"`, `"example"`, `"reusable"`) |
 | `uri` | `string` | Document URI where the error occurred |
 | `location` | `string` | JSON Pointer to the element within the document |
 | `codeFrame` | `string` | YAML snippet of the referencing element |
-| `refFieldName` | `string` | Reference field name (e.g., `"$ref"`, `"operationRef"`, `"externalValue"`) |
+| `refFieldName` | `string` | Reference field name (e.g., `"$ref"`, `"operationRef"`, `"externalValue"`, `"reference"`) |
 | `refFieldValue` | `string` | Reference field value |
 | `trace` | `Array` | Chain of reference hops from entry document to the failure |
 | `cause` | `Error` | The underlying error |
@@ -2909,12 +2913,26 @@ inlined in place. Example Object `externalValue` content is inlined, and an exte
 
 **Schema Objects** are a [JSON Schema 2020-12](https://json-schema.org/draft/2020-12) dialect and are
 bundled per the [JSON Schema Compound Document](https://json-schema.org/blog/posts/bundling-json-schema-compound-documents)
-rules: the external schema **resource** is embedded verbatim into `components.schemas` carrying its `$id`
-(one is assigned from the retrieval URI when absent), and the referencing `$ref` is left **unchanged** — it
-keeps resolving against the embedded resource's `$id`. The whole external 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.schemas`, deduplicated by resource
-URI. Internal Schema Object references are preserved untouched.
+rules: the external schema **resource** is embedded verbatim into `components.schemas` carrying its `$id`.
+A resource without a `$id` of its own gets one assigned as a URI-reference relative to the entry document's
+base URI (e.g. `schemas/ex.json`), so the bundle carries no absolute filesystem paths and stays self-contained
+when moved as a directory tree. The referencing `$ref` is **rebased** onto the embedded
+resource's `$id` (keeping any `$anchor` or JSON Pointer fragment) whenever it resolves to a different URI —
+e.g. `./ex.json#/$defs/Pet` becomes `https://example.com/schemas/pets#/$defs/Pet` — since once embedded the
+resource is reachable only by its `$id`; a `$ref` that already resolves to that `$id` is left unchanged. The
+whole external resource is embedded once, keyed by its `$id`; `$anchor`, `$dynamicRef`, and `$dynamicAnchor`
+inside the embedded resource are preserved verbatim. Nested external `$ref`s inside an embedded resource are
+bundled the same way — the nested resource is embedded flat into the top-level `components.schemas`,
+deduplicated by resource URI, and the nested `$ref` is rebased onto its `$id` when needed. Internal Schema
+Object references are preserved untouched.
+
+A Schema Object carried inside a hoisted component (a Response, Parameter, Request Body, Path Item, ...) changes
+its base URI on relocation — from the hoisted document's to the entry document's — so a location-based `$ref`
+in it is rewritten to address the embedded resource from the entry document: by the resource's declared `$id`,
+or, when the `$id` was assigned from the retrieval URI, by a URI reference relative to the entry document
+(e.g. `./pet.json` inside `responses/ok.json` becomes `responses/pet.json`), keeping any fragment. A `$ref`
+that resolves to the same URI from the entry document — under an absolute `$id`, or from a hoisted document
+sitting next to the entry document — is left as written.
 
 Multiple references to the **same** external target are collapsed into a single component; distinct targets
 each get their own component, even when their content happens to be identical. Internal Reference Objects are
@@ -2971,11 +2989,16 @@ The only external references Arazzo defines are **JSON Schema Objects** — a
 external documents that are intentionally kept external — neither is bundled.) Schema Objects are therefore
 bundled per the [JSON Schema Compound Document](https://json-schema.org/blog/posts/bundling-json-schema-compound-documents)
 rules, exactly as in the `openapi-3-1` strategy: the external schema **resource** is embedded verbatim into
-`components.inputs` carrying its `$id` (one is assigned from the retrieval URI when absent), and the referencing
-`$ref` is left **unchanged** — it keeps resolving against the embedded resource's `$id`. The whole external
-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.
+`components.inputs` carrying its `$id`. A resource without a `$id` of its own is assigned one relative to the
+entry document's base URI (its `$self` when present), e.g. `schemas/ex.json`. The referencing
+`$ref` is **rebased** onto the embedded resource's `$id` (keeping any `$anchor` or JSON Pointer fragment)
+whenever it resolves to a different URI — e.g. `./ex.json#/$defs/Pet` becomes
+`https://example.com/schemas/pets#/$defs/Pet` — since once embedded the resource is reachable only by its `$id`;
+a `$ref` that already resolves to that `$id` is left unchanged. The whole external resource is embedded once,
+keyed by its `$id`; `$anchor`, `$dynamicRef`, and `$dynamicAnchor` inside the embedded resource are preserved
+verbatim. Nested external `$ref`s inside an embedded resource are bundled the same way — the nested resource is
+embedded flat into the top-level `components.inputs`, deduplicated by resource URI, and the nested `$ref` is
+rebased onto its `$id` when needed. 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.