or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

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

bundling.mddocs/

Schema Bundling

Bundles all referenced files into a single schema that contains only internal $ref pointers, eliminating external dependencies while maintaining reference structure. This allows you to distribute a complete schema as a single file while preserving the benefits of modular development and avoiding circular reference issues during serialization.

Capabilities

Bundle Function (Static)

Bundles all referenced files/URLs into a single schema with internal $ref pointers only.

/**
 * Bundles all referenced files into a single schema with internal $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 bundled schema object
 */
function bundle<S extends object = JSONSchema>(
  schema: S | string | unknown
): Promise<S>;

/**
 * Bundles 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 bundled schema
 * @returns Promise that resolves to void when using callback
 */
function bundle<S extends object = JSONSchema>(
  schema: S | string | unknown,
  callback: SchemaCallback<S>
): Promise<void>;

/**
 * Bundles 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 bundled
 * @returns Promise that resolves with the bundled schema object
 */
function bundle<S extends object = JSONSchema>(
  schema: S | string | unknown,
  options: ParserOptions<S>
): Promise<S>;

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

/**
 * Bundles 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 bundled
 * @returns Promise that resolves with the bundled schema object
 */
function bundle<S extends object = JSONSchema>(
  path: string,
  schema: S | string | unknown,
  options: ParserOptions<S>
): Promise<S>;

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

Bundle Method (Instance)

Instance method on $RefParser class for bundling schemas.

class $RefParser<S extends object = JSONSchema> {
  schema: S | null;
  $refs: $Refs<S>;
  
  /**
   * Bundles all referenced files and updates instance schema property
   * @param schema - A JSON Schema object, or the file path or URL of a JSON Schema file
   * @returns Promise that resolves with the bundled schema object
   */
  bundle(schema: S | string | unknown): Promise<S>;
  
  /**
   * Bundles 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 bundled schema
   * @returns Promise that resolves to void when using callback
   */
  bundle(schema: S | string | unknown, callback: SchemaCallback<S>): Promise<void>;
  
  /**
   * Bundles 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 bundled
   * @returns Promise that resolves with the bundled schema object
   */
  bundle(schema: S | string | unknown, options: ParserOptions<S>): Promise<S>;
  
  /**
   * Bundles 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 bundled
   * @param callback - Error-first callback receiving the bundled schema
   * @returns Promise that resolves to void when using callback
   */
  bundle(schema: S | string | unknown, options: ParserOptions<S>, callback: SchemaCallback<S>): Promise<void>;
  
  /**
   * Bundles 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 bundled
   * @returns Promise that resolves with the bundled schema object
   */
  bundle(path: string, schema: S | string | unknown, options: ParserOptions<S>): Promise<S>;
  
  /**
   * Bundles 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 bundled
   * @param callback - Error-first callback receiving the bundled schema
   * @returns Promise that resolves to void when using callback
   */
  bundle(path: string, schema: S | string | unknown, options: ParserOptions<S>, callback: SchemaCallback<S>): Promise<void>;
}

Usage Examples:

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

// Basic bundling from file
const bundled = await $RefParser.bundle("./schemas/api.json");

// The bundled schema contains all external references as internal definitions
console.log(JSON.stringify(bundled, null, 2));

// Instance-based bundling
const parser = new $RefParser();
await parser.bundle("./schemas/api.json");
console.log("Bundled schema:", parser.schema);

// Bundling with custom options
const customBundled = await $RefParser.bundle("./schemas/api.json", {
  bundle: {
    excludedPathMatcher: (path) => path.includes("internal")
  }
});

// Safe serialization (no circular references)
const jsonString = JSON.stringify(bundled);
console.log("Serialized bundle:", jsonString);

Bundle Options

interface BundleOptions {
  /**
   * Function to exclude certain paths from bundling
   * @param path - The path being processed (the $ref string)
   * @returns True to exclude this path and all subpaths from processing
   */
  excludedPathMatcher?(path: string): boolean;

  /**
   * Callback invoked during bundling process
   * @param path - The path being processed (the $ref string)
   * @param value - The JSON-Schema that the $ref resolved to
   * @param parent - The parent of the processed object
   * @param parentPropName - The property name of the parent object
   */
  onBundle?(
    path: string,
    value: JSONSchemaObject,
    parent?: JSONSchemaObject,
    parentPropName?: string
  ): void;
}

How Bundling Works

  1. Resolution Phase: First resolves all external $ref pointers to gather all referenced files
  2. Bundling Phase: Copies all external schemas into a single schema structure
  3. Reference Rewriting: Converts external $ref pointers to internal ones pointing to the bundled content
  4. Structure Preservation: Maintains the original schema structure while eliminating external dependencies

Before and After Example

Before Bundling (multiple files):

// main.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "user": { "$ref": "./user.json" },
    "address": { "$ref": "./address.json" }
  }
}

// user.json  
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" }
  }
}

// address.json
{
  "type": "object", 
  "properties": {
    "street": { "type": "string" },
    "city": { "type": "string" }
  }
}

After Bundling (single file):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "user": { "$ref": "#/definitions/user" },
    "address": { "$ref": "#/definitions/address" }
  },
  "definitions": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "age": { "type": "number" }
      }
    },
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" }
      }
    }
  }
}

Benefits of Bundling

  • Single File Distribution: Deploy one file instead of managing multiple schema files
  • Reduced Network Requests: No external HTTP requests needed at runtime
  • Serialization Safety: Can safely use JSON.stringify() without circular reference errors
  • Reference Preservation: Maintains logical structure and reusability through internal references
  • Performance: Faster processing since all schemas are already loaded

Circular Reference Handling

Bundling automatically handles circular references by:

  • Detecting circular reference patterns during resolution
  • Preserving the circular structure using internal $ref pointers
  • Ensuring the bundled schema remains valid and serializable

Error Handling

Bundling operations can encounter various errors:

  • Resolution errors: Problems accessing or parsing referenced files
  • JSONParserError: Invalid schema structure in referenced files
  • Circular reference errors: Complex circular patterns that cannot be bundled safely
try {
  const bundled = await $RefParser.bundle("./schemas/api.json");
} catch (error) {
  if (error instanceof JSONParserError) {
    console.log("Bundling failed:", error.message);
    console.log("Error in file:", error.source);
  }
}