Overview
YAVI (pronounced jɑ-vάɪ) stands for Yet Another ValIdation. Since 0.18 it gives Java a Zod-like way to describe and validate input. Since 0.18 a schema written in code reads untyped input and either creates a typed object or reports every violation with its location. The same idea is found in Zod for TypeScript and in Raoh for Java; Comparison with Zod maps the two APIs.
Design principles
- Input-first. An input is described once and read from typed arguments, a map, a JSON tree or request parameters. The object is created only when every property is valid.
- Type safety by construction. Required and nullable values have different Java types, so NullAway and the Kotlin compiler can check the use of a validated value.
Validatedis sealed, and a reversible validator is checked at compile time. - No reflection. A property is read by a method reference, not by inspecting a class.
- No runtime annotations. Constraints are written as Java code, so the compiler checks them.
- No required runtime dependency. YAVI's JSpecify annotations are
provided, so they are not transitive and an application runs with only the YAVI jar on its classpath. Addorg.jspecify:jspecifyto compile code that declares@Nullable, or to run a nullness checker such as NullAway; static null checking is recommended, not required. - Staged builders. A modifier that has no effect, such as
.nullable().optional(), does not compile.
The classic ValidatorBuilder remains for objects that already exist, but the schema-first API is the recommended starting point.
What 0.18 adds
YAVI 0.18 is compiled for Java 21 and adds a schema-first API:
Yavi.schema()describes an input once and reads it from aMap, a JSON tree, request parameters or typed arguments.fromMap(f)creates the object only when every property is valid, so an invalid object never exists.- Properties can be nested objects, lists, maps, unions and structures that contain themselves.
- A validated property can be mapped to a value object and written back with a reversible schema.
- Rules that span several properties are written with
constraintOnTargetand fallible factories. description()andJsonSchemadescribe the input, for documentation and client generation.
The classic ValidatorBuilder API remains available for objects that already exist. See Migration from 0.17 for the changes between the releases.
Who this is for
This documentation is for developers who receive input they do not control, such as a JSON request body, a submitted form or a row read from a database, and who want a typed object or a complete list of violations in return. It assumes Java 21 and a working Maven or Gradle build.
Readers coming from Zod or Raoh can start with Comparison with Zod. Bean Validation solves the different problem of checking an object that already exists; that model is supported through ValidatorBuilder and described in Object Validation.
Documentation map
- Getting Started
- Introduction: the validation models and the guarantees of the library.
- Getting Started: the dependency, the first schema and the result.
- Core Concepts: input, schemas,
Validated, violations and nullness.
- Schemas
- Defining a Schema: properties, constraints, names and transforms.
- Optional and Default Values: absent keys,
null, defaults and recovery. - Value Objects and Transforms: mapping a value to a domain type.
- Objects and Collections: nested objects, lists, maps, embedding and recursion.
- Unions: alternatives and discriminated unions.
- Cross-Field Rules: rules over several properties and fallible factories.
- Describing a Schema: descriptions and JSON Schema.
- Inputs and results
- Reference
- Built-in Constraints lists every constraint.
- Object Validation covers the classic
ValidatorBuilderAPI. - Comparison with Bean Validation maps the annotations to YAVI constraints.