Skip to main content

API

AjvValidationPipe​

Validates values using Ajv JSON Schema validator. Register it globally to validate incoming HTTP parameters (e.g., body) in your controllers.

constructor(ajv: Ajv, schemaList?: AnySchema[])

Parameters

  • ajv (Ajv): The Ajv instance to use for validation. You can configure it with custom formats, keywords, and options.
  • schemaList (optional AnySchema[]): One or more JSON schemas applied globally to every validated value. These run before any parameter-level schemas added via @ValidateAjvSchema.

AjvValidationPipe can be registered as a global pipe: adapter.useGlobalPipe(new AjvValidationPipe(ajv)). This way, controller parameters decorated with @ValidateAjvSchema are automatically validated.

Example: register an AjvValidationPipe globally​

import { AjvValidationPipe } from '@inversifyjs/ajv-validation';
import { InversifyExpressHttpAdapter } from '@inversifyjs/http-express';
import { InversifyValidationErrorFilter } from '@inversifyjs/http-validation';
import Ajv from 'ajv';
import { Container } from 'inversify';

const container: Container = new Container();

const ajv: Ajv = new Ajv();

const adapter: InversifyExpressHttpAdapter = new InversifyExpressHttpAdapter(
  container,
  { logger: true },
);
adapter.useGlobalFilters(InversifyValidationErrorFilter);
adapter.useGlobalPipe(new AjvValidationPipe(ajv));

AjvCompiledValidationPipe​

An optimized version of AjvValidationPipe that uses compiled Ajv validation functions for better performance. Best suited for production environments where schemas don't change frequently.

constructor(ajv: Ajv, schemaList?: AnySchema[])

Parameters

  • ajv (Ajv): The Ajv instance to use for validation. Schemas must have an $id property to be compiled.
  • schemaList (optional AnySchema[]): One or more JSON schemas applied globally to every validated value.

Important: When using AjvCompiledValidationPipe, all schemas must have an $id property. The pipe compiles and caches validation functions for better performance.

Example: register an AjvCompiledValidationPipe globally​

import { AjvCompiledValidationPipe } from '@inversifyjs/ajv-validation';
import { InversifyExpressHttpAdapter } from '@inversifyjs/http-express';
import { InversifyValidationErrorFilter } from '@inversifyjs/http-validation';
import Ajv from 'ajv';
import { Container } from 'inversify';

const container: Container = new Container();

const ajv: Ajv = new Ajv();

const adapter: InversifyExpressHttpAdapter = new InversifyExpressHttpAdapter(
  container,
  { logger: true },
);
adapter.useGlobalFilters(InversifyValidationErrorFilter);
adapter.useGlobalPipe(new AjvCompiledValidationPipe(ajv));

ValidateAjvSchema​

Attaches one or more JSON schemas to a specific parameter (e.g., @Body()), so the AjvValidationPipe or AjvCompiledValidationPipe can validate the value before your controller method runs.

ValidateAjvSchema(...schemaList: AnySchema[]): ParameterDecorator

Parameters

  • schemaList: One or more JSON Schema objects that define the expected structure and constraints for the parameter value.

When multiple schemas are provided, they run in sequence. The value must pass all schema validations. Any schemas provided to AjvValidationPipe run first; parameter-level schemas run afterwards.

On validation failure, an InversifyValidationError is thrown and can be converted to a Bad Request HTTP response by ValidationErrorFilter.

Example: validate request body with JSON Schema​

import { ValidateAjvSchema } from '@inversifyjs/ajv-validation';
import { Body, Controller, Post } from '@inversifyjs/http-core';
import { AnySchema } from 'ajv';

interface User {
  name: string;
  email: string;
  age?: number;
}

const userSchema: AnySchema = {
  additionalProperties: false,
  properties: {
    age: { minimum: 0, type: 'number' },
    email: { format: 'email', type: 'string' },
    name: { minLength: 1, type: 'string' },
  },
  required: ['name', 'email'],
  type: 'object',
};

@Controller('/users')
export class UserController {
  @Post()
  public async createUser(
    @Body()
    @ValidateAjvSchema(userSchema)
    user: User,
  ): Promise<User> {
    return user;
  }
}

Error Handling​

When validation fails, Ajv provides detailed error information including:

  • Property path where validation failed
  • Expected vs actual values
  • Validation rule that was violated

The AjvValidationPipe automatically converts these errors into user-friendly messages that can be returned as HTTP responses.