DEV Community

Cover image for InversifyJS + OpenAPI: One Schema to Validate Them All
notaphplover
notaphplover

Posted on

InversifyJS + OpenAPI: One Schema to Validate Them All

#typescript #openapi #node

Here's a situation you've probably been in before:

# Your OpenAPI spec says this:
requestBody:
  content:
    application/json:
      schema:
        type: object
        required: [name, email]
        properties:
          name: { type: string, minLength: 1 }
          email: { type: string, format: email }
Enter fullscreen mode Exit fullscreen mode 
// Your validation layer says this:
const schema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});
Enter fullscreen mode Exit fullscreen mode

Two definitions of the same shape. They start identical. Then someone updates the OpenAPI spec but forgets the Zod schema. Or vice versa. A week later, your Swagger UI shows one contract and your server enforces a completely different one.

There's a better way.

Your OpenAPI Spec Is Already Your Schema

That's the core idea behind @inversifyjs/open-api-validation. If you're using InversifyJS and already decorating your controllers with @OasRequestBody, you've already written your validation schema — you just didn't know it.

The pipe reads the OpenAPI schemas from your @inversifyjs/http-open-api decorators, compiles them with Ajv, and validates incoming requests automatically. Zero extra schema definitions. Zero drift.

A Complete Example

Here's a real controller — name required with a minimum length, email required with format validation:

import { Controller, Post } from '@inversifyjs/http-core';
import { InversifyExpressHttpAdapter } from '@inversifyjs/http-express';
import { OasRequestBody, SwaggerUiProvider } from '@inversifyjs/http-open-api';
import { InversifyValidationErrorFilter } from '@inversifyjs/http-validation';
import { type OpenApi3Dot1Object } from '@inversifyjs/open-api-types/v3Dot1';
import { ValidatedBody } from '@inversifyjs/open-api-validation';
import { OpenApiValidationPipe } from '@inversifyjs/open-api-validation/v3Dot1';
import { Container } from 'inversify';

const container = new Container();

const openApiObject: OpenApi3Dot1Object = {
  info: { title: 'My API', version: '1.0.0' },
  openapi: '3.1.1',
};

const swaggerProvider = new SwaggerUiProvider({
  api: { openApiObject, path: '/docs' },
});

interface User {
  email: string;
  name: string;
}

@Controller('/users')
class UserController {
  @OasRequestBody({
    content: {
      'application/json': {
        schema: {
          additionalProperties: false,
          properties: {
            email: { format: 'email', type: 'string' },
            name: { minLength: 1, type: 'string' },
          },
          required: ['name', 'email'],
          type: 'object',
        },
      },
    },
  })
  @Post('/')
  public createUser(@ValidatedBody() user: User): string {
    return `Created user: ${user.name}`;
  }
}

container.bind(InversifyValidationErrorFilter).toSelf().inSingletonScope();
container.bind(UserController).toSelf().inSingletonScope();

// Merges @OasRequestBody metadata into the OpenAPI document
swaggerProvider.provide(container);

const adapter = new InversifyExpressHttpAdapter(container);

// The pipe receives the fully populated spec — no separate schema file
adapter.useGlobalPipe(new OpenApiValidationPipe(swaggerProvider.openApiObject));
adapter.useGlobalFilters(InversifyValidationErrorFilter);
Enter fullscreen mode Exit fullscreen mode

The @OasRequestBody decorator defines the contract. @ValidatedBody() marks the parameter for validation. OpenApiValidationPipe bridges the two. That's the entire setup.

What Happens When Validation Fails

Send a body with an unknown field (the schema uses additionalProperties: false):

POST /users
Content-Type: application/json

{ "name": "Alice", "email": "alice@example.com", "role": "admin" }
Enter fullscreen mode Exit fullscreen mode

Response:

HTTP/1.1 400 Bad Request

{
  "message": "[schema: #/additionalProperties, instance: ]: \"must NOT have additional properties\""
}
Enter fullscreen mode Exit fullscreen mode

Send an invalid email:

HTTP/1.1 400 Bad Request

{
  "message": "[schema: #/properties/email/format, instance: /email]: \"must match format \\\"email\\\"\""
}
Enter fullscreen mode Exit fullscreen mode

The error points directly to the failing schema path and instance path — no digging required. InversifyValidationErrorFilter catches the InversifyValidationError thrown by the pipe and returns the 400 automatically.

Query Parameter Validation Too

Body validation is only part of the story. Query parameters are just as common a source of bugs — and the same duplication problem applies. With @ValidatedQuery(), the pipe validates query params against the schemas defined in your @OasParameter({ in: 'query' }) decorators:

import { Controller, Get } from '@inversifyjs/http-core';
import { OasParameter } from '@inversifyjs/http-open-api';
import { ValidatedQuery } from '@inversifyjs/open-api-validation';

interface ProductQuery {
  limit?: number;
  search?: string;
}

@Controller('/products')
class ProductController {
  @OasParameter({
    in: 'query',
    name: 'search',
    required: false,
    schema: { type: 'string' },
  })
  @OasParameter({
    in: 'query',
    name: 'limit',
    required: false,
    schema: { minimum: 1, type: 'integer' },
  })
  @Get('/')
  public getProducts(@ValidatedQuery() query: ProductQuery): string {
    return `Search: ${query.search ?? ''}`;
  }
}
Enter fullscreen mode Exit fullscreen mode

Send GET /products?limit=not-a-number and you get:

{
  "message": "[query: limit, schemaPath: #/type, instancePath: ]: \"must be integer\""
}
Enter fullscreen mode Exit fullscreen mode

Query string values are automatically coerced to the declared type before validation — a ?limit=10 string becomes the number 10 before Ajv ever sees it.

Path parameters and headers work the same way with @ValidatedParams() and @ValidatedHeaders().

How It Compares to the Typical Approach

Typical open-api-validation
Schema definition Separate (Zod, Yup, Ajv…) @OasRequestBody / @OasParameter
OpenAPI spec Written separately or generated Written once, used for both
Drift risk High — two files to keep in sync None — one source of truth
Error details Depends on library Ajv schema path + instance path
Adoption All-or-nothing Per-parameter — add @ValidatedBody() / @ValidatedQuery() where you want it

How It Works Under the Hood

  1. swaggerProvider.provide(container) scans controller metadata and merges @OasRequestBody and @OasParameter data into the OpenAPI document.
  2. OpenApiValidationPipe receives the fully populated spec and uses JSON Pointer resolution to find the schema for each operation.
  3. Schemas are compiled into Ajv validators on first use and cached — cold starts only pay the compilation cost once.
  4. The compiled validator runs against the incoming request. On failure, an InversifyValidationError is thrown with full Ajv error details.

OpenAPI 3.1 and 3.2

Both versions are supported through dedicated subpath exports:

// Decorators work the same for both versions
import { ValidatedBody, ValidatedHeaders, ValidatedQuery, ValidatedParams } from '@inversifyjs/open-api-validation';

// Pick the version matching your spec
import { OpenApiValidationPipe } from '@inversifyjs/open-api-validation/v3Dot1';
import { OpenApiValidationPipe } from '@inversifyjs/open-api-validation/v3Dot2';
Enter fullscreen mode Exit fullscreen mode

Getting Started 

npm install @inversifyjs/open-api-validation ajv ajv-formats
Enter fullscreen mode Exit fullscreen mode

If you're already using @inversifyjs/http-open-api to document your API, adding body validation is a five-minute change. You're writing the schemas anyway — stop writing them twice.

Full documentation: https://inversify.io/framework/validation/openapi/introduction/
Source: github.com/inversify/monorepo

Have feedback or questions? Open an issue on GitHub or drop a comment below.

Top comments (0)