Skip to main content

ADR-005: Use Zod

Status​

Accepted

Date​

2026-07-20

Context​

Chilarai requires validation of data across multiple layers of the application, including:

  • Browser forms
  • API requests
  • API responses
  • Background jobs
  • Data import workflows
  • Future integration endpoints

The platform already uses TypeScript and aims to maintain a single source of truth for business contracts and validation rules.

The selected validation approach should minimize duplication while enabling consistent validation throughout the platform.

Decision Drivers​

The selected approach should:

  • Work well with TypeScript
  • Support runtime validation
  • Minimize duplication of validation rules
  • Support frontend and backend reuse
  • Be easy to understand and maintain
  • Integrate well with Next.js and NestJS
  • Have strong community adoption
  • Support future API and integration scenarios

Alternatives Considered​

Option 1: TypeScript Interfaces Only​

Advantages​

  • Simple
  • No additional dependency
  • Familiar to most developers

Disadvantages​

  • No runtime validation
  • Invalid external input cannot be detected automatically
  • Validation logic must be written separately

Assessment​

TypeScript interfaces improve developer experience but do not provide actual runtime protection.

Option 2: class-validator​

Advantages​

  • Commonly used within NestJS
  • Decorator-based validation
  • Good NestJS integration

Disadvantages​

  • Validation definitions are tied to classes
  • Less reusable across frontend and backend
  • Additional duplication between contracts and validation models

Assessment​

A viable choice for backend validation but less suitable for a shared validation strategy.

Option 3: Joi​

Advantages​

  • Mature ecosystem
  • Strong runtime validation
  • Proven library

Disadvantages​

  • Weaker TypeScript experience
  • Separate type definitions are often required
  • Increased maintenance overhead

Assessment​

Technically capable, but does not align as closely with a TypeScript-first architecture.

Option 4: Zod​

Advantages​

  • TypeScript-first design
  • Runtime validation
  • Type inference
  • Shared schema definitions
  • Strong ecosystem adoption
  • Easy integration with React and NestJS
  • Reduces duplication

Disadvantages​

  • Additional dependency
  • Developers must learn Zod schema syntax
  • Very large schemas can become difficult to maintain if not properly organized

Assessment​

Provides the best alignment with Chilarai's architecture and development practices.

Decision​

Use Zod as the standard validation framework for Chilarai.

Validation schemas will be stored in the shared-validation library and reused throughout the platform.

Rationale​

Zod enables Chilarai to maintain a single source of truth for validation logic.

A schema can be defined once and reused by:

  • Next.js forms
  • NestJS APIs
  • Import workflows
  • Background jobs
  • Future integration endpoints

This eliminates duplication between frontend validation and backend validation.

The library also integrates naturally with TypeScript, allowing types to be derived directly from schemas.

This approach reduces maintenance effort and improves consistency across the platform.

Consequences​

Positive Consequences​

  • Shared validation rules across frontend and backend
  • Reduced duplication
  • Runtime validation support
  • Strong TypeScript integration
  • Improved data quality
  • Simplified maintenance

Negative Consequences​

  • Additional dependency within the platform
  • Contributors must learn Zod conventions
  • Validation schemas require thoughtful organization as the platform grows

Follow-up Actions​

  • Maintain all shared schemas within shared-validation
  • Derive TypeScript types from validation schemas where appropriate
  • Standardize validation patterns across modules
  • Establish naming conventions for schemas
  • Integrate validation into all external input paths

Example Usage​

Validation schema:

  • StudentSchema
  • TeacherSchema
  • AdmissionSchema
  • FeeSchema
  • TenantSchema

Consumers:

  • web
  • api
  • imports
  • background jobs