Validators

Validators ensure incoming request data is correct before it reaches your controller or service. Arkos supports two validation libraries — Zod and class-validator — and integrates them directly into route definitions so validation runs automatically.

How Validation Works

You attach a schema or DTO to a route's validation config. Arkos validates the request against it before calling your handler. If validation fails, Arkos responds with a 400 error automatically — your handler never runs.

postRouter.post(
  {
    path: "/api/posts",
    validation: { body: CreatePostSchema },
  },
  postController.createOne
);

The validation object accepts three optional keys: body, query, and params.

Zod

src/modules/post/schemas/create-post.schema.ts

import { z } from "zod";

const CreatePostSchema = z.object({
  title: z.string().min(1),
  body: z.string().min(1),
  published: z.boolean().optional(),
});

export type CreatePostSchemaType = z.infer<typeof CreatePostSchema>;

export default CreatePostSchema;

Class Validator

src/modules/post/dtos/create-post.dto.ts

import { IsString, IsNotEmpty, IsBoolean, IsOptional } from "class-validator";

export default class CreatePostDto {
  @IsNotEmpty()
  @IsString()
  title!: string;

  @IsNotEmpty()
  @IsString()
  body!: string;

  @IsOptional()
  @IsBoolean()
  published?: boolean;
}

Attaching to Routes

src/modules/post/post.router.ts

import { ArkosRouter } from "arkos";
import CreatePostSchema from "./schemas/create-post.schema";
import QueryPostSchema from "./schemas/query-post.schema";
import postController from "./post.controller";

const postRouter = ArkosRouter();

postRouter.get(
  {
    path: "/api/posts",
    validation: { query: QueryPostSchema },
  },
  postController.findMany
);

postRouter.post(
  {
    path: "/api/posts",
    validation: { body: CreatePostSchema },
  },
  postController.createOne
);

export default postRouter;

Validation on Built-in Routes

For auto-generated routes, attach validation through a Route Hook:

src/modules/post/post.router.ts

import { ArkosRouter, RouteHook } from "arkos";
import CreatePostSchema from "./schemas/create-post.schema";
import UpdatePostSchema from "./schemas/update-post.schema";

export const hook: RouteHook = {
  createOne: { validation: { body: CreatePostSchema } },
  updateOne: { validation: { body: UpdatePostSchema } },
};

const postRouter = ArkosRouter();

export default postRouter;

RouteHook is the new name for export const config: RouterConfig. Existing code still works but logs a deprecation warning. See Route Hooks for details.

Scaffold with the CLI

Generate schemas or DTOs from your Prisma model automatically:

# Zod
arkos generate create-schema --module post
arkos generate update-schema --module post
arkos generate query-schema --module post

# class-validator
arkos generate create-dto --module post
arkos generate update-dto --module post
arkos generate query-dto --module post

Routers — Attach validators to routes
Route Hooks — Attach validators to auto-generated routes
CLI — Validation — Generate schemas and DTOs from your Prisma schema

How Validation Works

Zod

Class Validator

Attaching to Routes

Validation on Built-in Routes

Scaffold with the CLI

Related

On this page