or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bundling.mddereferencing.mderrors.mdindex.mdoptions.mdparsing.mdresolution.md
tile.json

index.mddocs/

JSON Schema $Ref Parser

JSON Schema $Ref Parser is a comprehensive TypeScript library that provides robust parsing, resolution, and dereferencing of JSON Schema $ref pointers. It handles complex cross-references between local files, remote URLs, and mixed formats, supporting both internal and external $ref pointers with built-in support for circular references and multiple file formats (JSON, YAML).

Package Information

  • Package Name: @apidevtools/json-schema-ref-parser
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @apidevtools/json-schema-ref-parser

Core Imports

import $RefParser from "@apidevtools/json-schema-ref-parser";
import { parse, resolve, bundle, dereference } from "@apidevtools/json-schema-ref-parser";

For CommonJS:

const $RefParser = require("@apidevtools/json-schema-ref-parser");
const { parse, resolve, bundle, dereference } = require("@apidevtools/json-schema-ref-parser");

Basic Usage

import $RefParser from "@apidevtools/json-schema-ref-parser";

// Parse a schema
const schema = await $RefParser.parse("my-schema.json");

// Resolve all $ref pointers
const $refs = await $RefParser.resolve("my-schema.json");

// Bundle into single schema with internal refs
const bundled = await $RefParser.bundle("my-schema.json");

// Fully dereference all $ref pointers
const dereferenced = await $RefParser.dereference("my-schema.json");

// Instance-based usage
const parser = new $RefParser();
await parser.parse("my-schema.json");
console.log(parser.schema);
console.log(parser.$refs.paths());

Architecture

JSON Schema $Ref Parser is built around several key components:

  • $RefParser Class: Main class providing both static and instance methods for all operations
  • Reference Resolution: Pluggable resolver system supporting file, HTTP, and custom protocols
  • Format Parsing: Multi-format parser system supporting JSON, YAML, text, and binary files
  • $Refs Management: Centralized reference tracking with helper methods for navigation
  • Error Handling: Comprehensive error system with specific error types for different failure modes
  • Options System: Extensive configuration for controlling parsing, resolution, bundling, and dereferencing behavior

Capabilities

Schema Parsing

Core functionality for parsing JSON Schema files in various formats (JSON, YAML) without resolving $ref pointers.

function parse<S extends object = JSONSchema>(
  schema: S | string | unknown
): Promise<S>;

function parse<S extends object = JSONSchema>(
  schema: S | string | unknown,
  options: ParserOptions<S>
): Promise<S>;

function parse<S extends object = JSONSchema>(
  path: string,
  schema: S | string | unknown,
  options: ParserOptions<S>
): Promise<S>;

Schema Parsing

Reference Resolution

Advanced resolution system that discovers and resolves all $ref pointers in schemas, supporting local files, remote URLs, and custom protocols.

function resolve<S extends object = JSONSchema>(
  schema: S | string | unknown
): Promise<$Refs<S>>;

function resolve<S extends object = JSONSchema>(
  schema: S | string | unknown,
  options: ParserOptions<S>
): Promise<$Refs<S>>;

interface $Refs<S extends object = JSONSchema> {
  circular: boolean;
  paths(...types: string[]): string[];
  values(...types: string[]): Record<string, S>;
  exists(path: string, options?: any): boolean;
  get(path: string, options?: any): any;
  set(path: string, value: any): void;
}

Reference Resolution

Schema Bundling

Bundles all referenced files into a single schema that contains only internal $ref pointers, eliminating external dependencies while maintaining reference structure.

function bundle<S extends object = JSONSchema>(
  schema: S | string | unknown
): Promise<S>;

function bundle<S extends object = JSONSchema>(
  schema: S | string | unknown,
  options: ParserOptions<S>
): Promise<S>;

Schema Bundling

Schema Dereferencing

Fully dereferences all $ref pointers by replacing them with their resolved values, creating a self-contained schema object without any references.

function dereference<S extends object = JSONSchema>(
  schema: S | string | unknown
): Promise<S>;

function dereference<S extends object = JSONSchema>(
  schema: S | string | unknown,
  options: ParserOptions<S>
): Promise<S>;

Schema Dereferencing

Configuration & Options

Comprehensive configuration system for customizing parsing, resolution, bundling, and dereferencing behavior.

interface ParserOptions<S extends object = JSONSchema> {
  parse?: {
    json?: Plugin | boolean;
    yaml?: Plugin | boolean;
    text?: Plugin | boolean;
    binary?: Plugin | boolean;
    [key: string]: Plugin | boolean | undefined;
  };
  resolve?: {
    external?: boolean;
    file?: Partial<ResolverOptions<S>> | boolean;
    http?: HTTPResolverOptions<S> | boolean;
    [key: string]: Partial<ResolverOptions<S>> | HTTPResolverOptions<S> | boolean | undefined;
  };
  bundle?: BundleOptions;
  dereference?: DereferenceOptions;
  continueOnError?: boolean;
  mutateInputSchema?: boolean;
  timeoutMs?: number;
}

Configuration & Options

Error Handling

Robust error handling system with specific error types for different failure scenarios and detailed error information.

class JSONParserError extends Error {
  readonly name: string;
  readonly message: string;
  source: string | undefined;
  path: Array<string | number> | null;
  readonly code: JSONParserErrorType;
  toJSON(): Error & this;
  get footprint(): string;
}

class JSONParserErrorGroup<S extends object = JSONSchema> extends Error {
  files: $RefParser<S>;
}

type JSONParserErrorType =
  | "EUNKNOWN"
  | "EPARSER"
  | "EUNMATCHEDPARSER"
  | "ETIMEOUT"
  | "ERESOLVER"
  | "EUNMATCHEDRESOLVER"
  | "EMISSINGPOINTER" 
  | "EINVALIDPOINTER";

Error Handling

Core Types

// Schema types
type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
type JSONSchemaObject = JSONSchema4Object | JSONSchema6Object | JSONSchema7Object;
type RefParserSchema = string | JSONSchema;

// Callback types
type SchemaCallback<S extends object = JSONSchema> = (
  err: Error | null,
  schema?: S | object | null
) => any;

type $RefsCallback<S extends object = JSONSchema> = (
  err: Error | null,
  $refs?: $Refs<S>
) => any;

// Plugin interfaces
interface Plugin {
  name?: string;
  order?: number;
  allowEmpty?: boolean;
  allowBOM?: boolean;
  encoding?: BufferEncoding;
  canParse?: boolean | RegExp | string | string[] | ((file: FileInfo) => boolean);
  parse: 
    | ((file: FileInfo, callback?: (error: Error | null, data: string | null) => any) => unknown | Promise<unknown>)
    | number
    | string;
}

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>);
}

interface FileInfo {
  url: string;
  hash: string;
  extension: string;
  data: string | Buffer;
}

// Utility functions
function isUnsafeUrl(url: string): boolean;
function isHandledError(err: any): err is JSONParserError;
function getJsonSchemaRefParserDefaultOptions(): $RefParserOptions<JSONSchema>;

Additional Utilities

// Internal functions (advanced usage)
function dereferenceInternal(parser: $RefParser, options: ParserOptions): void;
function jsonSchemaParserNormalizeArgs(...args: any[]): any;