Skip to content

Latest commit

 

History

History
1622 lines (1231 loc) · 65.6 KB

RaohTutorialInYavi.md

File metadata and controls

1622 lines (1231 loc) · 65.6 KB

The Raoh tutorial in YAVI

日本語

This page is the Raoh decoder practical guide written with YAVI 0.18.0, section by section and with the same numbers, so that the two can be read side by side. Every example was run with jshell; the comments show what it printed, and python3 docs/verify-examples.py runs them again and compares. Comparison with Raoh maps the two APIs in tables.

Why validators that produce a value?

Data from outside (a request body, a CSV file, the response of another API, a row of a table) is not of the types the application expects. A validator of YAVI takes such an input and returns either the domain object or all the violations with their paths:

input (typed arguments / Map / JSON tree / request parameters)
    ↓  validator.validate(input)
Valid[domain object]  or  Invalid[violations with a name, a path, a message key and a message]

What Raoh calls a decoder is a ValueValidator<I, T> here, Raoh's decode is validate, and Raoh's Ok / Err are Validated.Valid / Validated.Invalid.

0. Setup

Start jshell with the jar of YAVI, which needs no other library:

jshell --class-path yavi-0.18.0.jar
import am.ik.yavi.arguments.*;
import am.ik.yavi.core.*;
import am.ik.yavi.input.*;
import am.ik.yavi.message.*;
import am.ik.yavi.validator.Yavi;
import java.time.*;
  • jshell evaluates a snippet when a line completes it. A chain that is broken before a ., as the examples are, is pasted as one line.
  • jshell wants a sealed interface and its subtypes in one snippet, so the examples declare a plain interface.

1. Validating primitive values

The smallest unit is the validator of one value: Yavi._string(), Yavi._integer(), Yavi._bigDecimal(), Yavi._boolean() and so on.

Yavi._string().validate("hello")
// ==> Valid[value=hello]

Yavi._integer().validate(42)
// ==> Valid[value=42]

Yavi._boolean().validate(true)
// ==> Valid[value=true]

Yavi._bigDecimal().validate(new BigDecimal("19.99"))
// ==> Valid[value=19.99]

Yavi._double().validate(3.14)
// ==> Valid[value=3.14]

Yavi._float().validate(2.5f)
// ==> Valid[value=2.5]

Yavi._object(byte[].class).validate(new byte[]{1, 2, 3})
// ==> Valid[value=[B@...]

Unlike a decoder of Raoh's ObjectDecoders, these validators are typed: Yavi._integer().validate("not a number") does not compile. untyped() returns the validator of an Object, which checks the type first:

Yavi._integer().untyped().validate("not a number")
// ==> Invalid[errors=[The value must be of type integer (object.type)]]

Yavi._integer().untyped().validate(42L)
// ==> Valid[value=42]  (a number is taken as long as its value is kept)

Yavi._bigDecimal().untyped().validate(19.99)
// ==> Valid[value=19.99]

A failed result shows each violation as it reads: the JSON Pointer of the value (none for the validated value itself), the message and the message key. untyped() is rarely written: a schema (section 4) checks the types of its properties.

2. Adding constraints

The constraints are a function given to the validator. A violated constraint fails the validation.

String constraints

Yavi._string(c -> c.trim().toLowerCase().email()).validate("  USER@Example.COM  ")
// ==> Valid[value=user@example.com]

Yavi._string(c -> c.trim().toLowerCase().email()).validate("not-email")
// ==> Invalid[errors=[The value must be a valid email address (charSequence.email)]]

Yavi._string(c -> c.greaterThanOrEqual(3).lessThanOrEqual(20)).validate("ab")
// ==> Invalid[errors=[The size of the value must be greater than or equal to 3. The given size is 2 (container.greaterThanOrEqual)]]

Yavi._string(c -> c.pattern("^\\d{3}-\\d{4}$")).validate("123-4567")
// ==> Valid[value=123-4567]

Yavi._string(c -> c.uuid()).validate("550e8400-e29b-41d4-a716-446655440000")
// ==> Valid[value=550e8400-e29b-41d4-a716-446655440000]  (a String)

Yavi._object(UUID.class).untyped().validate("550e8400-e29b-41d4-a716-446655440000")
// ==> Valid[value=550e8400-e29b-41d4-a716-446655440000]  (a UUID)
  • The transforms (trim(), toLowerCase()) are written before the first constraint; c.email().trim() does not compile.
  • The length of a string is its size: greaterThanOrEqual(3) is Raoh's minLength(3), lessThanOrEqual(20) is Raoh's maxLength(20) and fixedSize(n) is Raoh's fixedLength(n).
  • A constraint keeps the type of the value. A value of another type is read by the validator of that type: Yavi._object(UUID.class) reads the canonical string.

Normalization

The size constraints count the code points of the NFC form, so a decomposed が (U+304B U+3099) is one character without a transform. The value is not changed; toNormalForm(form) normalizes it.

String nfd = "が";

Yavi._string(c -> c.lessThanOrEqual(1)).validate(nfd)
// ==> Valid[value=が]  (still two chars)

Yavi._string(c -> c.toNormalForm(java.text.Normalizer.Form.NFC).lessThanOrEqual(1)).validate(nfd).value().length()
// ==> 1

Yavi._string(c -> c.normalizer(null).lessThanOrEqual(1)).validate(nfd)
// ==> Invalid[errors=[The size of the value must be less than or equal to 1. The given size is 2 (container.lessThanOrEqual)]]

c.normalizer(form) selects the form for counting and c.normalizer(null) none.

URI / URL validation

Yavi._string(c -> c.uri()).validate("file:///tmp/data.csv")
// ==> Valid[value=file:///tmp/data.csv]

Yavi._string(c -> c.uri()).validate("foo/bar")
// ==> Invalid[errors=[The value must be a valid URI (charSequence.uri)]]

Yavi._string(c -> c.url()).validate("https://example.com/api")
// ==> Valid[value=https://example.com/api]

Yavi._string(c -> c.url()).validate("ftp://example.com")
// ==> Valid[value=ftp://example.com]

Yavi._string(c -> c.url(u -> u.protocol("http", "https").build())).validate("ftp://example.com")
// ==> Invalid[errors=[The protocol of the value must be one of the following values: [http, https] (charSequence.url.protocol)]]

Yavi._object(URI.class).untyped().validate("https://example.com/api")
// ==> Valid[value=https://example.com/api]  (a URI)

c.uri() needs a scheme, as uri() of Raoh does. c.url() takes every protocol that java.net.URL handles unless the protocols are given. Both keep the String; Yavi._object(URI.class) produces a URI and takes any URI reference, also a relative one.

Numeric constraints

Yavi._integer(c -> c.greaterThanOrEqual(0).lessThanOrEqual(150)).validate(25)
// ==> Valid[value=25]

Yavi._integer(c -> c.greaterThanOrEqual(0).lessThanOrEqual(150)).validate(300)
// ==> Invalid[errors=[The value must be less than or equal to 150 (numeric.lessThanOrEqual)]]

Yavi._integer(c -> c.positive()).validate(-1)
// ==> Invalid[errors=[The value must be positive (numeric.positive)]]

Yavi._bigDecimal(c -> c.fractionDigits(4)).validate(new BigDecimal("0.1234"))
// ==> Valid[value=0.1234]

Temporal constraints

A temporal validator reads an ISO-8601 string, so there is no string().date().

Yavi._localDate().untyped().validate("2025-06-15")
// ==> Valid[value=2025-06-15]

Yavi._instant().untyped().validate("2025-06-15T10:30:00Z")
// ==> Valid[value=2025-06-15T10:30:00Z]

Yavi._localDate(c -> c.after(() -> LocalDate.of(2020, 1, 1))).validate(LocalDate.of(2025, 6, 15))
// ==> Valid[value=2025-06-15]

Yavi._localDate(c -> c.before(() -> LocalDate.of(2030, 1, 1))).validate(LocalDate.of(2035, 1, 1))
// ==> Invalid[errors=[The value has to be before 2030-01-01 (temporal.before)]]

Yavi._localDate(c -> c.between(() -> LocalDate.of(2020, 1, 1), () -> LocalDate.of(2030, 12, 31))).validate(LocalDate.of(2025, 6, 15))
// ==> Valid[value=2025-06-15]

A bound is a supplier. Raoh has no past() and future() on purpose; YAVI has them and takes a Clock, so the result is reproducible:

var now = Instant.parse("2025-06-15T12:00:00Z");
Yavi._instant(c -> c.before(() -> now)).validate(Instant.parse("2025-06-15T11:00:00Z"))
// ==> Valid[value=2025-06-15T11:00:00Z]

var clock = Clock.fixed(now, ZoneOffset.UTC);
Yavi._instant(c -> c.past(clock)).validate(Instant.parse("2025-06-15T11:00:00Z"))
// ==> Valid[value=2025-06-15T11:00:00Z]

String-to-type conversions (coerce)

In Raoh the conversion is a part of the decoder (string().toInt().range(0, 150)). In YAVI it belongs to the input reader: the validator of an Integer stays the same, and the reader takes a string as text that stands for the type.

InputReader<Object> text = InputReader.ofJdkTypes().coercingStrings();

Yavi._integer().readingWith(text).validate("42")
// ==> Valid[value=42]

Yavi._integer(c -> c.greaterThanOrEqual(0).lessThanOrEqual(150)).readingWith(text).validate("25")
// ==> Valid[value=25]

Yavi._integer().readingWith(text).validate("abc")
// ==> Invalid[errors=[The value must be of type integer (object.type)]]

Yavi._long().readingWith(text).validate("9999999999")
// ==> Valid[value=9999999999]

Yavi._bigDecimal(c -> c.fractionDigits(2)).readingWith(text).validate("19.99")
// ==> Valid[value=19.99]

Yavi._bigDecimal().readingWith(text).validate("abc")
// ==> Invalid[errors=[The value must be of type number (object.type)]]

The rules are strict unless the reader is given others: a boolean is true or false, and a number has no surrounding white space. StringCoercion relaxes them for text written by a person:

Yavi._boolean().readingWith(text).validate("true")
// ==> Valid[value=true]

Yavi._boolean().readingWith(text).validate("1")
// ==> Invalid[errors=[The value must be of type boolean (object.type)]]

InputReader<Object> form = InputReader.ofJdkTypes().coercingStrings(StringCoercion.strict().trimming().booleanWords());

Yavi._boolean().readingWith(form).validate("1")
// ==> Valid[value=true]

Yavi._boolean().readingWith(form).validate("no")
// ==> Valid[value=false]

Yavi._boolean().readingWith(form).validate("maybe")
// ==> Invalid[errors=[The value must be of type boolean (object.type)]]

// isTrue() enforces an agreement (e.g. terms of service)
Yavi._boolean(c -> c.isTrue()).readingWith(form).validate("false")
// ==> Invalid[errors=[The value must be true (boolean.isTrue)]]

Yavi._integer().readingWith(form).validate("  42  ")
// ==> Valid[value=42]

booleanWords() takes true/1/yes/on and false/0/no/off in any case, and trimming() removes the white space around every text. A whole map of strings is read with readingParameters() (section 24).

3. Mapping to domain primitives

map converts a validated value into a domain type, so that only validated values of domain types flow inside the application.

record Email(String value) {}
record Age(int value) {}
record UserId(UUID value) {}

var emailValidator = Yavi._string(c -> c.trim().toLowerCase().notBlank().email()).map(Email::new);
var ageValidator = Yavi._integer(c -> c.greaterThanOrEqual(0).lessThanOrEqual(150)).map(Age::new);
var userIdValidator = Yavi._object(UUID.class).map(UserId::new);

emailValidator.validate("  ALICE@example.com  ")
// ==> Valid[value=Email[value=alice@example.com]]

ageValidator.validate(25)
// ==> Valid[value=Age[value=25]]

userIdValidator.untyped().validate("550e8400-e29b-41d4-a716-446655440000")
// ==> Valid[value=UserId[value=550e8400-e29b-41d4-a716-446655440000]]

email() accepts an empty string, as every format does, so notBlank() says that the value is given.

4. Validating objects

Yavi.schema() names the properties of an object, and fromMap ends them with a validator that reads a Map<String, Object> by these names, checks the types and calls the constructor. combine(field(...), ...).map(f) of Raoh is this chain. The violations of all properties are accumulated.

record User(UserId id, Email email, Age age) {}

var userValidator = Yavi.schema()
        ._object("id", userIdValidator)
        ._object("email", emailValidator)
        ._object("age", ageValidator)
        .fromMap(User::new);

userValidator.validate(Map.of(
        "id", "550e8400-e29b-41d4-a716-446655440000",
        "email", "alice@example.com",
        "age", 30))
// ==> Valid[value=User[id=UserId[value=550e8400-e29b-41d4-a716-446655440000], email=Email[value=alice@example.com], age=Age[value=30]]]

userValidator.validate(Map.of("id", "not-uuid", "email", "invalid", "age", 300))
// ==> Invalid[errors=[/id: "id" must be of type UUID (object.type), /email: "email" must be a valid email address (charSequence.email), /age: "age" must be less than or equal to 150 (numeric.lessThanOrEqual)]]

_object(name, validator) uses a validator under a name. A property is also written in place (._string("email", c -> c.notBlank().email())), and map after it creates the domain type, as field("email", string().email().map(Email::new)) of Raoh does:

Yavi.schema()
        ._object("id", UUID.class).map(UserId::new)
        ._string("email", c -> c.trim().toLowerCase().notBlank().email()).map(Email::new)
        ._integer("age", c -> c.greaterThanOrEqual(0).lessThanOrEqual(150)).map(Age::new)
        .fromMap(User::new);

map is one of the modifiers of a property, written before those that decide what null produces: ._string("nickname").map(Nickname::new).optional() is an Optional<Nickname>.

The schema is not bound to a map. The same properties end with apply(User::new) for typed arguments, and the validator of fromMap reads a JSON tree with readingWith and request parameters with readingParameters. Raoh chooses the input first, with the static import of Raoh's MapDecoders or JsonDecoders.

5. Nested objects

Raoh's nested(decoder) is _object(name, validator). The path of a violation is composed.

record Address(String city, String zip) {}
record Customer(String name, Address address) {}

var addressValidator = Yavi.schema()
        ._string("city", c -> c.notBlank())
        ._string("zip", c -> c.pattern("^\\d{3}-\\d{4}$"))
        .fromMap(Address::new);

var customerValidator = Yavi.schema()
        ._string("name", c -> c.notBlank())
        ._object("address", addressValidator)
        .fromMap(Customer::new);

customerValidator.validate(Map.of(
        "name", "Alice",
        "address", Map.of("city", "Tokyo", "zip", "100-0001")))
// ==> Valid[value=Customer[name=Alice, address=Address[city=Tokyo, zip=100-0001]]]

customerValidator.validate(Map.of(
        "name", "",
        "address", Map.of("city", "", "zip", "bad")))
// ==> Invalid[errors=[/name: "name" must not be blank (charSequence.notBlank), /address/city: "address.city" must not be blank (charSequence.notBlank), /address/zip: "address.zip" must match ^\d{3}-\d{4}$ (charSequence.pattern)]]

A violation has a pointer (/address/city) and a name (address.city), which its message shows.

6. Structuring flat data

The result of a JOIN and a CSV file are flat. _embedded is Raoh's flat: the embedded validator reads the same map as the properties.

record UserName(String first, String last) {}
record Department(String name, String code) {}
record Employee(UserName name, Department dept) {}

var userNameValidator = Yavi.schema()
        ._string("first_name", c -> c.notBlank())
        ._string("last_name", c -> c.notBlank())
        .fromMap(UserName::new);

var departmentValidator = Yavi.schema()
        ._string("dept_name", c -> c.notBlank())
        ._string("dept_code", c -> c.notBlank())
        .fromMap(Department::new);

var employeeValidator = Yavi.schema()
        ._embedded(userNameValidator)
        ._embedded(departmentValidator)
        .fromMap(Employee::new);

employeeValidator.validate(Map.of(
        "first_name", "Alice",
        "last_name", "Smith",
        "dept_name", "Engineering",
        "dept_code", "ENG"))
// ==> Valid[value=Employee[name=UserName[first=Alice, last=Smith], dept=Department[name=Engineering, code=ENG]]]

The properties of an embedded validator are known to the validator that embeds it, so it can be strict (section 17), which a combiner with Raoh's flat cannot. A name that two embedded validators define is rejected when the validator is built; rename the columns with SQL aliases.

With a LEFT JOIN all columns of the joined side are null when there is no row. An embedded validator that accepts null is given null when none of its properties has a value, so the department is an Optional, not the Presence of one column:

record EmployeeWithDept(UserName name, Optional<Department> dept) {}

var employeeWithDeptValidator = Yavi.schema()
        ._embedded(userNameValidator)
        ._embedded(departmentValidator).optional()
        .fromMap(EmployeeWithDept::new);

var row = new HashMap<String, Object>();
row.put("first_name", "Bob");
row.put("last_name", "Jones");
row.put("dept_name", null);
row.put("dept_code", null);

employeeWithDeptValidator.validate(row)
// ==> Valid[value=EmployeeWithDept[name=UserName[first=Bob, last=Jones], dept=Optional.empty]]

row.put("dept_name", "Engineering");
employeeWithDeptValidator.validate(row)
// ==> Invalid[errors=[/dept_code: "dept_code" must not be blank (charSequence.notBlank)]]

One-to-many JOIN

Each row is validated with the parent and the child embedded, and the rows are grouped by the parent afterwards. liftList() validates every row and prefixed locates the violations (section 15).

record OrderHeader(String orderId, String customerName) {}
record OrderLine(String productId, int quantity, BigDecimal unitPrice) {}
record OrderWithLines(OrderHeader header, List<OrderLine> lines) {}

var headerValidator = Yavi.schema()
        ._string("order_id", c -> c.notBlank())
        ._string("customer_name", c -> c.notBlank())
        .fromMap(OrderHeader::new);

var lineValidator = Yavi.schema()
        ._string("product_id", c -> c.notBlank())
        ._integer("qty", c -> c.positive())
        ._bigDecimal("unit_price", c -> c.positive())
        .fromMap(OrderLine::new);

var rowValidator = Yavi.schema()
        ._embedded(headerValidator)
        ._embedded(lineValidator)
        .fromMap((header, line) -> Map.entry(header, line));

// SELECT o.order_id, o.customer_name, l.product_id, l.qty, l.unit_price
// FROM orders o JOIN order_lines l ON o.order_id = l.order_id
var joinRows = List.<Map<String, Object>>of(
        Map.of("order_id", "ORD-001", "customer_name", "Alice", "product_id", "A01", "qty", 2, "unit_price", 1500),
        Map.of("order_id", "ORD-001", "customer_name", "Alice", "product_id", "B02", "qty", 1, "unit_price", 3000),
        Map.of("order_id", "ORD-002", "customer_name", "Bob", "product_id", "A01", "qty", 5, "unit_price", 1500));

var orders = rowValidator.liftList().prefixed("rows").validate(joinRows).map(entries ->
        entries.stream()
                .collect(Collectors.groupingBy(
                        Map.Entry::getKey,
                        LinkedHashMap::new,
                        Collectors.mapping(Map.Entry::getValue, Collectors.toList())))
                .entrySet().stream()
                .map(e -> new OrderWithLines(e.getKey(), e.getValue()))
                .toList());
orders
// ==> Valid[value=[OrderWithLines[header=OrderHeader[orderId=ORD-001, customerName=Alice], lines=[OrderLine[productId=A01, quantity=2, unitPrice=1500], OrderLine[productId=B02, quantity=1, unitPrice=3000]]], OrderWithLines[header=OrderHeader[orderId=ORD-002, customerName=Bob], lines=[OrderLine[productId=A01, quantity=5, unitPrice=1500]]]]]

7. Lists

_list(name, elementValidator) validates every element and locates a violation under its index. The constraints of the list itself are the third argument.

record OrderItem(String productId, int quantity) {}

var orderItemValidator = Yavi.schema()
        ._string("productId", c -> c.notBlank())
        ._integer("quantity", c -> c.positive())
        .fromMap(OrderItem::new);

var orderItemsValidator = Yavi.schema()
        ._list("items", orderItemValidator, c -> c.notEmpty())
        .fromMap();

orderItemsValidator.validate(Map.of("items", List.of(
        Map.of("productId", "A001", "quantity", 3),
        Map.of("productId", "", "quantity", -1))))
// ==> Invalid[errors=[/items/1/productId: "items[1].productId" must not be blank (charSequence.notBlank), /items/1/quantity: "items[1].quantity" must be positive (numeric.positive)]]

A schema of one property ends with fromMap() without a function: the value of the property is the result. It takes the place of a single field(...) of Raoh.

Yavi.schema()._list("tags", Yavi._string(), c -> c.greaterThanOrEqual(1).lessThanOrEqual(10)).fromMap()
        .validate(Map.of("tags", List.of("a", "b")))
// ==> Valid[value=[a, b]]

Yavi.schema()._list("tags", Yavi._string(), c -> c.unique()).fromMap()
        .validate(Map.of("tags", List.of("a", "b", "a")))
// ==> Invalid[errors=[/tags: "tags" must be unique. [a] is/are duplicated. (collection.unique)]]

Yavi.schema()._list("codes", Yavi._string(), c -> c.fixedSize(3)).fromMap()
        .validate(Map.of("codes", List.of("X", "Y")))
// ==> Invalid[errors=[/codes: The size of "codes" must be 3. The given size is 2 (container.fixedSize)]]

A custom message follows its constraint:

Yavi.schema()._list("tags", Yavi._string(), c -> c.greaterThanOrEqual(1).message("select at least one tag")).fromMap()
        .validate(Map.of("tags", List.of()))
// ==> Invalid[errors=[/tags: select at least one tag (container.greaterThanOrEqual)]]

The constraints of a list are checked when every element is valid. A list that is not a property is Yavi._list(elementValidator, c -> ...).

8. Maps

_map(name, valueValidator) validates the values of a map with dynamic keys.

var pricesValidator = Yavi.schema()
        ._map("prices", Yavi._bigDecimal(c -> c.positive()), c -> c.notEmpty())
        .fromMap();

pricesValidator.validate(Map.of("prices", Map.of("apple", 120, "banana", 80)))
// ==> Valid[value={banana=80, apple=120}]

pricesValidator.validate(Map.of("prices", Map.of("apple", -1)))
// ==> Invalid[errors=[/prices/apple: "prices.apple" must be positive (numeric.positive)]]

JSON stored in a string

Raoh's pipe is andThen. The parser is a validator that reports its failure as a violation. This one uses Jackson, which is added to the class path of jshell.

var mapper = new tools.jackson.databind.ObjectMapper();

ValueValidator<String, Map<String, Object>> parseJson = (s, locale, context) -> {
    try {
        @SuppressWarnings("unchecked")
        Map<String, Object> parsed = (Map<String, Object>) mapper.readValue(s, Map.class);
        return Validated.successWith(parsed);
    }
    catch (Exception e) {
        return Validated.failureWith(ViolationMessage.of("json.invalid", "\"{0}\" cannot be parsed as JSON"), s, locale);
    }
};

record Params(String kind, int count) {}

var paramsValidator = Yavi.schema()
        ._string("kind")
        ._integer("count")
        .fromMap(Params::new);

// "params" is a string column holding JSON
var validator = Yavi.schema()
        ._object("params", Yavi._string().andThen(parseJson).andThen(paramsValidator))
        .fromMap();

validator.validate(Map.of("params", "{\"kind\":\"like\",\"count\":3}"))
// ==> Valid[value=Params[kind=like, count=3]]

validator.validate(Map.of("params", "not json"))
// ==> Invalid[errors=[/params: "params" cannot be parsed as JSON (json.invalid)]]

validator.validate(Map.of("params", "{\"kind\":\"like\"}"))
// ==> Invalid[errors=[/params/count: "params.count" is required (object.required)]]

A hand-written validator is a lambda of the input, the locale and a context. A violation is created from a message key and a message format, where {0} is the name that the violation is reported under.

9. Optional, nullable and three-state properties

A property is required and rejects null unless a modifier after it says otherwise.

// required, null not allowed
Yavi.schema()._string("email", c -> c.email()).fromMap().validate(Map.of("email", "a@b.com"))
// ==> Valid[value=a@b.com]

// null allowed: the value is a @Nullable String
Yavi.schema()._string("nickname").nullable().fromMap().validate(Collections.singletonMap("nickname", null))
// ==> Valid[value=null]

// optional: the value is an Optional<String>
Yavi.schema()._string("middleName").optional().fromMap().validate(Map.of())
// ==> Valid[value=Optional.empty]

nullable(), optional() and defaultValue(...) accept both an absent key and null. Raoh keeps the two apart: field(name, nullable(dec)) requires the key and optionalField(name, dec) rejects null. The last modifier of a property says the same:

Yavi.schema()._string("nickname").nullable().required().fromMap()
        .validate(Map.of())
// ==> Invalid[errors=[/nickname: "nickname" is required (object.required)]]

Yavi.schema()._string("middleName").optional().rejectingNull().fromMap()
        .validate(Collections.singletonMap("middleName", null))
// ==> Invalid[errors=[/middleName: "middleName" must not be null (object.notNull)]]

presence() reads a property as a Presence, which tells the three states apart (Present(value), PresentNull, Absent).

var bioValidator = Yavi.schema()._string("bio").nullable().presence().fromMap();

bioValidator.validate(Map.of("bio", "hello"))
// ==> Valid[value=Present[value=hello]]

bioValidator.validate(Collections.singletonMap("bio", null))
// ==> Valid[value=PresentNull[]]

bioValidator.validate(Map.of())
// ==> Valid[value=Absent[]]

presence() adds only the absent state. Whether null is accepted is said by the property, so a property may be omitted but not cleared without nullable(). This suits a PATCH request:

record ProfilePatch(Presence<String> nickname, Presence<String> bio) {}

var profilePatchValidator = Yavi.schema()
        ._string("nickname", c -> c.lessThanOrEqual(50)).presence()        // may be omitted, cannot be cleared
        ._string("bio", c -> c.lessThanOrEqual(500)).nullable().presence() // may be omitted or cleared
        .fromMap(ProfilePatch::new);

profilePatchValidator.validate(Map.of("nickname", "alice"))
// ==> Valid[value=ProfilePatch[nickname=Present[value=alice], bio=Absent[]]]

profilePatchValidator.validate(Collections.singletonMap("nickname", null))
// ==> Invalid[errors=[/nickname: "nickname" must not be null (object.notNull)]]

10. Enums

An enum constant is read from its name. The name is matched exactly; ignoringCase() of the validator of the enum takes any case, as Raoh's enumOf does.

enum Role { ADMIN, MEMBER, GUEST }

Yavi.schema()._enum("role", Role.class).fromMap().validate(Map.of("role", "ADMIN"))
// ==> Valid[value=ADMIN]

Yavi.schema()._enum("role", Role.class).fromMap().validate(Map.of("role", "admin"))
// ==> Invalid[errors=[/role: "role" must be one of the following values: [ADMIN, MEMBER, GUEST] (object.oneOf)]]

Yavi.schema()._enum(Yavi._enum("role", Role.class).ignoringCase()).fromMap().validate(Map.of("role", "admin"))
// ==> Valid[value=ADMIN]

Yavi.schema()._enum("role", Role.class).defaultValue(Role.MEMBER).fromMap().validate(Map.of())
// ==> Valid[value=MEMBER]

11. Union types

Raoh's oneOf(a, b) is ValueValidator.anyOf(a, b): the first alternative that is valid. Raoh's literal("email") is the constraint equalTo.

interface Contact {}
record EmailContact(String address) implements Contact {}
record PhoneContact(String number) implements Contact {}

ValueValidator<Map<String, Object>, Contact> contactValidator = ValueValidator.anyOf(
        Yavi.schema()
                ._string("kind", c -> c.equalTo("email"))
                ._string("value", c -> c.email())
                .fromMap((kind, value) -> new EmailContact(value)),
        Yavi.schema()
                ._string("kind", c -> c.equalTo("phone"))
                ._string("value", c -> c.pattern("^\\d{10,15}$"))
                .fromMap((kind, value) -> new PhoneContact(value)));

contactValidator.validate(Map.of("kind", "email", "value", "a@b.com"))
// ==> Valid[value=EmailContact[address=a@b.com]]

contactValidator.validate(Map.of("kind", "phone", "value", "09012345678"))
// ==> Valid[value=PhoneContact[number=09012345678]]

contactValidator.validate(Map.of("kind", "fax", "value", "123"))
// ==> Invalid[errors=[The value must satisfy at least one of the 2 alternatives (object.anyOf) alternatives=[[/kind: "kind" must be equal to email (object.equalTo), /value: "value" must be a valid email address (charSequence.email)], [/kind: "kind" must be equal to phone (object.equalTo), /value: "value" must match ^\d{10,15}$ (charSequence.pattern)]]]]

No cast to the supertype is needed, but the type of the variable is: var infers Record & Contact. The one violation holds the violations of each alternative:

if (contactValidator.validate(Map.of("kind", "fax", "value", "123")).errors().get(0) instanceof ConstraintViolation.NoAlternativeMatched unmatched) {
    unmatched.alternatives().forEach(violations -> System.out.println(violations.messagesByPointer()));
}
// {/kind=["kind" must be equal to email], /value=["value" must be a valid email address]}
// {/kind=["kind" must be equal to phone], /value=["value" must match ^\d{10,15}$]}

A discriminated union

Raoh's discriminate("type", variant(...), ...) is DiscriminatedUnionValidator. It reads the discriminator first and validates only the selected alternative, which does not define the discriminator.

interface Shape {}
record Circle(double radius) implements Shape {}
record Rect(double width, double height) implements Shape {}

var shapeValidator = DiscriminatedUnionValidator.<Shape>of("type")
        .when("circle", Yavi.schema()._double("radius", c -> c.positive()).fromMap(Circle::new))
        .when("rect", Yavi.schema()
                ._double("width", c -> c.positive())
                ._double("height", c -> c.positive())
                .fromMap(Rect::new));

shapeValidator.validate(Map.of("type", "circle", "radius", 5.0))
// ==> Valid[value=Circle[radius=5.0]]

shapeValidator.validate(Map.of("type", "rect", "width", 3.0, "height", 4.0))
// ==> Valid[value=Rect[width=3.0, height=4.0]]

shapeValidator.validate(Map.of("type", "hexagon"))
// ==> Invalid[errors=[/type: "type" must be one of the following values: [circle, rect] (object.oneOf)]]

A schema of one property is a validator like any other, so no asDecoder() is needed. Two alternatives of one tag fail with IllegalArgumentException when the validator is built.

12. Cross-field validation

Raoh's flatMap is flatFromMap: the function receives the validated properties and returns a Validated, so a factory method that checks a rule of the domain is given as it is. It is called only when all properties are valid.

record DateRange(LocalDate start, LocalDate end) {
    static Validated<DateRange> parse(LocalDate start, LocalDate end) {
        if (!start.isBefore(end)) {
            return Validated.failureWith(ViolationMessage.of("dateRange.invalid", "start must be before end"));
        }
        return Validated.successWith(new DateRange(start, end));
    }
}

var dateRangeValidator = Yavi.schema()
        ._localDate("start")
        ._localDate("end")
        .flatFromMap(DateRange::parse);

dateRangeValidator.validate(Map.of("start", "2025-01-01", "end", "2025-12-31"))
// ==> Valid[value=DateRange[start=2025-01-01, end=2025-12-31]]

dateRangeValidator.validate(Map.of("start", "2025-12-31", "end", "2025-01-01"))
// ==> Invalid[errors=[start must be before end (dateRange.invalid)]]

Yavi.schema()._object("period", dateRangeValidator).fromMap()
        .validate(Map.of("period", Map.of("start", "2025-12-31", "end", "2025-01-01")))
// ==> Invalid[errors=[/period: start must be before end (dateRange.invalid)]]

The violation is reported on the object itself, and under period where the validator is nested. failureWith(message, args...) is Raoh's Result.fail(code, message): the factory method names neither a violated value nor a locale, which it is not given. The validator reports the violation with the locale of the validation, like the violations of the properties.

dateRangeValidator.validate(Map.of("start", "2025-12-31", "end", "2025-01-01"), Locale.JAPANESE)
        .errors().get(0).locale()
// ==> ja

A rule that is a predicate on the created object needs no factory method: constraintOnTarget takes the predicate, the name that locates the violation (the empty name is the object itself) and the message.

var dateRangeValidator2 = Yavi.schema()
        ._localDate("start")
        ._localDate("end")
        .fromMap(DateRange::new)
        .constraintOnTarget(range -> range.start().isBefore(range.end()), "end",
                ViolationMessage.of("dateRange.invalid", "\"{0}\" must be after \"start\""));

dateRangeValidator2.validate(Map.of("start", "2025-12-31", "end", "2025-01-01"))
// ==> Invalid[errors=[/end: "end" must be after "start" (dateRange.invalid)]]

13. Conditional validation

Validating the remaining properties by the value of one property is a discriminated union. The lambda of the Raoh tutorial, which reads method and switches, is not needed:

interface Payment {}
record CreditCard(String number, String expiry) implements Payment {}
record BankTransfer(String bankCode, String accountNumber) implements Payment {}

var paymentValidator = DiscriminatedUnionValidator.<Payment>of("method")
        .when("credit_card", Yavi.schema()
                ._string("number", c -> c.notBlank())
                ._string("expiry", c -> c.pattern("^\\d{2}/\\d{2}$"))
                .fromMap(CreditCard::new))
        .when("bank_transfer", Yavi.schema()
                ._string("bankCode", c -> c.notBlank())
                ._string("accountNumber", c -> c.notBlank())
                .fromMap(BankTransfer::new));

paymentValidator.validate(Map.of("method", "credit_card", "number", "4111111111111111", "expiry", "12/26"))
// ==> Valid[value=CreditCard[number=4111111111111111, expiry=12/26]]

paymentValidator.validate(Map.of("method", "bank_transfer", "bankCode", "0001", "accountNumber", "1234567"))
// ==> Valid[value=BankTransfer[bankCode=0001, accountNumber=1234567]]

paymentValidator.validate(Map.of("method", "cash"))
// ==> Invalid[errors=[/method: "method" must be one of the following values: [credit_card, bank_transfer] (object.oneOf)]]

14. Combining results of different sources

A schema combines the properties of one input. Two results of different inputs are combined with combine, which is Raoh's Result.map2:

record PersonalName(String first, String last) {}
record ContactInfo(String email, String phone) {}
record CustomerProfile(PersonalName name, ContactInfo contact) {}

var nameValidator = Yavi.schema()
        ._string("first", c -> c.notBlank())
        ._string("last", c -> c.notBlank())
        .fromMap(PersonalName::new);

var contactInfoValidator = Yavi.schema()
        ._string("email", c -> c.email())
        ._string("phone", c -> c.notBlank())
        .fromMap(ContactInfo::new);

var nameResult = nameValidator.validate(Map.of("first", "Alice", "last", "Smith"));
var contactResult = contactInfoValidator.validate(Map.of("email", "a@b.com", "phone", "090-1234-5678"));

nameResult.combine(contactResult).apply(CustomerProfile::new)
// ==> Valid[value=CustomerProfile[name=PersonalName[first=Alice, last=Smith], contact=ContactInfo[email=a@b.com, phone=090-1234-5678]]]

nameValidator.validate(Map.of("first", ""))
        .combine(contactInfoValidator.validate(Map.of("email", "x")))
        .apply(CustomerProfile::new)
// ==> Invalid[errors=[/first: "first" must not be blank (charSequence.notBlank), /last: "last" is required (object.required), /email: "email" must be a valid email address (charSequence.email), /phone: "phone" is required (object.required)]]

15. Validating the rows of a list

Raoh's Result.traverse(rows, decoder::decode, Path.of("orders")) is liftList() with prefixed: every row is validated and its violations are located under its index.

record Order(String orderId, BigDecimal total) {}

var orderValidator = Yavi.schema()
        ._string("order_id", c -> c.notBlank())
        ._bigDecimal("total", c -> c.positiveOrZero())
        .fromMap(Order::new);

var rows = List.<Map<String, Object>>of(
        Map.of("order_id", "A001", "total", 1000),
        Map.of("order_id", "", "total", -500),
        Map.of("order_id", "A003", "total", 300));

orderValidator.liftList().prefixed("orders").validate(rows)
// ==> Invalid[errors=[/orders/1/order_id: "orders[1].order_id" must not be blank (charSequence.notBlank), /orders/1/total: "orders[1].total" must be positive or zero (numeric.positiveOrZero)]]

16. Default values and recovery

defaultValue

Raoh's withDefault is defaultValue(...): the default applies to an absent key and to null. A value that is present but invalid is a violation.

var roleValidator = Yavi.schema()
        ._enum(Yavi._enum("role", Role.class).ignoringCase()).defaultValue(Role.MEMBER)
        .fromMap();

roleValidator.validate(Map.of())
// ==> Valid[value=MEMBER]

roleValidator.validate(Map.of("role", "admin"))
// ==> Valid[value=ADMIN]

roleValidator.validate(Map.of("role", "invalid"))
// ==> Invalid[errors=[/role: "role" must be one of the following values: [ADMIN, MEMBER, GUEST] (object.oneOf)]]

The modifier follows the property whatever the input is: the same schema defaults a JSON null, a missing member and an empty request parameter.

recover

recover(fallback) replaces any failure, an invalid value included.

var pageSizeValidator = Yavi.schema()
        ._integer("pageSize", c -> c.greaterThanOrEqual(1).lessThanOrEqual(100)).recover(20)
        .fromMap();

pageSizeValidator.validate(Map.of("pageSize", 999))
// ==> Valid[value=20]

pageSizeValidator.validate(Map.of())
// ==> Valid[value=20]

Use defaultValue for a property that is optional by concept, and recover for one that must not break whatever arrives. recoverWith(violations -> ...) computes the fallback from the violations, for example to log them.

17. Rejecting unknown properties

Raoh's strict(f) is rejectingUnknownProperties() of the validator.

record ApiRequest(String action, int amount) {}

var apiRequestValidator = Yavi.schema()
        ._string("action", c -> c.notBlank())
        ._integer("amount", c -> c.positive())
        .fromMap(ApiRequest::new)
        .rejectingUnknownProperties();

apiRequestValidator.validate(Map.of("action", "transfer", "amount", 100))
// ==> Valid[value=ApiRequest[action=transfer, amount=100]]

apiRequestValidator.validate(Map.of("action", "transfer", "amount", 100, "extra", true))
// ==> Invalid[errors=[/extra: "extra" is not a known property (object.unknownProperty)]]

18. Recursive structures

ValueValidator.recursive(self -> ...) gives the function that builds the validator a reference to it, so no array holds the validator before it is assigned.

record Comment(String body, List<Comment> replies) {}

ObjectInputValidator<Comment> commentValidator = ValueValidator.recursive(self -> Yavi.schema()
        ._string("body", c -> c.notBlank())
        ._list("replies", self).defaultValue(List.of())
        .fromMap(Comment::new));

commentValidator.validate(Map.of(
        "body", "top",
        "replies", List.of(
                Map.of("body", "reply1", "replies", List.of()),
                Map.of("body", "reply2", "replies", List.of(
                        Map.of("body", "nested", "replies", List.of()))))))
// ==> Valid[value=Comment[body=top, replies=[Comment[body=reply1, replies=[]], Comment[body=reply2, replies=[Comment[body=nested, replies=[]]]]]]]

commentValidator.validate(Map.of(
        "body", "top",
        "replies", List.of(
                Map.of("body", "reply1"),
                Map.of("body", "reply2", "replies", List.of(Map.of("body", ""))))))
// ==> Invalid[errors=[/replies/1/replies/0/body: "replies[1].replies[0].body" must not be blank (charSequence.notBlank)]]

The type of the variable is declared: var does not give the compiler the type of self. ValueValidator.lazy(() -> validator) is lazy of Raoh, for validators that refer to each other.

19. Handling violations

var checkValidator = Yavi.schema()
        ._string("email", c -> c.email())
        ._integer("age", c -> c.greaterThanOrEqual(0).lessThanOrEqual(150))
        .fromMap((email, age) -> Map.<String, Object>of("email", email, "age", age));

var result = checkValidator.validate(Map.of("email", "bad", "age", 300));

Validated is a sealed interface of the records Valid and Invalid, so a result is handled with a switch. errors() returns the violations of a failed result.

For forms

Raoh's issues.flatten() is messagesByPointer(), or messagesByName() with the names of the fields of a form.

switch (result) {
    case Validated.Invalid(var violations) -> System.out.println(violations.messagesByPointer());
    case Validated.Valid(var value) -> {}
}
// {/email=["email" must be a valid email address], /age=["age" must be less than or equal to 150]}

result.errors().messagesByName()
// ==> {email=["email" must be a valid email address], age=["age" must be less than or equal to 150]}

For APIs

Raoh's issues.toJsonList() is details(): a list of records that a JSON library serializes as they are. params is Raoh's meta.

result.errors().details()
// ==> [Simple[name=email, pointer=/email, messageKey=charSequence.email, message="email" must be a valid email address, params={}], Simple[name=age, pointer=/age, messageKey=numeric.lessThanOrEqual, message="age" must be less than or equal to 150, params={max=150}]]

Locale-aware messages

A MessageFormatter formats the messages. ResourceBundleMessageFormatter looks a message up by its key in a resource bundle, here messages_ja.properties on the class path, and is the ResourceBundleMessageResolver of Raoh:

charSequence.email="{0}" はメールアドレスの形式で入力してください
numeric.lessThanOrEqual="{0}" は {1} 以下で入力してください
var formatter = new ResourceBundleMessageFormatter("messages");

checkValidator.formattingWith(formatter).validate(Map.of("email", "bad", "age", 300), Locale.JAPANESE)
// ==> Invalid[errors=[/email: "email" はメールアドレスの形式で入力してください (charSequence.email), /age: "age" は 150 以下で入力してください (numeric.lessThanOrEqual)]]

The formatter is given to the validator, or to the violations afterwards (violations.formattedWith(formatter)). A key that the bundle does not have keeps its default message. With Spring, new MessageSourceMessageFormatter(messageSource::getMessage) reads a MessageSource.

20. Scenario: a user registration API

interface ContactMethod {}
record EmailMethod(String address) implements ContactMethod {}
record PhoneMethod(String number) implements ContactMethod {}
record Password(String value) {}
record UserRegistration(Email email, Password password, Role role, List<ContactMethod> contacts) {}

ValueValidator<Map<String, Object>, ContactMethod> contactMethodValidator = ValueValidator.anyOf(
        Yavi.schema()
                ._string("kind", c -> c.equalTo("email"))
                ._string("value", c -> c.email())
                .fromMap((kind, value) -> new EmailMethod(value)),
        Yavi.schema()
                ._string("kind", c -> c.equalTo("phone"))
                ._string("value", c -> c.pattern("^\\d{10,15}$"))
                .fromMap((kind, value) -> new PhoneMethod(value)));

var userRegistrationValidator = Yavi.schema()
        ._object("email", emailValidator)
        ._string("password", c -> c.greaterThanOrEqual(8).lessThanOrEqual(128)).map(Password::new)
        ._enum("role", Role.class).defaultValue(Role.MEMBER)
        ._list("contacts", contactMethodValidator, c -> c.notEmpty())
        .fromMap(UserRegistration::new);

userRegistrationValidator.validate(Map.of(
        "email", "  ALICE@Example.com  ",
        "password", "secureP@ss1",
        "contacts", List.of(
                Map.of("kind", "email", "value", "alice@example.com"),
                Map.of("kind", "phone", "value", "09012345678"))))
// ==> Valid[value=UserRegistration[email=Email[value=alice@example.com], password=Password[value=secureP@ss1], role=MEMBER, contacts=[EmailMethod[address=alice@example.com], PhoneMethod[number=09012345678]]]]

userRegistrationValidator.validate(Map.of(
        "email", "bad",
        "password", "short",
        "contacts", List.of(
                Map.of("kind", "email", "value", "not-email"))))
// ==> Invalid[errors=[/email: "email" must be a valid email address (charSequence.email), /password: The size of "password" must be greater than or equal to 8. The given size is 5 (container.greaterThanOrEqual), /contacts/0: "contacts[0]" must satisfy at least one of the 2 alternatives (object.anyOf) alternatives=[[/contacts/0/value: "contacts[0].value" must be a valid email address (charSequence.email)], [/contacts/0/kind: "contacts[0].kind" must be equal to phone (object.equalTo), /contacts/0/value: "contacts[0].value" must match ^\d{10,15}$ (charSequence.pattern)]]]]

A controller that receives JSON reads the tree with the same validator; nothing is imported differently. New features in 0.18.0 shows JsonNodeReader and the features of the mapper that keep a number as it is written, which Raoh gets from its own readTree.

@PostMapping("/users")
ResponseEntity<?> register(@RequestBody JsonNode body) {
    return switch (userRegistrationValidator.readingWith(JsonNodeReader.INSTANCE).validate(body)) {
        case Validated.Valid<UserRegistration>(var registration) ->
            ResponseEntity.status(201).body(userService.register(registration));
        case Validated.Invalid<UserRegistration>(var violations) ->
            ResponseEntity.badRequest().body(violations.details());
    };
}

21. Converting a list to a map

The list is validated and map converts it.

record Product(String id, BigDecimal price) {}

var productValidator = Yavi.schema()
        ._string("id", c -> c.notBlank())
        ._bigDecimal("price", c -> c.positive())
        .fromMap(Product::new);

var priceMapValidator = Yavi.schema()
        ._list("products", productValidator)
        .fromMap()
        .map(products -> products.stream().collect(Collectors.toMap(Product::id, Product::price)));

priceMapValidator.validate(Map.of("products", List.of(
        Map.of("id", "APPLE", "price", new BigDecimal("120")),
        Map.of("id", "BANANA", "price", new BigDecimal("80")))))
// ==> Valid[value={APPLE=120, BANANA=80}]

A duplicate id is the violation of a rule of the domain. unique(key) of the list reports the duplicated keys, where Raoh checks them by hand in flatMap:

var strictPriceMapValidator = Yavi.schema()
        ._list("products", productValidator, c -> c.unique(Product::id))
        .fromMap()
        .map(products -> products.stream().collect(Collectors.toMap(Product::id, Product::price)));

strictPriceMapValidator.validate(Map.of("products", List.of(
        Map.of("id", "APPLE", "price", new BigDecimal("120")),
        Map.of("id", "APPLE", "price", new BigDecimal("99")))))
// ==> Invalid[errors=[/products: "products" must be unique. [APPLE] is/are duplicated. (collection.uniqueBy)]]

22. Known properties and the remaining keys

_rest collects the keys that no property is defined for, which Raoh does with a hand-written decoder and Result.map2. The values are validated and a violation is located under its key.

record Goods(String name, Map<String, String> attrs) {}

var goodsValidator = Yavi.schema()
        ._string("name", c -> c.notBlank())
        ._rest(Yavi._string())
        .fromMap(Goods::new);

goodsValidator.validate(Map.of("name", "T-shirt", "color", "red", "size", "L"))
// ==> Valid[value=Goods[name=T-shirt, attrs={color=red, size=L}]]

goodsValidator.validate(Map.of("name", "", "color", 1))
// ==> Invalid[errors=[/name: "name" must not be blank (charSequence.notBlank), /color: "color" must be of type string (object.type)]]

_rest() without a validator takes the values as they are.

23. Password confirmation

The two rules are predicates on the three values. The confirmation is not kept, so the rules read an intermediate record and map creates the result. Each violation is located on a field of the form.

record PasswordForm(String current, String newPassword, String confirm) {}
record PasswordChange(String current, String newPassword) {}

var passwordChangeValidator = Yavi.schema()
        ._string("currentPassword", c -> c.notBlank())
        ._string("newPassword", c -> c.greaterThanOrEqual(8).lessThanOrEqual(128))
        ._string("confirmPassword", c -> c.notBlank())
        .fromMap(PasswordForm::new)
        .constraintOnTarget(form -> form.newPassword().equals(form.confirm()), "confirmPassword",
                ViolationMessage.of("password.mismatch", "\"{0}\" must match \"newPassword\""))
        .constraintOnTarget(form -> !form.current().equals(form.newPassword()), "newPassword",
                ViolationMessage.of("password.same", "\"{0}\" must differ from \"currentPassword\""))
        .map(form -> new PasswordChange(form.current(), form.newPassword()));

passwordChangeValidator.validate(Map.of(
        "currentPassword", "oldSecret",
        "newPassword", "newSecret1",
        "confirmPassword", "newSecret1"))
// ==> Valid[value=PasswordChange[current=oldSecret, newPassword=newSecret1]]

passwordChangeValidator.validate(Map.of(
        "currentPassword", "oldSecret",
        "newPassword", "short",
        "confirmPassword", "different"))
// ==> Invalid[errors=[/newPassword: The size of "newPassword" must be greater than or equal to 8. The given size is 5 (container.greaterThanOrEqual)]]

passwordChangeValidator.validate(Map.of(
        "currentPassword", "newSecret1",
        "newPassword", "newSecret1",
        "confirmPassword", "different"))
// ==> Invalid[errors=[/confirmPassword: "confirmPassword" must match "newPassword" (password.mismatch), /newPassword: "newPassword" must differ from "currentPassword" (password.same)]]

The rules are checked only when all properties are valid, like the checks inside flatMap. Unlike them, the rules added one after another are all checked: the last input violates both rules and reports both, so the user corrects the form once.

A rule that makes sense only when another holds is added after map or andThen, which are given a value that satisfies the rules before them. Here the rule on newPassword is checked only when the confirmation matches:

var stepwiseValidator = Yavi.schema()
        ._string("currentPassword", c -> c.notBlank())
        ._string("newPassword", c -> c.greaterThanOrEqual(8).lessThanOrEqual(128))
        ._string("confirmPassword", c -> c.notBlank())
        .fromMap(PasswordForm::new)
        .constraintOnTarget(form -> form.newPassword().equals(form.confirm()), "confirmPassword",
                ViolationMessage.of("password.mismatch", "\"{0}\" must match \"newPassword\""))
        .map(form -> new PasswordChange(form.current(), form.newPassword()))
        .constraintOnTarget(change -> !change.current().equals(change.newPassword()), "newPassword",
                ViolationMessage.of("password.same", "\"{0}\" must differ from \"currentPassword\""));

stepwiseValidator.validate(Map.of(
        "currentPassword", "newSecret1",
        "newPassword", "newSecret1",
        "confirmPassword", "different"))
// ==> Invalid[errors=[/confirmPassword: "confirmPassword" must match "newPassword" (password.mismatch)]]

24. Pagination and query parameters

defaultValue (when missing) and recover (from any failure) say per parameter how much it tolerates.

enum SortOrder { ASC, DESC }
record PageRequest(int page, int size, SortOrder order) {}

var pageRequestValidator = Yavi.schema()
        // page: 0 when absent, a negative number is a violation
        ._integer("page", c -> c.greaterThanOrEqual(0)).defaultValue(0)
        // size: 20 when absent or invalid
        ._integer("size", c -> c.greaterThanOrEqual(1).lessThanOrEqual(100)).recover(20)
        // sort: ASC when absent or invalid
        ._enum(Yavi._enum("sort", SortOrder.class).ignoringCase()).recover(SortOrder.ASC)
        .fromMap(PageRequest::new);

pageRequestValidator.validate(Map.of("page", 2, "size", 50, "sort", "desc"))
// ==> Valid[value=PageRequest[page=2, size=50, order=DESC]]

pageRequestValidator.validate(Map.of())
// ==> Valid[value=PageRequest[page=0, size=20, order=ASC]]

pageRequestValidator.validate(Map.of("size", 9999))
// ==> Valid[value=PageRequest[page=0, size=20, order=ASC]]

pageRequestValidator.validate(Map.of("page", -1))
// ==> Invalid[errors=[/page: "page" must be greater than or equal to 0 (numeric.greaterThanOrEqual)]]

recover covers an absent key too, so it is not combined with a default. Query parameters are strings, which the map of the Raoh tutorial does not show. readingParameters() reads them with the same schema:

var queryValidator = pageRequestValidator.readingParameters();

queryValidator.validate(Map.of("page", "2", "size", "50", "sort", "desc"))
// ==> Valid[value=PageRequest[page=2, size=50, order=DESC]]

queryValidator.validate(Map.of("page", "x", "size", "many"))
// ==> Invalid[errors=[/page: "page" must be of type integer (object.type)]]

25. Amount and currency

The number of decimal places that an amount may have depends on its currency.

enum Currency { JPY, USD, EUR }
record Money(BigDecimal amount, Currency currency) {}

var moneyValidator = Yavi.schema()
        ._bigDecimal("amount", c -> c.positiveOrZero())
        ._enum(Yavi._enum("currency", Currency.class).ignoringCase())
        .flatFromMap((amount, currency) -> {
            int maxScale = switch (currency) {
                case JPY -> 0;
                case USD, EUR -> 2;
            };
            if (amount.scale() > maxScale) {
                return Validated.failureWith(ViolationMessage.of("money.scale", "{1} does not allow more than {2} decimal places", "currency", "maxScale"),
                        currency, maxScale);
            }
            return Validated.successWith(new Money(amount, currency));
        });

moneyValidator.validate(Map.of("amount", new BigDecimal("1000"), "currency", "jpy"))
// ==> Valid[value=Money[amount=1000, currency=JPY]]

moneyValidator.validate(Map.of("amount", new BigDecimal("10.5"), "currency", "jpy"))
// ==> Invalid[errors=[JPY does not allow more than 0 decimal places (money.scale)]]

moneyValidator.validate(Map.of("amount", new BigDecimal("9.99"), "currency", "usd"))
// ==> Valid[value=Money[amount=9.99, currency=USD]]

The rule that does not need the currency is a constraint of the amount (positiveOrZero()). A rule without arguments in its message is shorter as a predicate:

        .fromMap(Money::new)
        .constraintOnTarget(money -> money.amount().scale() <= (money.currency() == Currency.JPY ? 0 : 2), "amount",
                ViolationMessage.of("money.scale", "\"{0}\" has too many decimal places for the currency"));
// ==> Invalid[errors=[/amount: "amount" has too many decimal places for the currency (money.scale)]]

26. CSV import

All rows are checked and the violations are reported with the index of their row.

record MemberImport(String email, String name, int age) {}

var memberValidator = Yavi.schema()
        ._string("email", c -> c.trim().toLowerCase().notBlank().email())
        ._string("name", c -> c.trim().notBlank().lessThanOrEqual(100))
        ._integer("age", c -> c.greaterThanOrEqual(0).lessThanOrEqual(150))
        .fromMap(MemberImport::new);

var rows = List.<Map<String, Object>>of(
        Map.of("email", "alice@example.com", "name", "Alice", "age", 30),
        Map.of("email", "bad-email", "name", "", "age", 200),
        Map.of("email", "bob@example.com", "name", "Bob", "age", 25),
        Map.of("email", "also-bad", "name", "Carol", "age", -1));

switch (memberValidator.liftList().prefixed("rows").validate(rows)) {
    case Validated.Valid(var members) -> System.out.println("Imported: " + members.size());
    case Validated.Invalid(var violations) -> violations.messagesByPointer().forEach((pointer, messages) ->
            System.out.println(pointer + ": " + messages));
}
// /rows/1/email: ["rows[1].email" must be a valid email address]
// /rows/1/name: ["rows[1].name" must not be blank]
// /rows/1/age: ["rows[1].age" must be less than or equal to 150]
// /rows/3/email: ["rows[3].email" must be a valid email address]
// /rows/3/age: ["rows[3].age" must be greater than or equal to 0]

The cells of a real CSV file are strings. The same validator reads them with readingParameters, and trimming() trims every cell, so no property repeats c.trim():

var cells = List.of(
        Map.of("email", " Alice@Example.com ", "name", " Alice ", "age", "30"),
        Map.of("email", "bad-email", "name", "  ", "age", "abc"));

memberValidator.readingParameters(StringCoercion.strict().trimming()).liftList().prefixed("rows").validate(cells)
// ==> Invalid[errors=[/rows/1/email: "rows[1].email" must be a valid email address (charSequence.email), /rows/1/name: "rows[1].name" must not be blank (charSequence.notBlank), /rows/1/age: "rows[1].age" must be of type integer (object.type)]]

27. Configuration files

Required and optional sections of a configuration file that is parsed into a map.

record DbConfig(String host, int port, String database) {}
record CacheConfig(String host, int port, int ttlSeconds) {}
record AppConfig(DbConfig db, CacheConfig cache, String logLevel) {}

var dbConfigValidator = Yavi.schema()
        ._string("host", c -> c.notBlank())
        ._integer("port", c -> c.greaterThanOrEqual(1).lessThanOrEqual(65535)).defaultValue(5432)
        ._string("database", c -> c.notBlank())
        .fromMap(DbConfig::new);

var cacheConfigValidator = Yavi.schema()
        ._string("host", c -> c.notBlank()).defaultValue("localhost")
        ._integer("port", c -> c.greaterThanOrEqual(1).lessThanOrEqual(65535)).defaultValue(6379)
        ._integer("ttlSeconds", c -> c.positive()).defaultValue(300)
        .fromMap(CacheConfig::new);

var appConfigValidator = Yavi.schema()
        ._object("db", dbConfigValidator)
        // the cache section itself is optional
        ._object("cache", cacheConfigValidator).defaultValue(new CacheConfig("localhost", 6379, 300))
        ._string("logLevel", c -> c.notBlank()).defaultValue("INFO")
        .fromMap(AppConfig::new);

appConfigValidator.validate(Map.of(
        "db", Map.of("host", "db.example.com", "database", "myapp")))
// ==> Valid[value=AppConfig[db=DbConfig[host=db.example.com, port=5432, database=myapp], cache=CacheConfig[host=localhost, port=6379, ttlSeconds=300], logLevel=INFO]]

appConfigValidator.validate(Map.of(
        "db", Map.of("host", "", "database", "myapp")))
// ==> Invalid[errors=[/db/host: "db.host" must not be blank (charSequence.notBlank)]]

28. Tuples

Arguments::of is Raoh's Tuple2::new: fromMap(Arguments::of) produces an Arguments2, a record that is deconstructed in a switch. There are Arguments1 to Arguments16.

var input = Map.<String, Object>of("name", "Alice", "age", 30);

var tupleValidator = Yavi.schema()
        ._string("name")
        ._integer("age")
        .fromMap(Arguments::of);

switch (tupleValidator.validate(input)) {
    case Validated.Valid(Arguments2(var name, var age)) -> System.out.println(name + " is " + age);
    case Validated.Invalid(var violations) -> System.out.println(violations.messagesByPointer());
}
// Alice is 30

The elements are arg1(), arg2(), ... without a pattern.

29. Writing an object back as a map

Raoh writes an encoder next to the decoder. In YAVI the schema that reads a map also writes it: Yavi.reversibleSchema() ends with fromMapReversible, which is fromMap with one accessor per property, and toMap is Raoh's encode. The names are written once.

record ItemId(long value) {}
record Item(ItemId id, String name, BigDecimal price) {}

var itemSchema = Yavi.reversibleSchema()
        ._long("id").map(ItemId::new, ItemId::value)
        ._string("name")
        ._bigDecimal("price")
        .fromMapReversible(Item::new, Item::id, Item::name, Item::price);

itemSchema.toMap(new Item(new ItemId(42L), "Widget", new BigDecimal("9.99")))
// ==> {id=42, name=Widget, price=9.99}

itemSchema.validate(itemSchema.toMap(new Item(new ItemId(42L), "Widget", new BigDecimal("9.99"))))
// ==> Valid[value=Item[id=ItemId[value=42], name=Widget, price=9.99]]
Raoh encoder YAVI
property("name", T::name, string()) _string("name") and the accessor T::name
object(property(...), ...) fromMapReversible(T::new, accessors...)
long_().contramap(ItemId::value) ._long("id").map(ItemId::new, ItemId::value)
nested(subEncoder) _object(name, subSchema)
list(elementEncoder) _list(name, elementSchema)
nullableProperty("x", T::x, enc) .nullable(), .optional()
propertyWithDefault("x", T::x, enc, v) .defaultValue(v)

map(f, g) is map(f) with its reverse. A property of a reversible schema has no map(f) alone, and a validator without a reverse is not taken as a property: neither compiles.

30. Writing null and default values

The modifiers of the property say what is written. A property without a value is written as null, because a named parameter of a statement needs its key.

record Tag(String name) {}
record Article(String title, Optional<String> description, List<Tag> tags) {}

var tagSchema = Yavi.reversibleSchema()
        ._string("name")
        .fromMapReversible(Tag::new, Tag::name);

var articleSchema = Yavi.reversibleSchema()
        ._string("title")
        ._string("description").optional()
        ._list("tags", tagSchema).defaultValue(List.of())
        .fromMapReversible(Article::new, Article::title, Article::description, Article::tags);

articleSchema.toMap(new Article("t", Optional.empty(), List.of()))
// ==> {title=t, description=null, tags=[]}

articleSchema.toMap(new Article("t", Optional.of("d"), List.of(new Tag("java"))))
// ==> {title=t, description=d, tags=[{name=java}]}

The object that is written was created by the validator, so tags is never null here; propertyWithDefault of Raoh replaces a null of the getter.

31. Writing nested objects

A nested schema writes a nested map and a list of them a list of maps.

record Buyer(String name) {}
record Purchase(long id, Buyer buyer, List<Item> items) {}

var buyerSchema = Yavi.reversibleSchema()
        ._string("name")
        .fromMapReversible(Buyer::new, Buyer::name);

var purchaseSchema = Yavi.reversibleSchema()
        ._long("id")
        ._object("buyer", buyerSchema)
        ._list("items", itemSchema)
        .fromMapReversible(Purchase::new, Purchase::id, Purchase::buyer, Purchase::items);

purchaseSchema.toMap(new Purchase(1L, new Buyer("Alice"), List.of(new Item(new ItemId(42L), "Widget", new BigDecimal("9.99")))))
// ==> {id=1, buyer={name=Alice}, items=[{id=42, name=Widget, price=9.99}]}

32. Writing a tagged union

An alternative that is added with the type of its objects is written back with the discriminator. The union that reads is the union that writes.

var circleSchema = Yavi.reversibleSchema()
        ._double("radius")
        .fromMapReversible(Circle::new, Circle::radius);

var rectSchema = Yavi.reversibleSchema()
        ._double("width")
        ._double("height")
        .fromMapReversible(Rect::new, Rect::width, Rect::height);

var shapeSchema = DiscriminatedUnionValidator.<Shape>of("type")
        .when("circle", Circle.class, circleSchema)
        .when("rect", Rect.class, rectSchema);

shapeSchema.toMap(new Circle(2.0))
// ==> {type=circle, radius=2.0}

shapeSchema.validate(shapeSchema.toMap(new Circle(2.0)))
// ==> Valid[value=Circle[radius=2.0]]

An object of a type that no alternative is defined for fails with IllegalArgumentException, as in Raoh.

See New features in 0.18.0 for the views that write some of the properties and for the properties that are withheld.