Zod Schema Generator - Tạo Zod Schema Từ JSON

Tính năng nổi bật

• Đọc JSON mẫu rồi dựng khối z.object đúng theo danh sách trường có trong object đó
• Suy kiểu tự động: chuỗi ra z.string, số nguyên ra z.number().int(), số thập phân ra z.number(), true/false ra z.boolean(), null ra z.null()
• Đi sâu vào object lồng nhau theo đệ quy, mỗi cấp sinh một z.object riêng chứ không gộp thành z.any()
• Mảng được suy từ phần tử đầu tiên thành z.array(kiểu phần tử), mảng rỗng thì trả về z.array(z.any())
• Sinh sẵn dòng export type bằng z.infer<typeof Schema> nên bạn có luôn kiểu tĩnh đi kèm schema
• Kèm dòng import { z } from "zod" ở đầu kết quả để khối mã dán thẳng vào file .ts là dùng được
• Ô tên schema tự chuẩn hóa về PascalCase và tự gắn hậu tố Schema, tên kiểu lấy phần còn lại sau khi bỏ hậu tố đó
• Dán vào một mảng thì công cụ lấy object đầu tiên làm mẫu; JSON sai cú pháp thì hiện đúng thông báo lỗi của bộ phân tích

Kiểu trong TypeScript biến mất lúc chạy, còn dữ liệu vào thì không

Khai báo một interface rồi ép kiểu response bằng as User không kiểm tra gì cả. Trình biên dịch tin lời bạn, xóa hết chú thích kiểu khi xuất ra JavaScript, và nếu máy chủ trả về createdAt là chuỗi thay vì số thì chương trình vẫn chạy tiếp cho tới khi vỡ ở một chỗ cách đó vài lớp hàm, thường là một lỗi undefined khó lần ngược về nguồn. Đó là lý do người ta cần một lớp kiểm tra thật sự tồn tại lúc chạy, đặt đúng tại ranh giới nhận dữ liệu: response từ API bên thứ ba, body của request, giá trị đọc từ localStorage, biến môi trường, dữ liệu form người dùng gõ vào. Zod làm việc đó, và điểm hay là schema Zod vừa kiểm tra lúc chạy vừa suy ra được kiểu tĩnh, nên bạn không phải duy trì hai bản mô tả cùng một cấu trúc. Việc gõ tay khối z.object cho một object hai ba chục trường thì lại chán và dễ sót trường, nhất là khi có object lồng nhau. Công cụ này lo phần gõ lặp đó để bạn tập trung vào phần thật sự cần suy nghĩ là các rule nghiệp vụ.

Lợi ích khi sử dụng

• •Có ngay khối z.object đủ trường thay vì gõ tay và sót mất vài trường ở cuối object dài
• •Object lồng nhau được dựng theo đúng cấu trúc, đỡ phải đếm ngoặc khi viết bằng tay
• •Dòng z.infer đi kèm giúp kiểu tĩnh và kiểm tra lúc chạy luôn khớp nhau vì cùng sinh từ một nguồn
• •Nhìn thấy toàn bộ trường của một response lạ trong vài giây, hữu ích khi đọc API chưa có tài liệu
• •Chạy hoàn toàn trong trình duyệt nên dán được cả JSON dài mà không phải chờ tải lên
• •Kết quả là mã Zod chuẩn, không phải định dạng riêng, nên chỉnh tiếp bằng tay rất tự nhiên

Năm bước từ JSON mẫu tới schema dùng được

1. 1Dán một JSON mẫu càng đầy đủ trường càng tốt vào ô bên trái, tốt nhất là một bản ghi thật có đủ mọi trường thay vì bản ghi đang thiếu vài giá trị.
2. 2Gõ tên schema vào ô phía trên, ví dụ User hoặc Product; công cụ tự chuyển về PascalCase và tự thêm hậu tố Schema nên bạn không cần gõ phần đuôi.
3. 3Đọc kết quả bên phải, đối chiếu từng dòng với ý định thật: trường nào có thể vắng mặt, trường nào có thể là null, trường nào chỉ nhận một tập giá trị cố định.
4. 4Bấm nút sao chép rồi dán vào một file .ts trong dự án, đặt cạnh nơi bạn gọi API hoặc khai báo form chứ đừng gom hết vào một file types dùng chung.
5. 5Bổ sung rule nghiệp vụ: thêm .optional() và .nullable() cho đúng trường, đổi z.string() thành z.enum([...]) khi giá trị có tập hữu hạn, thêm ràng buộc độ dài và định dạng, rồi mới dùng schema để parse dữ liệu thật.

Bảng suy kiểu công cụ đang dùng và những chỗ nó buộc phải đoán

Quy tắc suy kiểu ở đây rất thẳng và bạn nên nắm để biết chỗ nào cần sửa lại. Chuỗi cho ra z.string(). Số được xét thêm một bước: số nguyên cho ra z.number().int(), số có phần thập phân cho ra z.number(). Giá trị true hoặc false cho ra z.boolean(). Mảng lấy phần tử đầu tiên làm đại diện rồi bọc trong z.array, mảng rỗng không có gì để suy nên thành z.array(z.any()). Object được duyệt tiếp theo đệ quy, mỗi cấp là một z.object mới. Riêng null là chỗ đáng lưu ý nhất: công cụ trả về z.null(), tức là một schema chỉ chấp nhận đúng giá trị null và bác bỏ mọi giá trị khác. Gần như chắc chắn đó không phải ý bạn muốn, vì trong bản ghi mẫu trường đó tình cờ đang rỗng chứ bản chất nó là chuỗi hoặc số có thể vắng. Cách sửa là đổi thành dạng kiểu thật rồi thêm .nullable(), ví dụ z.string().nullable(). Điểm cần nhớ tiếp theo là JSON không có kiểu ngày tháng. Một chuỗi 2026-05-12T10:00:00Z vẫn chỉ là chuỗi nên kết quả là z.string(); nếu muốn nhận về đối tượng Date, bạn tự thêm bước chuyển đổi. Và vì công cụ chỉ nhìn đúng một bản ghi, nó không thể biết một trường vắng mặt trong mẫu là do không bắt buộc hay do bạn dán thiếu.

Bốn thứ phải tự thêm sau khi dán: bắt buộc, rỗng, tập giá trị và định dạng

Schema sinh ra coi mọi trường là bắt buộc và chỉ ràng buộc đúng kiểu nguyên thủy, nên có bốn nhóm rule bạn gần như luôn phải bổ sung. Thứ nhất là tính bắt buộc: trường nào có thể vắng khỏi object thì thêm .optional(), khác hẳn với .nullable() vốn dành cho trường có mặt nhưng mang giá trị null; hai khái niệm này hay bị nhầm và Zod phân biệt rõ, muốn cả hai thì dùng .nullish(). Thứ hai là tập giá trị hữu hạn: những trường như status, role, type thường chỉ nhận vài chuỗi cố định, để nguyên z.string() nghĩa là bạn chấp nhận mọi chuỗi rác lọt qua, thay bằng z.enum(["active", "banned"]) thì lỗi chính tả bị chặn ngay tại ranh giới. Thứ ba là định dạng chuỗi: email, URL, UUID đều có kiểm tra sẵn, ở Zod 3 viết là z.string().email() còn bản 4 chuyển sang dạng rút gọn z.email(), nên hãy theo phiên bản đang cài trong dự án. Thứ tư là giới hạn giá trị: .min() và .max() cho độ dài chuỗi và biên số, cộng thêm .refine() cho những rule liên quan nhiều trường như ngày kết thúc phải sau ngày bắt đầu. Bốn nhóm này là phần công cụ không đoán hộ được vì chúng nằm trong nghiệp vụ chứ không nằm trong dữ liệu mẫu.

z.infer và nguyên tắc một nguồn sự thật cho kiểu dữ liệu

Dòng cuối trong kết quả là export type Xxx = z.infer<typeof XxxSchema>, và nó quan trọng hơn vẻ ngoài. Cách làm phổ biến nhưng dở là viết một interface thủ công cho kiểu tĩnh, rồi viết thêm một schema cho việc kiểm tra lúc chạy. Hai bản mô tả đó lệch nhau chỉ sau vài lần sửa: ai đó thêm trường vào interface mà quên thêm vào schema, hoặc ngược lại, và trình biên dịch không hề báo gì vì chúng không liên quan tới nhau. Với z.infer, kiểu được rút ra trực tiếp từ schema nên không thể lệch: sửa schema là kiểu tự đổi theo, và mọi nơi đang dùng kiểu đó sẽ báo lỗi biên dịch nếu không còn hợp. Đây gọi là nguyên tắc một nguồn sự thật, và trong dự án TypeScript nó tiết kiệm rất nhiều lần sửa lặt vặt. Một mẹo đi kèm là phân biệt kiểu đầu vào với kiểu đầu ra khi schema có bước chuyển đổi: z.input lấy hình dạng trước khi chạy transform, z.output tương đương z.infer lấy hình dạng sau khi chạy. Với schema không có transform thì hai kiểu này giống nhau, nhưng khi bạn thêm .transform() để đổi chuỗi thành Date, việc dùng nhầm sẽ khiến kiểu ở lớp gọi bị sai. Nếu cần một bản mô tả cấu trúc độc lập ngôn ngữ để dùng chung cho nhiều nơi thay vì gắn với TypeScript, hãy dựng lược đồ tại /vi/tools/json-schema-generator.

Đặt schema ở đúng ranh giới: route handler, server action và React Hook Form

Schema chỉ có ích khi nằm đúng chỗ dữ liệu bên ngoài đi vào chương trình, và trong một dự án Next.js thường có bốn chỗ như vậy. Chỗ thứ nhất là route handler hoặc API route: đọc body rồi gọi safeParse, nhận về một object có trường success, nhánh thất bại trả mã 400 kèm chi tiết lỗi thay vì để dữ liệu xấu chạy xuống lớp dưới. Nên dùng safeParse thay cho parse ở đây vì parse ném lỗi, còn safeParse trả kết quả để bạn xử lý bằng if, hợp với việc trả về mã trạng thái HTTP. Chỗ thứ hai là server action: tham số vào từ form của trình duyệt nên tuyệt đối không tin, kiểm tra ngay dòng đầu tiên của hàm. Chỗ thứ ba là form phía client: cắm schema vào React Hook Form qua zodResolver trong gói @hookform/resolvers, khi đó thông báo lỗi bạn viết trong schema hiện thẳng dưới ô nhập, và cùng một schema dùng lại được ở phía máy chủ nên rule không bị lệch giữa hai phía. Chỗ thứ tư là biến môi trường: parse process.env ngay khi khởi động để ứng dụng chết sớm với thông báo rõ ràng thay vì chạy nửa chừng rồi lỗi vì thiếu khóa. Một lưu ý thực tế: dữ liệu từ form và từ query string luôn là chuỗi, nên với trường số hãy dùng z.coerce.number() để ép kiểu trước khi kiểm tra thay vì tự parseInt rải rác.

Ba trang sinh schema trên site khác nhau ở chỗ nào

Site có ba công cụ cùng nhận một JSON mẫu nhưng sinh ra ba thứ phục vụ ba tầng khác nhau, chọn nhầm là làm việc thừa. Trang này sinh mã Zod, tức một lớp kiểm tra chạy trong chương trình TypeScript của bạn, sống ở tầng ứng dụng và nói về việc dữ liệu đi vào có hợp lệ hay không. Trang /vi/tools/prisma-schema-generator sinh một khối model cho file schema.prisma, tức mô tả dành cho lớp ORM: nó nói về model, quan hệ giữa các model, migration và cách Prisma ánh xạ kiểu xuống cột thật. Trang /vi/tools/sql-create-table-generator sinh câu lệnh DDL thuần để chạy trực tiếp trong cơ sở dữ liệu, nói về kiểu cột của từng hệ quản trị, khóa chính, khóa ngoại, index và ràng buộc. Dữ liệu vào giống nhau nhưng đầu ra không thay thế được cho nhau: một schema Zod không tạo được bảng, một câu CREATE TABLE không chặn được request xấu. Trong một dự án đầy đủ bạn thường dùng cả hai đầu, Zod ở ranh giới ngoài và Prisma hoặc SQL ở ranh giới trong. Nếu bạn chỉ cần kiểu tĩnh thuần TypeScript không kèm kiểm tra lúc chạy, dùng /vi/tools/json-to-typescript nhẹ hơn. Nếu muốn vẽ toàn bộ mô hình dữ liệu nhiều bảng trước khi viết mã, xem /vi/tools/database-schema-designer.

Câu hỏi thường gặp (FAQ)

Từ khóa liên quan

• zod schema generator
• json to zod
• tạo zod schema từ json
• zod online
• zod validation typescript
• z.infer typescript
• z.object generator
• runtime validation typescript
• kiểm tra dữ liệu lúc chạy
• validate api response typescript
• zod nextjs server action
• zodresolver react hook form
• zod safeparse
• zod optional nullable
• zod enum
• zod coerce number
• typescript schema validation
• sinh schema từ json mẫu