fix: Add OpenAPI 3.1 $ref overrides

lib/dereference.js

@@ -50,6 +50,13 @@ function crawl (obj, path, pathFromRoot, parents, processedObjects, dereferenced
         dereferenced = dereference$Ref(obj, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options);
         result.circular = dereferenced.circular;
         result.value = dereferenced.value;
+        // OpenAPI 3.1 $ref overrides: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-19
+        if (obj.description) {
+          result.value.description = obj.description;
+        }
+        if (obj.summary) {
+          result.value.summary = obj.summary;
+        }
       }
       else {
         for (const key of Object.keys(obj)) {
@@ -64,6 +71,13 @@ function crawl (obj, path, pathFromRoot, parents, processedObjects, dereferenced
             // Avoid pointless mutations; breaks frozen objects to no profit
             if (obj[key] !== dereferenced.value) {
               obj[key] = dereferenced.value;
+              // OpenAPI 3.1 $ref overrides: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields-19
+              if (value.description) {
+                obj[key].description = value.description;
+              }
+              if (value.summary) {
+                obj[key].summary = value.summary;
+              }
             }
           }
           else {

test/specs/oas31/dereferenced.js

@@ -0,0 +1,26 @@
+"use strict";
+
+module.exports =
+{
+  required: [
+    "name"
+  ],
+  type: "object",
+  definitions: {
+    name: {
+      type: "string",
+      description: "Someone's name"
+    }
+  },
+  "properties": {
+    "name": {
+      "description": "Someone's name",
+      "type": "string"
+    },
+    "secretName": {
+      "description": "Someone's secret name",
+      "type": "string"
+    }
+  },
+  title: "Person"
+};

test/specs/oas31/oas31.spec.js

@@ -0,0 +1,39 @@
+"use strict";
+
+const { expect } = require("chai");
+const $RefParser = require("../../../lib");
+const helper = require("../../utils/helper");
+const path = require("../../utils/path");
+const parsedSchema = require("./parsed");
+const dereferencedSchema = require("./dereferenced");
+
+describe("Schema with OpenAPI 3.1 $ref description/schema overrides", () => {
+  it("should parse successfully", async () => {
+    let parser = new $RefParser();
+    const schema = await parser.parse(path.rel("specs/oas31/oas31.yaml"));
+    expect(schema).to.equal(parser.schema);
+    expect(schema).to.deep.equal(parsedSchema);
+    expect(parser.$refs.paths()).to.deep.equal([path.abs("specs/oas31/oas31.yaml")]);
+  });
+
+  it("should resolve successfully", helper.testResolve(
+    path.rel("specs/oas31/oas31.yaml"),
+    path.abs("specs/oas31/oas31.yaml"), parsedSchema
+  ));
+
+  it("should dereference successfully", async () => {
+    let parser = new $RefParser();
+    const schema = await parser.dereference(path.rel("specs/oas31/oas31.yaml"));
+    expect(schema).to.equal(parser.schema);
+    expect(schema).to.deep.equal(dereferencedSchema);
+    // The "circular" flag should NOT be set
+    expect(parser.$refs.circular).to.equal(false);
+  });
+
+  it("should bundle successfully", async () => {
+    let parser = new $RefParser();
+    const schema = await parser.bundle(path.rel("specs/oas31/oas31.yaml"));
+    expect(schema).to.equal(parser.schema);
+    expect(schema).to.deep.equal(parsedSchema);
+  });
+});

test/specs/oas31/oas31.yaml

@@ -0,0 +1,14 @@
+title: Person
+type: object
+required:
+  - name
+properties:
+  name:
+    $ref: "#/definitions/name"
+  secretName:
+    $ref: "#/definitions/name"
+    description: "Someone's secret name"
+definitions:
+  name:
+    description: "Someone's name"
+    type: string

test/specs/oas31/parsed.js

@@ -0,0 +1,25 @@
+"use strict";
+
+module.exports =
+{
+  required: [
+    "name"
+  ],
+  type: "object",
+  definitions: {
+    name: {
+      type: "string",
+      description: "Someone's name"
+    }
+  },
+  "properties": {
+    "name": {
+      "$ref": "#/definitions/name"
+    },
+    "secretName": {
+      "$ref": "#/definitions/name",
+      "description": "Someone's secret name"
+    }
+  },
+  title: "Person"
+};