@speclynx/apidom-reference 5.2.2 → 5.2.5

package/src/bundle/strategies/openapi-3-1/visitor.mjs

@@ -1,5 +1,5 @@
 import { propEq, none } from 'ramda';
-import { isElement, isObjectElement, isStringElement, ObjectElement, AnnotationElement, cloneDeep, cloneShallow } from '@speclynx/apidom-datamodel';
+import { isElement, isObjectElement, isStringElement, isParseResultElement, ObjectElement, AnnotationElement, cloneDeep, cloneShallow } from '@speclynx/apidom-datamodel';
 import { toValue, toYAML, fixedFields } from '@speclynx/apidom-core';
 import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 import { traverseAsync } from '@speclynx/apidom-traverse';
@@ -16,8 +16,8 @@ import Reference from "../../../Reference.mjs";
 import File from "../../../File.mjs";
 import { isAnchor, uriToAnchor, evaluate as $anchorEvaluate } from "../../../dereference/strategies/openapi-3-1/selectors/$anchor.mjs";
 import { evaluate as uriEvaluate } from "../../../dereference/strategies/openapi-3-1/selectors/uri.mjs";
-import { resolveSchema$refField, resolveSchema$idField, maybeRefractToSchemaElement } from "../../../dereference/strategies/openapi-3-1/util.mjs";
-import { toPascalCase, sanitizeComponentName, uniqueName as resolveUniqueName } from "../../util.mjs";
+import { resolveSchema$refField, resolveSchema$idField, resolveSchemaBaseURI, maybeRefractToSchemaElement } from "../../../dereference/strategies/openapi-3-1/util.mjs";
+import { rebaseSchema$ref, relocateSchema$ref, sanitizeComponentName, toPascalCase, uniqueName as resolveUniqueName } from "../../util.mjs";
 /**
  * Maps the `referenced-element` meta value (set during refraction) to the
  * Components Object field where the referenced element should be hoisted.
@@ -59,6 +59,12 @@ const componentFieldElementByField = {
   [cf.pathItems.name]: ComponentsPathItemsElement
 };
 
+/**
+ * A bundled element awaiting placement into the entry document's Components
+ * Object field.
+ * @public
+ */
+
 /**
  * @public
  */
@@ -116,18 +122,50 @@ class OpenAPI3_1BundleVisitor {
    * generic object referenced once as a Parameter and once as a Response).
    */
   refractCache;
+
+  /**
+   * Index of `$id`-bearing schemas per document, shared across the entry document
+   * and every external document visitor of a single bundle run so it never
+   * outlives mutations of the documents (e.g. the final placement of components).
+   */
+  schema$idIndex;
+
+  /**
+   * Bundled fragments waiting to be placed into the entry document's
+   * Components Object, shared across the entry document and every external
+   * document visitor. Placement is deferred until the entry document traversal
+   * completes: the traversal walks live content, so placing a fragment mid-way
+   * would make it descend into the fragment and re-bundle its `$ref`s against
+   * the entry document's base URI instead of the fragment's own.
+   */
+  placements;
+
+  /**
+   * The base URI the traversed content will have once placed into the entry
+   * document, when placement changes it: content hoisted out of a non-schema
+   * document (a Response, Parameter, Path Item, ...) trades that document's
+   * base URI for the entry document's. Unset for the entry document itself and
+   * for embedded schema resources, whose `$id` carries their base along.
+   */
+  relocationBaseURI;
   constructor({
     reference,
     options,
     assignments = new Map(),
     reservedNames = new Map(),
-    refractCache = new WeakMap()
+    refractCache = new WeakMap(),
+    schema$idIndex = new WeakMap(),
+    placements = [],
+    relocationBaseURI
   }) {
     this.reference = reference;
     this.options = options;
     this.assignments = assignments;
     this.reservedNames = reservedNames;
     this.refractCache = refractCache;
+    this.schema$idIndex = schema$idIndex;
+    this.placements = placements;
+    this.relocationBaseURI = relocationBaseURI;
   }
   getRefracted(source, type) {
     return this.refractCache.get(source)?.get(type);
@@ -185,6 +223,22 @@ class OpenAPI3_1BundleVisitor {
     return ref.startsWith('#') ? ref : url.getHash(ref);
   }
 
+  /**
+   * The base URI the given Schema Object's `$ref` will be resolved against once
+   * the content is placed into the entry document, or `undefined` when the
+   * `$ref` as written resolves to `$refBaseURI` from there as well: the content
+   * isn't relocated, an absolute `$id` on the schema's ancestor chain pins its
+   * base, or the hoisted document sits next to the entry document.
+   */
+  relocatedSchemaBaseURI(path, $refBaseURI) {
+    if (this.relocationBaseURI === undefined) return undefined;
+    const relocatedBaseURI = resolveSchemaBaseURI(this.relocationBaseURI, path);
+    if (resolveSchema$refField(relocatedBaseURI, path.node) === $refBaseURI) {
+      return undefined;
+    }
+    return relocatedBaseURI;
+  }
+
   /**
    * Handles an error according to the `bundle.continueOnError` option.
    *
@@ -303,13 +357,16 @@ class OpenAPI3_1BundleVisitor {
 
   /**
    * Computes a collision-free component name within the target field. A name is
-   * taken if it's already placed in components or reserved by a component that
-   * is still being bundled (reserved before recursion).
+   * taken if it's already present in the entry document's components or reserved
+   * by a component that is still being bundled (reserved before recursion).
    */
   uniqueName(candidate, field) {
-    const fieldElement = this.ensureComponentsField(field);
+    const {
+      components
+    } = this.entryResult;
+    const fieldElement = isObjectElement(components) ? components.get(field) : undefined;
     const reserved = this.reservedNames.get(field) ?? new Set();
-    return resolveUniqueName(candidate, name => fieldElement.hasKey(name) || reserved.has(name));
+    return resolveUniqueName(candidate, name => isObjectElement(fieldElement) && fieldElement.hasKey(name) || reserved.has(name));
   }
 
   /**
@@ -333,6 +390,28 @@ class OpenAPI3_1BundleVisitor {
     // append (never prepend) so the result element stays ahead of annotations
     this.entryParseResult.content.push(annotation);
   }
+
+  /**
+   * The entry document traversal is rooted at its Parse Result (nested
+   * traversals are rooted at fragments), so leaving it marks the moment the
+   * whole entry document has been visited and the collected fragments can be
+   * placed into its Components Object without the traversal descending into them.
+   * Guarded on the node so that a traversal rooted at any other Parse Result
+   * never flushes the shared placements early.
+   */
+  ParseResultElement = {
+    leave: path => {
+      if (path.node !== this.entryParseResult) return;
+      for (const {
+        field,
+        name,
+        element
+      } of this.placements) {
+        this.ensureComponentsField(field).set(name, element);
+      }
+      this.placements.length = 0;
+    }
+  };
   async ReferenceElement(path) {
     const referencingElement = path.node;
     const $ref = toValue(referencingElement.$ref);
@@ -420,14 +499,19 @@ class OpenAPI3_1BundleVisitor {
       if (!this.reservedNames.has(field)) this.reservedNames.set(field, new Set());
       this.reservedNames.get(field).add(componentName);
 
-      // own a copy of the fragment and bundle its own external references
+      // own a copy of the fragment and bundle its own external references; the
+      // fragment ends up in the entry document, so that is where its content
+      // resolves relative references from
       const hoistedElement = cloneDeep(referencedElement);
       const visitor = new OpenAPI3_1BundleVisitor({
         reference,
         options: this.options,
         assignments: this.assignments,
         reservedNames: this.reservedNames,
-        refractCache: this.refractCache
+        refractCache: this.refractCache,
+        schema$idIndex: this.schema$idIndex,
+        placements: this.placements,
+        relocationBaseURI: this.entryURI
       });
       const bundledElement = await traverseAsync(hoistedElement, visitor, {
         mutable: true
@@ -438,8 +522,12 @@ class OpenAPI3_1BundleVisitor {
         bundledElement.meta.set('ref-origin', reference.uri);
       }
 
-      // place the bundled fragment into the entry document's components
-      this.ensureComponentsField(field).set(componentName, bundledElement);
+      // queue the bundled fragment for placement into the entry document's components
+      this.placements.push({
+        field,
+        name: componentName,
+        element: bundledElement
+      });
 
       // rewrite the referencing element to point at the hoisted fragment
       referencingElement.set('$ref', internalPointer);
@@ -528,14 +616,19 @@ class OpenAPI3_1BundleVisitor {
       if (!this.reservedNames.has(field)) this.reservedNames.set(field, new Set());
       this.reservedNames.get(field).add(componentName);
 
-      // own a copy of the fragment and bundle its own external references
+      // own a copy of the fragment and bundle its own external references; the
+      // Path Item ends up in the entry document, so that is where its content
+      // resolves relative references from
       const hoistedElement = cloneDeep(referencedElement);
       const visitor = new OpenAPI3_1BundleVisitor({
         reference,
         options: this.options,
         assignments: this.assignments,
         reservedNames: this.reservedNames,
-        refractCache: this.refractCache
+        refractCache: this.refractCache,
+        schema$idIndex: this.schema$idIndex,
+        placements: this.placements,
+        relocationBaseURI: this.entryURI
       });
       const bundledElement = await traverseAsync(hoistedElement, visitor, {
         mutable: true
@@ -546,8 +639,12 @@ class OpenAPI3_1BundleVisitor {
       // internal `#/components/pathItems/...` pointer by the child traversal
       bundledElement.meta.set('ref-origin', reference.uri);
 
-      // place the bundled Path Item into the entry document's components
-      this.ensureComponentsField(field).set(componentName, bundledElement);
+      // queue the bundled Path Item for placement into the entry document's components
+      this.placements.push({
+        field,
+        name: componentName,
+        element: bundledElement
+      });
 
       // rewrite the referencing Path Item to point at the hoisted one, keeping
       // any sibling fields (e.g. summary, description) next to the $ref
@@ -582,7 +679,8 @@ class OpenAPI3_1BundleVisitor {
       // toReference) so an internal $ref needs no resolution and never trips the
       // resolve.maxDepth guard, matching how ReferenceElement returns early.
       const retrievalURI = this.reference.uri;
-      const $refBaseURI = resolveSchema$refField(retrievalURI, referencingElement);
+      const schemaBaseURI = resolveSchemaBaseURI(retrievalURI, path);
+      const $refBaseURI = resolveSchema$refField(schemaBaseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new File({
         uri: $refBaseURIStrippedHash
@@ -618,59 +716,95 @@ class OpenAPI3_1BundleVisitor {
       // as a canonical URI / URL against the current document's $id graph; if
       // that fails, fall back to fetching the external document and resolving
       // the fragment there as a $anchor or JSON Pointer.
+      //
+      // the fragment being traversed is searched before the whole document:
+      // content hoisted out of an external document (a Response, Parameter, Path
+      // Item, ...) is refracted with its own semantics, so the Schema Objects it
+      // contains are indexed, whereas the external document as a whole is parsed
+      // generically and refracted as a bare JSON Schema, which leaves those Schema
+      // Objects (under `content`, `schema`, ...) unrecognized and their `$id`s out
+      // of the index
+      const documentElement = this.reference.value.result;
+      const rootNode = path.getAncestorNodes().at(-1) ?? path.node;
+      const fragmentElement = isParseResultElement(rootNode) ? rootNode.result : rootNode;
+      const uriEvaluateOptions = {
+        baseURI: retrievalURI,
+        index: this.schema$idIndex
+      };
       let schemaReference = this.reference;
+      let resourceRoot;
+      let resourceBaseURI;
       try {
-        const referenceAsSchema = maybeRefractToSchemaElement(schemaReference.value.result);
-        uriEvaluate($refBaseURI, referenceAsSchema);
+        try {
+          uriEvaluate($refBaseURI, maybeRefractToSchemaElement(fragmentElement), uriEvaluateOptions);
+          // a $ref that resolves (by $id/$anchor/pointer) within the traversed
+          // content is internal even when its URI form (e.g. a URN or absolute
+          // $id) is not a bare fragment: the $id resource travels with the content
+          // wherever it is placed. Leave it untouched — it resolves against the
+          // in-content $id graph, and embedding the content into itself would be
+          // wrong.
+          return;
+        } catch (error) {
+          if (!(error instanceof EvaluationJsonSchemaUriError) || fragmentElement === documentElement) {
+            throw error;
+          }
+          const documentAsSchema = maybeRefractToSchemaElement(documentElement);
+          uriEvaluate($refBaseURI, documentAsSchema, uriEvaluateOptions);
+          // the $id resource sits in the current document but outside the
+          // traversed fragment, so it stays behind once the fragment is placed
+          // into the entry document. The resource to embed is that $id-bearing
+          // schema, addressed by its canonical URI (the $ref without fragment).
+          resourceRoot = uriEvaluate($refBaseURIStrippedHash, documentAsSchema, uriEvaluateOptions);
+          resourceBaseURI = $refBaseURIStrippedHash;
+        }
       } catch (error) {
         if (isURL && error instanceof EvaluationJsonSchemaUriError) {
+          schemaReference = await this.toReference(url.unsanitize($refBaseURI));
+          const referenceAsSchema = maybeRefractToSchemaElement(schemaReference.value.result);
           if (isAnchor(uriToAnchor($refBaseURI))) {
-            schemaReference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = uriToAnchor($refBaseURI);
-            const referenceAsSchema = maybeRefractToSchemaElement(schemaReference.value.result);
             $anchorEvaluate(selector, referenceAsSchema);
           } else {
-            schemaReference = await this.toReference(url.unsanitize($refBaseURI));
             const selector = URIFragmentIdentifier.fromURIReference($refBaseURI);
-            const referenceAsSchema = maybeRefractToSchemaElement(schemaReference.value.result);
             jsonPointerEvaluate(referenceAsSchema, selector);
           }
+
+          // the resource to embed is the WHOLE external document (its root
+          // schema), identified by its $id. A $ref into a fragment of the
+          // document embeds the entire document resource once; the fragment
+          // keeps resolving against the embedded $id.
+          resourceRoot = referenceAsSchema;
+          resourceBaseURI = resolveSchema$idField(url.stripHash(schemaReference.uri), resourceRoot) ?? url.stripHash(schemaReference.uri);
         } else {
           throw error;
         }
       }
-
-      // a $ref that resolves (by $id/$anchor/pointer) within the current document
-      // is internal even when its URI form (e.g. a URN or absolute $id) is not a
-      // bare fragment. Leave it untouched — it resolves against the in-document
-      // $id graph, and embedding the current document into itself would be wrong.
-      if (url.stripHash(schemaReference.uri) === url.stripHash(this.reference.uri)) {
-        return;
-      }
-
-      // the resource to embed is the WHOLE external document (its root schema),
-      // identified by its $id. A $ref into a fragment of the document embeds the
-      // entire document resource once; the fragment keeps resolving against the
-      // embedded $id.
-      const resourceRoot = maybeRefractToSchemaElement(schemaReference.value.result);
-      const resourceBaseURI = resolveSchema$idField(url.stripHash(schemaReference.uri), resourceRoot) ?? url.stripHash(schemaReference.uri);
       const field = cf.schemas.name;
       const canonicalKey = `${field}\t${resourceBaseURI}`;
 
-      // resource already embedded (or being embedded) — leave the referencing
-      // $ref untouched and stop. This also terminates circular external schema
+      // a location-based $ref to a self-identifying resource is rebased onto the
+      // resource's $id (keeping its fragment) — once embedded, the resource is
+      // reachable only by its $id. A $ref already resolving to that $id is left
+      // as written. See rebaseSchema$ref for the spec trade-off.
+      //
+      // a $ref whose base URI changes on relocation into the entry document
+      // (inside a hoisted Response, Parameter, Path Item, ...) is instead
+      // rewritten to address the embedded resource from the base it will have
+      // there, otherwise it dangles once placed. See relocateSchema$ref.
+      const relocatedBaseURI = this.relocatedSchemaBaseURI(path, $refBaseURI);
+      const rebased$ref = relocatedBaseURI === undefined ? rebaseSchema$ref($refBaseURI, resourceBaseURI) : relocateSchema$ref($refBaseURI, resourceBaseURI, relocatedBaseURI, isStringElement(resourceRoot.$id));
+
+      // resource already embedded (or being embedded) — point the referencing
+      // $ref at it and stop. This also terminates circular external schema
       // references, since the assignment is reserved BEFORE recursion.
       if (this.assignments.has(canonicalKey)) {
+        if (rebased$ref !== undefined) referencingElement.set('$ref', rebased$ref);
         path.skip();
         return;
       }
 
-      // own a copy of the resource and ensure it carries a $id so the unchanged
-      // $ref still resolves against it once embedded
+      // own a copy of the resource
       const embeddedElement = cloneDeep(resourceRoot);
-      if (!isStringElement(embeddedElement.$id)) {
-        embeddedElement.set('$id', resourceBaseURI);
-      }
 
       // the embedded thing is the WHOLE resource (keyed by its $id), so its name
       // is derived from the resource URI, not the $ref fragment — passing a root
@@ -692,20 +826,36 @@ class OpenAPI3_1BundleVisitor {
         options: this.options,
         assignments: this.assignments,
         reservedNames: this.reservedNames,
-        refractCache: this.refractCache
+        refractCache: this.refractCache,
+        schema$idIndex: this.schema$idIndex,
+        placements: this.placements
       });
       const bundledElement = await traverseAsync(embeddedElement, visitor, {
         mutable: true
       });
 
+      // a resource without its own $id is identified by its retrieval URI; write
+      // it relative to the entry document (the base of components.schemas) so the
+      // bundle carries no absolute filesystem path and stays relocatable. Assigned
+      // after the nested traversal so a reader deriving a schema's base from live
+      // $ids (see #540) never resolves the resource's own $refs against the entry
+      // document.
+      if (!isStringElement(bundledElement.$id)) {
+        bundledElement.set('$id', url.relative(this.entryURI, resourceBaseURI));
+      }
+
       // annotate the embedded resource with info about its origin
       bundledElement.meta.set('ref-origin', schemaReference.uri);
 
-      // place the embedded resource into the entry document's components
-      this.ensureComponentsField(field).set(componentName, bundledElement);
+      // queue the embedded resource for placement into the entry document's components
+      this.placements.push({
+        field,
+        name: componentName,
+        element: bundledElement
+      });
 
-      // the referencing $ref is left UNCHANGED — it resolves against the
-      // embedded resource's $id
+      // point the referencing $ref at the embedded resource's $id
+      if (rebased$ref !== undefined) referencingElement.set('$ref', rebased$ref);
       path.skip();
     } catch (error) {
       this.handleError(`Error while bundling Schema Object. Cannot resolve $ref "${$ref}": ${error.message}`, error, referencingElement, '$ref', $ref, path);

package/src/bundle/util.cjs

@@ -1,9 +1,11 @@
 "use strict";
 
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.uniqueName = exports.toPascalCase = exports.sanitizeComponentName = void 0;
+exports.uniqueName = exports.toPascalCase = exports.sanitizeComponentName = exports.relocateSchema$ref = exports.rebaseSchema$ref = void 0;
+var url = _interopRequireWildcard(require("../util/url.cjs"));
 /**
  * Upper-cases the first letter of each whitespace-separated word and joins
  * them, e.g. `pet model` -> `PetModel`.
@@ -39,4 +41,57 @@ const uniqueName = (candidate, isTaken) => {
   }
   return `${candidate}-${counter}`;
 };
-exports.uniqueName = uniqueName;
+
+/**
+ * Computes the `$ref` value addressing an embedded JSON Schema resource by its
+ * canonical `$id`. `$refURI` is the `$ref` resolved against the referencing
+ * document's base URI; `resourceURI` is the embedded resource's canonical URI
+ * (its `$id`, or the retrieval URI when it has none).
+ *
+ * When the two differ — a location-based `$ref` (e.g. `./ex.json#/$defs/Pet`)
+ * to a resource that identifies itself differently (`$id: https://example.com/pets`)
+ * — the `$ref` is rebased onto the resource URI, keeping its `$anchor` or JSON
+ * Pointer fragment. Once embedded, the resource is reachable only by its `$id`,
+ * so an unchanged `$ref` would dangle. When they already agree, `undefined` is
+ * returned and the `$ref` is to be left as written.
+ *
+ * This knowingly departs from the letter of JSON Schema 2020-12 §9.3.1
+ * ("references ... MUST NOT be changed"), which presumes `$ref`s are written
+ * against `$id`s. The target schema — and thus evaluation output — is unchanged;
+ * only the alias the loader knew the resource by is normalized to its canonical URI.
+ *
+ * @public
+ */
+exports.uniqueName = uniqueName;
+const rebaseSchema$ref = ($refURI, resourceURI) => {
+  if (url.stripHash($refURI) === resourceURI) {
+    return undefined;
+  }
+  const fragment = url.getHash($refURI);
+  return fragment === '#' ? resourceURI : `${resourceURI}${fragment}`;
+};
+
+/**
+ * Computes the `$ref` value addressing an embedded JSON Schema resource from a
+ * Schema Object whose base URI changes when it is relocated into the entry
+ * document — one carried inside a hoisted Response, Parameter, Path Item, etc.
+ * `$refURI` and `resourceURI` are as in `rebaseSchema$ref`; `baseURI` is the
+ * base the `$ref` resolves against after relocation.
+ *
+ * A resource that identifies itself (`isResourceIdentified`, i.e. it declares a
+ * `$id`) is addressed by that `$id`, exactly as `rebaseSchema$ref` does. A
+ * resource identified only by its retrieval URI is addressed by a URI reference
+ * relative to `baseURI`: it then resolves to the `$id` assigned from that
+ * retrieval URI wherever the bundle is placed, and no absolute retrieval
+ * location leaks into the `$ref`. The `$anchor` or JSON Pointer fragment is
+ * kept in both cases.
+ *
+ * @public
+ */
+exports.rebaseSchema$ref = rebaseSchema$ref;
+const relocateSchema$ref = ($refURI, resourceURI, baseURI, isResourceIdentified) => {
+  const target = isResourceIdentified ? resourceURI : url.relative(baseURI, resourceURI);
+  const fragment = url.getHash($refURI);
+  return fragment === '#' ? target : `${target}${fragment}`;
+};
+exports.relocateSchema$ref = relocateSchema$ref;

package/src/bundle/util.mjs

@@ -1,3 +1,4 @@
+import * as url from "../util/url.mjs";
 /**
  * Upper-cases the first letter of each whitespace-separated word and joins
  * them, e.g. `pet model` -> `PetModel`.
@@ -30,4 +31,55 @@ export const uniqueName = (candidate, isTaken) => {
     counter += 1;
   }
   return `${candidate}-${counter}`;
+};
+
+/**
+ * Computes the `$ref` value addressing an embedded JSON Schema resource by its
+ * canonical `$id`. `$refURI` is the `$ref` resolved against the referencing
+ * document's base URI; `resourceURI` is the embedded resource's canonical URI
+ * (its `$id`, or the retrieval URI when it has none).
+ *
+ * When the two differ — a location-based `$ref` (e.g. `./ex.json#/$defs/Pet`)
+ * to a resource that identifies itself differently (`$id: https://example.com/pets`)
+ * — the `$ref` is rebased onto the resource URI, keeping its `$anchor` or JSON
+ * Pointer fragment. Once embedded, the resource is reachable only by its `$id`,
+ * so an unchanged `$ref` would dangle. When they already agree, `undefined` is
+ * returned and the `$ref` is to be left as written.
+ *
+ * This knowingly departs from the letter of JSON Schema 2020-12 §9.3.1
+ * ("references ... MUST NOT be changed"), which presumes `$ref`s are written
+ * against `$id`s. The target schema — and thus evaluation output — is unchanged;
+ * only the alias the loader knew the resource by is normalized to its canonical URI.
+ *
+ * @public
+ */
+export const rebaseSchema$ref = ($refURI, resourceURI) => {
+  if (url.stripHash($refURI) === resourceURI) {
+    return undefined;
+  }
+  const fragment = url.getHash($refURI);
+  return fragment === '#' ? resourceURI : `${resourceURI}${fragment}`;
+};
+
+/**
+ * Computes the `$ref` value addressing an embedded JSON Schema resource from a
+ * Schema Object whose base URI changes when it is relocated into the entry
+ * document — one carried inside a hoisted Response, Parameter, Path Item, etc.
+ * `$refURI` and `resourceURI` are as in `rebaseSchema$ref`; `baseURI` is the
+ * base the `$ref` resolves against after relocation.
+ *
+ * A resource that identifies itself (`isResourceIdentified`, i.e. it declares a
+ * `$id`) is addressed by that `$id`, exactly as `rebaseSchema$ref` does. A
+ * resource identified only by its retrieval URI is addressed by a URI reference
+ * relative to `baseURI`: it then resolves to the `$id` assigned from that
+ * retrieval URI wherever the bundle is placed, and no absolute retrieval
+ * location leaks into the `$ref`. The `$anchor` or JSON Pointer fragment is
+ * kept in both cases.
+ *
+ * @public
+ */
+export const relocateSchema$ref = ($refURI, resourceURI, baseURI, isResourceIdentified) => {
+  const target = isResourceIdentified ? resourceURI : url.relative(baseURI, resourceURI);
+  const fragment = url.getHash($refURI);
+  return fragment === '#' ? target : `${target}${fragment}`;
 };

package/src/dereference/strategies/arazzo-1/index.cjs

@@ -20,31 +20,31 @@ Object.defineProperty(exports, "dereferenceSourceDescriptions", {
 Object.defineProperty(exports, "identifiedBy$self", {
   enumerable: true,
   get: function () {
-    return _util.identifiedBy$self;
+    return _util2.identifiedBy$self;
   }
 });
 Object.defineProperty(exports, "maybeRefractToJSONSchemaElement", {
   enumerable: true,
   get: function () {
-    return _util.maybeRefractToJSONSchemaElement;
+    return _util2.maybeRefractToJSONSchemaElement;
   }
 });
 Object.defineProperty(exports, "resolveArazzo$selfField", {
   enumerable: true,
   get: function () {
-    return _util.resolveArazzo$selfField;
+    return _util2.resolveArazzo$selfField;
   }
 });
 Object.defineProperty(exports, "resolveSchema$idField", {
   enumerable: true,
   get: function () {
-    return _util.resolveSchema$idField;
+    return _util2.resolveSchema$idField;
   }
 });
 Object.defineProperty(exports, "resolveSchema$refField", {
   enumerable: true,
   get: function () {
-    return _util.resolveSchema$refField;
+    return _util2.resolveSchema$refField;
   }
 });
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
@@ -54,8 +54,9 @@ var _DereferenceStrategy = _interopRequireDefault(require("../DereferenceStrateg
 var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
 var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
 var _visitor = _interopRequireDefault(require("./visitor.cjs"));
+var _util = require("../openapi-3-1/util.cjs");
 var _sourceDescriptions = require("./source-descriptions.cjs");
-var _util = require("./util.cjs");
+var _util2 = require("./util.cjs");
 /**
  * @public
  */
@@ -110,7 +111,8 @@ class Arazzo1DereferenceStrategy extends _DereferenceStrategy.default {
     const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new _visitor.default({
       reference,
-      options
+      options,
+      ancestorSchema$ids: (0, _util.detachedRootSchema$ids)(refSet.rootRef.value.result)
     });
     const dereferencedElement = await (0, _apidomTraverse.traverseAsync)(refSet.rootRef.value, visitor, {
       mutable: true,

package/src/dereference/strategies/arazzo-1/index.mjs

@@ -5,6 +5,7 @@ import DereferenceStrategy from "../DereferenceStrategy.mjs";
 import Reference from "../../../Reference.mjs";
 import ReferenceSet from "../../../ReferenceSet.mjs";
 import Arazzo1DereferenceVisitor from "./visitor.mjs";
+import { detachedRootSchema$ids } from "../openapi-3-1/util.mjs";
 import { dereferenceSourceDescriptions } from "./source-descriptions.mjs";
 /**
  * @public
@@ -59,7 +60,8 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
     const shouldDetectCircular = ['error', 'replace'].includes(options.dereference.circular);
     const visitor = new Arazzo1DereferenceVisitor({
       reference,
-      options
+      options,
+      ancestorSchema$ids: detachedRootSchema$ids(refSet.rootRef.value.result)
     });
     const dereferencedElement = await traverseAsync(refSet.rootRef.value, visitor, {
       mutable: true,

package/src/dereference/strategies/arazzo-1/selectors/$anchor.cjs

@@ -33,6 +33,12 @@ Object.defineProperty(exports, "isAnchor", {
     return _$anchor.isAnchor;
   }
 });
+Object.defineProperty(exports, "locate", {
+  enumerable: true,
+  get: function () {
+    return _$anchor.locate;
+  }
+});
 Object.defineProperty(exports, "parse", {
   enumerable: true,
   get: function () {

package/src/dereference/strategies/arazzo-1/selectors/$anchor.mjs

@@ -1 +1 @@
-export { isAnchor, uriToAnchor, parse, evaluate, EvaluationJsonSchema$anchorError, InvalidJsonSchema$anchorError, JsonSchema$anchorError } from "../../openapi-3-1/selectors/$anchor.mjs";
+export { isAnchor, uriToAnchor, parse, locate, evaluate, EvaluationJsonSchema$anchorError, InvalidJsonSchema$anchorError, JsonSchema$anchorError } from "../../openapi-3-1/selectors/$anchor.mjs";

package/src/dereference/strategies/arazzo-1/selectors/uri.cjs

@@ -21,4 +21,10 @@ Object.defineProperty(exports, "evaluate", {
     return _uri.evaluate;
   }
 });
+Object.defineProperty(exports, "locate", {
+  enumerable: true,
+  get: function () {
+    return _uri.locate;
+  }
+});
 var _uri = require("../../openapi-3-1/selectors/uri.cjs");

package/src/dereference/strategies/arazzo-1/selectors/uri.mjs

@@ -1 +1 @@
-export { evaluate, EvaluationJsonSchemaUriError, JsonSchemaUriError } from "../../openapi-3-1/selectors/uri.mjs";
+export { locate, evaluate, EvaluationJsonSchemaUriError, JsonSchemaUriError } from "../../openapi-3-1/selectors/uri.mjs";

package/src/dereference/strategies/arazzo-1/util.cjs

@@ -17,6 +17,12 @@ Object.defineProperty(exports, "resolveSchema$refField", {
     return _util.resolveSchema$refField;
   }
 });
+Object.defineProperty(exports, "resolveSchemaBaseURI", {
+  enumerable: true,
+  get: function () {
+    return _util.resolveSchemaBaseURI;
+  }
+});
 exports.validateSourceDescriptionAPI = void 0;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomCore = require("@speclynx/apidom-core");