Guide · Open source

How to use yup: schema validation for JavaScript and TypeScript

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Yup is an open-source (MIT licensed) schema builder for JavaScript and TypeScript. You describe the expected shape of a value with chained method calls, then check incoming data against that description or convert it into the right types. This guide walks through the core workflow from the project README so you can validate form input or API data with confidence.

Yupjquense/yup · ★ 23.7k · MIT Install options & downloads

Quick start

1Install or fetch yup. Add yup to your Node.js project. The README's listed command is git clone https://github.com/jquense/yup; check the current README for your package manager setup.
2Import the builders. Import object, string, number, date and InferType from 'yup' in the file where you validate data.
3Define the schema. Describe each field with a type and chained rules such as required, email or positive.
4Validate incoming data. Call await schema.validate(data) on form or API input and handle any ValidationError that is thrown.
5Cast when you only need conversion. Use schema.cast(data) to coerce values into the right types without running assertions.
6Infer types for TypeScript. Use InferType<typeof schema> to derive a static type from the schema so your code and validation stay in sync.

Install yup and check prerequisites

Yup is a JavaScript and TypeScript library, so you need Node.js in your project. The README's install section lists the command git clone https://github.com/jquense/yup, which fetches the repository source. The excerpt we reviewed does not show a package-manager install command, so check the project's current README for the setup your package manager expects.

Prerequisite: Node.js
Language: TypeScript (the library is written for the JavaScript and TypeScript ecosystem)

git clone https://github.com/jquense/yup

Define a schema with chained methods

A schema describes the expected shape of a value. Each field gets a type such as string, number or date, followed by chained rules. The README example models a user with a name, age, email, website and creation date. Rules like required, positive, integer, email, url and nullable are chained onto each field.

Schemas are built from parsing actions (transforms) and assertions (tests). Validation runs both, so a schema can convert values and check them in one place.

Import the builders you need, such as object, string, number and date.
Chain rules like .required() and .email() onto each field.
Use .default() to supply a value when none is given.

import { object, string, number, date, InferType } from 'yup';

let userSchema = object({
  name: string().required(),
  age: number().required().positive().integer(),
  email: string().email(),
  website: string().url().nullable(),
  createdOn: date().default(() => new Date()),
});

Validate input data

Call validate on the schema with the input value. Yup parses the value and runs the configured assertions, returning the validated result. If the input fails a rule, it throws a ValidationError. The README pairs this with an await call, since validation can be asynchronous.

If you already know the input is in the correct type, you can pass the strict option. This skips the parsing step. In the README example, a string '24' for age fails under strict mode with the error 'age is not a number'.

validate(value) parses and asserts the value.
validate(value, { strict: true }) skips type coercion and only checks.
Use the ValidationError class to read error details when validation fails.

let user = await userSchema.validate(await fetchUser());

let parsedUser = await userSchema.validate(
  { name: 'jimmy', age: '24' },
  { strict: true },
); // throws ValidationError: age is not a number

Cast values into the correct types

Use cast when you want to convert an input value into the right types without running assertions. The README shows a string age being converted to a number and a date string being converted to a Date object. Cast does not check the other rules, so use validate when you need pass or fail results.

cast coerces values to the schema's types.
cast does not make further assertions; pair it with validate if you need checks.

let parsedUser = userSchema.cast({
  name: 'jimmy',
  age: '24',
  createdOn: '2014-09-23T19:25:25Z',
});

Infer TypeScript types from a schema

For TypeScript projects, yup can infer static types from a schema. The InferType helper produces a type that matches the schema, including optional and nullable fields. This keeps your type definitions and validation rules in one place.

The library also supports the reverse direction, where you check that a schema correctly implements an existing type. The README's TypeScript section covers schema defaults, matching an existing type, and extending built-in schemas with your own methods.

Use InferType<typeof schema> to get the type of validated data.
Extend built-in schemas with your own type-safe methods through addMethod.

type User = InferType<typeof userSchema>;

Customize error messages and run async checks

Each rule accepts an optional message, either as a string or a function, so you can write error text for your users. Yup also supports async validation, which the README highlights for checking data against a server. Use await with validate for these checks.

The README's Error message customization section covers localization and i18n. The API section documents tests, when, transform and related methods for more advanced cases.

Pass a string or function as the message argument to a rule.
Use validate (async) when a test needs to call a server.
Read the API reference for test, when and transform.

What people use it for

Validating a sign-up form with a required name, a numeric age and an email address.
Checking API payloads before saving them, using strict mode when input is already typed.
Converting query-string or form values from strings into numbers and dates with cast.
Running async checks that confirm a value against a server.
Sharing one schema for TypeScript types and runtime validation.

Frequently asked questions

Is yup free to use?

Yup is released under the MIT licence, according to the project's listing. Check the LICENSE file in the repository for the full terms before you use it in a commercial product.

Do I need Node.js to use yup?

Yes. The listed prerequisite is Node.js, and yup is written for the JavaScript and TypeScript ecosystem. Projects that do not use JavaScript or TypeScript should choose a different tool.

What is the difference between validate and cast in yup?

validate parses the value and runs all the configured checks, returning a result or throwing a ValidationError. cast only converts the value into the right types and makes no further assertions.

Can yup infer TypeScript types from a schema?

Yes. The README shows InferType<typeof userSchema>, which produces a static type that matches the schema, including optional and nullable fields.

Does yup support async validation?

Yes. The README lists built-in async validation support and uses await with validate. This is useful for checking values against a server.

How does yup compare with Zod, Joi, Valibot or Ajv?

Yup, Zod, Joi, Valibot and Ajv are all schema or validation libraries in the same space. This guide does not benchmark them, so compare the API style, TypeScript support and bundle needs for your project before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Yup suits JavaScript and TypeScript developers who need to validate form or API input, especially when they want TypeScript types inferred from the same schema. It is not a good fit for projects outside the JavaScript ecosystem or for people who need a visual, non-developer tool. If you are on the pre-v1 API, use the pre-v1 branch docs that the README links to.

Install options & downloads