@apidevtools/json-schema-ref-parser 11.0.0 → 11.1.1

package/README.md

@@ -1,7 +1,5 @@
 # JSON Schema $Ref Parser
 
-_**This package needs [a new maintainer](https://github.com/APIDevTools/json-schema-ref-parser/issues/285) or at least some contributors. For more information [please read this article](https://phil.tech/2022/bundling-openapi-with-javascript/). As of v10.0.0 I am no longer spending any time working on this tool, so I can focus on scaling up my [reforestation charity](https://protect.earth/) instead of burning myself out trying to maintain a whole load of OSS projects I don't use in my vanishingly small spare time. Get in touch if you'd like to take over.** - [Phil Sturgeon](https://github.com/philsturgeon)_
-
 #### Parse, Resolve, and Dereference JSON Schema $ref pointers
 
 [![Build Status](https://github.com/APIDevTools/json-schema-ref-parser/workflows/CI-CD/badge.svg?branch=master)](https://github.com/APIDevTools/json-schema-ref-parser/actions)

package/dist/lib/dereference.js

@@ -130,7 +130,9 @@ function crawl(obj, path, pathFromRoot, parents, processedObjects, dereferencedC
  */
 function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options) {
     // console.log('Dereferencing $ref pointer "%s" at %s', $ref.$ref, path);
-    const $refPath = url.resolve(path, $ref.$ref);
+    const isExternalRef = ref_js_1.default.isExternal$Ref($ref);
+    const shouldResolveOnCwd = isExternalRef && options?.dereference.externalReferenceResolution === "root";
+    const $refPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref);
     const cache = dereferencedCache.get($refPath);
     if (cache) {
         const refKeys = Object.keys($ref);

package/dist/lib/index.js

@@ -88,6 +88,13 @@ class $RefParser {
             args.path = url.fromFileSystemPath(args.path);
             pathType = "file";
         }
+        else if (!args.path && args.schema && args.schema.$id) {
+            // when schema id has defined an URL should use that hostname to request the references,
+            // instead of using the current page URL
+            const params = url.parse(args.schema.$id);
+            const port = params.protocol === "https:" ? 443 : 80;
+            args.path = `${params.protocol}//${params.hostname}:${port}`;
+        }
         // Resolve the absolute path of the schema
         args.path = url.resolve(url.cwd(), args.path);
         if (args.schema && typeof args.schema === "object") {

package/dist/lib/options.d.ts

@@ -69,6 +69,12 @@ interface $RefParserOptions {
          * @argument {JSONSchemaObject} object The JSON-Schema that the `$ref` resolved to.
          */
         onDereference?(path: string, value: JSONSchemaObject): void;
+        /**
+         * Whether a reference should resolve relative to its directory/path, or from the cwd
+         *
+         * Default: `relative`
+         */
+        externalReferenceResolution?: "relative" | "root";
     };
 }
 export declare const getNewOptions: (options: DeepPartial<$RefParserOptions>) => $RefParserOptions;

package/dist/lib/options.js

@@ -69,6 +69,7 @@ const getDefaults = () => {
              * @type {function}
              */
             excludedPathMatcher: () => false,
+            referenceResolution: "relative",
         },
     };
     return (0, lodash_clonedeep_1.default)(defaults);

package/dist/lib/pointer.js

@@ -68,11 +68,11 @@ class Pointer {
         // Crawl the object, one token at a time
         this.value = unwrapOrThrow(obj);
         for (let i = 0; i < tokens.length; i++) {
-            if (resolveIf$Ref(this, options)) {
+            if (resolveIf$Ref(this, options, pathFromRoot)) {
                 // The $ref path has changed, so append the remaining tokens to the path
                 this.path = Pointer.join(this.path, tokens.slice(i));
             }
-            if (typeof this.value === "object" && this.value !== null && "$ref" in this.value) {
+            if (typeof this.value === "object" && this.value !== null && !isRootPath(pathFromRoot) && "$ref" in this.value) {
                 return this;
             }
             const token = tokens[i];
@@ -86,7 +86,7 @@ class Pointer {
         }
         // Resolve the final value
         if (!this.value || (this.value.$ref && url.resolve(this.path, this.value.$ref) !== pathFromRoot)) {
-            resolveIf$Ref(this, options);
+            resolveIf$Ref(this, options, pathFromRoot);
         }
         return this;
     }
@@ -190,13 +190,14 @@ class Pointer {
  *
  * @param pointer
  * @param options
+ * @param [pathFromRoot] - the path of place that initiated resolving
  * @returns - Returns `true` if the resolution path changed
  */
-function resolveIf$Ref(pointer, options) {
+function resolveIf$Ref(pointer, options, pathFromRoot) {
     // Is the value a JSON reference? (and allowed?)
     if (ref_js_1.default.isAllowed$Ref(pointer.value, options)) {
         const $refPath = url.resolve(pointer.path, pointer.value.$ref);
-        if ($refPath === pointer.path) {
+        if ($refPath === pointer.path && !isRootPath(pathFromRoot)) {
             // The value is a reference to itself, so there's nothing to do.
             pointer.circular = true;
         }
@@ -254,3 +255,6 @@ function unwrapOrThrow(value) {
     }
     return value;
 }
+function isRootPath(pathFromRoot) {
+    return typeof pathFromRoot == "string" && Pointer.parse(pathFromRoot).length == 0;
+}

package/dist/lib/resolve-external.js

@@ -102,8 +102,8 @@ function crawl(obj, path, $refs, options, seen, external) {
  * including nested references that are contained in externally-referenced files.
  */
 async function resolve$Ref($ref, path, $refs, options) {
-    // console.log('Resolving $ref pointer "%s" at %s', $ref.$ref, path);
-    const resolvedPath = url.resolve(path, $ref.$ref);
+    const shouldResolveOnCwd = options.dereference.externalReferenceResolution === "root";
+    const resolvedPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref);
     const withoutHash = url.stripHash(resolvedPath);
     // $ref.$ref = url.relative($refs._root$Ref.path, resolvedPath);
     // Do we already have this $ref?

package/dist/lib/resolvers/http.js

@@ -97,7 +97,7 @@ async function download(u, httpOptions, _redirects) {
                 throw (0, ono_1.ono)({ status: res.status }, `HTTP ${res.status} redirect with no location header`);
             }
             else {
-                const redirectTo = url.resolve(u, res.headers.location);
+                const redirectTo = url.resolve(u.href, res.headers.location);
                 return download(redirectTo, httpOptions, redirects);
             }
         }

package/dist/lib/util/convert-path-to-posix.js

@@ -9,6 +9,6 @@ function convertPathToPosix(filePath) {
     if (isExtendedLengthPath) {
         return filePath;
     }
-    return filePath.split(path_1.default.win32.sep).join(path_1.default.posix.sep);
+    return filePath.split(path_1.default?.win32?.sep).join(path_1.default.posix.sep);
 }
 exports.default = convertPathToPosix;

package/dist/lib/util/url.d.ts

@@ -1,10 +1,10 @@
-export declare const parse: (u: any) => URL;
+export declare const parse: (u: string | URL) => URL;
 /**
  * Returns resolved target URL relative to a base URL in a manner similar to that of a Web browser resolving an anchor tag HREF.
  *
  * @returns
  */
-export declare function resolve(from: any, to: any): string;
+export declare function resolve(from: string, to: string): string;
 /**
  * Returns the current working directory (in Node) or the current page URL (in browsers).
  *
@@ -91,4 +91,4 @@ export declare function toFileSystemPath(path: string | undefined, keepFileProto
  * @returns
  */
 export declare function safePointerToPath(pointer: any): any;
-export declare function relative(from: string | undefined, to: string | undefined): string;
+export declare function relative(from: string, to: string): string;

package/dist/lib/util/url.js

@@ -48,7 +48,8 @@ exports.parse = parse;
  * @returns
  */
 function resolve(from, to) {
-    const resolvedUrl = new URL(to, new URL(from, "resolve://"));
+    const fromUrl = new URL((0, convert_path_to_posix_1.default)(from), "resolve://");
+    const resolvedUrl = new URL((0, convert_path_to_posix_1.default)(to), fromUrl);
     if (resolvedUrl.protocol === "resolve:") {
         // `from` is a relative URL.
         const { pathname, search, hash } = resolvedUrl;

package/lib/dereference.ts

@@ -169,7 +169,9 @@ function dereference$Ref(
 ) {
   // console.log('Dereferencing $ref pointer "%s" at %s', $ref.$ref, path);
 
-  const $refPath = url.resolve(path, $ref.$ref);
+  const isExternalRef = $Ref.isExternal$Ref($ref);
+  const shouldResolveOnCwd = isExternalRef && options?.dereference.externalReferenceResolution === "root";
+  const $refPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref);
 
   const cache = dereferencedCache.get($refPath);
   if (cache) {

package/lib/index.ts

@@ -100,6 +100,13 @@ export class $RefParser {
     if (url.isFileSystemPath(args.path)) {
       args.path = url.fromFileSystemPath(args.path);
       pathType = "file";
+    } else if (!args.path && args.schema && args.schema.$id) {
+      // when schema id has defined an URL should use that hostname to request the references,
+      // instead of using the current page URL
+      const params = url.parse(args.schema.$id);
+      const port = params.protocol === "https:" ? 443 : 80;
+
+      args.path = `${params.protocol}//${params.hostname}:${port}`;
     }
 
     // Resolve the absolute path of the schema

package/lib/options.ts

@@ -83,6 +83,13 @@ interface $RefParserOptions {
      * @argument {JSONSchemaObject} object The JSON-Schema that the `$ref` resolved to.
      */
     onDereference?(path: string, value: JSONSchemaObject): void;
+
+    /**
+     * Whether a reference should resolve relative to its directory/path, or from the cwd
+     *
+     * Default: `relative`
+     */
+    externalReferenceResolution?: "relative" | "root";
   };
 }
 
@@ -149,8 +156,9 @@ const getDefaults = () => {
        * @type {function}
        */
       excludedPathMatcher: () => false,
+      referenceResolution: "relative",
     },
-  };
+  } as $RefParserOptions;
   return cloneDeep(defaults);
 };
 

package/lib/pointer.ts

@@ -83,12 +83,12 @@ class Pointer {
     this.value = unwrapOrThrow(obj);
 
     for (let i = 0; i < tokens.length; i++) {
-      if (resolveIf$Ref(this, options)) {
+      if (resolveIf$Ref(this, options, pathFromRoot)) {
         // The $ref path has changed, so append the remaining tokens to the path
         this.path = Pointer.join(this.path, tokens.slice(i));
       }
 
-      if (typeof this.value === "object" && this.value !== null && "$ref" in this.value) {
+      if (typeof this.value === "object" && this.value !== null && !isRootPath(pathFromRoot) && "$ref" in this.value) {
         return this;
       }
 
@@ -103,7 +103,7 @@ class Pointer {
 
     // Resolve the final value
     if (!this.value || (this.value.$ref && url.resolve(this.path, this.value.$ref) !== pathFromRoot)) {
-      resolveIf$Ref(this, options);
+      resolveIf$Ref(this, options, pathFromRoot);
     }
 
     return this;
@@ -224,15 +224,16 @@ class Pointer {
  *
  * @param pointer
  * @param options
+ * @param [pathFromRoot] - the path of place that initiated resolving
  * @returns - Returns `true` if the resolution path changed
  */
-function resolveIf$Ref(pointer: any, options: any) {
+function resolveIf$Ref(pointer: any, options: any, pathFromRoot?: any) {
   // Is the value a JSON reference? (and allowed?)
 
   if ($Ref.isAllowed$Ref(pointer.value, options)) {
     const $refPath = url.resolve(pointer.path, pointer.value.$ref);
 
-    if ($refPath === pointer.path) {
+    if ($refPath === pointer.path && !isRootPath(pathFromRoot)) {
       // The value is a reference to itself, so there's nothing to do.
       pointer.circular = true;
     } else {
@@ -294,3 +295,7 @@ function unwrapOrThrow(value: any) {
 
   return value;
 }
+
+function isRootPath(pathFromRoot: any): boolean {
+  return typeof pathFromRoot == "string" && Pointer.parse(pathFromRoot).length == 0;
+}

package/lib/refs.ts

@@ -95,7 +95,7 @@ export default class $Refs {
    * @param value The value to assign. Can be anything (object, string, number, etc.)
    */
   set(path: any, value: JSONSchema4Type | JSONSchema6Type | JSONSchema7Type) {
-    const absPath = url.resolve(this._root$Ref.path, path);
+    const absPath = url.resolve(this._root$Ref.path!, path);
     const withoutHash = url.stripHash(absPath);
     const $ref = this._$refs[withoutHash];
 
@@ -113,7 +113,7 @@ export default class $Refs {
    * @protected
    */
   _get$Ref(path: any) {
-    path = url.resolve(this._root$Ref.path, path);
+    path = url.resolve(this._root$Ref.path!, path);
     const withoutHash = url.stripHash(path);
     return this._$refs[withoutHash];
   }
@@ -145,7 +145,7 @@ export default class $Refs {
    * @protected
    */
   _resolve(path: string, pathFromRoot: string, options?: any) {
-    const absPath = url.resolve(this._root$Ref.path, path);
+    const absPath = url.resolve(this._root$Ref.path!, path);
     const withoutHash = url.stripHash(absPath);
     const $ref = this._$refs[withoutHash];
 

package/lib/resolve-external.ts

@@ -92,9 +92,8 @@ function crawl(
  * including nested references that are contained in externally-referenced files.
  */
 async function resolve$Ref($ref: JSONSchema, path: string, $refs: $Refs, options: Options) {
-  // console.log('Resolving $ref pointer "%s" at %s', $ref.$ref, path);
-
-  const resolvedPath = url.resolve(path, $ref.$ref);
+  const shouldResolveOnCwd = options.dereference.externalReferenceResolution === "root";
+  const resolvedPath = url.resolve(shouldResolveOnCwd ? url.cwd() : path, $ref.$ref!);
   const withoutHash = url.stripHash(resolvedPath);
 
   // $ref.$ref = url.relative($refs._root$Ref.path, resolvedPath);

package/lib/resolvers/http.ts

@@ -86,7 +86,7 @@ async function download(u: URL | string, httpOptions: HTTPResolverOptions, _redi
       } else if (!("location" in res.headers) || !res.headers.location) {
         throw ono({ status: res.status }, `HTTP ${res.status} redirect with no location header`);
       } else {
-        const redirectTo = url.resolve(u, res.headers.location);
+        const redirectTo = url.resolve(u.href, res.headers.location as string);
         return download(redirectTo, httpOptions, redirects);
       }
     } else {

package/lib/util/convert-path-to-posix.ts

@@ -7,5 +7,5 @@ export default function convertPathToPosix(filePath: string) {
     return filePath;
   }
 
-  return filePath.split(path.win32.sep).join(path.posix.sep);
+  return filePath.split(path?.win32?.sep).join(path.posix.sep);
 }

package/lib/util/url.ts

@@ -16,15 +16,16 @@ const urlEncodePatterns = [/\?/g, "%3F", /#/g, "%23"];
 // RegExp patterns to URL-decode special characters for local filesystem paths
 const urlDecodePatterns = [/%23/g, "#", /%24/g, "$", /%26/g, "&", /%2C/g, ",", /%40/g, "@"];
 
-export const parse = (u: any) => new URL(u);
+export const parse = (u: string | URL) => new URL(u);
 
 /**
  * Returns resolved target URL relative to a base URL in a manner similar to that of a Web browser resolving an anchor tag HREF.
  *
  * @returns
  */
-export function resolve(from: any, to: any) {
-  const resolvedUrl = new URL(to, new URL(from, "resolve://"));
+export function resolve(from: string, to: string) {
+  const fromUrl = new URL(convertPathToPosix(from), "resolve://");
+  const resolvedUrl = new URL(convertPathToPosix(to), fromUrl);
   if (resolvedUrl.protocol === "resolve:") {
     // `from` is a relative URL.
     const { pathname, search, hash } = resolvedUrl;
@@ -279,7 +280,7 @@ export function safePointerToPath(pointer: any) {
     });
 }
 
-export function relative(from: string | undefined, to: string | undefined) {
+export function relative(from: string, to: string) {
   if (!isFileSystemPath(from) || !isFileSystemPath(to)) {
     return resolve(from, to);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apidevtools/json-schema-ref-parser",
-  "version": "11.0.0",
+  "version": "11.1.1",
   "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
   "keywords": [
     "json",