or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

comparison-keywords.mdformat-validation.mdindex.mdplugin-integration.md
tile.json

plugin-integration.mddocs/

Plugin Integration

Core plugin functionality for integrating format validators with Ajv instances. Supports selective format inclusion, validation modes, and optional comparison keywords.

Capabilities

Main Plugin Function

The default export function that adds format validators to an Ajv instance.

/**
 * Add format validators to an Ajv instance
 * @param ajv - The Ajv instance to enhance with format validators
 * @param opts - Configuration options for format integration (defaults to {keywords: true})
 * @returns The enhanced Ajv instance
 */
function addFormats(ajv: Ajv, opts: FormatsPluginOptions = {keywords: true}): Ajv;

Usage Examples:

import Ajv from "ajv";
import addFormats from "ajv-formats";

// Add all formats with default options (includes comparison keywords)
const ajv1 = new Ajv();
addFormats(ajv1);

// Add specific formats only
const ajv2 = new Ajv();
addFormats(ajv2, ["date", "time", "email"]);

// Use options object for more control
const ajv3 = new Ajv();
addFormats(ajv3, {
  mode: "fast",
  formats: ["date", "email", "uri"],
  keywords: true
});

Format Retrieval

Static method on the plugin function to retrieve specific format definitions.

/**
 * Retrieve a specific format definition
 * @param format - The format name to retrieve
 * @param mode - Validation mode (defaults to "full")
 * @returns The format definition object
 * @throws Error if format name is unknown
 */
addFormats.get(format: FormatName, mode: FormatMode = "full"): Format;

Usage Examples:

// Get full validation format
const emailFormat = addFormats.get("email");
const dateFormat = addFormats.get("date", "full");

// Get fast validation format
const fastDateFormat = addFormats.get("date", "fast");

// Error handling
try {
  const unknownFormat = addFormats.get("unknown" as FormatName);
} catch (error) {
  console.error(error.message); // "Unknown format \"unknown\""
}

Configuration Options

Plugin accepts either an array of format names or a configuration object.

type FormatsPluginOptions = FormatName[] | FormatOptions;

interface FormatOptions {
  /** Validation mode: "fast" for simplified validation, "full" for complete validation */
  mode?: FormatMode;
  /** Specific formats to add (defaults to all formats if not specified) */
  formats?: FormatName[];
  /** Whether to add format comparison keywords (defaults to true) */
  keywords?: boolean;
}

type FormatMode = "fast" | "full";

Configuration Examples:

// Array format - adds only specified formats
addFormats(ajv, ["date", "time", "email"]);

// Object format - full control
addFormats(ajv, {
  mode: "fast",           // Use simplified validation
  formats: ["date", "uri"], // Only add these formats
  keywords: false         // Don't add comparison keywords
});

// Default behavior (equivalent configurations)
addFormats(ajv);
addFormats(ajv, { keywords: true });
addFormats(ajv, { mode: "full", keywords: true });

Validation Modes

Two validation modes provide different performance and accuracy trade-offs.

Full Mode (default):

  • Complete validation with all edge cases
  • Range validation for dates and times
  • Full URI parsing and validation
  • Higher accuracy, slightly slower performance

Fast Mode:

  • Simplified regex-based validation
  • Structure validation without range checking
  • Faster performance, reduced accuracy for edge cases
  • Suitable for performance-critical applications
// Full mode examples
const fullDateSchema = { type: "string", format: "date" };
ajv.validate(fullDateSchema, "2020-02-30"); // false (invalid date)

// Fast mode examples
addFormats(ajv, { mode: "fast" });
ajv.validate(fullDateSchema, "2020-02-30"); // true (valid format structure)

Types

interface FormatsPlugin extends Plugin<FormatsPluginOptions> {
  get(format: FormatName, mode?: FormatMode): Format;
}

type FormatsPluginOptions = FormatName[] | FormatOptions;

interface FormatOptions {
  mode?: FormatMode;
  formats?: FormatName[];
  keywords?: boolean;
}

type FormatMode = "fast" | "full";