class-validator — Decorator-Based Validation for TypeScript Classes

Introduction

class-validator brings declarative validation to TypeScript by using decorators on class properties. Instead of writing imperative checks scattered across your code, you annotate DTOs once and validate anywhere. It is the default validation layer in NestJS and pairs naturally with class-transformer for request body parsing.

What class-validator Does

• Validates class instances using 70+ built-in decorator constraints (email, URL, UUID, ranges, arrays)
• Supports nested object and array validation via @ValidateNested and @Type decorators
• Provides conditional validation with @ValidateIf for fields that depend on other values
• Returns structured error objects with property paths, constraint names, and human-readable messages
• Allows custom validators and async validators for domain-specific business rules

Architecture Overview

class-validator stores validation metadata (decorator definitions) in a global metadata storage keyed by class constructor and property name. When validate() is called, it iterates the target object's properties, looks up registered constraints, and executes each validator function. Failures accumulate into ValidationError objects with nested children for complex object graphs. The library is synchronous by default but supports async validators that return Promises.

Self-Hosting & Configuration

• Install from npm alongside class-transformer for automatic plain-to-class conversion
• Enable experimentalDecorators and emitDecoratorMetadata in tsconfig.json
• Use whitelist: true in validate options to strip unknown properties (security best practice)
• Configure forbidNonWhitelisted: true to reject payloads with unexpected fields
• Group validators with @IsString({ groups: ['create'] }) for context-specific validation

Key Features

• 70+ built-in validators: string formats, numeric ranges, arrays, dates, enums, and more
• Integrates seamlessly with NestJS ValidationPipe for automatic request validation
• Custom decorators via registerDecorator() for domain-specific rules
• Validation groups allow different rules for create vs. update operations
• Over 11,700 GitHub stars and 10 million weekly npm downloads

Comparison with Similar Tools

• Zod — schema-first with type inference; class-validator is decorator-first for OOP codebases
• Joi — schema builder popular with Express; class-validator integrates deeper with TypeScript classes
• Yup — similar to Joi with TypeScript support; class-validator co-locates rules on the class itself
• io-ts — runtime type checking via functional codecs; class-validator is imperative and OOP
• Valibot — modular schema validation; class-validator uses decorators rather than function composition

FAQ

Q: Do I need class-transformer alongside class-validator? A: For NestJS, yes — it converts plain JSON bodies into class instances before validation. For standalone use, you can instantiate classes manually.

Q: Can I validate arrays of objects? A: Yes. Use @ValidateNested({ each: true }) with @Type(() => ItemDto) on an array property.

Q: Does it work without decorators (plain JS)? A: It requires decorator syntax. For non-TypeScript projects, schema-based libraries like Zod or Joi are more appropriate.

Q: How do I write custom async validators? A: Use registerDecorator with validator.validate() returning a Promise. Common use: checking uniqueness against a database.

Sources

• https://github.com/typestack/class-validator
• https://github.com/typestack/class-validator/blob/develop/README.md