Skip to content
Valibot logo

Valibot

OfficialBetav0.1.0

@kubb/plugin-valibot

kubb add plugin-valibot

Valibot schemas for OpenAPI formats

Look up the Valibot call Kubb writes for each OpenAPI type and format, such as v.uuid() for format: uuid, and the keywords that add a v.check.

@kubb/plugin-valibot reads the type and format of each schema and prints the matching Valibot call. Constraints such as minLength and maximum go into the same v.pipe(...).

Numbers

OpenAPI type and formatValibotNotes
numberv.number()
integerv.pipe(v.number(), v.integer())format: int8, int16, int32, and their uint forms add v.minValue() and v.maxValue() for the format's range
integer, format: int64 / uint64v.pipe(v.union([v.bigint(), v.number(), v.string()]), v.toBigint(), v.minValue(BigInt('…')), v.maxValue(BigInt('…')))Converts, because JSON holds a number or a string, then checks the format's range
string, format: int32 / int64v.pipe(v.string(), v.regex(/^-?\d+$/))An integer sent as a JSON string. A pattern in the spec wins.
minimum, maximumv.minValue(n), v.maxValue(n)
exclusiveMinimum, exclusiveMaximumv.gtValue(n), v.ltValue(n)
multipleOfv.multipleOf(n)

With integerType: 'number' on the adapter, format: int64 prints v.pipe(v.number(), v.integer()).

Strings

OpenAPI type and formatValibotNotes
stringv.string()
string, format: uuidv.pipe(v.string(), v.uuid())
string, format: emailv.pipe(v.string(), v.email())
string, format: uriv.pipe(v.string(), v.url())
string, format: ipv4 / ipv6v.pipe(v.string(), v.ipv4())v.ipv6() for ipv6
string, format: bytev.pipe(v.string(), v.base64())Also for contentEncoding: base64
string, format: ulidv.pipe(v.string(), v.ulid())
string, format: binaryv.blob()
minLength, maxLength, patternv.minLength(n), v.maxLength(n), v.regex(...)See regexType
enumv.picklist([...])A single value prints v.literal(...). A boolean or mixed set prints a v.union of literals

Any other string format prints v.string().

Dates and times

OpenAPI type and formatValibotNotes
string, format: datev.pipe(v.string(), v.isoDate())ISO 8601 date
string, format: date-timev.pipe(v.string(), v.isoTimestamp())Needs a Z or an offset
string, format: timev.string()Not checked. Valibot's time actions reject fractional seconds.

These rows apply to the adapter's default dateType: 'string'. With dateType: 'stringLocal', a date-time prints v.string(), because Valibot has no check for a date-time without an offset.

Date fields

With dateType: 'date', a date, date-time, or time is a Date in your code and a string on the wire. A response schema converts the string to a Date, and a request schema converts it back:

OpenAPI type and formatResponse schemaRequest schema
string, format: datev.pipe(v.string(), v.isoDate(), v.transform((value) => new Date(value)))v.pipe(v.date(), v.transform((value) => value.toISOString().slice(0, 10)))
string, format: date-timev.pipe(v.string(), v.isoTimestamp(), v.transform(...))v.pipe(v.date(), v.transform((value) => value.toISOString()))
string, format: timeParses onto 1970-01-01, as UTC when the value has no offsetWrites HH:mm:ssZ, with milliseconds when the value has them

A component schema with such a field is generated twice: petSchema for responses and petInputSchema for requests. With coercion for dates, the response schema prints v.pipe(v.unknown(), v.toDate()).

Objects, arrays, and unions

OpenAPIValibotNotes
objectv.object(entries)Drops unknown keys from the output
object, additionalProperties: falsev.strictObject(entries)Rejects extra keys
object, additionalProperties: truev.looseObject(entries)Keeps extra keys
object, additionalProperties: <schema>v.record(v.string(), schema)v.objectWithRest(entries, schema) next to properties
Optional propertyv.optional(schema)A default prints v.optional(schema, value)
nullable: truev.nullable(schema)
arrayv.array(schema)uniqueItems adds a v.check(...)
prefixItemsv.tuple([...])v.tupleWithRest([...], schema) with items
anyOfv.union([...])
oneOfv.union([...])Plain object members are strict, so a value with another member's keys does not match them
oneOf with a discriminatorv.variant(key, [...])v.union when a member is not a plain object
allOf of objectsv.object({ ...base.entries, ... })Other members print v.intersect([...]), or extra actions in the pipe when a member only adds constraints
$refThe schema's constv.lazy(() => schema) for a circular reference

JSON Schema keywords

These keywords print a v.check:

KeywordCheck
if/then/else, dependentRequired, dependentSchemasChecks the input before parsing, in v.pipe(v.unknown(), v.check(...), schema).
minProperties, maxPropertiesCounts the keys of the input before parsing, in the same v.pipe(...).
propertyNames on an object that also declares propertiesChecks every key of the input. A dictionary keeps v.record(keySchema, schema).
patternProperties next to properties and additionalProperties: falseRejects a key that is not declared and matches no pattern.
contains with minContains and maxContainsCounts the matching items of an array.
contentSchema on a string that holds JSONParses the string and checks the result.
uniqueItemsRejects an array with duplicate entries.

A request body that is a circular schema prints inline without its readOnly keys. In a circular allOf, a $ref member that declares such a key prints inline too.

A schema with a check on the input is a v.pipe, so it is no member of a v.variant and does not merge into an allOf object. A request body that drops readOnly keys from such a schema leaves the input checks out.

The plugin does not write description or examples into the schemas.

To change the call for one type, replace its handler with printer.