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.

View the project on GitHub

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. Validated is 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. Add org.jspecify:jspecify to 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 a Map, 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 constraintOnTarget and fallible factories.
  • description() and JsonSchema describe 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