yup

Yup lets you define a schema once and use it to both assert the shape of a value and coerce it into the correct type. Schemas are built by chaining methods on primitive builders (object, string, number, date, array, boolean, tuple) into an expressive description of complex, interdependent data, and the same schema definition can validate synchronously or asynchronously.

It is best known as the validation layer underneath form libraries like Formik and React Hook Form, but it works equally well for validating API payloads, config objects, or any untrusted input on the client or server. Recent versions ship first-class TypeScript type inference (InferType) and compliance with the community Standard Schema spec, so a yup schema can double as both a runtime validator and a compile-time type source.

What You Get

• Chainable schema builders for object, string, number, date, array, boolean, and tuple types that compose into arbitrarily nested, complex shapes
• Both synchronous (validateSync/isValidSync) and asynchronous (validate/isValid) validation against the exact same schema definition
• Casting/coercion (schema.cast()) that converts loosely-typed input (e.g. string ‘24’) into the correctly-typed value before or instead of asserting validity
• Cross-field and conditional validation via ref() and .when(), so one field’s rules can depend on another field’s value
• Full TypeScript type inference with InferType<typeof schema>, so the runtime schema and the static type never drift apart
• Native support for the community Standard Schema spec, making yup schemas consumable by any Standard-Schema-aware tool without a yup-specific adapter

Common Use Cases

• Validating and normalizing form input in React apps via Formik or React Hook Form resolvers
• Validating request bodies/query params on a Node.js API before they reach business logic
• Casting loosely-typed config or environment values (strings from .env, query strings) into typed objects
• Building reusable, composable validation schemas shared between client and server in a single TypeScript codebase

Under The Hood

Architecture

Yup centers on a single base Schema class (src/schema.ts) that accumulates a SchemaSpec (coerce, nullable, optional, default, strict flags) as builder methods are chained, then runs that spec through a shared cast/validate pipeline; per-type subclasses (mixed, string, number, boolean, date, array, tuple, object) override type-checking and casting while reusing the same test-running machinery in util/createValidation.ts. Cross-field behavior is factored into dedicated collaborators: Condition.ts resolves .when() branches against sibling values, Reference.ts/Lazy.ts implement ref() and lazy, value-dependent schemas, and util/reach.ts implements path-based schema traversal for reach()/describe(). Errors propagate as a nested ValidationError tree (error.inner) rather than a flat list, and standardSchema.ts adapts the whole pipeline to the community Standard Schema spec. It’s a clean, layered design, though schema.ts and object.ts each carry a lot of the core logic.

Tech Stack

Yup is written almost entirely in TypeScript, built with Rollup plus rollup-plugin-dts for bundling and hand-generated type declarations, and transpiled via Babel. Tests run on Vitest, split into separate “sync” and “async” projects that exercise the exact same test files against both execution modes. The project uses Yarn 4 (Berry) for dependency management and keeps its runtime dependency surface deliberately small: property-expr for path parsing, tiny-case for key casing, toposort for resolving interdependent object-shape fields, and type-fest for TypeScript utility types. It ships both ESM and CJS builds (module/main fields).

Code Quality

The test/ directory mirrors every schema type (array, object, string, number, date, boolean, tuple, lazy, standardSchema, setLocale, ValidationError) plus a dedicated types/ directory for compile-time type-inference tests, all run through Vitest’s dual sync/async projects so both validation modes get identical coverage. ESLint is configured with typescript-eslint, import, and jest plugins, and CI runs via a GitHub Actions workflow. Errors are explicit and typed through a dedicated ValidationError class that supports nested/aggregated errors rather than throwing generic exceptions. Inline comment density is modest — mostly light JSDoc on public methods rather than extensive internal documentation.

API Design Yup popularized the chainable-builder-plus-type-inference pattern that much of the current validation-library generation follows. Its distinguishing choices are a single schema definition that validates identically whether called synchronously or asynchronously, .when()/ref() for expressing rules that depend on sibling fields, lazy() for recursive or value-dependent schemas, and recent adoption of the Standard Schema spec so a yup schema can be consumed by any Standard-Schema-aware tool without a custom adapter. InferType keeps the static TypeScript type and the runtime schema from drifting apart. The overall developer experience is low-boilerplate and consistent, even if the chainable-builder approach itself is no longer unique to yup.