@speclynx/apidom-reference 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.10.0](https://github.com/speclynx/apidom/compare/v2.9.0...v2.10.0) (2026-02-08)
+
+### Features
+
+- **reference:** add retrievalURI metadata for Arazzo Source Descriptions ([#79](https://github.com/speclynx/apidom/issues/79)) ([df78cb3](https://github.com/speclynx/apidom/commit/df78cb3226521e6f7097b85cccdbc6b0b39e7a7b))
+
 # [2.9.0](https://github.com/speclynx/apidom/compare/v2.8.0...v2.9.0) (2026-02-08)
 
 ### Features

package/README.md

@@ -301,7 +301,7 @@ Parser-specific options take precedence over global options.
   - `true` - parse all source descriptions
   - `string[]` - parse only source descriptions with matching names (e.g., `['petStore', 'paymentApi']`)
 
-  Each parsed source description is added with a `'source-description'` class and metadata (`name`, `type`).
+  Each parsed source description is added with a `'source-description'` class and metadata (`name`, `type`, `retrievalURI`).
   Only OpenAPI 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x, and Arazzo 1.x documents are accepted as source descriptions.
 - **sourceDescriptionsMaxDepth** - Maximum recursion depth for parsing nested Arazzo source descriptions.
   Defaults to `+Infinity`. Circular references are automatically detected and skipped.
@@ -321,6 +321,7 @@ with an `'error'` class within the parse result:
   for parsing are not met (e.g., API is not an Arazzo specification)
 
 ```js
+import { toValue } from '@speclynx/apidom-core';
 import { parse } from '@speclynx/apidom-reference';
 
 // Parse all source descriptions
@@ -345,8 +346,9 @@ const parseResultFiltered = await parse('/path/to/arazzo.json', {
 // Access parsed source descriptions
 for (const element of parseResult) {
   if (element.classes.includes('source-description')) {
-    console.log(element.meta.get('name').toValue()); // e.g., 'petStore'
-    console.log(element.meta.get('type').toValue()); // e.g., 'openapi'
+    console.log(toValue(element.meta.get('name'))); // e.g., 'petStore'
+    console.log(toValue(element.meta.get('type'))); // e.g., 'openapi'
+    console.log(toValue(element.meta.get('retrievalURI'))); // e.g., '/path/to/petstore.json'
   }
 }
 ```
@@ -361,6 +363,7 @@ regardless of success or failure:
 - **On failure**: The parseResult contains error/warning annotations explaining what went wrong
 
 ```js
+import { toValue } from '@speclynx/apidom-core';
 import { parse } from '@speclynx/apidom-reference';
 
 const parseResult = await parse('/path/to/arazzo.json', {
@@ -377,6 +380,7 @@ if (parsedDoc.errors.length > 0) {
   console.log('Parsing failed:', parsedDoc.errors);
 } else {
   console.log(parsedDoc.api.element); // e.g., 'openApi3_1'
+  console.log(toValue(parsedDoc.meta.get('retrievalURI'))); // URI where it was fetched from
 }
 ```
 
@@ -450,7 +454,7 @@ Parser-specific options take precedence over global options. See [arazzo-json-1]
   - `true` - parse all source descriptions
   - `string[]` - parse only source descriptions with matching names (e.g., `['petStore', 'paymentApi']`)
 
-  Each parsed source description is added with a `'source-description'` class and metadata (`name`, `type`).
+  Each parsed source description is added with a `'source-description'` class and metadata (`name`, `type`, `retrievalURI`).
   Only OpenAPI 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x, and Arazzo 1.x documents are accepted as source descriptions.
 - **sourceDescriptionsMaxDepth** - Maximum recursion depth for parsing nested Arazzo source descriptions.
   Defaults to `+Infinity`. Circular references are automatically detected and skipped.
@@ -1756,7 +1760,7 @@ Strategy-specific options take precedence over global options.
   - `true` - dereference all source descriptions
   - `string[]` - dereference only source descriptions with matching names (e.g., `['petStore', 'paymentApi']`)
 
-  Each dereferenced source description is added with a `'source-description'` class and metadata (`name`, `type`).
+  Each dereferenced source description is added with a `'source-description'` class and metadata (`name`, `type`, `retrievalURI`).
   Only OpenAPI 2.0, OpenAPI 3.0.x, OpenAPI 3.1.x, and Arazzo 1.x documents are accepted as source descriptions.
 - **sourceDescriptionsMaxDepth** - Maximum recursion depth for dereferencing nested Arazzo source descriptions.
   Defaults to `+Infinity`. Circular references are automatically detected and skipped.
@@ -1810,6 +1814,7 @@ regardless of success or failure:
 - **On failure**: The parseResult contains error/warning annotations explaining what went wrong
 
 ```js
+import { toValue } from '@speclynx/apidom-core';
 import { dereference } from '@speclynx/apidom-reference';
 
 const parseResult = await dereference('/path/to/arazzo.json', {
@@ -1826,6 +1831,7 @@ if (dereferencedDoc.errors.length > 0) {
   console.log('Dereferencing failed:', dereferencedDoc.errors);
 } else {
   console.log(dereferencedDoc.api.element); // e.g., 'openApi3_1'
+  console.log(toValue(dereferencedDoc.meta.get('retrievalURI'))); // URI where it was fetched from
 }
 ```
 

package/dist/apidom-reference.browser.js

@@ -998,6 +998,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
 
   // normalize URI for consistent cycle detection and refSet cache key matching
   const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_10__.sanitize(_util_url_ts__WEBPACK_IMPORTED_MODULE_10__.stripHash(_util_url_ts__WEBPACK_IMPORTED_MODULE_10__.resolve(ctx.baseURI, sourceDescriptionURI)));
+  parseResult.setMetaProperty('retrievalURI', retrievalURI);
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -1111,7 +1112,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  *   in `dereference.strategyOpts` to filter which source descriptions to process.
  * @param strategyName - Strategy name for options lookup (defaults to 'arazzo-1')
  * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
- *   (each with class 'source-description' and name/type metadata).
+ *   (each with class 'source-description' and metadata: name, type, retrievalURI).
  *   May return early with a single-element array containing a warning annotation when:
  *   - The API is not an Arazzo specification
  *   - The sourceDescriptions field is missing or not an array
@@ -1120,6 +1121,8 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  *
  * @example
  * ```typescript
+ * import { toValue } from '@speclynx/apidom-core';
+ *
  * // Dereference all source descriptions
  * await dereferenceSourceDescriptions(parseResult, uri, options);
  *
@@ -1131,6 +1134,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  * // Access dereferenced document from source description element
  * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
  * const dereferencedDoc = sourceDesc.meta.get('parseResult');
+ * const retrievalURI = toValue(dereferencedDoc.meta.get('retrievalURI'));
  * ```
  *
  * @public
@@ -5903,6 +5907,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
 
   // normalize URI for consistent cycle detection and cache key matching
   const retrievalURI = _util_url_ts__WEBPACK_IMPORTED_MODULE_10__.sanitize(_util_url_ts__WEBPACK_IMPORTED_MODULE_10__.stripHash(_util_url_ts__WEBPACK_IMPORTED_MODULE_10__.resolve(ctx.baseURI, sourceDescriptionURI)));
+  parseResult.setMetaProperty('retrievalURI', retrievalURI);
 
   // skip if already visited (cycle detection)
   if (ctx.visitedUrls.has(retrievalURI)) {
@@ -5984,7 +5989,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
  *   in `parse.parserOpts` to filter which source descriptions to process.
  * @param parserName - Parser name for options lookup (defaults to 'arazzo-json-1')
  * @returns Array of ParseResultElements. Returns one ParseResultElement per source description
- *   (each with class 'source-description' and name/type metadata).
+ *   (each with class 'source-description' and metadata: name, type, retrievalURI).
  *   May return early with a single-element array containing a warning annotation when:
  *   - The API is not an Arazzo specification
  *   - The sourceDescriptions field is missing or not an array
@@ -5993,6 +5998,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
  *
  * @example
  * ```typescript
+ * import { toValue } from '@speclynx/apidom-core';
  * import { options, mergeOptions } from '@speclynx/apidom-reference';
  * import { parseSourceDescriptions } from '@speclynx/apidom-reference/parse/parsers/arazzo-json-1';
  *
@@ -6007,6 +6013,7 @@ async function parseSourceDescription(sourceDescription, ctx) {
  * // Access parsed document from source description element
  * const sourceDesc = parseResult.api.sourceDescriptions.get(0);
  * const parsedDoc = sourceDesc.meta.get('parseResult');
+ * const retrievalURI = toValue(parsedDoc.meta.get('retrievalURI'));
  * ```
  *
  * @public