Skip to main content

​
Overview

tsoa v7.0.0 introduces OpenAPI 3.1.0 support, enhanced TypeScript compatibility, and several improvements to validation and type handling. This guide will help you migrate from v6.x to v7.x.
tsoa v7.0.0 is currently in alpha. Use in production environments at your own risk.

​
Prerequisites

Before upgrading, ensure your project meets these requirements:
  • Node.js: v18.0.0 or higher (unchanged from v6)
  • TypeScript: v5.2.2 or higher
  • Yarn: v1.9.4 or higher (if using Yarn)

​
Breaking Changes

​
OpenAPI 3.1.0 Support

tsoa v7 adds support for OpenAPI 3.1.0, which is now the default specification version when specVersion is set to 3.1 in your configuration.
1

Update specVersion configuration

If you want to use OpenAPI 3.1.0, update your tsoa.json configuration:
tsoa.json
{
  "spec": {
    "specVersion": 3.1,
    "outputDirectory": "build",
    "specFileBaseName": "openapi"
  }
}
OpenAPI 3.1.0 has differences from 3.0.x. Ensure your API consumers support 3.1.0 before upgrading.
2

Review schema changes

OpenAPI 3.1.0 schemas are more aligned with JSON Schema. Key differences include:
  • Use of const instead of single-value enum
  • Support for prefixItems for tuple validation
  • Enhanced $ref handling
  • Support for $defs alongside definitions

​
Validation Improvements

​
Circular Reference Handling

v7 includes improved handling of circular references in validation schemas.
Before (v6)
// Circular references could cause validation errors
interface Node {
  value: string;
  children: Node[]; // This might cause issues in v6
}
After (v7)
// Circular references are properly handled
interface Node {
  value: string;
  children: Node[]; // Works correctly in v7
}

​
Deep Model Error Output

Validation error messages for deeply nested models have been trimmed to prevent output explosion: 
interface DeepModel {
  level1: {
    level2: {
      level3: {
        value: string;
      };
    };
  };
}

// v7 produces more concise error messages
// for validation failures in deeply nested structures

​
Type System Enhancements

​
Zod Infer Type Support

tsoa v7 adds support for Zod’s infer type on response types: 
import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer<typeof UserSchema>;

@Route('users')
export class UserController extends Controller {
  @Get('{userId}')
  public async getUser(@Path() userId: string): Promise<User> {
    // v7 properly resolves the inferred type
    return { id: userId, name: 'John', email: '[email protected]' };
  }
}

​
Generic Type Resolution

Improved generic type resolution for query parameters: 
interface PaginatedQuery<T> {
  page: number;
  limit: number;
  filter?: T;
}

@Get('items')
public async getItems(
  @Query() query: PaginatedQuery<{ status: string }>,
): Promise<Item[]> {
  // Generic types are now properly resolved in v7
}

​
New Features

​
OpenAPI 3.1.0 Schema Generation

When using specVersion: 3.1, tsoa generates OpenAPI 3.1.0-compliant schemas: 
{
  "type": "string",
  "enum": ["active"]
}

​
Tuple Type Support

OpenAPI 3.1.0 introduces better tuple support using prefixItems: 
type Coordinate = [number, number];
type NamedCoordinate = [string, number, number];

interface Location {
  position: Coordinate; // [longitude, latitude]
  namedPosition: NamedCoordinate; // [name, longitude, latitude]
}
In OpenAPI 3.1.0, this generates: 
{
  "position": {
    "type": "array",
    "prefixItems": [
      { "type": "number" },
      { "type": "number" }
    ],
    "minItems": 2,
    "maxItems": 2
  }
}

​
Enhanced Status Code Support

Support for HTTP 425 Too Early status code: 
@Response<ErrorResponse>(425, 'Too Early')
@Post('process')
public async processRequest(): Promise<SuccessResponse> {
  // Handle early requests
}

​
Base Path Slash Options

Improved handling of base path slashes for more flexible routing:
tsoa.json
{
  "routes": {
    "basePath": "/api/v1",
    "routesDir": "./src"
  }
}
v7 properly handles both /api/v1 and api/v1 configurations.

​
Migration Steps

1

Update dependencies

Update your package.json to use tsoa v7:
package.json
{
  "dependencies": {
    "tsoa": "^7.0.0-alpha.0"
  },
  "devDependencies": {
    "@types/node": "^18.0.0",
    "typescript": "^5.7.2"
  }
}
Then install:
npm install
# or
yarn install
2

Update TypeScript configuration

Ensure your tsconfig.json uses TypeScript 5.x features:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
3

Choose your OpenAPI version

Decide whether to use OpenAPI 3.0.x or 3.1.0:
Update to OpenAPI 3.1.0:
tsoa.json
{
  "spec": {
    "specVersion": 3.1,
    // ... other config
  }
}
Verify that your API documentation tools and clients support OpenAPI 3.1.0.
4

Regenerate routes and spec

Regenerate your routes and OpenAPI specification:
npx tsoa spec-and-routes
5

Test validation

Test your API thoroughly, especially:
  • Circular reference models
  • Deep nested object validation
  • Generic type parameters
  • Tuple types (if using OpenAPI 3.1.0)
6

Update API documentation

If using OpenAPI 3.1.0, update your API documentation tooling:
  • Swagger UI: Use version 4.15.0 or higher
  • Redoc: Use version 2.0.0 or higher
  • Postman: Ensure you’re using a recent version

​
Deprecated Features

​
Multer Options in Config

The multerOpts configuration option in tsoa.json is now deprecated:
Deprecated (Still works in v7)
{
  "multerOpts": {
    "dest": "/tmp"
  }
}
Recommended
import { RegisterRoutes } from './routes';
import multer from 'multer';

const upload = multer({ dest: '/tmp' });

RegisterRoutes(app, {
  multer: upload,
});
multerOpts in config will be removed in a future version. Migrate to passing multer options to RegisterRoutes.

​
Package Structure

tsoa v7 maintains the same package structure as v6:
  • tsoa: Main package (includes both CLI and runtime)
  • @tsoa/cli: CLI tools for code generation
  • @tsoa/runtime: Runtime decorators and types
All packages are at version 7.0.0-alpha.0.

​
Dependency Updates

Key dependency updates in v7:
Packagev6v7
TypeScript^5.3.3^5.7.2
Node.js>=18.0.0>=18.0.0
validator^13.11.0^13.12.0
glob^10.3.10^10.4.5+
reflect-metadata^0.1.13^0.2.2

​
Rollback Plan

If you encounter issues with v7, you can rollback to v6:
package.json
{
  "dependencies": {
    "tsoa": "^6.6.1"
  }
}
Then reinstall dependencies and regenerate: 
npm install
npx tsoa spec-and-routes

​
Getting Help

If you encounter migration issues:

​
Next Steps

Configuration Reference

Review all configuration options for tsoa v7

OpenAPI Versions

Learn about OpenAPI 3.0.x vs 3.1.0 differences

Validation

Understand validation improvements in v7

GitHub Releases

View all release notes and changelogs

Build docs developers (and LLMs) love

Get started for freeTalk to us