Utility to convert Valibot schemas to JSON Schema. Supports JSON Schema draft-07, draft-2020-12, and OpenAPI 3.0 Schema Object formats.
import { toJsonSchema } from '@valibot/to-json-schema';import * as v from 'valibot';toJsonSchema(v.string()); // { $schema: "http://json-schema.org/draft-07/schema#", type: "string" }
This package is particularly popular for:
API Documentation: Generate OpenAPI specifications from your Valibot schemas
Code Generation: Create client SDKs and types from your validation schemas
LLM Integration: Generate structured outputs for Large Language Models
Schema Sharing: Share validation logic between different programming languages
Some Valibot features can't be mapped to JSON schema. For example, transformation actions have no equivalent in JSON schema. Also, some Valibot schemas or validations are too JS-specific and do not have an equivalent JSON schema attribute.
Supported features
Note: Converted schemas may behave slightly differently in JSON schema validators (especially for string format) because their implementation is different from Valibot's.
Schema
Status
Note
any
✅
array
✅
boolean
✅
enum
⚠️
Only JSON compatible values are supported
exactOptional
✅
intersect
✅
lazy
⚠️
The .getter function is always executed with undefined as input
Actions
Status
Note
base64
✅
bic
✅
cuid2
✅
decimal
✅
description
✅
digits
✅
domain
✅
email
✅
For length, minLength, and maxLength, string constraints have different length semantics in Valibot and JSON Schema. Valibot checks JavaScript string length (value.length, UTF-16 code units), while JSON Schema minLength and maxLength count Unicode code points. This can differ for non-BMP code points such as emoji and for multi-code-point grapheme clusters such as combining marks or ZWJ sequences.
Configurations
Option
Type
Note
target
'draft-07' | 'draft-2020-12' | 'openapi-3.0'
The target JSON Schema format. Defaults to 'draft-07'.
typeMode
'ignore' | 'input' | 'output'
Whether to convert the input or output type of the Valibot schema to JSON Schema.
errorMode
'throw' | 'warn' | 'ignore'
The policy for handling incompatible schemas and actions.
definitions
Record<string, GenericSchema>
The schema definitions for constructing recursive schemas. If not specified, the definitions are generated automatically.
Note: Some features like propertyNames for record schemas are not available in OpenAPI 3.0.
Type mode
The typeMode configuration controls whether to convert the input or output type of the Valibot schema to JSON Schema.
When set to 'input', conversion stops before the first potential type transformation action or second schema in any pipeline.
When set to 'output', conversion of any pipelines starts from the last schema in the pipeline. Therefore, the output type must be specified explicitly with a schema after the last type transformation action.
When set to 'ignore' (default), the entire pipeline is converted.
This is particularly useful when defining API endpoints where external developers need different schema information for requests vs responses:
import { toJsonSchema } from '@valibot/to-json-schema';import * as v from 'valibot';const ValibotSchema = v.pipe( v.string(), v.decimal(), v.transform(Number), v.number(), v.maxValue(100));toJsonSchema(ValibotSchema, { typeMode: 'input' });// {// $schema: "http://json-schema.org/draft-07/schema#",// type: "string",// pattern: "^[+-]?(?:\\d*\\.)?\\d+$"// }toJsonSchema(ValibotSchema, { typeMode: 'output' });
Error mode
The errorMode configuration controls how the converter handles unsupported schemas and actions. By default, the error mode is set to 'throw'. To force the conversion of unsupported Valibot features, you can set it to 'ignore'.
Unsupported schemas usually return an empty JSON schema ({}) and unsupported actions are usually ignored.
import { toJsonSchema } from '@valibot/to-json-schema';import * as v from 'valibot';toJsonSchema(v.file(), { errorMode: 'ignore' }); // {}toJsonSchema(v.pipe(v.string(), v.creditCard()), { errorMode: 'ignore' }); // { type: "string" }
Override functions
The package provides powerful override capabilities to customize the JSON Schema conversion process. You can override the conversion of specific schemas, actions, or references.
Override schema conversion
Handle unsupported schemas or customize conversion behavior:
Customize reference IDs for OpenAPI or other specifications:
import { toJsonSchemaDefs } from '@valibot/to-json-schema';import * as v from 'valibot';const UserSchema = v.object({ name: v.string() });toJsonSchemaDefs( { UserSchema }, { overrideRef: (context) => `#/schemas/${context.referenceId}` });
Enhanced metadata support
Use the generic metadata action to add title, description, and examples to your schemas or the individual title and description actions. Any other properties of the metadata action are added to the JSON Schema without further validation. This allows you to specify custom annotations and standard keywords such as format:
import { toJsonSchema } from '@valibot/to-json-schema';import * as v from 'valibot';const ValibotSchema = v.pipe( v.string(), v.email(), v.metadata({ title: 'Email Schema', description: 'A schema that validates email addresses.', examples: ['jane@example.com'], 'x-category': 'auth', }));toJsonSchema(ValibotSchema);// {// $schema: "http://json-schema.org/draft-07/schema#",// type: "string",// format: "email",
Definitions
Nested and recursive schemas can be broken in multiple reusable definitions.
Converts a Valibot schema to the Standard JSON Schema format. This format is useful when working with tools and libraries that support the Standard JSON Schema specification.
import { toStandardJsonSchema } from '@valibot/to-json-schema';import * as v from 'valibot';const schema = toStandardJsonSchema( v.object({ id: v.pipe(v.string(), v.uuid()), name: v.pipe(v.string(), v.nonEmpty()), age: v.optional(v.number()), }));
toJsonSchemaDefs
Converts only the provided Valibot schema definitions to JSON Schema definitions, without wrapping them in a root schema. This is particularly useful for OpenAPI specifications where you need only the schema definitions.
For advanced use cases, you can manage global schema definitions that will be automatically used when converting schemas. This is particularly useful for larger projects with many reusable schemas.