Standard Schema
lastmod 2025-02-06created 2025-02-061 edits
A common interface for TypeScript Validation
About
- A spec designed so that JavaScript/TypeScript-based schema libraries implement a common interface
- The goal is to let user-defined type validation logic be reused across libraries, so tools are compatible with each other without separate adapters
- Co-designed by the creators of major libraries such as Zod, Valibot, and ArkType
Main interface (StandardSchemaV1)
- Implements the entire spec through an object property called ~standard
- Inside ~standard there are required properties such as version, vendor, validate, and types
- The validate function returns value on success and an issues array on failure
- The types property lets TypeScript infer the schema's input and output types
- All updates maintain compatibility unless they are a major version
Design goals
- Runtime validation support: standardizes and delivers error information in a standard way
- Static type inference support: explicitly exposes the type information inferred by TypeScript-based libraries
- Simplicity: can be implemented by adding just a few lines to existing library functions
- Avoiding API conflicts: puts everything into the single ~standard namespace so it does not conflict with existing APIs
- Preserving developer experience: starting with a tilde (~), as in ~standard, lowers its priority in autocomplete
Which libraries implement it
- Zod, Valibot, ArkType, Arri Schema, TypeMap, and others already support Standard Schema
- tRPC, TanStack Form, TanStack Router, Hono Middleware, and others also accept user schemas based on Standard Schema
How to implement the spec in your own library
- Copy the StandardSchemaV1 interface into the library and add the ~standard property
- Connect the validate function to the existing validation function so it returns { value } on success and { issues } on failure
- Asynchronous validation is possible if needed, but synchronous validation is recommended
How to accept user-defined schemas with Standard Schema
- To use it directly without a schema library, install @standard-schema/spec or copy the interface
- As in the example function standardValidate, any schema with the standard interface can be validated the same way regardless of library
- To allow only synchronous validation, check whether the validate return value is a Promise and handle it as an exception
FAQ
- Do I need to add the @standard-schema/spec dependency?: It does not have to be added as a dependency; it can be copied and used
- Cannot be added as a dev dependency: it becomes part of the library's public API, so it must be available in the actual production environment
- Why a tilde (~) is used in front of ~standard: intended to make it appear after other properties in autocomplete
- Why a string key is used instead of a Symbol: in TypeScript, Symbol keys cause problems with autocomplete sorting and type inference