@speclynx/apidom-reference 5.2.4 → 5.2.5

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [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

@@ -2909,12 +2909,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 +2985,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.