メインコンテンツまでスキップ

Validation

Zelt uses Valibot for request validation, providing a type-safe and lightweight validation solution.

Installation​

npm install @zeltjs/validator-valibot valibot

OpenAPI 生成を使う場合​

@zeltjs/openapi で OpenAPI スペックを生成する場合は、@valibot/to-json-schema も必要です：

npm install @zeltjs/validator-valibot valibot @valibot/to-json-schema

:::tip バージョン互換性 @valibot/to-json-schema は valibot のバージョンと合わせる必要があります。例：

  • valibot@1.4.x → @valibot/to-json-schema@1.7.x
  • valibot@1.3.x → @valibot/to-json-schema@1.6.x

互換性については @valibot/to-json-schema releases を参照してください。 :::

Basic Usage​

Use validated() with a Valibot schema to validate request bodies:

import { Controller, Post, response } from '@zeltjs/core';
import { validated } from '@zeltjs/validator-valibot';
import * as v from 'valibot';

const CreateUserSchema = v.object({
  name: v.pipe(v.string(), v.minLength(1), v.maxLength(100)),
  email: v.pipe(v.string(), v.email()),
  age: v.optional(v.pipe(v.number(), v.minValue(0), v.maxValue(150))),
});

@Controller('/users')
export class UserController {
  @Post('/')
  create(body = validated(CreateUserSchema), res = response()) {
    // body is fully typed: { name: string; email: string; age?: number }
    return res.json({ id: '1', ...body }, 201);
  }
}

Form Data and File Uploads​

Use validated(schema, 'form') to validate multipart/form-data requests, including file uploads:

import { Controller, Post, response } from '@zeltjs/core';
import { validated } from '@zeltjs/validator-valibot';
import * as v from 'valibot';

const UploadSchema = v.object({
  file: v.instance(File),
  description: v.optional(v.string()),
});

@Controller('/upload')
export class UploadController {
  @Post('/')
  upload(body = validated(UploadSchema, 'form'), res = response()) {
    // body.file is a File object
    console.log(body.file.name, body.file.size, body.file.type);
    return res.json({ filename: body.file.name, size: body.file.size }, 201);
  }
}

Target Options​

The second argument to validated() specifies the request body format:

TargetContent-TypeUse Case
'json' (default)application/jsonJSON API requests
'form'multipart/form-data, application/x-www-form-urlencodedFile uploads, HTML forms

Multiple Files​

const MultiUploadSchema = v.object({
  files: v.array(v.instance(File)),
  category: v.string(),
});

@Controller('/upload')
class BulkUploadController {
  @Post('/bulk')
  bulkUpload(body = validated(MultiUploadSchema, 'form')) {
    for (const file of body.files) {
      console.log(file.name);
    }
    return { count: body.files.length };
  }
}

OpenAPI Generation​

When using 'form' target, OpenAPI output automatically uses multipart/form-data as the content type:

requestBody:
  required: true
  content:
    multipart/form-data:
      schema:
        $ref: '#/components/schemas/UploadSchema'

Validation Error Response​

When validation fails, Zelt automatically returns a 400 response:

{
  "code": "VALIDATION_FAILED",
  "issues": [
    {
      "kind": "validation",
      "type": "email",
      "message": "Invalid email",
      "path": ["email"]
    }
  ]
}

See Error Handling for more details on error responses.

Common Validations​

String Validations​

const schema = v.object({
  username: v.pipe(
    v.string(),
    v.minLength(3),
    v.maxLength(20),
    v.regex(/^[a-z0-9_]+$/i)
  ),
  email: v.pipe(v.string(), v.email()),
  url: v.pipe(v.string(), v.url()),
  uuid: v.pipe(v.string(), v.uuid()),
});

Number Validations​

const schema = v.object({
  age: v.pipe(v.number(), v.minValue(0), v.maxValue(150)),
  price: v.pipe(v.number(), v.minValue(0)),
  quantity: v.pipe(v.number(), v.integer(), v.minValue(1)),
});

Array Validations​

const schema = v.object({
  tags: v.pipe(
    v.array(v.string()),
    v.minLength(1),
    v.maxLength(10)
  ),
  scores: v.array(v.pipe(v.number(), v.minValue(0), v.maxValue(100))),
});

Optional and Nullable​

const schema = v.object({
  required: v.string(),
  optional: v.optional(v.string()),
  nullable: v.nullable(v.string()),
  optionalNullable: v.optional(v.nullable(v.string())),
  withDefault: v.optional(v.string(), 'default value'),
});

Nested Objects​

const AddressSchema = v.object({
  street: v.string(),
  city: v.string(),
  country: v.string(),
  zipCode: v.optional(v.string()),
});

const UserSchema = v.object({
  name: v.string(),
  address: AddressSchema,
  alternateAddresses: v.optional(v.array(AddressSchema)),
});

Type Inference​

Valibot schemas provide automatic TypeScript type inference:

const UserSchema = v.object({
  name: v.string(),
  age: v.number(),
});

// Infer the type from schema
type User = v.InferOutput<typeof UserSchema>;
// Equivalent to: { name: string; age: number }

Why Valibot?​

  • Type-safe — Full TypeScript support with automatic type inference
  • Lightweight — Tree-shakeable, only includes what you use
  • Fast — Optimized for runtime performance
  • Composable — Build complex schemas from simple building blocks