Validation API

Schema-based object validation and environment variable validation with custom decorators.

What It Does

The Validation API provides a comprehensive validation framework combining AJV (JSON Schema validator) with class-validator decorators. It enables schema-driven object validation, environment variable validation with type safety, and custom validators for domain-specific formats like US states, ZIP codes, EINs, and cron expressions.

Key Capabilities

Capability	Description
Schema-Based Validation	Validate objects against stored JTD (JSON Type Definition) schemas
Environment Validation	Strongly-typed environment variable validation at startup
Custom Decorators	Pre-built validators for domain-specific data formats
Caching Support	Two implementations for different performance needs
Schema Management	CRUD operations on validation schemas via repository
JTD Format	JSON Type Definition for efficient schema validation
Type Safety	Bridge JavaScript runtime validation with TypeScript types
Class Decorators	Use decorators on TypeScript classes for validation
File Validation	Check file path existence
Cron Validation	Validate and analyze cron expressions

Configuration

AJV Configuration

Format: JTD (JSON Type Definition)
Strict Mode: Enabled
All Errors: Captures all validation errors

Validation Modes

Simple: ObjectValidationService (fetches schemas per validation)
Cached: CachedObjectValidationService (loads all schemas once)

Exports

Services

BaseValidationService - Abstract base class
ObjectValidationService - Simple validation
CachedObjectValidationService - Performance-optimized
ValidationAdminService - Schema management
ValidationRepository - Schema persistence

Decorators

@IsState() - US state validation
@IsZipCode() - ZIP code validation
@IsEin() - EIN validation
@IsFile() - File existence
@IsCronExpression() - Cron syntax
@CronExpressionWithin() - Cron frequency
@IsMaxBytes() - Byte size limit

Functions

validateEnvironment<T>() - Environment validation
cronExpressIsWithin() - Cron frequency check

Models

IValidationSpec - Schema interface
ObjectNotValidError - Validation error
SchemaNotFoundError - Missing schema error

Validators

FilePath - File path constraint

Common Use Cases

API input validation: Validate request payloads against schemas
Environment configuration: Type-safe environment variables
Event validation: Validate pub/sub event payloads
Form validation: Validate user input in forms
Address validation: US address format validation
Tax ID validation: EIN format validation
Scheduled job config: Cron expression validation
File path validation: Config file existence checks
Payload size limits: Enforce byte size limits

What Customers Don’t Have to Build

Schema-based validation infrastructure
AJV integration with JTD format
Environment variable validation
Type conversion for env vars
Domain-specific validators (states, ZIPs, EINs)
Cron expression validation and analysis
File path existence checking
Byte size calculation and validation
Schema management CRUD operations
Schema repository and persistence
Validation error formatting
Path-specific error reporting
Observable schema queries
Cached validation implementation
Class decorator validation
Real-time schema updates