Valibot Plugin

Generate Valibot validation schemas from OpenAPI specifications

The Valibot plugin generates Valibot schemas from your OpenAPI specification. Valibot is a modular and lightweight schema library with excellent bundle size, making it ideal for client-side applications.

Installation

Install the required dependencies:

npm install valibot @hey-api/openapi-ts

Configuration

Add the Valibot plugin to your openapi-ts.config.ts:

openapi-ts.config.ts

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: 'path/to/openapi.json',
  output: {
    path: './src/client',
  },
  plugins: [
    '@hey-api/typescript',
    {
      name: '@hey-api/valibot',
      // Configuration options
    },
  ],
});

Schema Generation

Definitions

Generate schemas for reusable component definitions:

{
  name: '@hey-api/valibot',
  definitions: true,  // Enable definitions (default)
}

Customize definition schema names and casing:

{
  name: '@hey-api/valibot',
  definitions: {
    enabled: true,
    name: 'v{{name}}',  // Naming pattern (default)
    case: 'camelCase',  // Identifier casing
  },
}

Generated output:

valibot.gen.ts

import * as v from 'valibot';

/**
 * A pet in the pet store
 */
export const vPet = v.object({
  id: v.pipe(v.number(), v.integer()),
  name: v.string(),
  status: v.optional(v.picklist(['available', 'pending', 'sold'])),
});

Requests

Generate validators for API request data (body, query, path, headers):

{
  name: '@hey-api/valibot',
  requests: {
    enabled: true,
    name: 'v{{name}}Data',  // Naming pattern
    case: 'camelCase',
  },
}

Generated output:

valibot.gen.ts

export const vGetPetByIdData = v.object({
  path: v.object({
    petId: v.pipe(v.number(), v.integer()),
  }),
  query: v.optional(v.object({
    includeDetails: v.optional(v.boolean()),
  })),
});

Responses

Generate validators for API responses:

{
  name: '@hey-api/valibot',
  responses: {
    enabled: true,
    name: 'v{{name}}Response',  // Naming pattern
    case: 'camelCase',
  },
}

Generated output:

valibot.gen.ts

export const vGetPetByIdResponse = v.object({
  id: v.pipe(v.number(), v.integer()),
  name: v.string(),
  status: v.optional(v.picklist(['available', 'pending', 'sold'])),
});

Webhooks

Generate validators for webhook payloads:

{
  name: '@hey-api/valibot',
  webhooks: {
    enabled: true,
    name: 'v{{name}}WebhookRequest',
    case: 'camelCase',
  },
}

Valibot Pipes

Valibot uses a pipe-based architecture for transformations and validations. The plugin generates schemas using Valibot’s pipe syntax:

// String with length constraints
v.pipe(
  v.string(),
  v.minLength(3),
  v.maxLength(50)
)

// Number with range constraints
v.pipe(
  v.number(),
  v.integer(),
  v.minValue(1),
  v.maxValue(100)
)

// String with pattern validation
v.pipe(
  v.string(),
  v.regex(/^[a-zA-Z0-9_]*$/)
)

Metadata Support

Enable Valibot metadata for additional schema information:

{
  name: '@hey-api/valibot',
  metadata: true,  // Enable metadata (default: false)
}

Metadata is useful for documentation, code generation, AI structured outputs, and form validation.

Usage Examples

Validating API Requests

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

// Validate request data
const result = v.safeParse(vCreatePetData, {
  body: {
    name: 'Fluffy',
    status: 'available',
  },
});

if (result.success) {
  // Data is valid and typed
  await fetch('/api/pets', {
    method: 'POST',
    body: JSON.stringify(result.output.body),
  });
} else {
  // Handle validation errors
  console.error(result.issues);
}

Validating API Responses

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

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

// Validate and parse response
const pet = v.parse(vGetPetByIdResponse, data);
// pet is now fully typed

Async Validation

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

// Use parseAsync for async validation
const data = await v.parseAsync(vCreatePetData, requestData);

Type Inference

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

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

const pet: Pet = {
  id: 1,
  name: 'Fluffy',
};

Form Validation with React

import * as v from 'valibot';
import { useState } from 'react';
import { vCreatePetData } from './client/valibot.gen';

// Extract the body schema from the request data schema
const CreatePetSchema = vCreatePetData.entries.body;
type CreatePetForm = v.InferOutput<typeof CreatePetSchema>;

function CreatePetForm() {
  const [formData, setFormData] = useState<Partial<CreatePetForm>>({});
  const [errors, setErrors] = useState<string[]>([]);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

    // Validate form data
    const result = v.safeParse(CreatePetSchema, formData);

    if (result.success) {
      await fetch('/api/pets', {
        method: 'POST',
        body: JSON.stringify(result.output),
      });
      setErrors([]);
    } else {
      setErrors(result.issues.map(issue => issue.message));
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={formData.name || ''}
        onChange={(e) => setFormData({ ...formData, name: e.target.value })}
      />

      <select
        value={formData.status || ''}
        onChange={(e) => setFormData({ ...formData, status: e.target.value })}
      >
        <option value="available">Available</option>
        <option value="pending">Pending</option>
        <option value="sold">Sold</option>
      </select>

      {errors.length > 0 && (
        <ul>
          {errors.map((error, i) => <li key={i}>{error}</li>)}
        </ul>
      )}

      <button type="submit">Create Pet</button>
    </form>
  );
}

String Formats

Valibot automatically generates appropriate validators for OpenAPI string formats:

OpenAPI Format	Valibot Validator
date	v.isoDate()
date-time	v.isoTimestamp()
email	v.email()
ipv4, ipv6	v.ip()
time	v.isoTimeSecond()
uri	v.url()
uuid	v.uuid()

Example:

# OpenAPI specification
User:
  type: object
  properties:
    email:
      type: string
      format: email
    website:
      type: string
      format: uri
    createdAt:
      type: string
      format: date-time

Generated schema:

export const vUser = v.object({
  email: v.pipe(v.string(), v.email()),
  website: v.pipe(v.string(), v.url()),
  createdAt: v.pipe(v.string(), v.isoTimestamp()),
});

Advanced Configuration

Custom Naming Patterns

Use functions for dynamic naming:

{
  name: '@hey-api/valibot',
  definitions: {
    name: (name: string) => `valibotSchema${name}`,
  },
  requests: {
    name: (name: string) => `${name}RequestSchema`,
  },
}

Selective Schema Generation

Disable specific schema categories:

{
  name: '@hey-api/valibot',
  definitions: true,
  requests: false,    // Don't generate request schemas
  responses: true,
  webhooks: false,    // Don't generate webhook schemas
}

Global Configuration

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: 'path/to/openapi.json',
  output: {
    path: './src/client',
  },
  plugins: [
    '@hey-api/typescript',
    {
      name: '@hey-api/valibot',
      case: 'camelCase',
      comments: true,
      metadata: false,
      definitions: {
        name: 'v{{name}}',
      },
      requests: {
        name: 'v{{name}}Data',
      },
      responses: {
        name: 'v{{name}}Response',
      },
    },
  ],
});

Bundle Size Benefits

Valibot is designed to be tree-shakable and has a smaller bundle size compared to other validation libraries:

• Modular architecture: Only import what you need
• Tree-shakable: Unused validators are removed during bundling
• Minimal runtime: Core functionality is lightweight
• Pipe-based composition: Efficient schema composition

Example bundle comparison:

// Only the validators you use are included in your bundle
import * as v from 'valibot';

// This only bundles: object, string, number, integer, pipe
const schema = v.object({
  name: v.string(),
  age: v.pipe(v.number(), v.integer()),
});

Type Reference

The Valibot plugin exports these configuration types:

import type { ValibotPlugin } from '@hey-api/valibot';
import { defineConfig } from '@hey-api/valibot';

// Use the type helper for better type safety
const valibotConfig = defineConfig({
  name: '@hey-api/valibot',
  // ... your configuration
});

Migration from Zod

If you’re migrating from Zod to Valibot:

Zod

import { z } from 'zod';

const schema = z.object({
  name: z.string().min(3).max(50),
  age: z.number().int().min(0),
});

type User = z.infer<typeof schema>;

const result = schema.safeParse(data);
if (result.success) {
  console.log(result.data);
}

Valibot

import * as v from 'valibot';

const schema = v.object({
  name: v.pipe(v.string(), v.minLength(3), v.maxLength(50)),
  age: v.pipe(v.number(), v.integer(), v.minValue(0)),
});

type User = v.InferOutput<typeof schema>;

const result = v.safeParse(schema, data);
if (result.success) {
  console.log(result.output);
}

Key differences:

• Valibot uses v.pipe() for chaining validators instead of method chaining
• Valibot uses InferOutput instead of infer
• Valibot’s parse result uses output instead of data
• Valibot’s validation issues use a different structure

Related

Validators Overview

Learn about validator plugins and their benefits

Zod Plugin

Alternative validator with method chaining syntax

Valibot Documentation

Official Valibot library documentation