Valibot to JSON Schema

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.

Configurations

Target format

The target configuration allows you to specify which JSON Schema format to generate. Different targets have different capabilities and syntax:

import { toJsonSchema } from '@valibot/to-json-schema';
import * as v from 'valibot';

const schema = v.nullable(v.string());

// JSON Schema draft-07 (default)
toJsonSchema(schema);
// { $schema: "http://json-schema.org/draft-07/schema#", anyOf: [{ type: "string" }, { type: "null" }] }

// JSON Schema draft-2020-12
toJsonSchema(schema, { target: 'draft-2020-12' });
// { $schema: "https://json-schema.org/draft/2020-12/schema", anyOf: [{ type: "string" }, { type: "null" }] }

// OpenAPI 3.0 Schema Object
toJsonSchema(schema, { target: 'openapi-3.0' });
// { type: "string", nullable: true }

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' });

// {
//   $schema: "http://json-schema.org/draft-07/schema#",
//   type: "number",
//   maximum: 100
// }

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:

import { toJsonSchema } from '@valibot/to-json-schema';
import * as v from 'valibot';

const ValibotSchema = v.object({ createdAt: v.date() });

toJsonSchema(ValibotSchema, {
  overrideSchema(context) {
    if (context.valibotSchema.type === 'date') {
      return { type: 'string', format: 'date-time' };
    }
  },
});

// {
//   $schema: "http://json-schema.org/draft-07/schema#",
//   type: "object",
//   properties: {
//     createdAt: { type: "string" format: "date-time" }
//   },
//   required: ["createdAt"]
// }

Override reference IDs

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 titleand description actions:

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'],
  })
);

toJsonSchema(ValibotSchema);

// {
//   $schema: "http://json-schema.org/draft-07/schema#",
//   type: "string",
//   format: "email",
//   title: "Email Schema",
//   description: "A schema that validates email addresses.",
//   examples: ["jane@example.com"]
// }

Definitions

Nested and recursive schemas can be broken in multiple reusable definitions.

import { toJsonSchema } from '@valibot/to-json-schema';
import * as v from 'valibot';

const EmailSchema = v.pipe(v.string(), v.email());
toJsonSchema(v.object({ email: EmailSchema }), {
  definitions: { EmailSchema },
});

// {
//   $schema: "http://json-schema.org/draft-07/schema#",
//   type: "object",
//   properties: {
//     email: {
//       $ref: "#/$defs/EmailSchema"
//     }
//   },
//   required: ["email"],
//   $defs: {
//     EmailSchema: {
//       type: "string",
//       format: "email"
//     }
//   }
// }

Definitions are not required for converting lazy schemas. Missing definitions will be generated automatically.

import { toJsonSchema } from '@valibot/to-json-schema';
import * as v from 'valibot';

const StringSchema = v.string();
toJsonSchema(v.object({ key: v.lazy(() => StringSchema) }));

// {
//   $schema: "http://json-schema.org/draft-07/schema#",
//   type: "object",
//   properties: {
//     key: {
//       $ref: "#/$defs/0"
//     }
//   },
//   required: ["key"],
//   $defs: {
//     0: {
//       type: "string"
//     }
//   }
// }

Additional functions

toStandardJsonSchema

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.

import { toJsonSchemaDefs } from '@valibot/to-json-schema';
import * as v from 'valibot';

const EmailSchema = v.pipe(v.string(), v.email());
const UserSchema = v.object({
  name: v.string(),
  email: EmailSchema,
});

toJsonSchemaDefs({ EmailSchema, UserSchema });

// {
//   EmailSchema: {
//     type: "string",
//     format: "email"
//   },
//   UserSchema: {
//     type: "object",
//     properties: {
//       name: {
//         type: "string"
//       },
//       email: {
//         $ref: "#/$defs/EmailSchema"
//       }
//     },
//     required: ["name", "email"]
//   }
// }

OpenAPI integration

For OpenAPI specifications, you can customize reference IDs:

import { toJsonSchemaDefs } from '@valibot/to-json-schema';
import * as v from 'valibot';

const ValibotSchema1 = v.string();
const ValibotSchema2 = v.number();
const ValibotSchema3 = v.tuple([ValibotSchema1, ValibotSchema2]);

toJsonSchemaDefs(
  { ValibotSchema1, ValibotSchema2, ValibotSchema3 },
  { overrideRef: (context) => `#/schemas/${context.referenceId}` }
);

// {
//   ValibotSchema1: { type: "string" },
//   ValibotSchema2: { type: "number" },
//   ValibotSchema3: {
//     type: "array",
//     items: [
//       { $ref: "#/schemas/ValibotSchema1" },
//       { $ref: "#/schemas/ValibotSchema2" }
//     ],
//     minItems: 2
//   }
// }

Global 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.

import { addGlobalDefs, toJsonSchema } from '@valibot/to-json-schema';
import * as v from 'valibot';

const ValibotSchema1 = v.string();
const ValibotSchema2 = v.number();

addGlobalDefs({ ValibotSchema1, ValibotSchema2 });

const ValibotSchema3 = v.tuple([ValibotSchema1, ValibotSchema2]);

toJsonSchema(ValibotSchema3);

// {
//   $schema: "http://json-schema.org/draft-07/schema#",
//   type: "array",
//   items: [
//     { $ref: "#/$defs/ValibotSchema1" },
//     { $ref: "#/$defs/ValibotSchema2" }
//   ],
//   minItems: 2,
//   $defs: {
//     ValibotSchema1: { type: "string" },
//     ValibotSchema2: { type: "number" }
//   }
// }

You can also convert global definitions directly using toJsonSchemaDefs:

const globalDefs = getGlobalDefs();
if (globalDefs) {
  const schemaDefs = toJsonSchemaDefs(globalDefs);
}