@speclynx/apidom-reference 6.1.2 → 6.2.0

package/CHANGELOG.md

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

@@ -1536,6 +1536,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 +1943,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**