@speclynx/apidom-reference 4.13.0 → 4.15.0

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.
 
+# [4.15.0](https://github.com/speclynx/apidom/compare/v4.14.0...v4.15.0) (2026-06-24)
+
+### Features
+
+- **reference:** add Arazzo 1 bundle strategy ([#367](https://github.com/speclynx/apidom/issues/367)) ([c2bbf7f](https://github.com/speclynx/apidom/commit/c2bbf7f27214839d7288c6439ec482e4094756a3))
+
+# [4.14.0](https://github.com/speclynx/apidom/compare/v4.13.0...v4.14.0) (2026-06-23)
+
+### Features
+
+- **reference:** add OpenAPI 3.1 bundle strategy ([#361](https://github.com/speclynx/apidom/issues/361)) ([ab3effb](https://github.com/speclynx/apidom/commit/ab3effb7d1f19ae4d757ba222b194e477e64d6e8)), closes [#351](https://github.com/speclynx/apidom/issues/351)
+
 # [4.13.0](https://github.com/speclynx/apidom/compare/v4.12.1...v4.13.0) (2026-06-23)
 
 ### Features

package/README.md

@@ -2863,9 +2863,27 @@ the original.
 
 Bundle strategy for bundling [OpenApi 3.1.x](https://spec.openapis.org/oas/v3.1.2.html) definitions.
 
-> **Note:** this strategy is **not implemented yet**. It matches OpenAPI 3.1.x
-> documents but currently returns the parse result unchanged (no references are
-> resolved or hoisted). For real bundling, use OpenAPI 3.0.x for now.
+It produces a self-contained, transferable Compound Document. **Reference Objects** are bundled exactly as
+in the `openapi-3-0` strategy: every external reference is resolved and lifted into the appropriate
+`components` field, and the referencing `$ref` is rewritten to an internal JSON Pointer. The one upgrade
+over 3.0 is **Path Item Objects** — OpenAPI 3.1 adds a `components.pathItems` field, so an external Path
+Item is hoisted there (and its `$ref` rewritten to `#/components/pathItems/<name>`) instead of being
+inlined in place. Example Object `externalValue` content is inlined, and an external Link Object
+`operationRef` is rewritten to an absolute URI so the link stays resolvable.
+
+**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.
+
+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
+preserved untouched; only a self-file reference (e.g. `./root.json#/components/parameters/userId`) is
+normalized to a bare fragment (`#/components/parameters/userId`) so the bundled document remains transferable.
 
 Supported media types:
 
@@ -2883,6 +2901,83 @@ Supported media types:
 ]
 ```
 
+This strategy's behavior is controlled by the same `bundle` options as the `openapi-3-0` strategy
+(`componentNamesStrategy`, `onComponentNameCollision`, `immutable`, `maxDepth`, `continueOnError`, `refSet`),
+documented above. Per-strategy overrides use the `openapi-3-1` key in `bundle.strategyOpts`:
+
+```js
+import { bundle } from '@speclynx/apidom-reference';
+
+await bundle('/home/user/oas.json', {
+  parse: {
+    mediaType: 'application/openapi+json;version=3.1.0',
+  },
+  bundle: {
+    strategyOpts: {
+      'openapi-3-1': {
+        onComponentNameCollision: 'error',
+      },
+    },
+  },
+});
+```
+
+Hoisted components and embedded schema resources are annotated with a `ref-origin` meta field pointing at
+their source document. The bundling process is **immutable** by default (`bundle.immutable: true`).
+
+##### [arazzo-1](https://github.com/speclynx/apidom/tree/main/packages/apidom-reference/src/bundle/strategies/arazzo-1)
+
+Bundle strategy for bundling [Arazzo 1.x](https://spec.openapis.org/arazzo/latest.html) definitions.
+
+The only external references Arazzo defines are **JSON Schema Objects** — a
+[JSON Schema 2020-12](https://json-schema.org/draft/2020-12) dialect used by Input Objects and inline schemas.
+(Reusable Objects are internal-only runtime-expression references, and Source Descriptions point at whole
+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.
+
+Supported media types:
+
+```js
+[
+  'application/vnd.oai.workflows;version=1.0.0',
+  'application/vnd.oai.workflows+json;version=1.0.0',
+  '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'
+]
+```
+
+This strategy's behavior is controlled by the same `bundle` options as the `openapi-3-1` strategy
+(`componentNamesStrategy`, `onComponentNameCollision`, `immutable`, `maxDepth`, `continueOnError`, `refSet`),
+documented above. Per-strategy overrides use the `arazzo-1` key in `bundle.strategyOpts`:
+
+```js
+import { bundle } from '@speclynx/apidom-reference';
+
+await bundle('/home/user/arazzo.json', {
+  parse: {
+    mediaType: 'application/vnd.oai.workflows+json;version=1.0.1',
+  },
+  bundle: {
+    strategyOpts: {
+      'arazzo-1': {
+        onComponentNameCollision: 'error',
+      },
+    },
+  },
+});
+```
+
+Embedded schema resources are annotated with a `ref-origin` meta field pointing at their source document.
+The bundling process is **immutable** by default (`bundle.immutable: true`).
+
 ##### Bundle strategies execution order
 
 It's important to understand that default bundle strategies are run in specific order. The order is determined
@@ -2898,6 +2993,7 @@ returns `true` or until entire list of strategies is exhausted (throws error).
   new OpenAPI2BundleStrategy(),
   new OpenAPI3_0BundleStrategy(),
   new OpenAPI3_1BundleStrategy(),
+  new Arazzo1BundleStrategy(),
 ]
 ```
 Most specific strategies are listed first, most generic are listed last.