Advanced resolution system that discovers and resolves all $ref pointers in schemas, supporting local files, remote URLs, and custom protocols. The resolve operation parses the schema and then downloads/reads all referenced files, building a complete map of references without dereferencing them.
Resolves all JSON references ($ref pointers) in a schema and returns a $Refs object containing the reference map.
/**
* Resolves all JSON references in the given schema
* @param schema - A JSON Schema object, or the file path or URL of a JSON Schema file
* @returns Promise that resolves with a $Refs object containing all resolved references
*/
function resolve<S extends object = JSONSchema>(
schema: S | string | unknown
): Promise<$Refs<S>>;
/**
* Resolves with callback support
* @param schema - A JSON Schema object, or the file path or URL of a JSON Schema file
* @param callback - Error-first callback receiving the $Refs object
* @returns Promise that resolves to void when using callback
*/
function resolve<S extends object = JSONSchema>(
schema: S | string | unknown,
callback: $RefsCallback<S>
): Promise<void>;
/**
* Resolves with custom options
* @param schema - A JSON Schema object, or the file path or URL of a JSON Schema file
* @param options - Options that determine how references are resolved
* @returns Promise that resolves with a $Refs object
*/
function resolve<S extends object = JSONSchema>(
schema: S | string | unknown,
options: ParserOptions<S>
): Promise<$Refs<S>>;
/**
* Resolves with options and callback
* @param schema - A JSON Schema object, or the file path or URL of a JSON Schema file
* @param options - Options that determine how references are resolved
* @param callback - Error-first callback receiving the $Refs object
* @returns Promise that resolves to void when using callback
*/
function resolve<S extends object = JSONSchema>(
schema: S | string | unknown,
options: ParserOptions<S>,
callback: $RefsCallback<S>
): Promise<void>;
/**
* Resolves schema at specific path with separate schema object
* @param path - The file path or URL of the JSON schema
* @param schema - A JSON schema object to use instead of reading from path
* @param options - Options that determine how references are resolved
* @returns Promise that resolves with a $Refs object
*/
function resolve<S extends object = JSONSchema>(
path: string,
schema: S | string | unknown,
options: ParserOptions<S>
): Promise<$Refs<S>>;
/**
* Resolves with path, schema, options, and callback
* @param path - The file path or URL of the JSON schema
* @param schema - A JSON schema object to use instead of reading from path
* @param options - Options that determine how references are resolved
* @param callback - Error-first callback receiving the $Refs object
* @returns Promise that resolves to void when using callback
*/
function resolve<S extends object = JSONSchema>(
path: string,
schema: S | string | unknown,
options: ParserOptions<S>,
callback: $RefsCallback<S>
): Promise<void>;Instance method on $RefParser class for resolving references.
class $RefParser<S extends object = JSONSchema> {
schema: S | null;
$refs: $Refs<S>;
/**
* Resolves all JSON references and updates instance $refs property
* @param schema - A JSON Schema object, or the file path or URL of a JSON Schema file
* @returns Promise that resolves with the $Refs object
*/
resolve(schema: S | string | unknown): Promise<$Refs<S>>;
/**
* Resolves with callback support
* @param schema - A JSON Schema object, or the file path or URL of a JSON Schema file
* @param callback - Error-first callback receiving the $Refs object
* @returns Promise that resolves to void when using callback
*/
resolve(schema: S | string | unknown, callback: $RefsCallback<S>): Promise<void>;
/**
* Resolves with custom options
* @param schema - A JSON Schema object, or the file path or URL of a JSON Schema file
* @param options - Options that determine how references are resolved
* @returns Promise that resolves with the $Refs object
*/
resolve(schema: S | string | unknown, options: ParserOptions<S>): Promise<$Refs<S>>;
/**
* Resolves with options and callback
* @param schema - A JSON Schema object, or the file path or URL of a JSON Schema file
* @param options - Options that determine how references are resolved
* @param callback - Error-first callback receiving the $Refs object
* @returns Promise that resolves to void when using callback
*/
resolve(schema: S | string | unknown, options: ParserOptions<S>, callback: $RefsCallback<S>): Promise<void>;
/**
* Resolves schema at specific path with separate schema object
* @param path - The file path or URL of the JSON schema
* @param schema - A JSON schema object to use instead of reading from path
* @param options - Options that determine how references are resolved
* @returns Promise that resolves with the $Refs object
*/
resolve(path: string, schema: S | string | unknown, options: ParserOptions<S>): Promise<$Refs<S>>;
/**
* Resolves with path, schema, options, and callback
* @param path - The file path or URL of the JSON schema
* @param schema - A JSON schema object to use instead of reading from path
* @param options - Options that determine how references are resolved
* @param callback - Error-first callback receiving the $Refs object
* @returns Promise that resolves to void when using callback
*/
resolve(path: string, schema: S | string | unknown, options: ParserOptions<S>, callback: $RefsCallback<S>): Promise<void>;
}The $Refs object provides access to all resolved references and helper methods for working with them.
/**
* Container for resolved JSON references with helper methods
*/
class $Refs<S extends object = JSONSchema> {
/**
* True if the schema contains any circular references
*/
circular: boolean;
/**
* Returns the paths/URLs of all files in the schema
* @param types - Optional filter for specific path types ("file", "http", etc.)
* @returns Array of file paths/URLs
*/
paths(...types: (string | string[])[]): string[];
/**
* Returns a map of paths/URLs and their corresponding values
* @param types - Optional filter for specific path types ("file", "http", etc.)
* @returns Object mapping paths to their resolved values
*/
values(...types: (string | string[])[]): S;
/**
* Checks if a given path exists in the schema
* @param path - The JSON Reference path, optionally with a JSON Pointer in the hash
* @param options - Optional resolution options
* @returns True if the path exists, false otherwise
*/
exists(path: string, options?: any): boolean;
/**
* Resolves the given JSON reference and returns the resolved value
* @param path - The JSON Reference path, with a JSON pointer in the hash
* @param options - Optional resolution options
* @returns The resolved value at the given path
*/
get(path: string, options?: any): any;
/**
* Sets the value at the given path in the schema
* @param path - The JSON Reference path, optionally with a JSON Pointer in the hash
* @param value - The value to assign (can be anything)
*/
set(path: string, value: any): void;
/**
* Returns a POJO (plain old JavaScript object) for serialization as JSON
* Equivalent to calling values() with no parameters
* @returns Object suitable for JSON serialization
*/
toJSON(): S;
}Usage Examples:
import $RefParser from "@apidevtools/json-schema-ref-parser";
// Basic resolution
const $refs = await $RefParser.resolve("./schemas/api.json");
// Check for circular references
if ($refs.circular) {
console.log("Schema contains circular references");
}
// Get all file paths
const paths = $refs.paths();
console.log("Referenced files:", paths);
// Get all HTTP URLs only
const httpPaths = $refs.paths("http");
console.log("Remote references:", httpPaths);
// Get all resolved values
const values = $refs.values();
console.log("All resolved schemas:", values);
// Check if specific reference exists
if ($refs.exists("#/definitions/User")) {
const userSchema = $refs.get("#/definitions/User");
console.log("User schema:", userSchema);
}
// Instance-based resolution
const parser = new $RefParser();
await parser.resolve("./schemas/api.json");
console.log("Paths:", parser.$refs.paths());
console.log("Has circular refs:", parser.$refs.circular);interface ResolveOptions {
/**
* Whether external $ref pointers will be resolved
*/
external?: boolean;
/**
* File resolver configuration
*/
file?: Partial<ResolverOptions> | boolean;
/**
* HTTP resolver configuration
*/
http?: HTTPResolverOptions | boolean;
/**
* Custom resolvers
*/
[key: string]: Partial<ResolverOptions> | HTTPResolverOptions | boolean | undefined;
}
interface HTTPResolverOptions {
/**
* HTTP headers to send when downloading files
*/
headers?: RequestInit["headers"] | null;
/**
* Request timeout in milliseconds (default: 5000)
*/
timeout?: number;
/**
* Maximum number of redirects to follow (default: 5)
*/
redirects?: number;
/**
* Send credentials for CORS requests
*/
withCredentials?: boolean;
/**
* Allow unsafe URLs like localhost (default: true)
*/
safeUrlResolver?: boolean;
}You can add custom resolvers for additional protocols:
interface ResolverOptions<S extends object = JSONSchema> {
name?: string;
order?: number;
canRead: boolean | RegExp | string | string[] | ((file: FileInfo) => boolean);
read:
| string
| object
| ((
file: FileInfo,
callback?: (error: Error | null, data: string | null) => any,
) => string | Buffer | S | Promise<string | Buffer | S>);
}Resolution can encounter various errors:
try {
const $refs = await $RefParser.resolve("./schemas/api.json");
} catch (error) {
if (error instanceof ResolverError) {
console.log("Resolution failed:", error.message);
}
}