From d45400af13ff3f436a5c737f5dd6e81df8c64f4a Mon Sep 17 00:00:00 2001
From: Vladimir Gorej <vladimir.gorej@gmail.com>
Date: Tue, 6 Dec 2022 11:08:59 +0100
Subject: [PATCH] feat(reference): add support for allowMetaPatches option

This affects OpenAPI 3.1 swagger-client dereference strategy.

Refs #2336
---
 .../openapi-3-1-swagger-client/index.ts       |  9 ++-
 .../openapi-3-1-swagger-client/visitor.ts     | 43 +++++++++++++++
 .../meta-patches-external/dereferenced.json   | 14 +++++
 .../fixtures/meta-patches-external/ex1.json   |  5 ++
 .../fixtures/meta-patches-external/ex2.json   |  5 ++
 .../fixtures/meta-patches-external/ex3.json   |  6 ++
 .../fixtures/meta-patches-external/root.json  | 11 ++++
 .../meta-patches-internal/dereferenced.json   | 23 ++++++++
 .../fixtures/meta-patches-internal/root.json  | 17 ++++++
 .../path-item-object/index.ts                 | 55 ++++++++++++++++++-
 .../meta-patches-external/dereferenced.json   | 16 ++++++
 .../fixtures/meta-patches-external/ex1.json   |  5 ++
 .../fixtures/meta-patches-external/ex2.json   |  5 ++
 .../fixtures/meta-patches-external/ex3.json   |  8 +++
 .../fixtures/meta-patches-external/root.json  | 11 ++++
 .../meta-patches-internal/dereferenced.json   | 27 +++++++++
 .../fixtures/meta-patches-internal/root.json  | 18 ++++++
 .../reference-object/index.ts                 | 55 ++++++++++++++++++-
 .../meta-patches-external/dereferenced.json   | 14 +++++
 .../fixtures/meta-patches-external/ex1.json   |  5 ++
 .../fixtures/meta-patches-external/ex2.json   |  5 ++
 .../fixtures/meta-patches-external/ex3.json   |  8 +++
 .../fixtures/meta-patches-external/root.json  | 11 ++++
 .../meta-patches-internal/dereferenced.json   | 19 +++++++
 .../fixtures/meta-patches-internal/root.json  | 16 ++++++
 .../schema-object/index.ts                    | 52 ++++++++++++++++++
 26 files changed, 460 insertions(+), 3 deletions(-)
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/dereferenced.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex1.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex2.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex3.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/root.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-internal/dereferenced.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-internal/root.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/dereferenced.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex1.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex2.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex3.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/root.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-internal/dereferenced.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-internal/root.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/dereferenced.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex1.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex2.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex3.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/root.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-internal/dereferenced.json
 create mode 100644 packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-internal/root.json

diff --git a/packages/apidom-reference/src/dereference/strategies/openapi-3-1-swagger-client/index.ts b/packages/apidom-reference/src/dereference/strategies/openapi-3-1-swagger-client/index.ts
index 5f08a26467..97e4d89751 100644
--- a/packages/apidom-reference/src/dereference/strategies/openapi-3-1-swagger-client/index.ts
+++ b/packages/apidom-reference/src/dereference/strategies/openapi-3-1-swagger-client/index.ts
@@ -24,6 +24,7 @@ const visitAsync = visit[Symbol.for('nodejs.util.promisify.custom')];
 // eslint-disable-next-line @typescript-eslint/naming-convention
 interface IOpenApi3_1SwaggerClientDereferenceStrategy extends IDereferenceStrategy {
   useCircularStructures: boolean;
+  allowMetaPatches: boolean;
 }
 
 // eslint-disable-next-line @typescript-eslint/naming-convention
@@ -31,14 +32,19 @@ const OpenApi3_1SwaggerClientDereferenceStrategy: stampit.Stamp<IOpenApi3_1Swagg
   stampit(DereferenceStrategy, {
     props: {
       useCircularStructures: true,
+      allowMetaPatches: false,
     },
     init(
       this: IOpenApi3_1SwaggerClientDereferenceStrategy,
-      { useCircularStructures = this.useCircularStructures } = {},
+      {
+        useCircularStructures = this.useCircularStructures,
+        allowMetaPatches = this.allowMetaPatches,
+      } = {},
     ) {
       // @ts-ignore
       this.name = 'openapi-3-1-swagger-client';
       this.useCircularStructures = useCircularStructures;
+      this.allowMetaPatches = allowMetaPatches;
     },
     methods: {
       canDereference(file: IFile): boolean {
@@ -69,6 +75,7 @@ const OpenApi3_1SwaggerClientDereferenceStrategy: stampit.Stamp<IOpenApi3_1Swagg
           namespace,
           options,
           useCircularStructures: this.useCircularStructures,
+          allowMetaPatches: this.allowMetaPatches,
         });
         const dereferencedElement = await visitAsync(refSet.rootRef.value, visitor, {
           keyMap,
diff --git a/packages/apidom-reference/src/dereference/strategies/openapi-3-1-swagger-client/visitor.ts b/packages/apidom-reference/src/dereference/strategies/openapi-3-1-swagger-client/visitor.ts
index 29bcb76737..92cacbccba 100644
--- a/packages/apidom-reference/src/dereference/strategies/openapi-3-1-swagger-client/visitor.ts
+++ b/packages/apidom-reference/src/dereference/strategies/openapi-3-1-swagger-client/visitor.ts
@@ -2,6 +2,8 @@ import stampit from 'stampit';
 import { hasIn, pathSatisfies, propEq, none } from 'ramda';
 import { isUndefined, isNotUndefined } from 'ramda-adjunct';
 import {
+  isObjectElement,
+  ObjectElement,
   isPrimitiveElement,
   isStringElement,
   visit,
@@ -65,6 +67,7 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = stampit({
     namespace,
     options,
     useCircularStructures,
+    allowMetaPatches,
   }) {
     this.indirections = indirections;
     this.visited = visited;
@@ -72,6 +75,7 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = stampit({
     this.reference = reference;
     this.options = options;
     this.useCircularStructures = useCircularStructures;
+    this.allowMetaPatches = allowMetaPatches;
   },
   methods: {
     toBaseURI(uri: string): string {
@@ -160,6 +164,7 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = stampit({
         namespace: this.namespace,
         indirections: [...this.indirections],
         options: this.options,
+        allowMetaPatches: this.allowMetaPatches,
       });
       fragment = await visitAsync(fragment, visitor, { keyMap, nodeTypeGetter: getNodeType });
 
@@ -188,6 +193,19 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = stampit({
         fragment.summary = referenceElement.summary;
       }
 
+      // apply meta patches
+      if (this.allowMetaPatches && isObjectElement(fragment)) {
+        const objectFragment = fragment as ObjectElement;
+        // apply meta patch only when not already applied
+        if (typeof objectFragment.get('$$ref') === 'undefined') {
+          const absoluteJSONPointerURL = url.resolve(
+            reference.uri,
+            referenceElement.$ref?.toValue(),
+          );
+          objectFragment.set('$$ref', absoluteJSONPointerURL);
+        }
+      }
+
       this.indirections.pop();
 
       // transclude the element for a fragment
@@ -238,6 +256,7 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = stampit({
         namespace: this.namespace,
         indirections: [...this.indirections],
         options: this.options,
+        allowMetaPatches: this.allowMetaPatches,
       });
       referencedElement = await visitAsync(referencedElement, visitor, {
         keyMap,
@@ -267,6 +286,18 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = stampit({
       // annotate referenced element with info about origin
       mergedResult.setMetaProperty('ref-origin', reference.uri);
 
+      // apply meta patches
+      if (this.allowMetaPatches) {
+        // apply meta patch only when not already applied
+        if (typeof mergedResult.get('$$ref') === 'undefined') {
+          const absoluteJSONPointerURL = url.resolve(
+            reference.uri,
+            pathItemElement.$ref?.toValue(),
+          );
+          mergedResult.set('$$ref', absoluteJSONPointerURL);
+        }
+      }
+
       // transclude referencing element with merged referenced element
       return mergedResult;
     },
@@ -490,6 +521,7 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = stampit({
         options: this.options,
         visited: this.visited,
         useCircularStructures: this.useCircularStructures,
+        allowMetaPatches: this.allowMetaPatches,
       });
       referencedElement = await visitAsync(referencedElement, visitor, {
         keyMap,
@@ -530,6 +562,17 @@ const OpenApi3_1SwaggerClientDereferenceVisitor = stampit({
       });
       // annotate fragment with info about origin
       mergedResult.setMetaProperty('ref-origin', reference.uri);
+      // apply meta patches
+      if (this.allowMetaPatches) {
+        // apply meta patch only when not already applied
+        if (typeof mergedResult.get('$$ref') === 'undefined') {
+          const absoluteJSONPointerURL = url.resolve(
+            reference.uri,
+            referencingElement.$ref?.toValue(),
+          );
+          mergedResult.set('$$ref', absoluteJSONPointerURL);
+        }
+      }
 
       // transclude referencing element with merged referenced element
       return mergedResult;
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/dereferenced.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/dereferenced.json
new file mode 100644
index 0000000000..3cfa9cf6f2
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/dereferenced.json
@@ -0,0 +1,14 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "pathItems": {
+        "externalRef": {
+          "description": "external ref",
+          "get": {},
+          "$$ref": "http://localhost:8123/ex3.json#/externalPathItem"
+        }
+      }
+    }
+  }
+]
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex1.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex1.json
new file mode 100644
index 0000000000..f46bebc5f4
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex1.json
@@ -0,0 +1,5 @@
+{
+  "indirection": {
+    "$ref": "./ex2.json#/indirection"
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex2.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex2.json
new file mode 100644
index 0000000000..5d5e2e2955
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex2.json
@@ -0,0 +1,5 @@
+{
+  "indirection": {
+    "$ref": "./ex3.json#/externalPathItem"
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex3.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex3.json
new file mode 100644
index 0000000000..08774eea34
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/ex3.json
@@ -0,0 +1,6 @@
+{
+  "externalPathItem": {
+    "description": "this is path item stored in external file",
+    "get": {}
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/root.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/root.json
new file mode 100644
index 0000000000..0601253768
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-external/root.json
@@ -0,0 +1,11 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "pathItems": {
+       "externalRef": {
+        "$ref": "./ex1.json#/indirection",
+        "description": "external ref"
+      }
+    }
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-internal/dereferenced.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-internal/dereferenced.json
new file mode 100644
index 0000000000..3a4375cef0
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-internal/dereferenced.json
@@ -0,0 +1,23 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "pathItems": {
+        "pathItem1": {
+          "summary": "path item summary",
+          "description": "path item description",
+          "$$ref": "http://localhost:8123/root.json#/components/pathItems/pathItem3"
+        },
+        "pathItem2": {
+          "summary": "path item summary",
+          "description": "path item description",
+          "$$ref": "http://localhost:8123/root.json#/components/pathItems/pathItem3"
+        },
+        "pathItem3": {
+          "summary": "path item summary",
+          "description": "path item description"
+        }
+      }
+    }
+  }
+]
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-internal/root.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-internal/root.json
new file mode 100644
index 0000000000..b745848015
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/fixtures/meta-patches-internal/root.json
@@ -0,0 +1,17 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "pathItems": {
+      "pathItem1": {
+        "$ref": "#/components/pathItems/pathItem2"
+      },
+      "pathItem2": {
+        "$ref": "#/components/pathItems/pathItem3"
+      },
+      "pathItem3": {
+        "summary": "path item summary",
+        "description": "path item description"
+      }
+    }
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/index.ts b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/index.ts
index 43f2def4c3..d1d5593c93 100644
--- a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/index.ts
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/path-item-object/index.ts
@@ -3,10 +3,11 @@ import { assert } from 'chai';
 import { toValue } from '@swagger-api/apidom-core';
 import { mediaTypes } from '@swagger-api/apidom-ns-openapi-3-1';
 
-import { loadJsonFile } from '../../../../helpers';
+import { createHTTPServer, loadJsonFile } from '../../../../helpers';
 import { dereference } from '../../../../../src';
 import { DereferenceError, MaximumDereferenceDepthError } from '../../../../../src/util/errors';
 import * as bootstrap from '../bootstrap';
+import OpenApi3_1SwaggerClientDereferenceStrategy from '../../../../../src/dereference/strategies/openapi-3-1-swagger-client';
 
 const rootFixturePath = path.join(__dirname, 'fixtures');
 
@@ -164,6 +165,58 @@ describe('dereference', function () {
             });
           });
 
+          context('given $ref field pointing internally', function () {
+            context('and allowMetaPatches=true', function () {
+              specify('should dereference', async function () {
+                let httpServer: any;
+
+                try {
+                  const fixturePath = path.join(rootFixturePath, 'meta-patches-internal');
+                  httpServer = createHTTPServer({ port: 8123, cwd: fixturePath });
+                  const actual = await dereference('http://localhost:8123/root.json', {
+                    parse: { mediaType: mediaTypes.latest('json') },
+                    dereference: {
+                      strategies: [
+                        OpenApi3_1SwaggerClientDereferenceStrategy({ allowMetaPatches: true }),
+                      ],
+                    },
+                  });
+                  const expected = loadJsonFile(path.join(fixturePath, 'dereferenced.json'));
+
+                  assert.deepEqual(toValue(actual), expected);
+                } finally {
+                  httpServer?.terminate();
+                }
+              });
+            });
+          });
+
+          context('given $ref field pointing externally', function () {
+            context('and allowMetaPatches=true', function () {
+              specify('should dereference', async function () {
+                let httpServer: any;
+
+                try {
+                  const fixturePath = path.join(rootFixturePath, 'meta-patches-external');
+                  httpServer = createHTTPServer({ port: 8123, cwd: fixturePath });
+                  const actual = await dereference('http://localhost:8123/root.json', {
+                    parse: { mediaType: mediaTypes.latest('json') },
+                    dereference: {
+                      strategies: [
+                        OpenApi3_1SwaggerClientDereferenceStrategy({ allowMetaPatches: true }),
+                      ],
+                    },
+                  });
+                  const expected = loadJsonFile(path.join(fixturePath, 'dereferenced.json'));
+
+                  assert.deepEqual(toValue(actual), expected);
+                } finally {
+                  httpServer?.terminate();
+                }
+              });
+            });
+          });
+
           context('given $ref field with invalid JSON Pointer', function () {
             const fixturePath = path.join(rootFixturePath, 'invalid-pointer');
 
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/dereferenced.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/dereferenced.json
new file mode 100644
index 0000000000..bec19f8a01
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/dereferenced.json
@@ -0,0 +1,16 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "parameters": {
+        "externalRef": {
+          "name": "externalParameter",
+          "in": "query",
+          "description": "external ref",
+          "required": true,
+          "$$ref": "http://localhost:8123/ex3.json#/externalParameter"
+        }
+      }
+    }
+  }
+]
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex1.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex1.json
new file mode 100644
index 0000000000..f46bebc5f4
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex1.json
@@ -0,0 +1,5 @@
+{
+  "indirection": {
+    "$ref": "./ex2.json#/indirection"
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex2.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex2.json
new file mode 100644
index 0000000000..091689f702
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex2.json
@@ -0,0 +1,5 @@
+{
+  "indirection": {
+    "$ref": "./ex3.json#/externalParameter"
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex3.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex3.json
new file mode 100644
index 0000000000..fc8a07edcd
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/ex3.json
@@ -0,0 +1,8 @@
+{
+  "externalParameter": {
+    "name": "externalParameter",
+    "in": "query",
+    "description": "this is parameter stored in external file",
+    "required": true
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/root.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/root.json
new file mode 100644
index 0000000000..3614c32b3c
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-external/root.json
@@ -0,0 +1,11 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "parameters": {
+       "externalRef": {
+        "$ref": "./ex1.json#/indirection",
+        "description": "external ref"
+      }
+    }
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-internal/dereferenced.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-internal/dereferenced.json
new file mode 100644
index 0000000000..9dffe470b0
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-internal/dereferenced.json
@@ -0,0 +1,27 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "parameters": {
+        "param1": {
+          "name": "offset",
+          "in": "query",
+          "required": true,
+          "$$ref": "http://localhost:8123/root.json#/components/parameters/param3"
+        },
+        "param2": {
+          "name": "offset",
+          "in": "query",
+          "required": true,
+          "$$ref": "http://localhost:8123/root.json#/components/parameters/param3"
+        },
+        "param3": {
+          "name": "offset",
+          "in": "query",
+          "required": true
+        }
+      }
+    }
+  }
+
+]
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-internal/root.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-internal/root.json
new file mode 100644
index 0000000000..be9fcab8b0
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/fixtures/meta-patches-internal/root.json
@@ -0,0 +1,18 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "parameters": {
+      "param1": {
+        "$ref": "#/components/parameters/param2"
+      },
+      "param2": {
+        "$ref": "#/components/parameters/param3"
+      },
+      "param3": {
+        "name": "offset",
+        "in": "query",
+        "required": true
+      }
+    }
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/index.ts b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/index.ts
index fe423a8c3a..ec390363ce 100644
--- a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/index.ts
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/reference-object/index.ts
@@ -4,7 +4,7 @@ import { ParseResultElement, toValue } from '@swagger-api/apidom-core';
 import { isParameterElement, mediaTypes } from '@swagger-api/apidom-ns-openapi-3-1';
 import { evaluate } from '@swagger-api/apidom-json-pointer';
 
-import { loadJsonFile } from '../../../../helpers';
+import { createHTTPServer, loadJsonFile } from '../../../../helpers';
 import { dereference, dereferenceApiDOM, resolve, parse } from '../../../../../src';
 import {
   DereferenceError,
@@ -13,6 +13,7 @@ import {
 } from '../../../../../src/util/errors';
 import Reference from '../../../../../src/Reference';
 import ReferenceSet from '../../../../../src/ReferenceSet';
+import OpenApi3_1SwaggerClientDereferenceStrategy from '../../../../../src/dereference/strategies/openapi-3-1-swagger-client';
 import * as bootstrap from '../bootstrap';
 
 const rootFixturePath = path.join(__dirname, 'fixtures');
@@ -153,6 +154,58 @@ describe('dereference', function () {
           });
         });
 
+        context('given Reference Objects pointing internally', function () {
+          context('and allowMetaPatches=true', function () {
+            specify('should dereference', async function () {
+              let httpServer: any;
+
+              try {
+                const fixturePath = path.join(rootFixturePath, 'meta-patches-internal');
+                httpServer = createHTTPServer({ port: 8123, cwd: fixturePath });
+                const actual = await dereference('http://localhost:8123/root.json', {
+                  parse: { mediaType: mediaTypes.latest('json') },
+                  dereference: {
+                    strategies: [
+                      OpenApi3_1SwaggerClientDereferenceStrategy({ allowMetaPatches: true }),
+                    ],
+                  },
+                });
+                const expected = loadJsonFile(path.join(fixturePath, 'dereferenced.json'));
+
+                assert.deepEqual(toValue(actual), expected);
+              } finally {
+                httpServer?.terminate();
+              }
+            });
+          });
+        });
+
+        context('given Reference Objects pointing externally', function () {
+          context('and allowMetaPatches=true', function () {
+            specify('should dereference', async function () {
+              let httpServer: any;
+
+              try {
+                const fixturePath = path.join(rootFixturePath, 'meta-patches-external');
+                httpServer = createHTTPServer({ port: 8123, cwd: fixturePath });
+                const actual = await dereference('http://localhost:8123/root.json', {
+                  parse: { mediaType: mediaTypes.latest('json') },
+                  dereference: {
+                    strategies: [
+                      OpenApi3_1SwaggerClientDereferenceStrategy({ allowMetaPatches: true }),
+                    ],
+                  },
+                });
+                const expected = loadJsonFile(path.join(fixturePath, 'dereferenced.json'));
+
+                assert.deepEqual(toValue(actual), expected);
+              } finally {
+                httpServer?.terminate();
+              }
+            });
+          });
+        });
+
         context('given Reference Objects with internal cycles', function () {
           const fixturePath = path.join(rootFixturePath, 'cycle-internal');
 
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/dereferenced.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/dereferenced.json
new file mode 100644
index 0000000000..4d409494c4
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/dereferenced.json
@@ -0,0 +1,14 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "schemas": {
+        "externalRef": {
+          "description": "external ref",
+          "type": "object",
+          "$$ref": "http://localhost:8123/ex3.json#/$defs/externalSchema"
+        }
+      }
+    }
+  }
+]
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex1.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex1.json
new file mode 100644
index 0000000000..f46bebc5f4
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex1.json
@@ -0,0 +1,5 @@
+{
+  "indirection": {
+    "$ref": "./ex2.json#/indirection"
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex2.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex2.json
new file mode 100644
index 0000000000..ceeb4f9251
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex2.json
@@ -0,0 +1,5 @@
+{
+  "indirection": {
+    "$ref": "./ex3.json#/$defs/externalSchema"
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex3.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex3.json
new file mode 100644
index 0000000000..e0e2ec2e5f
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/ex3.json
@@ -0,0 +1,8 @@
+{
+  "$defs": {
+    "externalSchema": {
+      "description": "this is path item stored in external file",
+      "type": "object"
+    }
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/root.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/root.json
new file mode 100644
index 0000000000..fe6be223aa
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-external/root.json
@@ -0,0 +1,11 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "schemas": {
+       "externalRef": {
+        "$ref": "./ex1.json#/indirection",
+        "description": "external ref"
+      }
+    }
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-internal/dereferenced.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-internal/dereferenced.json
new file mode 100644
index 0000000000..fdeb76de23
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-internal/dereferenced.json
@@ -0,0 +1,19 @@
+[
+  {
+    "openapi": "3.1.0",
+    "components": {
+      "schemas": {
+        "schema1": {
+          "type": "object",
+          "$$ref": "http://localhost:8123/root.json#/components/schemas/schema3"
+        },
+        "schema2": {
+          "$ref": "#/components/schemas/schema3"
+        },
+        "schema3": {
+          "type": "object"
+        }
+      }
+    }
+  }
+]
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-internal/root.json b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-internal/root.json
new file mode 100644
index 0000000000..3b107b785b
--- /dev/null
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/fixtures/meta-patches-internal/root.json
@@ -0,0 +1,16 @@
+{
+  "openapi": "3.1.0",
+  "components": {
+    "schemas": {
+      "schema1": {
+        "$ref": "#/components/schemas/schema2"
+      },
+      "schema2": {
+        "$ref": "#/components/schemas/schema3"
+      },
+      "schema3": {
+        "type": "object"
+      }
+    }
+  }
+}
diff --git a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/index.ts b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/index.ts
index ed6b84d254..ade736073e 100644
--- a/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/index.ts
+++ b/packages/apidom-reference/test/dereference/strategies/openapi-3-1-swagger-client/schema-object/index.ts
@@ -187,6 +187,58 @@ describe('dereference', function () {
           });
         });
 
+        context('given Schema Object pointing internally', function () {
+          context('and allowMetaPatches=true', function () {
+            specify('should dereference', async function () {
+              let httpServer: any;
+
+              try {
+                const fixturePath = path.join(rootFixturePath, 'meta-patches-internal');
+                httpServer = createHTTPServer({ port: 8123, cwd: fixturePath });
+                const actual = await dereference('http://localhost:8123/root.json', {
+                  parse: { mediaType: mediaTypes.latest('json') },
+                  dereference: {
+                    strategies: [
+                      OpenApi3_1SwaggerClientDereferenceStrategy({ allowMetaPatches: true }),
+                    ],
+                  },
+                });
+                const expected = loadJsonFile(path.join(fixturePath, 'dereferenced.json'));
+
+                assert.deepEqual(toValue(actual), expected);
+              } finally {
+                httpServer?.terminate();
+              }
+            });
+          });
+        });
+
+        context('given Schema Object pointing externally', function () {
+          context('and allowMetaPatches=true', function () {
+            specify('should dereference', async function () {
+              let httpServer: any;
+
+              try {
+                const fixturePath = path.join(rootFixturePath, 'meta-patches-external');
+                httpServer = createHTTPServer({ port: 8123, cwd: fixturePath });
+                const actual = await dereference('http://localhost:8123/root.json', {
+                  parse: { mediaType: mediaTypes.latest('json') },
+                  dereference: {
+                    strategies: [
+                      OpenApi3_1SwaggerClientDereferenceStrategy({ allowMetaPatches: true }),
+                    ],
+                  },
+                });
+                const expected = loadJsonFile(path.join(fixturePath, 'dereferenced.json'));
+
+                assert.deepEqual(toValue(actual), expected);
+              } finally {
+                httpServer?.terminate();
+              }
+            });
+          });
+        });
+
         context('given Schema Objects with internal and external cycles', function () {
           const fixturePath = path.join(rootFixturePath, 'cycle-internal-external');