03 / 09
Şema, tip çıkarımı, hata mesajları ve dönüşüm.
TypeScript tipleri derlemeden sonra silinir. Formdan, URL'den ya da bir API'den gelen veri çalışma anında ne olduğunu bilmediğiniz bir değerdir. Zod bu değeri bir şemaya göre doğrular ve aynı şemadan TypeScript tipini çıkarır. Böylece kural ve tip tek bir yerde durur.1
Bu ders Zod 4.6 ile yazıldı:2
$ pnpm add zodimport { z } from "zod";
export const signUpSchema = z.object({
name: z.string().trim().min(2),
email: z.email(),
age: z.number().int().min(18),
newsletter: z.boolean(),
});
export type SignUp = z.infer<typeof signUpSchema>;
// { name: string; email: string; age: number; newsletter: boolean }Zod 4'te e-posta, URL ve UUID gibi biçimler üst düzey fonksiyonlardır: z.email(), z.url(), z.uuid(). Eski z.string().email() yazımı çalışır ama kullanımdan kaldırılmıştır.34
signUpSchema.parse(input); // geçersizse ZodError fırlatır
const result = signUpSchema.safeParse(input);
if (!result.success) {
console.log(result.error.issues);
} else {
result.data; // SignUp tipinde, temizlenmiş veri
}Formlarda ve Server Action'larda safeParse kullanın; hata beklenen bir durumdur, istisna değil.1 Yalnızca evet/hayır gerekiyorsa Zod 4.6 ile gelen .validate() hata nesnesi kurmadan boolean döndürür:5
if (signUpSchema.validate(input)) {
input.email; // tip daraltıldı
}Zod 4'te mesaj, error parametresiyle ya da doğrudan metinle verilir:6
z.string().min(2, "The name must be at least 2 characters.");
z.string().min(2, { error: "The name must be at least 2 characters." });
z.number({ error: "Enter your age." }); // tip hatası içinZod 3'teki message, invalid_type_error ve required_error yerine artık tek parametre error var. İnternetteki eski örneklerde (Next.js'in form rehberindeki örnek dahil) hâlâ bu adları görebilirsiniz.7
Türkçe varsayılan mesajlar. Zod'un yerleşik dil paketleri var. Uygulamanın girişinde bir kez ayarlayın:6
import { z } from "zod";
import { tr } from "zod/locales";
z.config(tr());
z.string().min(2).safeParse("a").error?.issues[0].message;
// "Çok küçük: beklenen string >=2 karakter"Bu mesajlar geneldir ve son kullanıcı için teknik kalır. Kullanıcının göreceği alanlarda kendi mesajınızı yazın; dil paketi unuttuğunuz yerler için güvenlik ağıdır.
Bir kural birden fazla alana bakıyorsa nesneye .refine ekleyin. path hatanın hangi alana yazılacağını seçer:8
const passwordSchema = z
.object({
password: z.string().min(8, "The password must be at least 8 characters."),
confirmPassword: z.string(),
})
.refine((data) => data.password === data.confirmPassword, {
error: "The passwords do not match.",
path: ["confirmPassword"],
});Uyarı
Nesnedeki bir alanda tip hatası varsa (seçilmemiş enum, NaN sayı) nesnenin .refine'ı hiç çalışmaz. Zod refinement'a yalnızca tipi doğru veriyi verir. Kullanıcı başka bir alanı düzeltene kadar "The passwords do not match." görünmez. Gerekirse when seçeneğiyle refine'ın hangi koşulda çalışacağını kendiniz belirleyin.8
.transform doğrulanan değeri başka bir değere çevirir. Şemanın girdi ve çıktı tipi artık farklıdır:9
const priceSchema = z
.string()
.regex(/^\d+(,\d{1,2})?$/, "Enter the price as 1250,50.")
.transform((value) => Number(value.replace(",", ".")));
type PriceInput = z.input<typeof priceSchema>; // string
type PriceOutput = z.output<typeof priceSchema>; // number.pipe bir şemanın çıktısını ikinci bir şemaya verir. Dönüşümden sonra tekrar doğrulamak için kullanılır:9
const ibanSchema = z
.string()
.transform((digits) => `TR${digits}`)
.pipe(z.iban("The IBAN is invalid; check the number."));Girdi ve çıktı tipinin ayrılması formlarda önemlidir: form girdi tipini tutar, gönderim çıktı tipini alır (bkz. React Hook Form ile Zod).
Formdan gelen değer çoğu zaman metindir ve boş alan ""'dır, undefined değil. Üç sık hata:
// Boş bırakılabilir URL
website: z.union([z.url("Enter the website as https://example.com."), z.literal("")]),
// Zorunlu sayı: boş metni önce yakalayın
age: z.string().min(1, "Enter your age.").pipe(z.coerce.number<string>().int().min(18)),z.coerce.number()'ın girdi tipi unknown'dır; şemayı formla kullanırken bu tip useForm'a da yansır. pipe ile bağlarken girdi tipini generic ile verin: z.coerce.number<string>().11
result.error.issues ham listedir. Zod 4 üç yardımcı verir:12
const result = signUpSchema.safeParse(input);
if (!result.success) {
z.flattenError(result.error);
// { formErrors: [], fieldErrors: { email: ["Geçersiz e-posta adresi"] } }
z.treeifyError(result.error); // iç içe nesne ve diziler için
z.prettifyError(result.error); // log için okunur metin
}Düz formlarda z.flattenError yeterlidir; sunucudan alan hatası döndürmek için kullanacaksınız. Zod 3'teki error.flatten() ve error.format() kullanımdan kaldırıldı.12
Zod 4.5 ve 4.6 formlarda işe yarayan iki biçim ekledi:513
z.creditCard(); // 12-19 hane ve Luhn sağlaması; boşluklu "4111 1111 1111 1111" geçerli
z.iban(); // elektronik biçim: boşluksuz, büyük harf, mod-97 sağlamasıTelefon için z.e164() (+905321234567) hazır gelir.3 Maskeli alanlarda bu biçimleri ham değer üzerinde nasıl kullanacağınız Maskeleme ve regex dersinde.
signUpSchema'yı yazıp safeParse'a { name: " a", email: "x@", age: "20" } verin. Kaç hata çıkıyor? age neden hata veriyor?
z.config(tr()) ekleyip aynı denemeyi yapın.
Şifre şemasına role: z.enum(["buyer", "seller"]) ekleyin, role: "" ve farklı şifreler verin. "The passwords do not match." görünüyor mu?
z.url().optional()'a "" verin, sonra z.literal("") ile birleştirin.
priceSchema için z.input ve z.output tiplerini editörde fareyle inceleyin.
Resmi doküman: "Basic usage"; şema, parse ve tip çıkarımı.1
Resmi doküman: "Customizing errors"; error parametresi, öncelik sırası ve dil paketleri.6
Resmi doküman: "Migration guide"; Zod 3'ten 4'e değişen API'ler.7
Kaynaklar
Şema tanımlamak, `parse`, `safeParse` ve `z.infer`.
Kurulum ve gereksinimler.
Üst düzey string biçimleri, `z.e164`, `z.creditCard` ve `z.iban`.
Zod 4'teki yenilikler ve üst düzey biçim fonksiyonları.
9 Eylül 2026. `.validate()` ve `z.iban()`.
`error` parametresi ve `z.config` ile dil paketleri.
`message`, `invalid_type_error`, `required_error` ve `flatten`'ın yerini alanlar.
`.refine`, `path`, `abort` ve `when`.
`.transform`, `.pipe`, `z.input` ve `z.output`.
`optional`'ın yalnızca `undefined`'ı kabul etmesi.
`z.coerce` ve girdi tipinin `unknown` olması.
`z.flattenError`, `z.treeifyError` ve `z.prettifyError`.
28 Ağustos 2026. `z.creditCard()` ve diğer yenilikler.
Dersin ana fikirlerini üç soruyla kontrol edin.
İlerlemeniz yalnızca bu tarayıcıda saklanır.
Son güncelleme tarihi: 3 Kasım 2026