@speclynx/apidom-reference 5.2.1 → 5.2.4

package/package.json

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

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

@@ -7,9 +7,6 @@ Object.defineProperty(exports, "__esModule", {
 exports.dereferenceSourceDescriptions = dereferenceSourceDescriptions;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
-var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
-var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
-var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
 var _apidomCore = require("@speclynx/apidom-core");
 var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 var _util = require("../../../options/util.cjs");
@@ -44,14 +41,25 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
   const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
   parseResult.setMetaProperty('retrievalURI', retrievalURI);
 
-  // skip if already visited (cycle detection)
-  if (ctx.visitedUrls.has(retrievalURI)) {
+  // skip if the document is still being dereferenced higher up the chain (cycle detection)
+  if (ctx.ancestors.includes(retrievalURI)) {
     const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
     annotation.classes.push('warning');
     parseResult.push(annotation);
     return parseResult;
   }
-  ctx.visitedUrls.add(retrievalURI);
+
+  // a document reached again through a different path is a shared dependency, not a cycle;
+  // point at the result where it was dereferenced instead of dereferencing it again
+  const sharedDereferenceResult = ctx.dereferenced.get(retrievalURI);
+  if (sharedDereferenceResult !== undefined) {
+    const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" has already been dereferenced. Reusing existing dereference result`);
+    annotation.classes.push('info');
+    parseResult.push(annotation);
+    parseResult.meta.set('parseResult', sharedDereferenceResult);
+    (0, _util2.validateSourceDescriptionAPI)(parseResult, sourceDescription, sharedDereferenceResult.api, retrievalURI);
+    return parseResult;
+  }
 
   // check if source description was already parsed (e.g., during parse phase with sourceDescriptions: true)
   const existingParseResult = sourceDescription.meta.get('parseResult');
@@ -74,7 +82,8 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
             [ctx.strategyName]: {
               sourceDescriptions: true,
               sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsVisitedUrls: ctx.visitedUrls
+              sourceDescriptionsAncestors: ctx.ancestors,
+              sourceDescriptionsDereferenced: ctx.dereferenced
             }
           }
         }
@@ -93,7 +102,8 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
             [ctx.strategyName]: {
               sourceDescriptions: true,
               sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsVisitedUrls: ctx.visitedUrls
+              sourceDescriptionsAncestors: ctx.ancestors,
+              sourceDescriptionsDereferenced: ctx.dereferenced
             }
           }
         }
@@ -113,32 +123,14 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
     return parseResult;
   }
 
-  // only allow OpenAPI and Arazzo as source descriptions
+  // register dereferenced document for later references to it
   const {
     api: sourceDescriptionAPI
   } = parseResult;
-  const isOpenApi = (0, _apidomNsOpenapi.isSwaggerElement)(sourceDescriptionAPI) || (0, _apidomNsOpenapi2.isOpenApi3_0Element)(sourceDescriptionAPI) || (0, _apidomNsOpenapi3.isOpenApi3_1Element)(sourceDescriptionAPI);
-  const isArazzo = (0, _apidomNsArazzo.isArazzoSpecification1Element)(sourceDescriptionAPI);
-  if (!isOpenApi && !isArazzo) {
-    const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" is not an OpenAPI or Arazzo document`);
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // validate declared type matches actual dereferenced type
-  const declaredType = (0, _apidomCore.toValue)(sourceDescription.type);
-  if (typeof declaredType === 'string') {
-    if (declaredType === 'openapi' && !isOpenApi) {
-      const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" declared as "openapi" but dereferenced as Arazzo document`);
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    } else if (declaredType === 'arazzo' && !isArazzo) {
-      const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" declared as "arazzo" but dereferenced as OpenAPI document`);
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    }
+  for (const documentURI of (0, _util2.arazzoDocumentURIs)(retrievalURI, sourceDescriptionAPI)) {
+    ctx.dereferenced.set(documentURI, parseResult);
   }
+  (0, _util2.validateSourceDescriptionAPI)(parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI);
   return parseResult;
 }
 
@@ -150,6 +142,13 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  * regardless of success or failure. On failure, the ParseResultElement
  * contains annotations explaining what went wrong.
  *
+ * A document referenced from more than one place is dereferenced only once.
+ * Every later source description referencing it gets its own result carrying
+ * an 'info' annotation and a 'parseResult' meta pointing at the result where
+ * the document was dereferenced; that result is also what gets attached to the
+ * SourceDescriptionElement's meta. A document referencing one of its ancestors
+ * forms a cycle and is skipped with a 'warning' annotation instead.
+ *
  * @param parseResult - ParseResult containing a parsed (optionally dereferenced) Arazzo specification
  * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
  * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
@@ -213,14 +212,9 @@ async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalUR
   // recursion state comes from strategy-specific options
   const sharedOpts = options?.dereference?.strategyOpts?.[strategyName] ?? {};
   const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
-  const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
-
-  // 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);
+  const dereferenced = sharedOpts.sourceDescriptionsDereferenced ?? new Map();
+  // current file is an ancestor of everything dereferenced below
+  const ancestors = [...(sharedOpts.sourceDescriptionsAncestors ?? []), ...(0, _util2.arazzoDocumentURIs)(retrievalURI, api)];
   if (currentDepth >= maxDepth) {
     const annotation = new _apidomDatamodel.AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${retrievalURI}"`);
     annotation.classes.push('error');
@@ -229,11 +223,13 @@ async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalUR
     return [parseResult];
   }
   const ctx = {
-    baseURI,
+    // base URI for resolving source description URLs honors Arazzo `$self` field
+    baseURI: (0, _util2.resolveArazzo$selfField)(retrievalURI, api),
     options,
     strategyName,
     currentDepth,
-    visitedUrls
+    ancestors,
+    dereferenced
   };
 
   // determine which source descriptions to dereference (array filters by name)
@@ -244,11 +240,12 @@ async function dereferenceSourceDescriptions(parseResult, parseResultRetrievalUR
     return typeof name === 'string' && sourceDescriptionsOption.includes(name);
   }) : api.sourceDescriptions;
 
-  // process sequentially to ensure proper cycle detection with shared visitedUrls
+  // process sequentially to ensure proper cycle detection with shared state
   for (const sourceDescription of sourceDescriptions) {
     const sourceDescriptionDereferenceResult = await dereferenceSourceDescription(sourceDescription, ctx);
-    // always attach result (even on failure - contains annotations)
-    sourceDescription.meta.set('parseResult', sourceDescriptionDereferenceResult);
+    // always attach result (even on failure - contains annotations);
+    // a shared document attaches the result where it was dereferenced
+    sourceDescription.meta.set('parseResult', sourceDescriptionDereferenceResult.meta.get('parseResult') ?? sourceDescriptionDereferenceResult);
     results.push(sourceDescriptionDereferenceResult);
   }
   return results;

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

@@ -1,13 +1,10 @@
 import { ParseResultElement, AnnotationElement, isArrayElement, isStringElement, isParseResultElement } from '@speclynx/apidom-datamodel';
 import { isArazzoSpecification1Element, isSourceDescriptionElement } from '@speclynx/apidom-ns-arazzo-1';
-import { isSwaggerElement } from '@speclynx/apidom-ns-openapi-2';
-import { isOpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';
-import { isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
 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";
+import { arazzoDocumentURIs, resolveArazzo$selfField, validateSourceDescriptionAPI } from "./util.mjs";
 /**
  * Dereferences a single source description element.
  * Returns ParseResultElement on success, or with annotation if skipped.
@@ -37,14 +34,25 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
   const retrievalURI = url.sanitize(url.stripHash(url.resolve(ctx.baseURI, sourceDescriptionURI)));
   parseResult.setMetaProperty('retrievalURI', retrievalURI);
 
-  // skip if already visited (cycle detection)
-  if (ctx.visitedUrls.has(retrievalURI)) {
+  // skip if the document is still being dereferenced higher up the chain (cycle detection)
+  if (ctx.ancestors.includes(retrievalURI)) {
     const annotation = new AnnotationElement(`Source description "${retrievalURI}" has already been visited. Skipping to prevent cycle`);
     annotation.classes.push('warning');
     parseResult.push(annotation);
     return parseResult;
   }
-  ctx.visitedUrls.add(retrievalURI);
+
+  // a document reached again through a different path is a shared dependency, not a cycle;
+  // point at the result where it was dereferenced instead of dereferencing it again
+  const sharedDereferenceResult = ctx.dereferenced.get(retrievalURI);
+  if (sharedDereferenceResult !== undefined) {
+    const annotation = new AnnotationElement(`Source description "${retrievalURI}" has already been dereferenced. Reusing existing dereference result`);
+    annotation.classes.push('info');
+    parseResult.push(annotation);
+    parseResult.meta.set('parseResult', sharedDereferenceResult);
+    validateSourceDescriptionAPI(parseResult, sourceDescription, sharedDereferenceResult.api, retrievalURI);
+    return parseResult;
+  }
 
   // check if source description was already parsed (e.g., during parse phase with sourceDescriptions: true)
   const existingParseResult = sourceDescription.meta.get('parseResult');
@@ -67,7 +75,8 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
             [ctx.strategyName]: {
               sourceDescriptions: true,
               sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsVisitedUrls: ctx.visitedUrls
+              sourceDescriptionsAncestors: ctx.ancestors,
+              sourceDescriptionsDereferenced: ctx.dereferenced
             }
           }
         }
@@ -86,7 +95,8 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
             [ctx.strategyName]: {
               sourceDescriptions: true,
               sourceDescriptionsDepth: ctx.currentDepth + 1,
-              sourceDescriptionsVisitedUrls: ctx.visitedUrls
+              sourceDescriptionsAncestors: ctx.ancestors,
+              sourceDescriptionsDereferenced: ctx.dereferenced
             }
           }
         }
@@ -106,32 +116,14 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
     return parseResult;
   }
 
-  // only allow OpenAPI and Arazzo as source descriptions
+  // register dereferenced document for later references to it
   const {
     api: sourceDescriptionAPI
   } = parseResult;
-  const isOpenApi = isSwaggerElement(sourceDescriptionAPI) || isOpenApi3_0Element(sourceDescriptionAPI) || isOpenApi3_1Element(sourceDescriptionAPI);
-  const isArazzo = isArazzoSpecification1Element(sourceDescriptionAPI);
-  if (!isOpenApi && !isArazzo) {
-    const annotation = new AnnotationElement(`Source description "${retrievalURI}" is not an OpenAPI or Arazzo document`);
-    annotation.classes.push('warning');
-    parseResult.push(annotation);
-    return parseResult;
-  }
-
-  // validate declared type matches actual dereferenced type
-  const declaredType = toValue(sourceDescription.type);
-  if (typeof declaredType === 'string') {
-    if (declaredType === 'openapi' && !isOpenApi) {
-      const annotation = new AnnotationElement(`Source description "${retrievalURI}" declared as "openapi" but dereferenced as Arazzo document`);
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    } else if (declaredType === 'arazzo' && !isArazzo) {
-      const annotation = new AnnotationElement(`Source description "${retrievalURI}" declared as "arazzo" but dereferenced as OpenAPI document`);
-      annotation.classes.push('warning');
-      parseResult.push(annotation);
-    }
+  for (const documentURI of arazzoDocumentURIs(retrievalURI, sourceDescriptionAPI)) {
+    ctx.dereferenced.set(documentURI, parseResult);
   }
+  validateSourceDescriptionAPI(parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI);
   return parseResult;
 }
 
@@ -143,6 +135,13 @@ async function dereferenceSourceDescription(sourceDescription, ctx) {
  * regardless of success or failure. On failure, the ParseResultElement
  * contains annotations explaining what went wrong.
  *
+ * A document referenced from more than one place is dereferenced only once.
+ * Every later source description referencing it gets its own result carrying
+ * an 'info' annotation and a 'parseResult' meta pointing at the result where
+ * the document was dereferenced; that result is also what gets attached to the
+ * SourceDescriptionElement's meta. A document referencing one of its ancestors
+ * forms a cycle and is skipped with a 'warning' annotation instead.
+ *
  * @param parseResult - ParseResult containing a parsed (optionally dereferenced) Arazzo specification
  * @param parseResultRetrievalURI - URI from which the parseResult was retrieved
  * @param options - Full ReferenceOptions. Pass `sourceDescriptions` as an array of names
@@ -206,14 +205,9 @@ export async function dereferenceSourceDescriptions(parseResult, parseResultRetr
   // recursion state comes from strategy-specific options
   const sharedOpts = options?.dereference?.strategyOpts?.[strategyName] ?? {};
   const currentDepth = sharedOpts.sourceDescriptionsDepth ?? 0;
-  const visitedUrls = sharedOpts.sourceDescriptionsVisitedUrls ?? new Set();
-
-  // 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);
+  const dereferenced = sharedOpts.sourceDescriptionsDereferenced ?? new Map();
+  // current file is an ancestor of everything dereferenced below
+  const ancestors = [...(sharedOpts.sourceDescriptionsAncestors ?? []), ...arazzoDocumentURIs(retrievalURI, api)];
   if (currentDepth >= maxDepth) {
     const annotation = new AnnotationElement(`Maximum dereference depth of ${maxDepth} has been exceeded by file "${retrievalURI}"`);
     annotation.classes.push('error');
@@ -222,11 +216,13 @@ export async function dereferenceSourceDescriptions(parseResult, parseResultRetr
     return [parseResult];
   }
   const ctx = {
-    baseURI,
+    // base URI for resolving source description URLs honors Arazzo `$self` field
+    baseURI: resolveArazzo$selfField(retrievalURI, api),
     options,
     strategyName,
     currentDepth,
-    visitedUrls
+    ancestors,
+    dereferenced
   };
 
   // determine which source descriptions to dereference (array filters by name)
@@ -237,11 +233,12 @@ export async function dereferenceSourceDescriptions(parseResult, parseResultRetr
     return typeof name === 'string' && sourceDescriptionsOption.includes(name);
   }) : api.sourceDescriptions;
 
-  // process sequentially to ensure proper cycle detection with shared visitedUrls
+  // process sequentially to ensure proper cycle detection with shared state
   for (const sourceDescription of sourceDescriptions) {
     const sourceDescriptionDereferenceResult = await dereferenceSourceDescription(sourceDescription, ctx);
-    // always attach result (even on failure - contains annotations)
-    sourceDescription.meta.set('parseResult', sourceDescriptionDereferenceResult);
+    // always attach result (even on failure - contains annotations);
+    // a shared document attaches the result where it was dereferenced
+    sourceDescription.meta.set('parseResult', sourceDescriptionDereferenceResult.meta.get('parseResult') ?? sourceDescriptionDereferenceResult);
     results.push(sourceDescriptionDereferenceResult);
   }
   return results;

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

@@ -4,7 +4,7 @@ var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopReq
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.resolveArazzo$selfField = exports.refractToJSONSchemaElement = exports.maybeRefractToJSONSchemaElement = exports.identifiedBy$self = void 0;
+exports.resolveArazzo$selfField = exports.refractToJSONSchemaElement = exports.maybeRefractToJSONSchemaElement = exports.identifiedBy$self = exports.arazzoDocumentURIs = void 0;
 Object.defineProperty(exports, "resolveSchema$idField", {
   enumerable: true,
   get: function () {
@@ -17,9 +17,13 @@ Object.defineProperty(exports, "resolveSchema$refField", {
     return _util.resolveSchema$refField;
   }
 });
+exports.validateSourceDescriptionAPI = void 0;
 var _apidomDatamodel = require("@speclynx/apidom-datamodel");
 var _apidomCore = require("@speclynx/apidom-core");
 var _apidomNsArazzo = require("@speclynx/apidom-ns-arazzo-1");
+var _apidomNsOpenapi = require("@speclynx/apidom-ns-openapi-2");
+var _apidomNsOpenapi2 = require("@speclynx/apidom-ns-openapi-3-0");
+var _apidomNsOpenapi3 = require("@speclynx/apidom-ns-openapi-3-1");
 var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 var _util = require("../openapi-3-1/util.cjs");
 /**
@@ -44,6 +48,47 @@ const resolveArazzo$selfField = (retrievalURI, element) => {
   return url.resolve(retrievalURI, url.sanitize(url.stripHash($self)));
 };
 
+/**
+ * URIs an Arazzo document is known by: its retrieval URI and, when the
+ * document carries a `$self` field resolving elsewhere, its identity.
+ */
+exports.resolveArazzo$selfField = resolveArazzo$selfField;
+const arazzoDocumentURIs = (retrievalURI, element) => {
+  const identity = resolveArazzo$selfField(retrievalURI, element);
+  return identity === retrievalURI ? [retrievalURI] : [retrievalURI, identity];
+};
+
+/**
+ * Annotates a source description result when the document is not an OpenAPI
+ * or Arazzo document, or does not match the type the source description declares.
+ */
+exports.arazzoDocumentURIs = arazzoDocumentURIs;
+const validateSourceDescriptionAPI = (parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI) => {
+  // only allow OpenAPI and Arazzo as source descriptions
+  const isOpenApi = (0, _apidomNsOpenapi.isSwaggerElement)(sourceDescriptionAPI) || (0, _apidomNsOpenapi2.isOpenApi3_0Element)(sourceDescriptionAPI) || (0, _apidomNsOpenapi3.isOpenApi3_1Element)(sourceDescriptionAPI);
+  const isArazzo = (0, _apidomNsArazzo.isArazzoSpecification1Element)(sourceDescriptionAPI);
+  if (!isOpenApi && !isArazzo) {
+    const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" is not an OpenAPI or Arazzo document`);
+    annotation.classes.push('warning');
+    parseResult.push(annotation);
+    return;
+  }
+
+  // validate declared type matches actual type
+  const declaredType = (0, _apidomCore.toValue)(sourceDescription.type);
+  if (typeof declaredType === 'string') {
+    if (declaredType === 'openapi' && !isOpenApi) {
+      const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" declared as "openapi" but is an Arazzo document`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    } else if (declaredType === 'arazzo' && !isArazzo) {
+      const annotation = new _apidomDatamodel.AnnotationElement(`Source description "${retrievalURI}" declared as "arazzo" but is an OpenAPI document`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    }
+  }
+};
+
 /**
  * Predicate matching a Reference by the identity (`$self`) of the Arazzo
  * document it holds, rather than by its retrieval URI. Implements identity-based
@@ -52,7 +97,7 @@ const resolveArazzo$selfField = (retrievalURI, element) => {
  *
  * @public
  */
-exports.resolveArazzo$selfField = resolveArazzo$selfField;
+exports.validateSourceDescriptionAPI = validateSourceDescriptionAPI;
 const identifiedBy$self = uri => reference => {
   const result = reference.value?.result;
   return (0, _apidomNsArazzo.isArazzoSpecification1Element)(result) && resolveArazzo$selfField(reference.uri, result) === uri;

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

@@ -1,6 +1,9 @@
-import { isPrimitiveElement } from '@speclynx/apidom-datamodel';
+import { AnnotationElement, isPrimitiveElement } from '@speclynx/apidom-datamodel';
 import { toValue } from '@speclynx/apidom-core';
 import { refractJSONSchema, isArazzoSpecification1Element } from '@speclynx/apidom-ns-arazzo-1';
+import { isSwaggerElement } from '@speclynx/apidom-ns-openapi-2';
+import { isOpenApi3_0Element } from '@speclynx/apidom-ns-openapi-3-0';
+import { isOpenApi3_1Element } from '@speclynx/apidom-ns-openapi-3-1';
 import * as url from "../../../util/url.mjs";
 export { resolveSchema$refField, resolveSchema$idField } from "../openapi-3-1/util.mjs";
 /**
@@ -25,6 +28,45 @@ export const resolveArazzo$selfField = (retrievalURI, element) => {
   return url.resolve(retrievalURI, url.sanitize(url.stripHash($self)));
 };
 
+/**
+ * URIs an Arazzo document is known by: its retrieval URI and, when the
+ * document carries a `$self` field resolving elsewhere, its identity.
+ */
+export const arazzoDocumentURIs = (retrievalURI, element) => {
+  const identity = resolveArazzo$selfField(retrievalURI, element);
+  return identity === retrievalURI ? [retrievalURI] : [retrievalURI, identity];
+};
+
+/**
+ * Annotates a source description result when the document is not an OpenAPI
+ * or Arazzo document, or does not match the type the source description declares.
+ */
+export const validateSourceDescriptionAPI = (parseResult, sourceDescription, sourceDescriptionAPI, retrievalURI) => {
+  // only allow OpenAPI and Arazzo as source descriptions
+  const isOpenApi = isSwaggerElement(sourceDescriptionAPI) || isOpenApi3_0Element(sourceDescriptionAPI) || isOpenApi3_1Element(sourceDescriptionAPI);
+  const isArazzo = isArazzoSpecification1Element(sourceDescriptionAPI);
+  if (!isOpenApi && !isArazzo) {
+    const annotation = new AnnotationElement(`Source description "${retrievalURI}" is not an OpenAPI or Arazzo document`);
+    annotation.classes.push('warning');
+    parseResult.push(annotation);
+    return;
+  }
+
+  // validate declared type matches actual type
+  const declaredType = toValue(sourceDescription.type);
+  if (typeof declaredType === 'string') {
+    if (declaredType === 'openapi' && !isOpenApi) {
+      const annotation = new AnnotationElement(`Source description "${retrievalURI}" declared as "openapi" but is an Arazzo document`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    } else if (declaredType === 'arazzo' && !isArazzo) {
+      const annotation = new AnnotationElement(`Source description "${retrievalURI}" declared as "arazzo" but is an OpenAPI document`);
+      annotation.classes.push('warning');
+      parseResult.push(annotation);
+    }
+  }
+};
+
 /**
  * Predicate matching a Reference by the identity (`$self`) of the Arazzo
  * document it holds, rather than by its retrieval URI. Implements identity-based