@speclynx/apidom-reference 6.1.2 → 7.0.0

package/CHANGELOG.md

@@ -3,6 +3,69 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [7.0.0](https://github.com/speclynx/apidom/compare/v6.2.0...v7.0.0) (2026-11-08)
+
+### Bug Fixes
+
+- **reference:** address arazzo-1 dereference review findings ([319775e](https://github.com/speclynx/apidom/commit/319775e226c65e9dd123f1b0f08618f9e003ded6)), closes [#757](https://github.com/speclynx/apidom/issues/757)
+- **reference:** address dereference by expected type review findings ([d08052d](https://github.com/speclynx/apidom/commit/d08052dd65470057fe0fb49ccb9c22826aa080a3)), closes [#757](https://github.com/speclynx/apidom/issues/757)
+- **reference:** dereference arazzo-1 references by expected type ([76570ce](https://github.com/speclynx/apidom/commit/76570ce6f5aacf61038c0474d10ba816b8fa486d)), closes [#751](https://github.com/speclynx/apidom/issues/751) [#757](https://github.com/speclynx/apidom/issues/757)
+- **reference:** dereference asyncapi-2 references by expected type ([0ea89fd](https://github.com/speclynx/apidom/commit/0ea89fdd7a7c6e2329336980c805050cf1b8ad80)), closes [#753](https://github.com/speclynx/apidom/issues/753) [#756](https://github.com/speclynx/apidom/issues/756)
+- **reference:** dereference each shared reusable component once ([cc26ac4](https://github.com/speclynx/apidom/commit/cc26ac4fb5573913155383624e86da6213febd04)), closes [#751](https://github.com/speclynx/apidom/issues/751)
+- **reference:** dereference frozen elements without editing them ([98917c0](https://github.com/speclynx/apidom/commit/98917c0d636517c338533316a5ee793810f647e9)), closes [#766](https://github.com/speclynx/apidom/issues/766)
+- **reference:** dereference openapi-2 references by expected type ([b1bbe37](https://github.com/speclynx/apidom/commit/b1bbe37156714e0e837a52c83aac17bed96dbe98)), closes [#753](https://github.com/speclynx/apidom/issues/753) [#756](https://github.com/speclynx/apidom/issues/756)
+- **reference:** dereference openapi-3-0 references by expected type ([d570b0c](https://github.com/speclynx/apidom/commit/d570b0c1c35a826b7c2372c4deb807c15af4d6bb)), closes [#753](https://github.com/speclynx/apidom/issues/753) [#756](https://github.com/speclynx/apidom/issues/756)
+- **reference:** dereference openapi-3-1 references by expected type ([70c7f94](https://github.com/speclynx/apidom/commit/70c7f94632185dba21cfa1aa5eafeaaaa786e27f)), closes [#754](https://github.com/speclynx/apidom/issues/754) [#756](https://github.com/speclynx/apidom/issues/756)
+- **reference:** dereference reusable objects nested in components ([64dff81](https://github.com/speclynx/apidom/commit/64dff81cc9d62a3b518db2b9b95f0335d529fdc3)), closes [#751](https://github.com/speclynx/apidom/issues/751)
+- **reference:** detect generic targets by class in DereferenceVisitor ([5baea86](https://github.com/speclynx/apidom/commit/5baea86a9d8ac2d479380a3e12c8abaa84981e48)), closes [#757](https://github.com/speclynx/apidom/issues/757)
+- **reference:** report error locations in external documents once ([a24358b](https://github.com/speclynx/apidom/commit/a24358b4e668ec6860798058a5a0210568211cde)), closes [#555](https://github.com/speclynx/apidom/issues/555)
+- **reference:** select parsers by the given media type first ([5b490c7](https://github.com/speclynx/apidom/commit/5b490c7c16517b373fc985c3ec3fb42efb7ad454)), closes [#620](https://github.com/speclynx/apidom/issues/620)
+- **reference:** skip only dereferenced elements in arazzo-1 deref ([4789960](https://github.com/speclynx/apidom/commit/47899604d0796932d127f14f2419facdefeee8e6)), closes [#751](https://github.com/speclynx/apidom/issues/751)
+- **reference:** skip parsed source descriptions in arazzo-1 deref ([45f4484](https://github.com/speclynx/apidom/commit/45f448474ac0db8ad08f580f2e50df74db6bb96f)), closes [#757](https://github.com/speclynx/apidom/issues/757)
+- **traverse:** use the leaving node's own key on leave ([a44ef46](https://github.com/speclynx/apidom/commit/a44ef467872a2b0e724b4cbd37187374f14f3ea2)), closes [#16](https://github.com/speclynx/apidom/issues/16)
+
+### Code Refactoring
+
+- **reference:** remove AncestorLineage ([e9e62c2](https://github.com/speclynx/apidom/commit/e9e62c2da1dcb5526eafd75e1898db8a1f1ed157)), closes [#757](https://github.com/speclynx/apidom/issues/757)
+
+### BREAKING CHANGES
+
+- **reference:** Arazzo1DereferenceVisitor no longer dereferences when
+  traversed directly: its dereference(element) method does, and its
+  handlers only record transclusions. Arazzo1DereferenceVisitorOptions no
+  longer accepts indirections, ancestors and visited. A Reusable Object
+  referencing a component of another type yields that component refracted
+  to the expected type, and a JSON Schema $ref to a non-schema element
+  yields a JSON Schema. A ReferenceSet passed to the arazzo-1 strategy
+  is no longer cloned with immutable=true: documents loaded during
+  dereference are added to it as parsed, and its circular flag is set.
+- **reference:** DereferenceAncestorLineage is no longer exported, nor
+  is the AncestorLineage type from the dereference strategies.
+  OpenAPI3_1DereferenceVisitor, OpenAPI3_0DereferenceVisitor,
+  OpenAPI2DereferenceVisitor and AsyncAPI2DereferenceVisitor extend
+- **reference:** when parse.mediaType is listed by a parser, that parser
+  parses the file even if the file's contents are detected as another
+  specification or version by an earlier configured parser. Media types
+  differing from the listed ones only in case, whitespace or additional
+  parameters, or listed with wildcards, now select the parsers and
+  strategies listing them instead of falling back to detection or
+  matching no strategy. File.mediaType is trimmed, and text/plain for a
+  blank media type or one that isn't a string.
+
+# [6.2.0](https://github.com/speclynx/apidom/compare/v6.1.2...v6.2.0) (2026-11-07)
+
+### Bug Fixes
+
+- **reference:** decode file system path characters only once ([41b8476](https://github.com/speclynx/apidom/commit/41b8476ca854b4eb0225e7b07736a416f7420e31)), closes [#733](https://github.com/speclynx/apidom/issues/733)
+- **reference:** keep an encoded file:// page URL as default baseURI ([af3bfe0](https://github.com/speclynx/apidom/commit/af3bfe09690ad0c9289cf9bd3411bf3ebb4a9413)), closes [#733](https://github.com/speclynx/apidom/issues/733)
+- **reference:** normalize root URI across entry points ([9c2475d](https://github.com/speclynx/apidom/commit/9c2475d2ad4da4ae3b2bdc54e353f754655463ef)), closes [#733](https://github.com/speclynx/apidom/issues/733)
+- **reference:** round-trip '?' in file system paths ([bb4af5b](https://github.com/speclynx/apidom/commit/bb4af5b9a980ea97688ad6b919b3bb932dd55257)), closes [#733](https://github.com/speclynx/apidom/issues/733)
+- **reference:** sanitize the path of file:// URLs in url.normalize ([8db965b](https://github.com/speclynx/apidom/commit/8db965baac0667eafd5ca2ab2bf695595c6c8831)), closes [#733](https://github.com/speclynx/apidom/issues/733)
+
+### Features
+
+- **reference:** add url.normalize util ([dcb7aea](https://github.com/speclynx/apidom/commit/dcb7aeaa6aa91b9c28fc52e769e7e6fd9848be36)), closes [#733](https://github.com/speclynx/apidom/issues/733)
+
 ## [6.1.2](https://github.com/speclynx/apidom/compare/v6.1.1...v6.1.2) (2026-10-29)
 
 **Note:** Version bump only for package @speclynx/apidom-reference

package/README.md

@@ -79,6 +79,15 @@ await parse('https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/ex
 Notice how we explicitly pass a `mediaType` parse option. This option is actually **not required**,
 but if not provided, the Parse component will try to identify appropriate parser plugin by file contents, and it's extension (`.json`).
 
+When provided, the parser plugins listing the `mediaType` parse the file first, before the ones detecting it by its contents,
+which are only used when the listing ones fail. A media type of a serialization format only (`application/json`, `application/yaml`,
+`text/yaml`) names no specification, so for it the parser plugins keep their configured order, which puts the specific ones
+(e.g. OpenAPI JSON) before the generic ones (JSON). Media types are compared as defined by [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#section-8.3.1):
+type, subtype and parameter names ignore case, whitespace around the media type and its parameters doesn't matter, and the given media type
+may carry additional parameters, so a `Content-Type` value like `application/openapi+yaml; version=3.1.2; charset=utf-8`
+selects the OpenAPI 3.1 YAML parser. Resolve, dereference and bundle strategies compare the `mediaType` with the media types
+they list the same way.
+
 What actually happens if you don't provide `mediaType` parse option?
 
 ```js
@@ -1536,6 +1545,12 @@ await resolve('https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/
 When externally resolving an ApiDOM fragment, [baseURI](https://github.com/speclynx/apidom/blob/91763fa4ad876375a413e7049c28c2031c7bbe83/apidom/packages/apidom-reference/src/options/index.ts#L47)
 resolve option needs to be provided to have a starting point for external dependency resolution.
 `mediaType` parse option is unnecessary as we can directly assert the type of ApiDOM fragment.
+A fragment in `baseURI` means the ApiDOM fragment is located at that fragment of the document,
+e.g. `/home/user/root.json#/components/parameters/userId`. When passing a whole document,
+give `baseURI` without a fragment.
+`baseURI` must be absolute: a file system path, a `file://` URL or an HTTP(S) URL. It defaults
+to the current working directory (the page URL in browsers). The same applies to the file passed
+to `resolve`, `dereference` or `bundle`; resolve a relative path first, e.g. with `path.resolve`.
 
 ```js
 import { OpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
@@ -1937,6 +1952,12 @@ await dereference('https://raw.githubusercontent.com/OAI/OpenAPI-Specification/m
 When dereferencing an ApiDOM fragment, [baseURI](https://github.com/speclynx/apidom/blob/91763fa4ad876375a413e7049c28c2031c7bbe83/apidom/packages/apidom-reference/src/options/index.ts#L47)
 resolve option needs to be provided to have a starting point for external dependency resolution.
 `mediaType` parse option is unnecessary as we can directly assert the type of ApiDOM fragment.
+A fragment in `baseURI` means the ApiDOM fragment is located at that fragment of the document,
+e.g. `/home/user/root.json#/components/parameters/userId`. When passing a whole document,
+give `baseURI` without a fragment.
+`baseURI` must be absolute: a file system path, a `file://` URL or an HTTP(S) URL. It defaults
+to the current working directory (the page URL in browsers). The same applies to the file passed
+to `resolve`, `dereference` or `bundle`; resolve a relative path first, e.g. with `path.resolve`.
 
 **ex.json**
 
@@ -1987,6 +2008,13 @@ const dereferenced = await dereferenceApiDOM(apidom, {
 Dereference strategy determines how a document is internally or externally dereferenced. Depending on document `mediaType` option,
 every strategy differs significantly. `Dereference component` comes with six (6) default dereference strategies.
 
+The `arazzo-1`, `asyncapi-2`, `openapi-2`, `openapi-3-0` and `openapi-3-1` strategies read a referenced structure
+as the type its reference expects (a structure referenced as a Parameter Object and as a Header Object is read as both),
+and dereference it once per type. Elements transcluded in place of references carry the `ref-type` meta.
+Frozen elements aren't edited: when the dereferenced element, a document of the `dereference.refSet` or its parsed
+result is frozen, `dereference.immutable: false` dereferences as `dereference.immutable: true` does, for the whole run.
+Only these are checked: a frozen element within an unfrozen document is dereferenced in place.
+
 #### [apidom](https://github.com/speclynx/apidom/tree/main/packages/apidom-reference/src/dereference/strategies/apidom)
 
 Dereference strategy for dereferencing ApiDOM using [Ref Element](https://apielements.org/en/latest/element-definitions.html?highlight=referencing#ref-element).
@@ -2043,6 +2071,35 @@ base URI. Per Arazzo 1.1.0, the base URI is the Arazzo Object's `$self` field wh
 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.
 
+With `dereference.immutable` (the default) the dereferenced documents aren't edited: the result is a new tree.
+With `dereference.immutable: false` the documents are dereferenced in place and the dereferenced
+ParseResultElement itself is returned. Elements transcluded in place of references carry the `ref-type` meta
+and aren't traversed again, so dereferencing a document dereferenced in place earlier leaves those parts as they are.
+
+The **reference decides the type of what it points at**. A Reusable Object (`reference` field holding
+a `$components.*` runtime expression) reads its target as the type it expects in its position: a Parameter in
+`parameters`, a Success Action in `onSuccess` / `successActions`, a Failure Action in `onFailure` / `failureActions`.
+A JSON Schema `$ref` reads its target as a JSON Schema, whatever object it is otherwise (e.g. a Parameter
+component), keeping the keywords next to the `$ref`. A target of a different type is refracted to the expected type
+from the target dereferenced as its own type, so the result doesn't depend on which reference reaches it first;
+the component itself keeps its own type. Reusable Objects and `$ref`s nested within the target are dereferenced too
+(e.g. Parameter references in the `parameters` of a component Success or Failure Action), and the `value` field
+of a Reusable Object overrides the `value` of the Parameter it references.
+
+Every referenced structure is dereferenced once per type and shared by all the references reading it as that type,
+and each unresolvable reference is reported once. `dereference.maxDepth` limits the number of references followed
+in a row, Reusable Objects and `$ref`s alike. A reference leading back to a structure that's still being
+dereferenced is a circular reference and is handled per the `dereference.circular` option: `ignore` creates
+a cyclic structure, `error` fails with an `UnresolvableReferenceError` and `replace` substitutes a `RefElement`
+processed by the `circularReplacer` (`dereference.strategyOpts['arazzo-1'].circularReplacer` takes precedence over
+`dereference.circularReplacer`). Parsed Arazzo documents form circular references through JSON Schema `$ref`s;
+Reusable Objects, read as their expected types, don't lead back to the components holding them, but are handled
+the same way when they do.
+
+Source Descriptions parsed into the document (`parse.parserOpts.sourceDescriptions`) are never dereferenced in
+the context of the document referencing them: they're left as parsed, or dereferenced in their own context when
+the `sourceDescriptions` strategy option is set.
+
 Supported media types:
 
 ```js