Yup

Yup is a schema builder for runtime value parsing and validation. Define a schema, transform a value to match, assert the shape of an existing value, or both. Yup schema are extremely expressive and allow modeling complex, interdependent validations, or value transformation.

You are viewing docs for the v1.0.0 of yup, pre-v1 docs are available: here

Killer Features:

• Concise yet expressive schema interface, equipped to model simple to complex data models
• Powerful TypeScript support. Infer static types from schema, or ensure schema correctly implement a type
• Built-in async validation support. Model server-side and client-side validation equally well
• Extensible: add your own type-safe methods and schema
• Rich error details, make debugging a breeze

Getting Started

Schema are comprised of parsing actions (transforms) as well as assertions (tests) about the input value. Validate an input value to parse it and run the configured set of assertions. Chain together methods to build a schema.

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()),
});

// parse and assert validity
const user = await userSchema.validate(await fetchUser());

type User = InferType<typeof userSchema>;
/* {
  name: string;
  age: number;
  email?: string | undefined
  website?: string | null | undefined
  createdOn: Date
}*/

Use a schema to coerce or "cast" an input value into the correct type, and optionally transform that value into more concrete and specific values, without making further assertions.

// Attempts to coerce values to the correct type
const parsedUser = userSchema.cast({
  name: 'jimmy',
  age: '24',
  createdOn: '2014-09-23T19:25:25Z',
});
// ✅  { name: 'jimmy', age: 24, createdOn: Date }

Know that your input value is already parsed? You can "strictly" validate an input, and avoid the overhead of running parsing logic.

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

Table of Contents

• Schema basics
• Parsing: Transforms
• Validation: Tests
  • Customizing errors
• Composition and Reuse
• TypeScript integration
• Schema defaults
• Ensuring a schema matches an existing type
• Extending built-in schema with new methods
• TypeScript configuration
• Error message customization
• localization and i18n
• API
• yup
  • reach(schema: Schema, path: string, value?: object, context?: object): Schema
  • addMethod(schemaType: Schema, name: string, method: ()=> Schema): void
  • ref(path: string, options: { contextPrefix: string }): Ref
  • lazy((value: any) => Schema): Lazy
  • ValidationError(errors: string | Array<string>, value: any, path: string)
• Schema
  • Schema.clone(): Schema
  • Schema.label(label: string): Schema
  • Schema.meta(metadata: object): Schema
  • Schema.describe(options?: ResolveOptions): SchemaDescription
  • Schema.concat(schema: Schema): Schema
  • Schema.validate(value: any, options?: object): Promise<InferType<Schema>, ValidationError>
  • Schema.validateSync(value: any, options?: object): InferType<Schema>
  • Schema.validateAt(path: string, value: any, options?: object): Promise<InferType<Schema>, ValidationError>
  • Schema.validateSyncAt(path: string, value: any, options?: object): InferType<Schema>
  • Schema.isValid(value: any, options?: object): Promise<boolean>
  • Schema.isValidSync(value: any, options?: object): boolean
  • Schema.cast(value: any, options = {}): InferType<Schema>
  • Schema.isType(value: any): value is InferType<Schema>
  • Schema.strict(enabled: boolean = false): Schema
  • Schema.strip(enabled: boolean = true): Schema
  • Schema.withMutation(builder: (current: Schema) => void): void
  • Schema.default(value: any): Schema
  • Schema.getDefault(options?: object): Any
  • Schema.nullable(): Schema
  • Schema.nonNullable(): Schema
  • Schema.defined(): Schema
  • Schema.optional(): Schema
  • Schema.required(message?: string | function): Schema
  • Schema.notRequired(): Schema
  • Schema.typeError(message: string): Schema
  • Schema.oneOf(arrayOfValues: Array<any>, message?: string | function): Schema Alias: equals
  • Schema.notOneOf(arrayOfValues: Array<any>, message?: string | function)
  • Schema.when(keys: string | string[], builder: object | (values: any[], schema) => Schema): Schema
  • Schema.test(name: string, message: string | function | any, test: function): Schema
  • Schema.test(options: object): Schema
  • Schema.transform((currentValue: any, originalValue: any) => any): Schema
• mixed
• string
  • string.required(message?: string | function): Schema
  • string.length(limit: number | Ref, message?: string | function): Schema
  • string.min(limit: number | Ref, message?: string | function): Schema
  • string.max(limit: number | Ref, message?: string | function): Schema
  • string.matches(regex: Regex, message?: string | function): Schema
  • string.matches(regex: Regex, options: { message: string, excludeEmptyString: bool }): Schema
  • string.email(message?: string | function): Schema
  • string.url(message?: string | function): Schema
  • string.uuid(message?: string | function): Schema
  • string.ensure(): Schema
  • string.trim(message?: string | function): Schema
  • string.lowercase(message?: string | function): Schema
  • string.uppercase(message?: string | function): Schema
• number
  • number.min(limit: number | Ref, message?: string | function): Schema
  • number.max(limit: number | Ref, message?: string | function): Schema
  • number.lessThan(max: number | Ref, message?: string | function): Schema
  • number.moreThan(min: number | Ref, message?: string | function): Schema
  • number.positive(message?: string | function): Schema
  • number.negative(message?: string | function): Schema
  • number.integer(message?: string | function): Schema
  • number.truncate(): Schema
  • number.round(type: 'floor' | 'ceil' | 'trunc' | 'round' = 'round'): Schema
• boolean
• date
  • date.min(limit: Date | string | Ref, message?: string | function): Schema
  • date.max(limit: Date | string | Ref, message?: string | function): Schema
• array
  • array.of(type: Schema): this
  • array.json(): this
  • array.length(length: number | Ref, message?: string | function): this
  • array.min(limit: number | Ref, message?: string | function): this
  • array.max(limit: number | Ref, message?: string | function): this
  • array.ensure(): this
  • array.compact(rejector: (value) => boolean): Schema
• tuple
• object
  • Object schema defaults
  • object.shape(fields: object, noSortEdges?: Array<[string, string]>): Schema
  • object.json(): this
  • object.concat(schemaB: ObjectSchema): ObjectSchema
  • object.pick(keys: string[]): Schema
  • object.omit(keys: string[]): Schema
  • object.from(fromKey: string, toKey: string, alias: boolean = false): this
  • object.noUnknown(onlyKnownKeys: boolean = true, message?: string | function): Schema
  • object.camelCase(): Schema
  • object.constantCase(): Schema

Schema basics

Schema definitions, are comprised of parsing "transforms" which manipulate inputs into the desired shape and type, "tests", which make assertions over parsed data. Schema also store a bunch of "metadata", details about the schema itself, which can be used to improve error messages, build tools that dynamically consume schema, or serialize schema into another format.

In order to be maximally flexible yup allows running both parsing and assertions separately to match specific needs

Parsing: Transforms

Each built-in type implements basic type parsing, which comes in handy when parsing serialized data, such as JSON. Additionally types implement type specific transforms that can be enabled.

const num = number().cast('1'); // 1

const obj = object({
  firstName: string().lowercase().trim(),
})
  .camelCase()
  .cast('{"first_name": "jAnE "}'); // { firstName: 'jane' }

Custom transforms can be added

const reversedString = string()
  .transform((currentValue) => currentValue.split('').reverse().join(''))
  .cast('dlrow olleh'); // "hello world"

Transforms form a "pipeline", where the value of a previous transform is piped into the next one. If the end value is undefined yup will apply the schema default if it's configured.

Watch out! values are not guaranteed to be valid types in transform functions. Previous transforms may have failed. For example a number transform may be receive the input value, NaN, or a number.

Validation: Tests

Yup has robust support for assertions, or "tests", over input values. Tests assert that inputs conform to some criteria. Tests are distinct from transforms, in that they do not change or alter the input (or its type) and are usual