Standard Schema - Giao diện chung cho Validation trong TypeScript

• Một đặc tả được thiết kế để các thư viện schema dựa trên JavaScript/TypeScript cùng triển khai một giao diện chung
• Mục tiêu là cho phép tái sử dụng logic kiểm chứng kiểu do người dùng định nghĩa giữa các thư viện khác nhau, giúp các công cụ tương thích với nhau mà không cần adapter riêng
• Được đồng thiết kế bởi các tác giả của những thư viện lớn như Zod, Valibot, ArkType

Giao diện chính (StandardSchemaV1)

• Toàn bộ đặc tả được triển khai thông qua thuộc tính đối tượng ~standard
• Bên trong ~standard có các thuộc tính bắt buộc như version, vendor, validate, types
• Hàm validate trả về value khi thành công, và mảng issues khi thất bại
• Thuộc tính types cho phép suy luận kiểu đầu vào (input) và đầu ra (output) của schema trong TypeScript
• Mọi bản cập nhật đều duy trì khả năng tương thích nếu không phải major version

Mục tiêu thiết kế

• Hỗ trợ validation lúc runtime: Chuẩn hóa cách truyền thông tin lỗi theo phương thức tiêu chuẩn
• Hỗ trợ suy luận kiểu tĩnh: Các thư viện dựa trên TypeScript có thể công khai rõ ràng thông tin kiểu đã suy luận
• Tính gọn nhẹ: Có thể triển khai bằng cách thêm chỉ vài dòng vào các hàm hiện có của thư viện
• Tránh xung đột API: Đặt toàn bộ nội dung trong một namespace ~standard để không va chạm với API hiện có
• Giữ nguyên trải nghiệm lập trình viên: Dùng tiền tố dấu ngã (~) trong ~standard để hạ ưu tiên trong tự động hoàn thành

Những thư viện nào đang triển khai

• Hiện đã có hỗ trợ Standard Schema trong Zod, Valibot, ArkType, Arri Schema, TypeMap và nhiều thư viện khác
• tRPC, TanStack Form, TanStack Router, Hono Middleware cũng chấp nhận schema người dùng dựa trên Standard Schema

Cách triển khai đặc tả vào thư viện của bạn

• Sao chép interface StandardSchemaV1 vào thư viện và thêm thuộc tính ~standard
• Nối hàm validate với hàm kiểm chứng hiện có để khi thành công trả về { value }, và khi thất bại trả về { issues }
• Có thể hỗ trợ validation bất đồng bộ khi cần, nhưng khuyến nghị dùng validation đồng bộ

Cách nhận schema do người dùng định nghĩa bằng Standard Schema

• Nếu muốn dùng trực tiếp mà không cần thư viện schema, có thể cài @standard-schema/spec hoặc sao chép interface để sử dụng
• Nếu schema có giao diện chuẩn như ví dụ standardValidate, thì có thể kiểm tra tính hợp lệ theo cùng một cách bất kể nó đến từ thư viện nào
• Nếu chỉ muốn cho phép validation đồng bộ, có thể kiểm tra xem giá trị trả về của validate có phải Promise hay không rồi xử lý ngoại lệ

FAQ

• Có cần thêm dependency @standard-schema/spec không?: Không bắt buộc phải thêm dependency, có thể sao chép rồi dùng
• Không thể thêm dưới dạng dev dependency: Vì đây là một phần của public API của thư viện nên phải dùng được cả trong môi trường triển khai thực tế
• Vì sao dùng dấu ngã (~) trước ~standard: Nhằm để nó xuất hiện phía sau các thuộc tính khác trong danh sách tự động hoàn thành
• Vì sao dùng khóa chuỗi thay vì Symbol: Vì khóa Symbol trong TypeScript có thể gây vấn đề với sắp xếp tự động hoàn thành và suy luận kiểu