Validators Overview

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:

Definitions - Reusable component schemas
Requests - Request bodies, query parameters, path parameters, and headers
Responses - Response bodies and status codes
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',
    },
  ],
});

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/valibot',
    },
  ],
});

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>;

import * as v from 'valibot';
import { vPet } from './client/valibot.gen';

// Infer TypeScript type from Valibot schema
type Pet = v.InferOutput<typeof vPet>;

Or enable automatic type generation:

{
  name: '@hey-api/zod',
  types: {
    infer: true,  // Generate inferred types
  },
}

Get Started

Configuration

Core Plugins

HTTP Clients

Validators

State Management

Web Frameworks

Advanced

Why Use Validators?

Available Validator Libraries

Zod

Valibot

How It Works

Quick Start

Configuration Options

Schema Generation

Naming Patterns

Casing Conventions

Usage Examples

Validating API Responses

Validating Request Data

Type Inference

Next Steps

Zod Plugin

Valibot Plugin

​Why Use Validators?

​Available Validator Libraries

Zod

Valibot

​How It Works

​Quick Start

​Configuration Options

​Schema Generation

​Naming Patterns

​Casing Conventions

​Usage Examples

​Validating API Responses

​Validating Request Data

​Type Inference

​Next Steps

Zod Plugin

Valibot Plugin

Why Use Validators?

Available Validator Libraries

How It Works

Quick Start

Configuration Options

Schema Generation

Naming Patterns

Casing Conventions

Usage Examples

Validating API Responses

Validating Request Data

Type Inference

Next Steps