@apidevtools/json-schema-ref-parser 14.2.1 → 15.0.0

package/dist/lib/util/url.js

@@ -1,64 +1,11 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parse = void 0;
-exports.resolve = resolve;
-exports.cwd = cwd;
-exports.getProtocol = getProtocol;
-exports.getExtension = getExtension;
-exports.stripQuery = stripQuery;
-exports.getHash = getHash;
-exports.stripHash = stripHash;
-exports.isHttp = isHttp;
-exports.isUnsafeUrl = isUnsafeUrl;
-exports.isFileSystemPath = isFileSystemPath;
-exports.fromFileSystemPath = fromFileSystemPath;
-exports.toFileSystemPath = toFileSystemPath;
-exports.safePointerToPath = safePointerToPath;
-exports.relative = relative;
-const convert_path_to_posix_1 = __importDefault(require("./convert-path-to-posix"));
-const path_1 = __importStar(require("path"));
+import convertPathToPosix from "./convert-path-to-posix.js";
+import path, { win32 } from "path";
 const forwardSlashPattern = /\//g;
 const protocolPattern = /^(\w{2,}):\/\//i;
 const jsonPointerSlash = /~1/g;
 const jsonPointerTilde = /~0/g;
-const path_2 = require("path");
-const is_windows_1 = require("./is-windows");
+import { join } from "path";
+import { isWindows } from "./is-windows.js";
 // RegExp patterns to URL-encode special characters in local filesystem paths
 const urlEncodePatterns = [
     [/\?/g, "%3F"],
@@ -66,31 +13,36 @@ const urlEncodePatterns = [
 ];
 // RegExp patterns to URL-decode special characters for local filesystem paths
 const urlDecodePatterns = [/%23/g, "#", /%24/g, "$", /%26/g, "&", /%2C/g, ",", /%40/g, "@"];
-const parse = (u) => new URL(u);
-exports.parse = parse;
+export const parse = (u) => 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
  */
-function resolve(from, to) {
+export function resolve(from, to) {
     // we use a non-existent URL to check if its a relative URL
-    const fromUrl = new URL((0, convert_path_to_posix_1.default)(from), "https://aaa.nonexistanturl.com");
-    const resolvedUrl = new URL((0, convert_path_to_posix_1.default)(to), fromUrl);
+    const fromUrl = new URL(convertPathToPosix(from), "https://aaa.nonexistanturl.com");
+    const resolvedUrl = new URL(convertPathToPosix(to), fromUrl);
     const endSpaces = to.match(/(\s*)$/)?.[1] || "";
     if (resolvedUrl.hostname === "aaa.nonexistanturl.com") {
         // `from` is a relative URL.
         const { pathname, search, hash } = resolvedUrl;
-        return pathname + search + hash + endSpaces;
+        return pathname + search + decodeURIComponent(hash) + endSpaces;
+    }
+    const resolved = resolvedUrl.toString() + endSpaces;
+    // if there is a #, we want to split on the first one only, and decode the part after
+    if (resolved.includes("#")) {
+        const [base, hash] = resolved.split("#", 2);
+        return base + "#" + decodeURIComponent(hash || "");
     }
-    return resolvedUrl.toString() + endSpaces;
+    return resolved;
 }
 /**
  * Returns the current working directory (in Node) or the current page URL (in browsers).
  *
  * @returns
  */
-function cwd() {
+export function cwd() {
     if (typeof window !== "undefined" && window.location && window.location.href) {
         const href = window.location.href;
         if (!href || !href.startsWith("http")) {
@@ -123,7 +75,7 @@ function cwd() {
  * @param path
  * @returns
  */
-function getProtocol(path) {
+export function getProtocol(path) {
     const match = protocolPattern.exec(path || "");
     if (match) {
         return match[1].toLowerCase();
@@ -137,7 +89,7 @@ function getProtocol(path) {
  * @param path
  * @returns
  */
-function getExtension(path) {
+export function getExtension(path) {
     const lastDot = path.lastIndexOf(".");
     if (lastDot >= 0) {
         return stripQuery(path.substring(lastDot).toLowerCase());
@@ -150,7 +102,7 @@ function getExtension(path) {
  * @param path
  * @returns
  */
-function stripQuery(path) {
+export function stripQuery(path) {
     const queryIndex = path.indexOf("?");
     if (queryIndex >= 0) {
         path = path.substring(0, queryIndex);
@@ -164,7 +116,7 @@ function stripQuery(path) {
  * @param path
  * @returns
  */
-function getHash(path) {
+export function getHash(path) {
     if (!path) {
         return "#";
     }
@@ -180,7 +132,7 @@ function getHash(path) {
  * @param path
  * @returns
  */
-function stripHash(path) {
+export function stripHash(path) {
     if (!path) {
         return "";
     }
@@ -196,7 +148,7 @@ function stripHash(path) {
  * @param path
  * @returns
  */
-function isHttp(path) {
+export function isHttp(path) {
     const protocol = getProtocol(path);
     if (protocol === "http" || protocol === "https") {
         return true;
@@ -216,7 +168,7 @@ function isHttp(path) {
  * @param path - The URL or path to check
  * @returns true if the URL is unsafe/internal, false otherwise
  */
-function isUnsafeUrl(path) {
+export function isUnsafeUrl(path) {
     if (!path || typeof path !== "string") {
         return true;
     }
@@ -363,7 +315,7 @@ function isInternalPort(port) {
  * @param path
  * @returns
  */
-function isFileSystemPath(path) {
+export function isFileSystemPath(path) {
     // @ts-ignore
     if (typeof window !== "undefined" || (typeof process !== "undefined" && process.browser)) {
         // We're running in a browser, so assume that all paths are URLs.
@@ -389,24 +341,24 @@ function isFileSystemPath(path) {
  * @param path
  * @returns
  */
-function fromFileSystemPath(path) {
+export function fromFileSystemPath(path) {
     // Step 1: On Windows, replace backslashes with forward slashes,
     // rather than encoding them as "%5C"
-    if ((0, is_windows_1.isWindows)()) {
+    if (isWindows()) {
         const projectDir = cwd();
         const upperPath = path.toUpperCase();
-        const projectDirPosixPath = (0, convert_path_to_posix_1.default)(projectDir);
+        const projectDirPosixPath = convertPathToPosix(projectDir);
         const posixUpper = projectDirPosixPath.toUpperCase();
         const hasProjectDir = upperPath.includes(posixUpper);
         const hasProjectUri = upperPath.includes(posixUpper);
-        const isAbsolutePath = path_1.win32?.isAbsolute(path) ||
+        const isAbsolutePath = win32?.isAbsolute(path) ||
             path.startsWith("http://") ||
             path.startsWith("https://") ||
             path.startsWith("file://");
         if (!(hasProjectDir || hasProjectUri || isAbsolutePath) && !projectDir.startsWith("http")) {
-            path = (0, path_2.join)(projectDir, path);
+            path = join(projectDir, path);
         }
-        path = (0, convert_path_to_posix_1.default)(path);
+        path = convertPathToPosix(path);
     }
     // Step 2: `encodeURI` will take care of MOST characters
     path = encodeURI(path);
@@ -421,7 +373,7 @@ function fromFileSystemPath(path) {
 /**
  * Converts a URL to a local filesystem path.
  */
-function toFileSystemPath(path, keepFileProtocol) {
+export function toFileSystemPath(path, keepFileProtocol) {
     // Step 1: `decodeURI` will decode characters such as Cyrillic characters, spaces, etc.
     path = decodeURI(path);
     // Step 2: Manually decode characters that are not decoded by `decodeURI`.
@@ -437,7 +389,7 @@ function toFileSystemPath(path, keepFileProtocol) {
         // Strip-off the protocol, and the initial "/", if there is one
         path = path.replace(/^file:\/\//, "").replace(/^\//, "");
         // insert a colon (":") after the drive letter on Windows
-        if ((0, is_windows_1.isWindows)() && path[1] === "/") {
+        if (isWindows() && path[1] === "/") {
             path = `${path[0]}:${path.substring(1)}`;
         }
         if (keepFileProtocol) {
@@ -449,11 +401,11 @@ function toFileSystemPath(path, keepFileProtocol) {
             // On Windows, it will start with something like "C:/".
             // On Posix, it will start with "/"
             isFileUrl = false;
-            path = (0, is_windows_1.isWindows)() ? path : "/" + path;
+            path = isWindows() ? path : "/" + path;
         }
     }
     // Step 4: Normalize Windows paths (unless it's a "file://" URL)
-    if ((0, is_windows_1.isWindows)() && !isFileUrl) {
+    if (isWindows() && !isFileUrl) {
         // Replace forward slashes with backslashes
         path = path.replace(forwardSlashPattern, "\\");
         // Capitalize the drive letter
@@ -469,7 +421,7 @@ function toFileSystemPath(path, keepFileProtocol) {
  * @param pointer
  * @returns
  */
-function safePointerToPath(pointer) {
+export function safePointerToPath(pointer) {
     if (pointer.length <= 1 || pointer[0] !== "#" || pointer[1] !== "/") {
         return [];
     }
@@ -477,15 +429,15 @@ function safePointerToPath(pointer) {
         .slice(2)
         .split("/")
         .map((value) => {
-        return decodeURIComponent(value).replace(jsonPointerSlash, "/").replace(jsonPointerTilde, "~");
+        return value.replace(jsonPointerSlash, "/").replace(jsonPointerTilde, "~");
     });
 }
-function relative(from, to) {
+export function relative(from, to) {
     if (!isFileSystemPath(from) || !isFileSystemPath(to)) {
         return resolve(from, to);
     }
-    const fromDir = path_1.default.dirname(stripHash(from));
+    const fromDir = path.dirname(stripHash(from));
     const toPath = stripHash(to);
-    const result = path_1.default.relative(fromDir, toPath);
+    const result = path.relative(fromDir, toPath);
     return result + getHash(to);
 }

package/lib/bundle.ts

@@ -2,10 +2,10 @@ import $Ref from "./ref.js";
 import Pointer from "./pointer.js";
 import * as url from "./util/url.js";
 import type $Refs from "./refs.js";
-import type $RefParser from "./index";
-import type { ParserOptions } from "./index";
-import type { JSONSchema } from "./index";
-import type { BundleOptions } from "./options";
+import type $RefParser from "./index.js";
+import type { ParserOptions } from "./index.js";
+import type { JSONSchema } from "./index.js";
+import type { BundleOptions } from "./options.js";
 
 export interface InventoryEntry {
   $ref: any;
@@ -40,7 +40,7 @@ function bundle<S extends object = JSONSchema, O extends ParserOptions<S> = Pars
   crawl<S, O>(parser, "schema", parser.$refs._root$Ref.path + "#", "#", 0, inventory, parser.$refs, options);
 
   // Remap all $ref pointers
-  remap(inventory);
+  remap<S, O>(inventory, options);
 }
 
 /**
@@ -203,7 +203,10 @@ function inventory$Ref<S extends object = JSONSchema, O extends ParserOptions<S>
  *
  * @param inventory
  */
-function remap(inventory: InventoryEntry[]) {
+function remap<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
+  inventory: InventoryEntry[],
+  options: O,
+) {
   // Group & sort all the $ref pointers, so they're in the order that we need to dereference/remap them
   inventory.sort((a: InventoryEntry, b: InventoryEntry) => {
     if (a.file !== b.file) {
@@ -254,10 +257,10 @@ function remap(inventory: InventoryEntry[]) {
       // This $ref already resolves to the main JSON Schema file
       entry.$ref.$ref = entry.hash;
     } else if (entry.file === file && entry.hash === hash) {
-      // This $ref points to the same value as the prevous $ref, so remap it to the same path
+      // This $ref points to the same value as the previous $ref, so remap it to the same path
       entry.$ref.$ref = pathFromRoot;
     } else if (entry.file === file && entry.hash.indexOf(hash + "/") === 0) {
-      // This $ref points to a sub-value of the prevous $ref, so remap it beneath that path
+      // This $ref points to a sub-value of the previous $ref, so remap it beneath that path
       entry.$ref.$ref = Pointer.join(pathFromRoot, Pointer.parse(entry.hash.replace(hash, "#")));
     } else {
       // We've moved to a new file or new hash
@@ -267,7 +270,7 @@ function remap(inventory: InventoryEntry[]) {
 
       // This is the first $ref to point to this value, so dereference the value.
       // Any other $refs that point to the same value will point to this $ref instead
-      entry.$ref = entry.parent[entry.key] = $Ref.dereference(entry.$ref, entry.value);
+      entry.$ref = entry.parent[entry.key] = $Ref.dereference(entry.$ref, entry.value, options);
 
       if (entry.circular) {
         // This $ref points to itself

package/lib/dereference.ts

@@ -3,9 +3,8 @@ import Pointer from "./pointer.js";
 import * as url from "./util/url.js";
 import type $Refs from "./refs.js";
 import type { DereferenceOptions, ParserOptions } from "./options.js";
-import type { JSONSchema } from "./types";
-import type $RefParser from "./index";
-import { TimeoutError } from "./util/errors";
+import { type $RefParser, type JSONSchema } from "./index.js";
+import { TimeoutError } from "./util/errors.js";
 
 export default dereference;
 
@@ -278,7 +277,7 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
   }
 
   // Dereference the JSON reference
-  let dereferencedValue = $Ref.dereference($ref, pointer.value);
+  let dereferencedValue = $Ref.dereference($ref, pointer.value, options);
 
   // Crawl the dereferenced value (unless it's circular)
   if (!circular) {

package/lib/normalize-args.ts

@@ -1,6 +1,6 @@
 import type { Options, ParserOptions } from "./options.js";
 import { getNewOptions } from "./options.js";
-import type { JSONSchema, SchemaCallback } from "./types";
+import type { JSONSchema, SchemaCallback } from "./index.js";
 
 // I really dislike this function and the way it's written. It's not clear what it's doing, and it's way too flexible
 // In the future, I'd like to deprecate the api and accept only named parameters in index.ts

package/lib/options.ts

@@ -82,6 +82,13 @@ export interface DereferenceOptions {
    * Default: `relative`
    */
   externalReferenceResolution?: "relative" | "root";
+
+  /**
+   * Whether duplicate keys should be merged when dereferencing objects.
+   *
+   * Default: `true`
+   */
+  mergeKeys?: boolean;
 }
 
 /**
@@ -229,6 +236,7 @@ export const getJsonSchemaRefParserDefaultOptions = () => {
        */
       excludedPathMatcher: () => false,
       referenceResolution: "relative",
+      mergeKeys: true,
     },
 
     mutateInputSchema: true,

package/lib/pointer.ts

@@ -3,7 +3,8 @@ import type { ParserOptions } from "./options.js";
 import $Ref from "./ref.js";
 import * as url from "./util/url.js";
 import { JSONParserError, InvalidPointerError, MissingPointerError, isHandledError } from "./util/errors.js";
-import type { JSONSchema } from "./types";
+import type { JSONSchema } from "./index.js";
+import type { JSONSchema4Type, JSONSchema6Type, JSONSchema7Type } from "json-schema";
 
 export const nullSymbol = Symbol("null");
 
@@ -12,14 +13,6 @@ const tildes = /~/g;
 const escapedSlash = /~1/g;
 const escapedTilde = /~0/g;
 
-const safeDecodeURIComponent = (encodedURIComponent: string): string => {
-  try {
-    return decodeURIComponent(encodedURIComponent);
-  } catch {
-    return encodedURIComponent;
-  }
-};
-
 /**
  * This class represents a single JSON pointer and its resolved value.
  *
@@ -90,7 +83,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
    */
   resolve(obj: S, options?: O, pathFromRoot?: string) {
     const tokens = Pointer.parse(this.path, this.originalPath);
-    const found: any = [];
+    const found: string[] = [];
 
     // Crawl the object, one token at a time
     this.value = unwrapOrThrow(obj);
@@ -123,7 +116,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
         // actually instead pointing to an existing `null` value then we should use that
         // `null` value.
         if (token in this.value && this.value[token] === null) {
-          // We use a `null` symbol for internal tracking to differntiate between a general `null`
+          // We use a `null` symbol for internal tracking to differentiate between a general `null`
           // value and our expected `null` value.
           this.value = nullSymbol;
           continue;
@@ -163,7 +156,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
    * @returns
    * Returns the modified object, or an entirely new object if the entire object is overwritten.
    */
-  set(obj: S, value: any, options?: O) {
+  set(obj: S, value: JSONSchema4Type | JSONSchema6Type | JSONSchema7Type, options?: O) {
     const tokens = Pointer.parse(this.path);
     let token;
 
@@ -190,7 +183,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
     }
 
     // Set the value of the final token
-    resolveIf$Ref(this, options);
+    resolveIf$Ref<S, O>(this, options);
     token = tokens[tokens.length - 1];
     setValue(this, token, value);
 
@@ -225,7 +218,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
 
     // Decode each part, according to RFC 6901
     for (let i = 0; i < split.length; i++) {
-      split[i] = safeDecodeURIComponent(split[i].replace(escapedSlash, "/").replace(escapedTilde, "~"));
+      split[i] = split[i].replace(escapedSlash, "/").replace(escapedTilde, "~");
     }
 
     if (split[0] !== "") {
@@ -253,7 +246,9 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
     for (let i = 0; i < tokens.length; i++) {
       const token = tokens[i];
       // Encode the token, according to RFC 6901
-      base += "/" + encodeURIComponent(token.replace(tildes, "~0").replace(slashes, "~1"));
+      // RFC 6901 only requires encoding ~ as ~0 and / as ~1
+      // We do NOT use encodeURIComponent as it encodes characters like $ which should remain literal
+      base += "/" + token.replace(tildes, "~0").replace(slashes, "~1");
     }
 
     return base;
@@ -271,7 +266,11 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
  * @param [pathFromRoot] - the path of place that initiated resolving
  * @returns - Returns `true` if the resolution path changed
  */
-function resolveIf$Ref(pointer: any, options: any, pathFromRoot?: any) {
+function resolveIf$Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
+  pointer: Pointer,
+  options: O | undefined,
+  pathFromRoot?: string,
+) {
   // Is the value a JSON reference? (and allowed?)
 
   if ($Ref.isAllowed$Ref(pointer.value, options)) {
@@ -291,7 +290,7 @@ function resolveIf$Ref(pointer: any, options: any, pathFromRoot?: any) {
       if ($Ref.isExtended$Ref(pointer.value)) {
         // This JSON reference "extends" the resolved value, rather than simply pointing to it.
         // So the resolved path does NOT change.  Just the value does.
-        pointer.value = $Ref.dereference(pointer.value, resolved.value);
+        pointer.value = $Ref.dereference(pointer.value, resolved.value, options);
         return false;
       } else {
         // Resolve the reference
@@ -318,7 +317,7 @@ export default Pointer;
  * @param value - The value to assign
  * @returns - Returns the assigned value
  */
-function setValue(pointer: any, token: any, value: any) {
+function setValue(pointer: Pointer, token: string, value: JSONSchema4Type | JSONSchema6Type | JSONSchema7Type) {
   if (pointer.value && typeof pointer.value === "object") {
     if (token === "-" && Array.isArray(pointer.value)) {
       pointer.value.push(value);
@@ -333,7 +332,7 @@ function setValue(pointer: any, token: any, value: any) {
   return value;
 }
 
-function unwrapOrThrow(value: any) {
+function unwrapOrThrow(value: unknown) {
   if (isHandledError(value)) {
     throw value;
   }
@@ -341,6 +340,6 @@ function unwrapOrThrow(value: any) {
   return value;
 }
 
-function isRootPath(pathFromRoot: any): boolean {
+function isRootPath(pathFromRoot: string | unknown): boolean {
   return typeof pathFromRoot == "string" && Pointer.parse(pathFromRoot).length == 0;
 }

package/lib/ref.ts

@@ -4,7 +4,8 @@ import { InvalidPointerError, isHandledError, normalizeError } from "./util/erro
 import { safePointerToPath, stripHash, getHash } from "./util/url.js";
 import type $Refs from "./refs.js";
 import type { ParserOptions } from "./options.js";
-import type { JSONSchema } from "./types";
+import type { JSONSchema } from "./index.js";
+import type { JSONSchema4Type, JSONSchema6Type, JSONSchema7Type } from "json-schema";
 
 export type $RefError = JSONParserError | ResolverError | ParserError | MissingPointerError;
 
@@ -150,7 +151,7 @@ class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOpt
    * @param path - The full path of the property to set, optionally with a JSON pointer in the hash
    * @param value - The value to assign
    */
-  set(path: string, value: any) {
+  set(path: string, value: JSONSchema4Type | JSONSchema6Type | JSONSchema7Type) {
     const pointer = new Pointer(this, path);
     this.value = pointer.set(this.value, value);
     if (this.value === nullSymbol) {
@@ -273,14 +274,16 @@ class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOpt
    *
    * @param $ref - The JSON reference object (the one with the "$ref" property)
    * @param resolvedValue - The resolved value, which can be any type
+   * @param options - The options
    * @returns - Returns the dereferenced value
    */
   static dereference<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
     $ref: $Ref<S, O>,
     resolvedValue: S,
+    options?: O,
   ): S {
     if (resolvedValue && typeof resolvedValue === "object" && $Ref.isExtended$Ref($ref)) {
-      const merged = {};
+      const merged = {} as Partial<S>;
       for (const key of Object.keys($ref)) {
         if (key !== "$ref") {
           // @ts-expect-error TS(7053): Element implicitly has an 'any' type because expre... Remove this comment to see the full error message
@@ -288,10 +291,24 @@ class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOpt
         }
       }
 
-      for (const key of Object.keys(resolvedValue)) {
+      const mergeKeys = options?.dereference?.mergeKeys ?? true;
+
+      for (const _key of Object.keys(resolvedValue)) {
+        const key = _key as keyof S;
         if (!(key in merged)) {
-          // @ts-expect-error TS(7053): Element implicitly has an 'any' type because expre... Remove this comment to see the full error message
           merged[key] = resolvedValue[key];
+        } else {
+          // TODO: this behavior should be configurable from options on the CLI
+          // Key is already in merged, so we should merge them if both are objects
+          if (
+            mergeKeys &&
+            typeof merged[key] === "object" &&
+            merged[key] !== null &&
+            typeof resolvedValue[key] === "object" &&
+            resolvedValue[key] !== null
+          ) {
+            merged[key] = deepMerge<(typeof merged)[keyof S]>(resolvedValue[key], merged[key]);
+          }
         }
       }
 
@@ -303,4 +320,37 @@ class $Ref<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOpt
   }
 }
 
+function deepMerge<T>(target: Partial<T>, source: Partial<T>): T {
+  //return {...target, ...source};
+
+  // If either isn't an object, just return source (overwrite)
+  if (typeof target !== "object" || target === null) {
+    return source as T;
+  }
+  if (typeof source !== "object" || source === null) {
+    return source;
+  }
+
+  // Ensure we don't mutate target directly
+  const output = Array.isArray(target) ? [...target] : { ...target };
+
+  for (const key of Object.keys(source)) {
+    // @ts-expect-error
+    if (Array.isArray(source[key])) {
+      // If it's an array, replace entirely (you can customize this to concat instead)
+      // @ts-expect-error
+      output[key] = [...source[key]];
+      // @ts-expect-error
+    } else if (typeof source[key] === "object" && source[key] !== null) {
+      // @ts-expect-error
+      output[key] = deepMerge(target[key], source[key]);
+    } else {
+      // @ts-expect-error
+      output[key] = source[key];
+    }
+  }
+
+  return output as T;
+}
+
 export default $Ref;

package/lib/refs.ts

@@ -2,8 +2,8 @@ import $Ref from "./ref.js";
 import * as url from "./util/url.js";
 import type { JSONSchema4Type, JSONSchema6Type, JSONSchema7Type } from "json-schema";
 import type { ParserOptions } from "./options.js";
-import convertPathToPosix from "./util/convert-path-to-posix";
-import type { JSONSchema } from "./types";
+import convertPathToPosix from "./util/convert-path-to-posix.js";
+import type { JSONSchema } from "./index.js";
 
 interface $RefsMap<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>> {
   [url: string]: $Ref<S, O>;

package/lib/types/index.ts

@@ -7,7 +7,7 @@ import type {
   JSONSchema7Object,
 } from "json-schema";
 import type $Refs from "../refs.js";
-import type { ParserOptions } from "../options";
+import type { ParserOptions } from "../options.js";
 
 export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
 export type JSONSchemaObject = JSONSchema4Object | JSONSchema6Object | JSONSchema7Object;

package/lib/util/errors.ts

@@ -2,7 +2,7 @@ import { getHash, stripHash, toFileSystemPath } from "./url.js";
 import type $RefParser from "../index.js";
 import type { ParserOptions } from "../index.js";
 import type { JSONSchema } from "../index.js";
-import type $Ref from "../ref";
+import type $Ref from "../ref.js";
 
 export type JSONParserErrorType =
   | "EUNKNOWN"
@@ -201,7 +201,7 @@ export class InvalidPointerError extends JSONParserError {
   }
 }
 
-export function isHandledError(err: any): err is JSONParserError {
+export function isHandledError(err: unknown): err is JSONParserError {
   return err instanceof JSONParserError || err instanceof JSONParserErrorGroup;
 }