fix(ref): pass original ref

Author: jonluca

docs/plugins/file-info-object.md

@@ -7,5 +7,7 @@ The file info object currently only consists of a few properties, but it may gro
 | Property    | Type                                                                       | Description                                                                                                                                                                             |
 | :---------- | :------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `url`       | `string`                                                                   | The full URL of the file. This could be any type of URL, including "http://", "https://", "file://", "ftp://", "mongodb://", or even a local filesystem path (when running in Node.js). |
+| `reference` | `string`                                                                   | The unresolved `$ref` value exactly as it appeared in the parent schema, without the hash. This is useful for custom resolvers that need the original relative reference.              |
+| `baseUrl`   | `string`                                                                   | The URL that `reference` was resolved against to produce `url`. This may include a JSON Pointer fragment when the reference came from a nested location.                              |
 | `extension` | `string`                                                                   | The lowercase file extension, such as ".json", ".yaml", ".txt", etc.                                                                                                                    |
 | `data`      | `string` [`Buffer`](https://nodejs.org/api/buffer.html#buffer_buffer) etc. | The raw file contents, in whatever form they were returned by the [resolver](resolvers.md) that read the file.                                                                          |

lib/parse.ts

@@ -12,14 +12,24 @@ import type $Refs from "./refs.js";
 import type { ParserOptions } from "./options.js";
 import type { FileInfo, JSONSchema } from "./types/index.js";
 
+interface ParseTarget {
+  url: string;
+  reference?: string;
+  baseUrl?: string;
+}
+
 /**
  * Reads and parses the specified file path or URL.
  */
 async function parse<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
-  path: string,
+  target: string | ParseTarget,
   $refs: $Refs<S, O>,
   options: O,
 ) {
+  let path = typeof target === "string" ? target : target.url;
+  const baseUrl = typeof target === "string" ? undefined : target.baseUrl;
+  let reference = typeof target === "string" ? undefined : target.reference;
+
   // Remove the URL fragment, if any
   const hashIndex = path.indexOf("#");
   let hash = "";
@@ -28,6 +38,12 @@ async function parse<S extends object = JSONSchema, O extends ParserOptions<S> =
     // Remove the URL fragment, if any
     path = path.substring(0, hashIndex);
   }
+  if (reference) {
+    const referenceHashIndex = reference.indexOf("#");
+    if (referenceHashIndex >= 0) {
+      reference = reference.substring(0, referenceHashIndex);
+    }
+  }
 
   // Add a new $Ref for this file, even though we don't have the value yet.
   // This ensures that we don't simultaneously read & parse the same file multiple times
@@ -38,6 +54,8 @@ async function parse<S extends object = JSONSchema, O extends ParserOptions<S> =
     url: path,
     hash,
     extension: url.getExtension(path),
+    ...(reference !== undefined ? { reference } : {}),
+    ...(baseUrl !== undefined ? { baseUrl } : {}),
   } as FileInfo;
 
   // Read the file and then parse the data

lib/resolve-external.ts

@@ -129,7 +129,19 @@ async function resolve$Ref<S extends object = JSONSchema, O extends ParserOption
 
   // Parse the $referenced file/url
   try {
-    const result = await parse(resolvedPath, $refs, options);
+    const reference = ($ref as JSONSchema).$ref;
+    const parseTarget: { url: string; baseUrl: string; reference?: string } = {
+      url: resolvedPath,
+      baseUrl: resolutionBase,
+    };
+    if (typeof reference === "string") {
+      parseTarget.reference = reference;
+    }
+    const result = await parse(
+      parseTarget,
+      $refs,
+      options,
+    );
 
     // Crawl the parsed value
     // console.log('Resolving $ref pointers in %s', withoutHash);

lib/types/index.ts

@@ -139,6 +139,19 @@ export interface FileInfo {
    */
   url: string;
 
+  /**
+   * The unresolved `$ref` value exactly as it appeared in the parent schema, without the hash.
+   * This is useful for custom resolvers that need to preserve relative reference semantics instead
+   * of relying on the already-resolved `url`.
+   */
+  reference?: string;
+
+  /**
+   * The URL that `reference` was resolved against to produce `url`.
+   * This may include a JSON Pointer fragment when the reference originated from a nested location.
+   */
+  baseUrl?: string;
+
   /**
    * The hash (URL fragment) of the file URL, including the # symbol. If the URL doesn't have a hash, then this will be an empty string.
    */

test/specs/resolvers/resolvers.spec.ts

@@ -198,6 +198,101 @@ describe("options.resolve", () => {
     expect(schema).to.deep.equal(dereferencedSchema);
   });
 
+  it("should expose the original relative $ref to custom resolvers", async () => {
+    const rootPath = path.abs("test/specs/resolvers/resolvers.yaml");
+    const rootUrl = path.abs("test/specs/resolvers/resolvers.yaml");
+    const petUrl = path.abs("test/specs/resolvers/definitions/pet.yaml");
+    let canReadInfo: Pick<FileInfo, "url" | "reference" | "baseUrl" | "hash"> | undefined;
+    let readInfo: Pick<FileInfo, "url" | "reference" | "baseUrl" | "hash"> | undefined;
+
+    const schema = await $RefParser.dereference(
+      rootPath,
+      {
+        type: "object",
+        properties: {
+          pet: {
+            $ref: "definitions/pet.yaml",
+          },
+        },
+      },
+      {
+        resolve: {
+          relativeFile: {
+            order: 1,
+            canRead(file: FileInfo) {
+              canReadInfo = {
+                url: file.url,
+                reference: file.reference,
+                baseUrl: file.baseUrl,
+                hash: file.hash,
+              };
+              return file.reference === "definitions/pet.yaml";
+            },
+            async read(file: FileInfo) {
+              readInfo = {
+                url: file.url,
+                reference: file.reference,
+                baseUrl: file.baseUrl,
+                hash: file.hash,
+              };
+
+              return {
+                title: "pet",
+                type: "object",
+                properties: {
+                  name: {
+                    type: "string",
+                  },
+                  age: {
+                    type: "number",
+                  },
+                  species: {
+                    type: "string",
+                    enum: ["cat", "dog", "bird", "fish"],
+                  },
+                },
+              };
+            },
+          },
+        },
+      },
+    );
+
+    expect(canReadInfo).to.deep.equal({
+      url: petUrl,
+      reference: "definitions/pet.yaml",
+      baseUrl: `${rootUrl}#/properties/pet`,
+      hash: "",
+    });
+    expect(readInfo).to.deep.equal({
+      url: petUrl,
+      reference: "definitions/pet.yaml",
+      baseUrl: `${rootUrl}#/properties/pet`,
+      hash: "",
+    });
+    expect(schema).to.deep.equal({
+      type: "object",
+      properties: {
+        pet: {
+          title: "pet",
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+            },
+            age: {
+              type: "number",
+            },
+            species: {
+              type: "string",
+              enum: ["cat", "dog", "bird", "fish"],
+            },
+          },
+        },
+      },
+    });
+  });
+
   it("should use a custom resolver that calls a callback", async () => {
     const schema = await $RefParser.dereference(path.abs("test/specs/resolvers/resolvers.yaml"), {
       resolve: {