Skip to content

Latest commit

 

History

History

to-json-schema

README.md

Valibot to JSON Schema

Utility to convert Valibot schemas to JSON schema (draft 07).

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

toJsonSchema(v.string()); // { type: "string" }

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 ✅
intersect ✅
lazy ⚠️ The .getterfunction is always executed with undefined as input
literal ⚠️ Only JSON compatible values are supported
looseObject ✅
looseTuple ✅
null ✅
nullable ✅
nullish ✅
number ✅
objectWithRest ✅
object ✅
optional ✅
picklist ⚠️ Only JSON compatible values are supported
record ⚠️ Only plain string schemas for the key of the record are supported
strictObject ✅
strictTuple ✅
string ✅
tupleWithRest ✅
tuple ✅
union ✅
unknown ✅
variant ⚠️ The discriminator key will be ignored
Actions Status Note
description ✅
email ✅
integer ✅
ipv4 ✅
ipv6 ✅
isoDate ✅
isoTimestamp ✅
length ⚠️ Only in combination with string and array schema
maxLength ⚠️ Only in combination with string and array schema
maxValue ⚠️ Only in combination with number schema
minLength ⚠️ Only in combination with string and array schemas
minValue ⚠️ Only in combination with number schema
multipleOf ✅
regex ⚠️ RexExp flags are not supported in JSON schema
uuid ✅
value ✅

Configurations

Option Type Note
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.

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" }

Definitions

Nested schemas can be broken in multiple named 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"],
  additionalProperties: false,
  $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"],
  additionalProperties: false,
  $defs: {
    "0": {
      type: "string",
    },
  },
}
*/