Standard JSON Schema

Standard JSON Schema is a common interface designed to be implemented by JavaScript and TypeScript entities that are or can be converted to JSON Schema.
The goal is to make it easier for ecosystem tools to accept user-defined types (typically defined using schema/validation libraries) without needing to write custom logic or adapters for each supported library. And since Standard JSON Schema is a specification, they can do so with no additional runtime dependencies.
Many libraries need JSON Schema representations of type information:
Previously, type information was commonly destroyed in the process of converting a schema (Zod, ArkType, Valibot) to JSON Schema. This spec provides a standardized, unified JSON Schema representation that preserves inferred type information.
The spec was designed by the creators of Zod, Valibot, and ArkType. Recent versions of these libraries already implement the spec (see the full list of compatible libraries below).
The specification consists of a single TypeScript interface StandardJSONSchemaV1 to be implemented by any library wishing to be spec-compliant.
This interface can be found below in its entirety. Libraries wishing to implement the spec can copy/paste the code block below into their codebase. It's also available at @standard-schema/spec on npm and JSR.
The specification meets a few primary design objectives:
These are the libraries that have already implemented the Standard JSON Schema interface. (If you maintain a library that implements the spec, create a PR to add yourself!)
The answer to this question is a little more nuanced than with regular Standard Schema. The spec can be implemented by any object that is or can be converted to JSON Schema. It's intentionally designed to support multiple use cases.
Usage examples for each implementing library.
The following tools accept user-defined schemas conforming to the Standard JSON Schema spec. If you maintain a tool that supports Standard JSON Schemas, create a PR to add yourself!
When creating a PR to add your tool, please add a new row to the table below with:
These are the most frequently asked questions about Standard JSON Schema. If your question is not listed, feel free to create an issue.
Starting with the next @standard-schema/[email protected] version, Standard JSON Schema will be published alongside the existing Standard Schema spec.
Standard JSON Schema is orthogonal to Standard Schema. This interface contains no affordance for data validation. Think of them as "traits" or "interfaces". Any given object/instance/entity can implement one or both.
Different tooling requires different versions of JSON Schema. Currently there is a divide in the ecosystem between "draft-07" and "draft-2020-12". Library authors that implement this spec are encouraged to implement as many formats as is practical, with a special emphasis on "draft-07" and "draft-2020-12". Supporting multiple formats is not required to implement the spec; it is entirely on a best-effort basis.
Yes, the type signature for "target" was intentionally widened with {} & string. This allows libraries to support unspecified formats. It also allows the spec to evolve to include future versions of JSON Schema without breaking assignability down the line.
The OpenAPI 3.0 specification (still in wide use) implements its own schema definition format. It's a superset of JSON Schema "draft-04" that's augmented with additional keywords like nullable. Despite not being an official JSON Schema draft, it's in wide use and has been included in the list of recommended drafts.
Many schemas perform transformations during validation. For example, a schema might accept a string as input ("123") but output a number (123). The input and output types can differ, so their JSON Schema representations need to differ as well. The jsonSchema.input method generates a JSON Schema for the input type, while jsonSchema.output generates one for the output type. In cases where input and output types are identical, both methods will return the same schema.
If a given schema/entity cannot be converted to JSON Schema, the conversion method call may throw. They may also throw if the entity is non-convertible or otherwise cannot be soundly represented as JSON Schema. Any integrating frameworks/libraries should account for this.
The two concerns are orthogonal. StandardSchemaV1 is about validation, while StandardJSONSchemaV1 is about conversion to a JSON Schema representation. Keeping them separate allows greater flexibility for use cases where only one or the other may be required.
Refer to the implementation example for a worked example.
Use the interface to accept values from the user.
To infer generic type information from the user-defined schema:
The two specs are implemented as plain TypeScript interfaces, so you can merge them (and any future specs) as needed for your use case.
by @colinhacks, @fabianhiller, and @ssalbdivad