Skip to main content
OpenAPI TypeScript supports generating runtime validation schemas from your OpenAPI specifications. Validators provide runtime type safety by validating data against your API contracts at runtime, catching errors before they reach your application logic.

​
Why Use Validators?

While TypeScript provides compile-time type safety, validators add runtime safety:
  • Runtime validation: Ensure data from external sources matches your expected types
  • Type inference: Generate TypeScript types from validation schemas
  • API contract enforcement: Validate requests and responses against your OpenAPI spec
  • Developer experience: Get instant feedback when data doesn’t match expectations

​
Available Validator Libraries

OpenAPI TypeScript supports multiple validation libraries:

Zod

TypeScript-first schema validation with static type inference

Valibot

Modular and lightweight schema library with excellent bundle size

​
How It Works

Validator plugins generate schemas from your OpenAPI specification that can validate:
  1. Definitions - Reusable component schemas
  2. Requests - Request bodies, query parameters, path parameters, and headers
  3. Responses - Response bodies and status codes
  4. Webhooks - Webhook payload schemas

​
Quick Start

Add a validator plugin to your configuration: 
import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: 'path/to/openapi.json',
  output: {
    path: './src/client',
  },
  plugins: [
    '@hey-api/typescript',
    '@hey-api/sdk',
    {
      name: '@hey-api/zod',
    },
  ],
});
Generate your schemas: 
npx @hey-api/openapi-ts

​
Configuration Options

Both validator plugins share similar configuration patterns:

​
Schema Generation

Control which schemas are generated: 
{
  name: '@hey-api/zod', // or '@hey-api/valibot'
  definitions: true,    // Component schemas
  requests: true,       // Request validators
  responses: true,      // Response validators
  webhooks: true,       // Webhook validators
}

​
Naming Patterns

Customize generated schema names: 
{
  name: '@hey-api/zod',
  definitions: {
    name: 'z{{name}}',  // Prefix with 'z'
  },
  requests: {
    name: 'z{{name}}Data',
  },
  responses: {
    name: 'z{{name}}Response',
  },
}

​
Casing Conventions

Set casing for generated identifiers: 
{
  name: '@hey-api/zod',
  case: 'camelCase',  // or 'PascalCase', 'snake_case', 'SCREAMING_SNAKE_CASE'
}

​
Usage Examples

​
Validating API Responses

import { zGetPetResponse } from './client/zod.gen';

const response = await fetch('/api/pets/1');
const data = await response.json();

// Validate and parse the response
const pet = await zGetPetResponse.parseAsync(data);
// pet is now fully typed and validated

​
Validating Request Data

import { zCreatePetData } from './client/zod.gen';

// Validate request data before sending
const requestData = await zCreatePetData.parseAsync({
  name: 'Fluffy',
  age: 3,
});

await fetch('/api/pets', {
  method: 'POST',
  body: JSON.stringify(requestData),
});

​
Type Inference

Generate TypeScript types from your validation schemas: 
import { z } from 'zod';
import { zPet } from './client/zod.gen';

// Infer TypeScript type from Zod schema
type Pet = z.infer<typeof zPet>;
Or enable automatic type generation: 
{
  name: '@hey-api/zod',
  types: {
    infer: true,  // Generate inferred types
  },
}

​
Next Steps

Zod Plugin

Learn about Zod-specific features and configuration

Valibot Plugin

Learn about Valibot-specific features and configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us