Creates an optional schema.

const Schema = v.optional<TWrapped, TDefault>(wrapped, default_);



  • wrapped TWrapped
  • default_ TDefault


With optional the validation of your schema will pass undefined inputs, and if you specify a default_ input value, the schema will use it if the input is undefined. For this reason, the output type may differ from the input type of the schema.

Note that optional does not accept null as an input. If you want to accept null inputs, use nullable, and if you want to accept null and undefined inputs, use nullish instead. Also, if you want to set a default output value for any invalid input, you should use fallback instead.



The following examples show how optional can be used.

Optional string schema

Schema that accepts string and undefined.

const OptionalStringSchema = v.optional(v.string(), "I'm the default!");

Optional date schema

Schema that accepts Date and undefined.

By using a function as the default_ parameter, the schema will return a new Date instance each time the input is undefined.

const OptionalDateSchema = v.optional(v.date(), () => new Date());

Optional entry schema

Object schema with an optional entry.

const OptionalEntrySchema = v.object({
  key: v.optional(v.string()),

Unwrap optional schema

Use unwrap to undo the effect of optional.

const OptionalNumberSchema = v.optional(v.number());
const NumberSchema = v.unwrap(OptionalNumberSchema);

The following APIs can be combined with optional.






Thanks to all the contributors who helped make this page better!

  • GitHub profile picture of fabian-hiller
  • GitHub profile picture of sqmasep


Thanks to our partners who support the project ideally and financially.


Thanks to our GitHub sponsors who support the project financially.

  • GitHub profile picture of dailydotdev
  • GitHub profile picture of Thanaen
  • GitHub profile picture of KATT
  • GitHub profile picture of osdiab
  • GitHub profile picture of ruiaraujo012
  • GitHub profile picture of hyunbinseo
  • GitHub profile picture of F0rce
  • GitHub profile picture of caegdeveloper
  • GitHub profile picture of seahindeniz