@speclynx/apidom-reference 5.1.1 → 5.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "5.1.1",
+  "version": "5.2.1",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "keywords": [
     "apidom",
@@ -299,35 +299,35 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^8.0.0",
-    "@speclynx/apidom-core": "5.1.1",
-    "@speclynx/apidom-datamodel": "5.1.1",
-    "@speclynx/apidom-error": "5.1.1",
-    "@speclynx/apidom-json-pointer": "5.1.1",
-    "@speclynx/apidom-ns-arazzo-1": "5.1.1",
-    "@speclynx/apidom-ns-asyncapi-2": "5.1.1",
-    "@speclynx/apidom-ns-json-schema-2020-12": "5.1.1",
-    "@speclynx/apidom-ns-openapi-2": "5.1.1",
-    "@speclynx/apidom-ns-openapi-3-0": "5.1.1",
-    "@speclynx/apidom-ns-openapi-3-1": "5.1.1",
-    "@speclynx/apidom-ns-overlay-1": "5.1.1",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "5.1.1",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "5.1.1",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "5.1.1",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "5.1.1",
-    "@speclynx/apidom-parser-adapter-json": "5.1.1",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "5.1.1",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "5.1.1",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "5.1.1",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "5.1.1",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "5.1.1",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "5.1.1",
-    "@speclynx/apidom-parser-adapter-overlay-json-1": "5.1.1",
-    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "5.1.1",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "5.1.1",
-    "@speclynx/apidom-traverse": "5.1.1",
+    "@speclynx/apidom-core": "5.2.1",
+    "@speclynx/apidom-datamodel": "5.2.1",
+    "@speclynx/apidom-error": "5.2.1",
+    "@speclynx/apidom-json-pointer": "5.2.1",
+    "@speclynx/apidom-ns-arazzo-1": "5.2.1",
+    "@speclynx/apidom-ns-asyncapi-2": "5.2.1",
+    "@speclynx/apidom-ns-json-schema-2020-12": "5.2.1",
+    "@speclynx/apidom-ns-openapi-2": "5.2.1",
+    "@speclynx/apidom-ns-openapi-3-0": "5.2.1",
+    "@speclynx/apidom-ns-openapi-3-1": "5.2.1",
+    "@speclynx/apidom-ns-overlay-1": "5.2.1",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "5.2.1",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "5.2.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "5.2.1",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "5.2.1",
+    "@speclynx/apidom-parser-adapter-json": "5.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "5.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "5.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "5.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "5.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "5.2.1",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "5.2.1",
+    "@speclynx/apidom-parser-adapter-overlay-json-1": "5.2.1",
+    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "5.2.1",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "5.2.1",
+    "@speclynx/apidom-traverse": "5.2.1",
     "@swaggerexpert/arazzo-runtime-expression": "^3.1.0",
     "axios": "^1.19.0",
-    "picomatch": "^4.0.5",
+    "picomatch": "^4.0.7",
     "process": "^0.11.10",
     "ramda": "~0.32.0",
     "ramda-adjunct": "^6.1.0"
@@ -346,5 +346,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "b661f6f038953d118ad09eec0d7da7927db46f5c"
+  "gitHead": "814e67e36b1e27546288c74a25eab8f9463943eb"
 }

package/src/bundle/strategies/arazzo-1/visitor.cjs

@@ -43,6 +43,13 @@ const cf = (0, _apidomCore.fixedFields)(_apidomNsArazzo.ComponentsElement, {
  */
 class Arazzo1BundleVisitor {
   reference;
+
+  /**
+   * Base URI of the current document for resolving relative references.
+   * Honors the Arazzo `$self` field when present, otherwise falls back
+   * to the retrieval URI (`this.reference.uri`).
+   */
+  baseURI;
   options;
 
   /**
@@ -81,12 +88,13 @@ class Arazzo1BundleVisitor {
     reservedNames = new Map()
   }) {
     this.reference = reference;
+    this.baseURI = (0, _util.resolveArazzo$selfField)(reference.uri, reference.value?.result);
     this.options = options;
     this.assignments = assignments;
     this.reservedNames = reservedNames;
   }
   toBaseURI(uri) {
-    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+    return url.resolve(this.baseURI, url.sanitize(url.stripHash(uri)));
   }
   async toReference(uri) {
     // detect maximum depth of resolution
@@ -105,6 +113,12 @@ class Arazzo1BundleVisitor {
     if (refSet.has(baseURI)) {
       return refSet.find(ref => ref.uri === baseURI);
     }
+
+    // identity-based referencing: URI matches `$self` of an already processed Arazzo document
+    const referenceBy$self = refSet.find((0, _util.identifiedBy$self)(baseURI));
+    if (referenceBy$self !== undefined) {
+      return referenceBy$self;
+    }
     const parseResult = await (0, _index.default)(url.unsanitize(baseURI), {
       ...this.options,
       parse: {
@@ -279,19 +293,18 @@ class Arazzo1BundleVisitor {
     }
     const $ref = (0, _apidomCore.toValue)(referencingElement.$ref);
     try {
-      // compute baseURI using rules around $id and $ref keywords. The current
-      // document's URI is the retrieval URI — derive it directly (not via
-      // toReference) so an internal $ref needs no resolution and never trips the
+      // compute baseURI using rules around $self, $id and $ref keywords. The
+      // current document's base URI is derived directly (not via toReference)
+      // so an internal $ref needs no resolution and never trips the
       // resolve.maxDepth guard.
-      const retrievalURI = this.reference.uri;
-      const $refBaseURI = (0, _util.resolveSchema$refField)(retrievalURI, referencingElement);
+      const $refBaseURI = (0, _util.resolveSchema$refField)(this.baseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new _File.default({
         uri: $refBaseURIStrippedHash
       });
       const isUnknownURI = (0, _ramda.none)(r => r.canRead(file), this.options.resolve.resolvers);
       const isURL = !isUnknownURI;
-      const isInternalReference = url.stripHash(this.reference.uri) === $refBaseURIStrippedHash;
+      const isInternalReference = this.baseURI === $refBaseURIStrippedHash;
       const isExternalReference = !isInternalReference;
 
       // internal Schema Object $refs resolve against the in-document $id graph;
@@ -345,7 +358,10 @@ class Arazzo1BundleVisitor {
       // 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)) {
+      // The same holds for a $ref resolving into the entry document (e.g. by its
+      // `$self` identity) — it's already part of the bundle.
+      const schemaReferenceURI = url.stripHash(schemaReference.uri);
+      if (schemaReferenceURI === url.stripHash(this.reference.uri) || schemaReferenceURI === url.stripHash(this.reference.refSet.rootRef.uri)) {
         return;
       }
 

package/src/bundle/strategies/arazzo-1/visitor.mjs

@@ -15,7 +15,7 @@ import Reference from "../../../Reference.mjs";
 import File from "../../../File.mjs";
 import { isAnchor, uriToAnchor, evaluate as $anchorEvaluate } from "../../../dereference/strategies/arazzo-1/selectors/$anchor.mjs";
 import { evaluate as uriEvaluate } from "../../../dereference/strategies/arazzo-1/selectors/uri.mjs";
-import { resolveSchema$refField, resolveSchema$idField, maybeRefractToJSONSchemaElement } from "../../../dereference/strategies/arazzo-1/util.mjs";
+import { resolveSchema$refField, resolveSchema$idField, maybeRefractToJSONSchemaElement, resolveArazzo$selfField, identifiedBy$self } from "../../../dereference/strategies/arazzo-1/util.mjs";
 import { toPascalCase, sanitizeComponentName, uniqueName as resolveUniqueName } from "../../util.mjs";
 /**
  * The Components Object field where embedded JSON Schema resources are hoisted.
@@ -35,6 +35,13 @@ const cf = fixedFields(ComponentsElement, {
  */
 class Arazzo1BundleVisitor {
   reference;
+
+  /**
+   * Base URI of the current document for resolving relative references.
+   * Honors the Arazzo `$self` field when present, otherwise falls back
+   * to the retrieval URI (`this.reference.uri`).
+   */
+  baseURI;
   options;
 
   /**
@@ -73,12 +80,13 @@ class Arazzo1BundleVisitor {
     reservedNames = new Map()
   }) {
     this.reference = reference;
+    this.baseURI = resolveArazzo$selfField(reference.uri, reference.value?.result);
     this.options = options;
     this.assignments = assignments;
     this.reservedNames = reservedNames;
   }
   toBaseURI(uri) {
-    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+    return url.resolve(this.baseURI, url.sanitize(url.stripHash(uri)));
   }
   async toReference(uri) {
     // detect maximum depth of resolution
@@ -97,6 +105,12 @@ class Arazzo1BundleVisitor {
     if (refSet.has(baseURI)) {
       return refSet.find(ref => ref.uri === baseURI);
     }
+
+    // identity-based referencing: URI matches `$self` of an already processed Arazzo document
+    const referenceBy$self = refSet.find(identifiedBy$self(baseURI));
+    if (referenceBy$self !== undefined) {
+      return referenceBy$self;
+    }
     const parseResult = await parse(url.unsanitize(baseURI), {
       ...this.options,
       parse: {
@@ -271,19 +285,18 @@ class Arazzo1BundleVisitor {
     }
     const $ref = toValue(referencingElement.$ref);
     try {
-      // compute baseURI using rules around $id and $ref keywords. The current
-      // document's URI is the retrieval URI — derive it directly (not via
-      // toReference) so an internal $ref needs no resolution and never trips the
+      // compute baseURI using rules around $self, $id and $ref keywords. The
+      // current document's base URI is derived directly (not via toReference)
+      // so an internal $ref needs no resolution and never trips the
       // resolve.maxDepth guard.
-      const retrievalURI = this.reference.uri;
-      const $refBaseURI = resolveSchema$refField(retrievalURI, referencingElement);
+      const $refBaseURI = resolveSchema$refField(this.baseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new File({
         uri: $refBaseURIStrippedHash
       });
       const isUnknownURI = none(r => r.canRead(file), this.options.resolve.resolvers);
       const isURL = !isUnknownURI;
-      const isInternalReference = url.stripHash(this.reference.uri) === $refBaseURIStrippedHash;
+      const isInternalReference = this.baseURI === $refBaseURIStrippedHash;
       const isExternalReference = !isInternalReference;
 
       // internal Schema Object $refs resolve against the in-document $id graph;
@@ -337,7 +350,10 @@ class Arazzo1BundleVisitor {
       // 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)) {
+      // The same holds for a $ref resolving into the entry document (e.g. by its
+      // `$self` identity) — it's already part of the bundle.
+      const schemaReferenceURI = url.stripHash(schemaReference.uri);
+      if (schemaReferenceURI === url.stripHash(this.reference.uri) || schemaReferenceURI === url.stripHash(this.reference.refSet.rootRef.uri)) {
         return;
       }
 

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

@@ -17,12 +17,24 @@ Object.defineProperty(exports, "dereferenceSourceDescriptions", {
     return _sourceDescriptions.dereferenceSourceDescriptions;
   }
 });
+Object.defineProperty(exports, "identifiedBy$self", {
+  enumerable: true,
+  get: function () {
+    return _util.identifiedBy$self;
+  }
+});
 Object.defineProperty(exports, "maybeRefractToJSONSchemaElement", {
   enumerable: true,
   get: function () {
     return _util.maybeRefractToJSONSchemaElement;
   }
 });
+Object.defineProperty(exports, "resolveArazzo$selfField", {
+  enumerable: true,
+  get: function () {
+    return _util.resolveArazzo$selfField;
+  }
+});
 Object.defineProperty(exports, "resolveSchema$idField", {
   enumerable: true,
   get: function () {

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

@@ -104,6 +104,6 @@ class Arazzo1DereferenceStrategy extends DereferenceStrategy {
   }
 }
 export { Arazzo1DereferenceVisitor };
-export { resolveSchema$refField, resolveSchema$idField, maybeRefractToJSONSchemaElement } from "./util.mjs";
+export { resolveSchema$refField, resolveSchema$idField, resolveArazzo$selfField, identifiedBy$self, maybeRefractToJSONSchemaElement } from "./util.mjs";
 export { dereferenceSourceDescriptions } from "./source-descriptions.mjs";
 export default Arazzo1DereferenceStrategy;

package/src/dereference/strategies/arazzo-1/source-descriptions.cjs

@@ -14,6 +14,7 @@ var _apidomCore = require("@speclynx/apidom-core");
 var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 var _util = require("../../../options/util.cjs");
 var _index = _interopRequireWildcard(require("../../index.cjs"));
+var _util2 = require("./util.cjs");
 /**
  * Dereferences a single source description element.
  * Returns ParseResultElement on success, or with annotation if skipped.
@@ -183,7 +184,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  * @public
  */
 async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalURI, options, strategyName = 'arazzo-1') {
-  const baseURI = url.sanitize(url.stripHash(parseResultRetrievalURI));
+  const retrievalURI = url.sanitize(url.stripHash(parseResultRetrievalURI));
   const results = [];
 
   // get API from dereferenced parse result
@@ -214,10 +215,14 @@ async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalUR
   const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
   const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
 
-  // add current file to visited URLs to prevent cycles
+  // base URI for resolving source description URLs honors Arazzo `$self` field
+  const baseURI = (0, _util2.resolveArazzo$selfField)(retrievalURI, api);
+
+  // add current file to visited URLs to prevent cycles (by retrieval URI and by identity)
+  visitedUrls.add(retrievalURI);
   visitedUrls.add(baseURI);
   if (currentDepth >= maxDepth) {
-    const annotation = new _apidomDatamodel.AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${baseURI}"`);
+    const annotation = new _apidomDatamodel.AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${retrievalURI}"`);
     annotation.classes.push('error');
     const parseResult = new _apidomDatamodel.ParseResultElement([annotation]);
     parseResult.classes.push('source-description');

package/src/dereference/strategies/arazzo-1/source-descriptions.mjs

@@ -7,6 +7,7 @@ import { toValue } from '@speclynx/apidom-core';
 import * as url from "../../../util/url.mjs";
 import { merge as mergeOptions } from "../../../options/util.mjs";
 import dereference, { dereferenceApiDOM } from "../../index.mjs";
+import { resolveArazzo$selfField } from "./util.mjs";
 /**
  * Dereferences a single source description element.
  * Returns ParseResultElement on success, or with annotation if skipped.
@@ -176,7 +177,7 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  * @public
  */
 export async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalURI, options, strategyName = 'arazzo-1') {
-  const baseURI = url.sanitize(url.stripHash(parseResultRetrievalURI));
+  const retrievalURI = url.sanitize(url.stripHash(parseResultRetrievalURI));
   const results = [];
 
   // get API from dereferenced parse result
@@ -207,10 +208,14 @@ export async function dereferenceSourceDescriptions(parseResult, parseResultRetr
   const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
   const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
 
-  // add current file to visited URLs to prevent cycles
+  // base URI for resolving source description URLs honors Arazzo `$self` field
+  const baseURI = resolveArazzo$selfField(retrievalURI, api);
+
+  // add current file to visited URLs to prevent cycles (by retrieval URI and by identity)
+  visitedUrls.add(retrievalURI);
   visitedUrls.add(baseURI);
   if (currentDepth >= maxDepth) {
-    const annotation = new AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${baseURI}"`);
+    const annotation = new AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${retrievalURI}"`);
     annotation.classes.push('error');
     const parseResult = new ParseResultElement([annotation]);
     parseResult.classes.push('source-description');

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

@@ -1,9 +1,10 @@
 "use strict";
 
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.refractToJSONSchemaElement = exports.maybeRefractToJSONSchemaElement = void 0;
+exports.resolveArazzo$selfField = exports.refractToJSONSchemaElement = exports.maybeRefractToJSONSchemaElement = exports.identifiedBy$self = void 0;
 Object.defineProperty(exports, "resolveSchema$idField", {
   enumerable: true,
   get: function () {
@@ -17,11 +18,50 @@ Object.defineProperty(exports, "resolveSchema$refField", {
   }
 });
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
 var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 var _util = require("../openapi-3-1/util.cjs");
+/**
+ * Computes the base URI of an Arazzo document per Arazzo 1.1.0 rules.
+ *
+ * When the Arazzo Object carries a `$self` field, it establishes the document's
+ * canonical identity and the base URI for resolving relative references. `$self`
+ * may itself be relative, in which case it's resolved against the retrieval URI.
+ * Any fragment is stripped, as `$self` MUST NOT contain one. When `$self` is
+ * absent (or `element` is not an Arazzo document), the retrieval URI is the base URI.
+ *
+ * @public
+ */
+const resolveArazzo$selfField = (retrievalURI, element) => {
+  if (!(0, _apidomNsArazzo.isArazzoSpecification1Element)(element)) {
+    return retrievalURI;
+  }
+  const $self = (0, _apidomCore.toValue)(element.$self);
+  if (typeof $self !== 'string' || $self === '') {
+    return retrievalURI;
+  }
+  return url.resolve(retrievalURI, url.sanitize(url.stripHash($self)));
+};
+
+/**
+ * Predicate matching a Reference by the identity (`$self`) of the Arazzo
+ * document it holds, rather than by its retrieval URI. Implements identity-based
+ * referencing from Arazzo 1.1.0: a URI matching a loaded document's `$self`
+ * refers to that document, regardless of where it was retrieved from.
+ *
+ * @public
+ */
+exports.resolveArazzo$selfField = resolveArazzo$selfField;
+const identifiedBy$self = uri => reference => {
+  const result = reference.value?.result;
+  return (0, _apidomNsArazzo.isArazzoSpecification1Element)(result) && resolveArazzo$selfField(reference.uri, result) === uri;
+};
+
 /**
  * Cached version of JSONSchemaElement.refract.
  */
+exports.identifiedBy$self = identifiedBy$self;
 const refractToJSONSchemaElement = element => {
   if (refractToJSONSchemaElement.cache.has(element)) {
     return refractToJSONSchemaElement.cache.get(element);

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

@@ -1,6 +1,43 @@
 import { isPrimitiveElement } from '@speclynx/apidom-datamodel';
-import { refractJSONSchema } from '@speclynx/apidom-ns-arazzo-1';
+import { toValue } from '@speclynx/apidom-core';
+import { refractJSONSchema, isArazzoSpecification1Element } from '@speclynx/apidom-ns-arazzo-1';
+import * as url from "../../../util/url.mjs";
 export { resolveSchema$refField, resolveSchema$idField } from "../openapi-3-1/util.mjs";
+/**
+ * Computes the base URI of an Arazzo document per Arazzo 1.1.0 rules.
+ *
+ * When the Arazzo Object carries a `$self` field, it establishes the document's
+ * canonical identity and the base URI for resolving relative references. `$self`
+ * may itself be relative, in which case it's resolved against the retrieval URI.
+ * Any fragment is stripped, as `$self` MUST NOT contain one. When `$self` is
+ * absent (or `element` is not an Arazzo document), the retrieval URI is the base URI.
+ *
+ * @public
+ */
+export const resolveArazzo$selfField = (retrievalURI, element) => {
+  if (!isArazzoSpecification1Element(element)) {
+    return retrievalURI;
+  }
+  const $self = toValue(element.$self);
+  if (typeof $self !== 'string' || $self === '') {
+    return retrievalURI;
+  }
+  return url.resolve(retrievalURI, url.sanitize(url.stripHash($self)));
+};
+
+/**
+ * Predicate matching a Reference by the identity (`$self`) of the Arazzo
+ * document it holds, rather than by its retrieval URI. Implements identity-based
+ * referencing from Arazzo 1.1.0: a URI matching a loaded document's `$self`
+ * refers to that document, regardless of where it was retrieved from.
+ *
+ * @public
+ */
+export const identifiedBy$self = uri => reference => {
+  const result = reference.value?.result;
+  return isArazzoSpecification1Element(result) && resolveArazzo$selfField(reference.uri, result) === uri;
+};
+
 /**
  * Cached version of JSONSchemaElement.refract.
  */

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

@@ -37,6 +37,13 @@ var _EvaluationJsonSchemaUriError = _interopRequireDefault(require("../../../err
 class Arazzo1DereferenceVisitor {
   indirections;
   reference;
+
+  /**
+   * Base URI of the current document for resolving relative references.
+   * Honors the Arazzo `$self` field when present, otherwise falls back
+   * to the retrieval URI (`this.reference.uri`).
+   */
+  baseURI;
   options;
   visited;
 
@@ -55,6 +62,7 @@ class Arazzo1DereferenceVisitor {
   }) {
     this.indirections = indirections;
     this.reference = reference;
+    this.baseURI = (0, _util2.resolveArazzo$selfField)(reference.uri, reference.value?.result);
     this.options = options;
     this.ancestors = new _util3.AncestorLineage(...ancestors);
     this.visited = visited;
@@ -66,7 +74,7 @@ class Arazzo1DereferenceVisitor {
     return [ancestorsLineage, directAncestors];
   }
   toBaseURI(uri) {
-    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+    return url.resolve(this.baseURI, url.sanitize(url.stripHash(uri)));
   }
   async toReference(uri) {
     // detect maximum depth of resolution
@@ -85,6 +93,12 @@ class Arazzo1DereferenceVisitor {
     if (refSet.has(baseURI)) {
       return refSet.find((0, _ramda.propEq)(baseURI, 'uri'));
     }
+
+    // identity-based referencing: URI matches `$self` of an already processed Arazzo document
+    const referenceBy$self = refSet.find((0, _util2.identifiedBy$self)(baseURI));
+    if (referenceBy$self !== undefined) {
+      return referenceBy$self;
+    }
     const parseResult = await (0, _index.default)(url.unsanitize(baseURI), {
       ...this.options,
       parse: {
@@ -288,19 +302,19 @@ class Arazzo1DereferenceVisitor {
     }
     const indirectionsSize = this.indirections.length;
     try {
-      // compute baseURI using rules around $id and $ref keywords
+      // compute baseURI using rules around $self, $id and $ref keywords
       let reference = await this.toReference(url.unsanitize(this.reference.uri));
       let {
         uri: retrievalURI
       } = reference;
-      const $refBaseURI = (0, _util.resolveSchema$refField)(retrievalURI, referencingElement);
+      const $refBaseURI = (0, _util.resolveSchema$refField)(this.baseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new _File.default({
         uri: $refBaseURIStrippedHash
       });
       const isUnknownURI = (0, _ramda.none)(r => r.canRead(file), this.options.resolve.resolvers);
       const isURL = !isUnknownURI;
-      let isInternalReference = url.stripHash(this.reference.uri) === $refBaseURI;
+      let isInternalReference = this.baseURI === $refBaseURI;
       let isExternalReference = !isInternalReference;
 
       // determining reference, proper evaluation and selection mechanism
@@ -327,7 +341,7 @@ class Arazzo1DereferenceVisitor {
         } else {
           // we're assuming here that we're dealing with JSON Pointer here
           retrievalURI = this.toBaseURI($refBaseURI);
-          isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+          isInternalReference = this.baseURI === retrievalURI;
           isExternalReference = !isInternalReference;
 
           // ignore resolving internal Schema Objects
@@ -354,7 +368,7 @@ class Arazzo1DereferenceVisitor {
         if (isURL && error instanceof _EvaluationJsonSchemaUriError.default) {
           if ((0, _$anchor.isAnchor)((0, _$anchor.uriToAnchor)($refBaseURI))) {
             // we're dealing with JSON Schema $anchor here
-            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+            isInternalReference = this.baseURI === retrievalURI;
             isExternalReference = !isInternalReference;
 
             // ignore resolving internal Schema Objects
@@ -375,7 +389,7 @@ class Arazzo1DereferenceVisitor {
           } else {
             // we're assuming here that we're dealing with JSON Pointer here
             retrievalURI = this.toBaseURI($refBaseURI);
-            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+            isInternalReference = this.baseURI === retrievalURI;
             isExternalReference = !isInternalReference;
 
             // ignore resolving internal Schema Objects

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

@@ -9,7 +9,7 @@ import { parse as parseRuntimeExpression } from '@swaggerexpert/arazzo-runtime-e
 import { isAnchor, uriToAnchor, evaluate as $anchorEvaluate } from "./selectors/$anchor.mjs";
 import { evaluate as uriEvaluate } from "./selectors/uri.mjs";
 import { resolveSchema$refField } from "../openapi-3-1/util.mjs";
-import { maybeRefractToJSONSchemaElement } from "./util.mjs";
+import { maybeRefractToJSONSchemaElement, resolveArazzo$selfField, identifiedBy$self } from "./util.mjs";
 import UnresolvableReferenceError from "../../../errors/UnresolvableReferenceError.mjs";
 import MaximumDereferenceDepthError from "../../../errors/MaximumDereferenceDepthError.mjs";
 import MaximumResolveDepthError from "../../../errors/MaximumResolveDepthError.mjs";
@@ -28,6 +28,13 @@ import EvaluationJsonSchemaUriError from "../../../errors/EvaluationJsonSchemaUr
 class Arazzo1DereferenceVisitor {
   indirections;
   reference;
+
+  /**
+   * Base URI of the current document for resolving relative references.
+   * Honors the Arazzo `$self` field when present, otherwise falls back
+   * to the retrieval URI (`this.reference.uri`).
+   */
+  baseURI;
   options;
   visited;
 
@@ -46,6 +53,7 @@ class Arazzo1DereferenceVisitor {
   }) {
     this.indirections = indirections;
     this.reference = reference;
+    this.baseURI = resolveArazzo$selfField(reference.uri, reference.value?.result);
     this.options = options;
     this.ancestors = new AncestorLineage(...ancestors);
     this.visited = visited;
@@ -57,7 +65,7 @@ class Arazzo1DereferenceVisitor {
     return [ancestorsLineage, directAncestors];
   }
   toBaseURI(uri) {
-    return url.resolve(this.reference.uri, url.sanitize(url.stripHash(uri)));
+    return url.resolve(this.baseURI, url.sanitize(url.stripHash(uri)));
   }
   async toReference(uri) {
     // detect maximum depth of resolution
@@ -76,6 +84,12 @@ class Arazzo1DereferenceVisitor {
     if (refSet.has(baseURI)) {
       return refSet.find(propEq(baseURI, 'uri'));
     }
+
+    // identity-based referencing: URI matches `$self` of an already processed Arazzo document
+    const referenceBy$self = refSet.find(identifiedBy$self(baseURI));
+    if (referenceBy$self !== undefined) {
+      return referenceBy$self;
+    }
     const parseResult = await parse(url.unsanitize(baseURI), {
       ...this.options,
       parse: {
@@ -279,19 +293,19 @@ class Arazzo1DereferenceVisitor {
     }
     const indirectionsSize = this.indirections.length;
     try {
-      // compute baseURI using rules around $id and $ref keywords
+      // compute baseURI using rules around $self, $id and $ref keywords
       let reference = await this.toReference(url.unsanitize(this.reference.uri));
       let {
         uri: retrievalURI
       } = reference;
-      const $refBaseURI = resolveSchema$refField(retrievalURI, referencingElement);
+      const $refBaseURI = resolveSchema$refField(this.baseURI, referencingElement);
       const $refBaseURIStrippedHash = url.stripHash($refBaseURI);
       const file = new File({
         uri: $refBaseURIStrippedHash
       });
       const isUnknownURI = none(r => r.canRead(file), this.options.resolve.resolvers);
       const isURL = !isUnknownURI;
-      let isInternalReference = url.stripHash(this.reference.uri) === $refBaseURI;
+      let isInternalReference = this.baseURI === $refBaseURI;
       let isExternalReference = !isInternalReference;
 
       // determining reference, proper evaluation and selection mechanism
@@ -318,7 +332,7 @@ class Arazzo1DereferenceVisitor {
         } else {
           // we're assuming here that we're dealing with JSON Pointer here
           retrievalURI = this.toBaseURI($refBaseURI);
-          isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+          isInternalReference = this.baseURI === retrievalURI;
           isExternalReference = !isInternalReference;
 
           // ignore resolving internal Schema Objects
@@ -345,7 +359,7 @@ class Arazzo1DereferenceVisitor {
         if (isURL && error instanceof EvaluationJsonSchemaUriError) {
           if (isAnchor(uriToAnchor($refBaseURI))) {
             // we're dealing with JSON Schema $anchor here
-            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+            isInternalReference = this.baseURI === retrievalURI;
             isExternalReference = !isInternalReference;
 
             // ignore resolving internal Schema Objects
@@ -366,7 +380,7 @@ class Arazzo1DereferenceVisitor {
           } else {
             // we're assuming here that we're dealing with JSON Pointer here
             retrievalURI = this.toBaseURI($refBaseURI);
-            isInternalReference = url.stripHash(this.reference.uri) === retrievalURI;
+            isInternalReference = this.baseURI === retrievalURI;
             isExternalReference = !isInternalReference;
 
             // ignore resolving internal Schema Objects