or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

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

parsing.mddocs/

Schema Parsing

Core functionality for parsing JSON Schema files in various formats (JSON, YAML) without resolving $ref pointers. The parsing operation reads a single file and parses it as a JavaScript object, but does not follow or resolve any external references.

Capabilities

Parse Function (Static)

Parses a JSON Schema file or object without resolving any $ref pointers.

/**
 * Parses the given JSON schema without resolving any $ref pointers
 * @param schema - A JSON Schema object, or the file path or URL of a JSON Schema file
 * @returns Promise that resolves with the parsed JSON schema object
 */
function parse<S extends object = JSONSchema>(
  schema: S | string | unknown
): Promise<S>;

/**
 * Parses the given JSON schema 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 parsed schema
 * @returns Promise that resolves to void when using callback
 */
function parse<S extends object = JSONSchema>(
  schema: S | string | unknown,
  callback: SchemaCallback<S>
): Promise<void>;

/**
 * Parses the given JSON schema 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 the schema is parsed
 * @returns Promise that resolves with the parsed JSON schema object
 */
function parse<S extends object = JSONSchema>(
  schema: S | string | unknown,
  options: ParserOptions<S>
): Promise<S>;

/**
 * Parses the given JSON schema 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 the schema is parsed
 * @param callback - Error-first callback receiving the parsed schema
 * @returns Promise that resolves to void when using callback
 */
function parse<S extends object = JSONSchema>(
  schema: S | string | unknown,
  options: ParserOptions<S>,
  callback: SchemaCallback<S>
): Promise<void>;

/**
 * Parses a schema at a 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 the schema is parsed
 * @returns Promise that resolves with the parsed JSON schema object
 */
function parse<S extends object = JSONSchema>(
  path: string,
  schema: S | string | unknown,
  options: ParserOptions<S>
): Promise<S>;

/**
 * Parses a schema at a specific path with schema object, 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 the schema is parsed
 * @param callback - Error-first callback receiving the parsed schema
 * @returns Promise that resolves to void when using callback
 */
function parse<S extends object = JSONSchema>(
  path: string,
  schema: S | string | unknown,
  options: ParserOptions<S>,
  callback: SchemaCallback<S>
): Promise<void>;

Parse Method (Instance)

Instance method on $RefParser class for parsing schemas.

class $RefParser<S extends object = JSONSchema> {
  schema: S | null;
  $refs: $Refs<S>;
  
  /**
   * Parses the given JSON schema and stores result in instance
   * @param schema - A JSON Schema object, or the file path or URL of a JSON Schema file
   * @returns Promise that resolves with the parsed JSON schema object
   */
  parse(schema: S | string | unknown): Promise<S>;
  
  /**
   * Parses 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 parsed schema
   * @returns Promise that resolves to void when using callback  
   */
  parse(schema: S | string | unknown, callback: SchemaCallback<S>): Promise<void>;
  
  /**
   * Parses 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 the schema is parsed
   * @returns Promise that resolves with the parsed JSON schema object
   */
  parse(schema: S | string | unknown, options: ParserOptions<S>): Promise<S>;
  
  /**
   * Parses 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 the schema is parsed
   * @param callback - Error-first callback receiving the parsed schema
   * @returns Promise that resolves to void when using callback
   */
  parse(schema: S | string | unknown, options: ParserOptions<S>, callback: SchemaCallback<S>): Promise<void>;
  
  /**
   * Parses 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 the schema is parsed
   * @returns Promise that resolves with the parsed JSON schema object
   */
  parse(path: string, schema: S | string | unknown, options: ParserOptions<S>): Promise<S>;
  
  /**
   * Parses 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 the schema is parsed
   * @param callback - Error-first callback receiving the parsed schema
   * @returns Promise that resolves to void when using callback
   */
  parse(path: string, schema: S | string | unknown, options: ParserOptions<S>, callback: SchemaCallback<S>): Promise<void>;
}

Usage Examples:

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

// Static parsing from file
const schema = await $RefParser.parse("./schemas/user.json");

// Static parsing with schema object
const schemaObj = { type: "object", properties: { name: { type: "string" } } };
const parsed = await $RefParser.parse(schemaObj);

// Instance-based parsing
const parser = new $RefParser();
await parser.parse("./schemas/user.json");
console.log(parser.schema); // Parsed schema available on instance

// Parsing with custom options
const customSchema = await $RefParser.parse("./schemas/user.yaml", {
  parse: {
    yaml: true,
    json: false
  }
});

// Using callbacks
$RefParser.parse("./schemas/user.json", (err, schema) => {
  if (err) {
    console.error("Parse error:", err);
  } else {
    console.log("Parsed schema:", schema);
  }
});

Supported File Formats

The parser supports multiple file formats through built-in parsers:

  • JSON: Standard JSON files (.json)
  • YAML: YAML files (.yaml, .yml)
  • Text: Plain text files (.txt)
  • Binary: Binary files for custom parsing

Each parser can be configured or disabled through the parse options.

Parse Options

interface ParseOptions {
  json?: Plugin | boolean;    // Enable/configure JSON parser
  yaml?: Plugin | boolean;    // Enable/configure YAML parser  
  text?: Plugin | boolean;    // Enable/configure text parser
  binary?: Plugin | boolean;  // Enable/configure binary parser
  [key: string]: Plugin | boolean | undefined; // Custom parsers
}

Error Handling

Parse operations can throw various errors:

  • JSONParserError: Base parsing error with source and path information
  • ParserError: Specific parser-related errors
  • UnmatchedParserError: No suitable parser found for file format
  • SyntaxError: Invalid JSON Schema structure
try {
  const schema = await $RefParser.parse("invalid-schema.json");
} catch (error) {
  if (error instanceof JSONParserError) {
    console.log("Parse error:", error.message);
    console.log("Source:", error.source);
    console.log("Path:", error.path);
  }
}