Standard Schema - Antarmuka Umum untuk Validasi TypeScript

• Spesifikasi yang dirancang agar library skema berbasis JavaScript/TypeScript mengimplementasikan antarmuka umum
• Tujuannya adalah memungkinkan logika validasi tipe yang didefinisikan pengguna dapat digunakan ulang di berbagai library, sehingga tool dapat saling kompatibel tanpa adaptor terpisah
• Dirancang bersama oleh para pembuat library utama seperti Zod, Valibot, dan ArkType

Antarmuka utama (StandardSchemaV1)

• Seluruh spesifikasi diimplementasikan melalui properti objek bernama ~standard
• Di dalam ~standard terdapat properti wajib seperti version, vendor, validate, dan types
• Fungsi validate mengembalikan value saat berhasil, dan array issues saat gagal
• Melalui properti types, TypeScript dapat menginfer tipe input (input) dan output (output) dari skema
• Semua pembaruan akan menjaga kompatibilitas selama bukan perubahan versi mayor

Tujuan desain

• Dukungan validasi runtime: informasi error distandardisasi dan dikirimkan dengan cara yang konsisten
• Dukungan inferensi tipe statis: informasi tipe yang diinferensikan oleh library berbasis TypeScript diekspos secara eksplisit
• Kesederhanaan: dapat diimplementasikan hanya dengan menambahkan beberapa baris pada fungsi library yang sudah ada
• Menghindari benturan API: semua isi ditempatkan hanya dalam satu namespace ~standard agar tidak bertabrakan dengan API yang sudah ada
• Menjaga pengalaman pengembang: diawali dengan tilde (~) seperti ~standard agar prioritasnya lebih rendah dalam autocomplete

Library mana saja yang mengimplementasikannya

• Standard Schema sudah didukung oleh Zod, Valibot, ArkType, Arri Schema, TypeMap, dan lainnya
• tRPC, TanStack Form, TanStack Router, Hono Middleware, dan lainnya juga menerima skema pengguna berdasarkan Standard Schema

Cara mengimplementasikan spesifikasi ini di library Anda

• Salin antarmuka StandardSchemaV1 ke library lalu tambahkan properti ~standard
• Hubungkan fungsi validate ke fungsi validasi yang sudah ada agar mengembalikan { value } saat berhasil dan { issues } saat gagal
• Jika diperlukan, validasi asinkron juga dimungkinkan, tetapi validasi sinkron direkomendasikan

Cara menerima skema buatan pengguna dengan Standard Schema

• Jika ingin menggunakannya langsung tanpa library skema, instal @standard-schema/spec atau salin antarmukanya untuk digunakan
• Seperti pada contoh fungsi standardValidate, jika sebuah skema memiliki antarmuka standar, validasi dapat dilakukan dengan cara yang sama apa pun library-nya
• Jika hanya ingin mengizinkan validasi sinkron, cukup periksa apakah nilai balik validate adalah Promise lalu tangani sebagai pengecualian

FAQ

• Apakah perlu menambahkan dependensi @standard-schema/spec?: Tidak wajib ditambahkan sebagai dependensi, dan bisa digunakan dengan menyalinnya
• Tidak bisa ditambahkan sebagai dev dependency: karena ini menjadi bagian dari API publik library, maka harus dapat digunakan juga di lingkungan distribusi nyata
• Alasan menggunakan tilde (~) di depan ~standard: agar muncul setelah properti lain dalam autocomplete
• Alasan menggunakan key string alih-alih Symbol: karena key Symbol di TypeScript dapat menimbulkan masalah pada pengurutan autocomplete maupun inferensi tipe