Validation & Type Safety with Zod

Deterministic validation layer ensuring that all data entering the system conforms to the defined architectural contracts.

Zod Validation Architecture

Benefits: Zod allows combining runtime validation with TypeScript typing, creating a single source of truth for forms and API data.

Zod Schema & Types Structure

Naming Conventions

Zod Schemas:
Located in schema/. Strictly one pair per operation: [name]-create.schema.ts ↔ [name]-create-form.types.ts. Runtime only — no z.infer exports here; ENUM_FORM_* is imported by the direct file path, not the ../types barrel.
Types & Interfaces:
Located in types/[name]-[op]-form.types.ts. z.infer form types (e.g. TEntityCreateSchema) and ENUM_FORM_... live here, never in schema files. The schema is imported only via import type.

01Schema Definition

Creating a Zod object using i18nKey for localized error messages.

entities/entity-name/schema/entity-name-create.schema.ts

import { z } from "zod";
import { type TEntityPageKeys, i18nKey } from "@/shared/config";
// прямой путь к form.types — не barrel "../types" (нет цикла schema ↔ types)
import { ENUM_FORM_ENTITY_CREATE } from "../types/entity-name-create-form.types";

const msg = i18nKey<TEntityPageKeys>();
const F = ENUM_FORM_ENTITY_CREATE;

/** Runtime only — never export inferred types from schema files.
 *  Одна схема на операцию: update — в entity-name-update.schema.ts */
export const ENTITY_CREATE_SCHEMA = z.object({
	[F.DESCRIPTION]: z
		.string()
		.trim()
		.min(1, {
			message: msg("form.overview.fields.description.errors.required")
		})
		.min(3, {
			message: msg("form.overview.fields.description.errors.min")
		})
		.max(5000, {
			message: msg("form.overview.fields.description.errors.max")
		}),
});

02Type Inference

Using z.infer to automatically generate TypeScript types from the schema.

entities/entity-name/types/entity-name-create-form.types.ts

import type { FieldValues } from "react-hook-form";
import { z } from "zod";
// только import type — в рантайме зависимость schema → form.types односторонняя
import type { ENTITY_CREATE_SCHEMA } from "../schema";

export const ENUM_FORM_ENTITY_CREATE = {
	DESCRIPTION: "description",
} as const;

export type ENUM_FORM_ENTITY_CREATE_TYPE =
	(typeof ENUM_FORM_ENTITY_CREATE)[keyof typeof ENUM_FORM_ENTITY_CREATE];

/** z.infer and form enums live in types/ — пара к entity-name-create.schema.ts */
export type TEntityCreateSchema = z.infer<typeof ENTITY_CREATE_SCHEMA> &
	FieldValues;

03Form Integration

Connecting the schema to react-hook-form via zodResolver.

widgets/entity-name/ui/entity-name.tsx

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import {
	type TEntityCreateSchema,
	ENTITY_CREATE_SCHEMA,
} from "@/entities/entity-name";

const form = useForm<TEntityCreateSchema>({
    resolver: zodResolver(ENTITY_CREATE_SCHEMA),
    mode: "onSubmit"
});