or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

comparison-keywords.md format-validation.md index.md plugin-integration.md

tile.json

Comparison Keywords

Format-based range validation keywords that work with ordered formats like dates and times. Enables minimum/maximum constraints based on format-specific comparison logic.

Capabilities

Format Limit Keywords

Additional validation keywords that enable range validation for formats with natural ordering.

type LimitKeywords = 
  | "formatMaximum"          // Maximum value (inclusive)
  | "formatMinimum"          // Minimum value (inclusive) 
  | "formatExclusiveMaximum" // Maximum value (exclusive)
  | "formatExclusiveMinimum"; // Minimum value (exclusive)

Usage Examples:

// Date range validation
const dateRangeSchema = {
  type: "string",
  format: "date",
  formatMinimum: "2023-01-01",
  formatMaximum: "2023-12-31"
};

ajv.validate(dateRangeSchema, "2023-06-15"); // true
ajv.validate(dateRangeSchema, "2022-12-31"); // false (before minimum)
ajv.validate(dateRangeSchema, "2024-01-01"); // false (after maximum)

// Time range validation
const timeRangeSchema = {
  type: "string",
  format: "time", 
  formatMinimum: "09:00:00Z",
  formatExclusiveMaximum: "17:00:00Z"
};

ajv.validate(timeRangeSchema, "09:00:00Z"); // true (inclusive minimum)
ajv.validate(timeRangeSchema, "16:59:59Z"); // true
ajv.validate(timeRangeSchema, "17:00:00Z"); // false (exclusive maximum)

// Date-time range validation
const dateTimeRangeSchema = {
  type: "string",
  format: "date-time",
  formatMinimum: "2023-01-01T00:00:00Z",
  formatExclusiveMaximum: "2023-12-31T23:59:59Z"
};

Format Limit Plugin

Standalone plugin that adds only the format comparison keywords without format validators.

/**
 * Add format limit keywords to an Ajv instance
 * @param ajv - The Ajv instance to enhance
 * @returns The enhanced Ajv instance
 */
function formatLimit(ajv: Ajv): Ajv;

Usage Examples:

import Ajv from "ajv";
import formatLimit from "ajv-formats/dist/limit";
import { fullFormats } from "ajv-formats/dist/formats";

// Add format limit keywords to Ajv with existing formats
const ajv = new Ajv({ formats: fullFormats });
formatLimit(ajv);

// Now can use format limit keywords
const schema = {
  type: "string",
  format: "date",
  formatMinimum: "2023-01-01"
};

Supported Formats for Comparison

Format comparison keywords work with formats that have comparison functions defined.

type ComparableFormats = 
  | "date"          // Date comparison (lexicographic)
  | "time"          // Time comparison (with timezone normalization)
  | "date-time"     // Date-time comparison
  | "iso-time"      // ISO time comparison (without timezone normalization)
  | "iso-date-time"; // ISO date-time comparison

Comparison Behavior:

date: Lexicographic string comparison (works because ISO date format)
time: Normalized to common timezone before comparison
date-time: Full date-time comparison with timezone handling
iso-time: Time-only comparison ignoring timezone differences
iso-date-time: Combined date and time comparison

Error Handling

Format limit validation errors provide detailed information about the constraint violation.

type LimitFormatError = ErrorObject<
  "formatMaximum" | "formatMinimum" | "formatExclusiveMaximum" | "formatExclusiveMinimum",
  {
    limit: string;
    comparison: "<=" | ">=" | "<" | ">";
  }
>;

Error Examples:

const schema = {
  type: "string", 
  format: "date",
  formatMaximum: "2023-06-30"
};

const result = ajv.validate(schema, "2023-07-15");
if (!result) {
  console.log(ajv.errors);
  // [{
  //   keyword: "formatMaximum",
  //   message: "should be <= 2023-06-30",
  //   params: { limit: "2023-06-30", comparison: "<=" },
  //   ...
  // }]
}

Integration with Main Plugin

Format comparison keywords are automatically included when using the main plugin with default options.

// These are equivalent for keyword inclusion:
addFormats(ajv);
addFormats(ajv, { keywords: true });

// Disable keywords explicitly:
addFormats(ajv, { keywords: false });

// Keywords with specific formats:
addFormats(ajv, { 
  formats: ["date", "time"], 
  keywords: true 
});

$data References

Format limit keywords support Ajv's $data references for dynamic constraint values.

const schema = {
  type: "object",
  properties: {
    startDate: { type: "string", format: "date" },
    endDate: { 
      type: "string", 
      format: "date",
      formatMinimum: { $data: "1/startDate" }
    }
  }
};

// Valid: endDate >= startDate
ajv.validate(schema, {
  startDate: "2023-01-01",
  endDate: "2023-06-30"
}); // true

// Invalid: endDate < startDate  
ajv.validate(schema, {
  startDate: "2023-06-30", 
  endDate: "2023-01-01"
}); // false

Types

type LimitFormatError = ErrorObject<
  "formatMaximum" | "formatMinimum" | "formatExclusiveMaximum" | "formatExclusiveMinimum",
  {
    limit: string;
    comparison: "<=" | ">=" | "<" | ">";
  }
>;

type Comparison = "<=" | ">=" | "<" | ">";

type LimitKeyword = "formatMaximum" | "formatMinimum" | "formatExclusiveMaximum" | "formatExclusiveMinimum";

Version

Tile

Files