json-schema-to-valibot

Convert JSON Schema definitions to Valibot schema definitions.

This is the Valibot equivalent of json-schema-to-zod - a runtime package and CLI tool to convert JSON schema objects or files into Valibot schemas. The API and structure are heavily inspired by json-schema-to-zod.

Installation

1pnpm install json-schema-to-valibot

CLI Usage

1# Convert from file
2json-schema-to-valibot -i schema.json
3
4# Convert from stdin
5cat schema.json | json-schema-to-valibot
6
7# Direct JSON input
8json-schema-to-valibot -i '{"type":"string","minLength":5}'
9
10# Specify output file
11json-schema-to-valibot -i schema.json -o output.ts
12
13# Generate CommonJS module
14json-schema-to-valibot -i schema.json --module cjs
15
16# Generate TypeScript types
17json-schema-to-valibot -i schema.json --types
18
19# Custom schema name
20json-schema-to-valibot -i schema.json --name userSchema

CLI Options

• -i, --input <path> - Input JSON Schema file path or JSON string
• -o, --output <path> - Output file path (defaults to stdout)
• -n, --name <name> - Schema name in output (default: "schema")
• -m, --module <type> - Module system: esm, cjs, none (default: "esm")
• -t, --types - Generate TypeScript type exports
• -d, --jsdoc - Include JSDoc comments
• --depth <number> - Maximum recursion depth (default: 10)
• --export-definitions - Export schema definitions (default: true)

Programmatic Usage

1import { jsonSchemaToValibot } from 'json-schema-to-valibot'
2
3const schema = {
4  type: 'object',
5  properties: {
6    name: { type: 'string', minLength: 1 },
7    age: { type: 'integer', minimum: 0 }
8  },
9  required: ['name']
10}
11
12const valibotCode = jsonSchemaToValibot(schema, {
13  name: 'userSchema',
14  module: 'esm',
15  withTypes: true,
16  exportDefinitions: true // Control whether to export schema definitions
17})
18
19console.log(valibotCode)

Supported JSON Schema Features

Basic Types

• string with constraints (minLength, maxLength, pattern, format)
• number/integer with constraints (minimum, maximum, multipleOf)
• boolean
• null
• array with items, length constraints, uniqueItems
• object with properties, required fields, additionalProperties

Advanced Features

• const values → v.literal() for primitives, v.object()/v.tuple() for complex types
• enum values → v.picklist() for primitives, v.union() for mixed types
• anyOf → v.union()
• allOf → v.intersect() (for objects)
• oneOf → v.union()
• not → v.custom() validation
• nullable → v.nullable()
• Boolean schemas → true becomes v.any(), false becomes v.never()

References & Recursive Schemas

• $ref → Resolves references to definitions and $defs
• Recursive schemas → Uses v.lazy() for circular dependencies
• TypeScript types → Generates proper TypeScript type definitions for recursive schemas
• Export control → exportDefinitions option to control definition exports

String Formats

• email → v.email()
• url/uri → v.url()
• uuid → v.uuid()
• date → v.isoDate()
• date-time → v.isoDateTime()
• time → v.isoTime()
• ipv4 → v.ipv4()
• ipv6 → v.ipv6()

Examples

Input JSON Schema

1{
2  "type": "object",
3  "properties": {
4    "name": {
5      "type": "string",
6      "minLength": 1,
7      "maxLength": 100
8    },
9    "email": {
10      "type": "string", 
11      "format": "email"
12    },
13    "age": {
14      "type": "integer",
15      "minimum": 0,
16      "maximum": 150
17    },
18    "tags": {
19      "type": "array",
20      "items": { "type": "string" },
21      "uniqueItems": true
22    }
23  },
24  "required": ["name", "email"]
25}

Generated Valibot Schema

1import * as v from 'valibot'
2
3export const schema = v.object({
4  "name": v.string([v.minLength(1), v.maxLength(100)]),
5  "email": v.string([v.email()]),
6  "age": v.optional(v.integer([v.minValue(0), v.maxValue(150)])),
7  "tags": v.optional(v.pipe(v.array(v.string()), v.unique()))
8})

Recursive Schema Example

Input JSON Schema with recursive references:

1{
2  "type": "object",
3  "properties": {
4    "tree": { "$ref": "#/definitions/BinaryTree" }
5  },
6  "definitions": {
7    "BinaryTree": {
8      "type": "object",
9      "properties": {
10        "value": { "type": "number" },
11        "left": {
12          "anyOf": [
13            { "$ref": "#/definitions/BinaryTree" },
14            { "type": "null" }
15          ]
16        },
17        "right": {
18          "anyOf": [
19            { "$ref": "#/definitions/BinaryTree" },
20            { "type": "null" }
21          ]
22        }
23      },
24      "required": ["value"]
25    }
26  }
27}

Generated output with proper TypeScript types:

1import * as v from 'valibot'
2
3export type BinaryTree = { 
4  value: number; 
5  left?: BinaryTree | null; 
6  right?: BinaryTree | null 
7};
8
9export const BinaryTreeSchema: v.GenericSchema<BinaryTree> = v.object({
10  "value": v.number(),
11  "left": v.optional(v.union([v.lazy(() => BinaryTreeSchema), v.null_()])),
12  "right": v.optional(v.union([v.lazy(() => BinaryTreeSchema), v.null_()]))
13});
14
15export const schema = v.object({
16  "tree": v.optional(BinaryTreeSchema)
17})

Development

1# Install dependencies
2pnpm install
3
4# Run tests
5pnpm test
6
7# Run specific test categories
8pnpm test:dev      # Unit tests only
9pnpm test:e2e      # End-to-end CLI tests
10pnpm test:suite    # JSON Schema test suite validation
11
12# Type check
13pnpm typecheck
14
15# Lint code
16pnpm lint
17pnpm lint:fix
18
19# Build
20pnpm build
21
22# Development CLI
23pnpm dev -i example-schema.json

Credits

This project is heavily inspired by and based on json-schema-to-zod. Many thanks to the original authors for their excellent work.

License

MIT