# Comparison with Raoh [Raoh](https://github.com/raoh-project/raoh-java) is a Java library of decoders inspired by Zod: a decoder takes untyped input and returns either a domain object or all the errors with their paths. YAVI covers the same workflow since 0.18.0. This page writes the sections of the [Raoh tutorial](https://github.com/raoh-project/raoh-java/blob/main/docs/tutorial.md) with YAVI, in the same order, and lists what YAVI cannot do yet. [The Raoh tutorial in YAVI](RaohTutorialInYavi.md) is the whole tutorial with the output of every example. * [Vocabulary](#vocabulary) * [Values](#values): primitives, constraints, coercion, domain primitives * [Objects](#objects): nested, flat, lists, maps, optional, enum, strict, recursive * [Unions](#unions) * [Cross-field rules](#cross-field-rules) * [Defaults and recovery](#defaults-and-recovery) * [Several results and several rows](#several-results-and-several-rows) * [Errors](#errors) * [Scenarios](#scenarios) * [Differences](#differences) * [Encoders](#encoders) The examples assume these imports: ```java import am.ik.yavi.arguments.*; import am.ik.yavi.core.*; import am.ik.yavi.input.*; import am.ik.yavi.validator.Yavi; ``` ## Vocabulary | Raoh | YAVI | | --- | --- | | `Decoder` | `ValueValidator` | | `decoder.decode(input)` returns `Result` | `validator.validate(input)` returns `Validated` | | `Ok(value)` / `Err(issues)` | `Validated.Valid(value)` / `Validated.Invalid(violations)`, a sealed interface | | `Issue` (`path`, `code`, `message`, `meta`) | `ConstraintViolation` (`path()` / `name()`, `messageKey()`, `message()`, `params()`) | | path `/address/zip`, `/items/1/name` | `pointer()` `/address/zip`, `/items/1/name`; `name()` `address.zip`, `items[1].name` | | `combine(field(...), ...).map(f)` | `Yavi.schema()._xxx(...).fromMap(f)` (`ObjectInputValidator`) | | `ObjectDecoders` (input `Object`) | `validator.untyped()` | | `MapDecoders` / `JsonDecoders` / `JooqRecordDecoders` | `fromMap(f)` / `from(reader, f)` with an `InputReader` | | `decoder.map(f)` | `validator.map(f)` | | `decoder.pipe(next)` | `validator.andThen(next)` | | `decoder.flatMap(f)` | `validator.andThen(next)`, or `constraintOnTarget` for a predicate | | `combine(field(...), ...).flatMap(f)` | `Yavi.schema()._xxx(...).flatFromMap(f)` (`flatApply(f)` for arguments) | | `Result.fail(code, message)` | `Validated.failureWith(ViolationMessage.of(key, format))`; in a validator, which is given the value and the locale, `Validated.failureWith(ViolationMessage.of(key, format), value, locale)` | | `result.map(f)` / `result.flatMap(f)` | `validated.map(f)` / `validated.flatMap(f)` | In Raoh the kind of input is chosen first, with the static import (`MapDecoders.*` or `JsonDecoders.*`). In YAVI the schema is written once and the input is chosen last: `fromMap(f)` for a map, `.readingWith(reader)` for a JSON tree, `.readingParameters()` for request parameters, `apply(f)` for typed arguments. ## Values ### Primitive values A validator of a single value is built with `Yavi._string(c -> ...)`, `Yavi._integer(c -> ...)` and so on: the methods have the names of the properties of `Yavi.schema()` and take the constraints. `untyped()` makes the validator accept an `Object` and check its type, which is what `string()` and `int_()` of Raoh do. ```java ValueValidator string = Yavi._string().untyped(); ValueValidator integer = Yavi._integer().untyped(); string.validate("hello"); // Valid[hello] integer.validate(42); // Valid[42] integer.validate(42L); // Valid[42], a number is taken as long as its value is kept integer.validate("not a number"); // object.type: The value must be of type integer ``` | Raoh | YAVI | | --- | --- | | `string()` | `Yavi._string()`, `Yavi._string(c -> ...)` | | `int_()`, `long_()`, `double_()`, `float_()`, `decimal()` | `Yavi._integer`, `Yavi._long`, `Yavi._double`, `Yavi._float`, `Yavi._bigDecimal` | | `bool()` | `Yavi._boolean()` | | `bytes()` | `Yavi._object(byte[].class)` | | `date()`, `iso8601()` | `Yavi._localDate`, `Yavi._instant` and the other temporal methods | | `enumOf(Role.class)` | `Yavi._enum(Role.class)` | Like a Raoh decoder, a validator of a value rejects `null`. It is reported with `object.notNull`, or with the violation of a constraint that rejects `null` such as `notBlank()`. A violation of such a validator has the empty name, and its message says "The value" where a named one shows the name. The name is given by the place where the validator is used (`tags[0]`, `prices.apple`), or as the first parameter: `Yavi._string("email", c -> ...)`. ### Constraints | Raoh | YAVI | | --- | --- | | `string().email()` | `c.email()` | | `minLength(3).maxLength(20)` | `c.greaterThanOrEqual(3).lessThanOrEqual(20)` | | `fixedLength(n)` | `c.fixedSize(n)` | | `nonBlank()` | `c.notBlank()` | | `pattern(regex)` | `c.pattern(regex)` | | `uuid()` (returns `UUID`) | `_object(name, UUID.class)`, which reads the canonical string; `c.uuid()` for a `String` | | `url()` (returns `URI`, `http` / `https` only) | `_object(name, URI.class)`, which reads any URI reference; `c.url()` (any protocol of `java.net.URL`) for a `String` | | `uri()` (returns `URI`, any scheme) | `_object(name, URI.class)`; `c.uri()` for a `String` | | `ip()`, `ipv4()`, `ipv6()` | `c.ip()`, `c.ipv4()`, `c.ipv6()` | | `ulid()` | `c.ulid()` | | `cuid()` | `c.pattern("^c[0-9a-z]{24}$")`; cuid is deprecated by its authors, so it has no constraint of its own | | `int_().range(0, 150)` | `c.greaterThanOrEqual(0).lessThanOrEqual(150)` | | `positive()`, `nonNegative()` | `c.positive()`, `c.positiveOrZero()` | | `int_().multipleOf(n)`, also of `long_()` and `decimal()` | `c.multipleOf(n)` of the integral types, `BigInteger` and `BigDecimal` | | `decimal().scale(4)` | `c.fractionDigits(4)`; `c.integerDigits(n)` bounds the digits before the decimal point | | `date().after(d)`, `before(d)`, `between(a, b)` | `c.after(() -> d)`, `c.before(() -> d)`, `c.between(() -> a, () -> b)` | | a bound taken from a clock by the caller | `c.past()`, `c.future()`, `c.past(clock)` ... | | `string().date()`, `string().iso8601()` | not needed: a temporal validator reads an ISO-8601 string | | a trailing custom message | `.message("...")` after the constraint | ```java ValueValidator date = Yavi._localDate(c -> c.after(() -> LocalDate.of(2020, 1, 1))) .untyped(); date.validate("2025-06-15"); // Valid[2025-06-15] date.validate("2025-13-15"); // object.type: The value must be of type LocalDate ``` ### Transforms and normalization Raoh chains transforms with constraints (`string().trim().toLowerCase().email()`). So does the validator of a `String` value in YAVI: the transforms are written before the constraints and applied in that order, and the constraints and the produced value see the transformed value. ```java StringValidator normalizedEmail = Yavi._string(c -> c.trim().toLowerCase().notBlank().email()); normalizedEmail.validate(" USER@Example.COM "); // Valid[user@example.com] ``` | Raoh | YAVI | | --- | --- | | `trim()` | `c.trim()` (white space of `Character.isWhitespace`, as for `notBlank()`) | | `toLowerCase()`, `toUpperCase()` | `c.toLowerCase()`, `c.toUpperCase()` (`Locale.ROOT`) | | `normalize()` | `c.toNormalForm(Normalizer.Form.NFC)` | | `map(f)` before the constraints | `c.transform(f)` | * A transform is written before the first constraint; `c.notBlank().trim()` does not compile. `null` is not transformed. * A value of another type is transformed with `preprocess` on its validator: `Yavi._bigDecimal("price", c -> c.positive()).preprocess(BigDecimal::stripTrailingZeros)`. * A transform keeps the description and the input type, so the validator is a property of `fromMap`, where the transform runs after the type check. `compose` keeps neither: `email.compose(String::trim)` must be given its type again with `untyped(String.class)`. * The constraints of a property (`ValidatorBuilder#constraint`) have no transforms: that validator checks an object and does not produce a value. The size constraints count code points of the NFC form by default, so `lessThanOrEqual(1)` accepts a decomposed が (U+304B U+3099) without `normalize()`. `c.normalizer(form)` selects another form for counting, and `c.normalizer(null)` none; neither changes the value. ### String-to-type conversions (coerce) In Raoh the conversion is written per decoder (`string().toInt().range(0, 150)`). In YAVI it is a property of the input: the validator of an `Integer` does not change, and the reader takes strings as text that stands for the type. ```java InputReader text = InputReader.ofJdkTypes().coercingStrings(); ValueValidator age = Yavi._integer(c -> c.greaterThanOrEqual(0).lessThanOrEqual(150)) .readingWith(text); age.validate("25"); // Valid[25] age.validate("abc"); // object.type age.validate(""); // object.notNull, an empty string is null ``` For a whole map of strings use `readingParameters()`; see [Pagination](#pagination-and-query-parameters). The rules are stricter than those of Raoh unless the reader is given others (`StringCoercion`): | Input | Raoh | YAVI | YAVI with `StringCoercion.strict().trimming().booleanWords()` | | --- | --- | --- | --- | | `"1"`, `"yes"`, `"on"` for a boolean | `true` (`toBool()`) | `object.type`; only `"true"` and `"false"` are taken | `true`, in any case | | `" 42 "` for a number | `string().trim().toInt()` | `object.type` | `42` | | `" Acme "` for a string | `string().trim()` | `" Acme "`; `c.trim()` trims it | `"Acme"` | | `""` | an error of `toInt()` | `null`, so `optional()` and `defaultValue` apply | `null`, and so is a blank string | ```java InputReader lenient = InputReader.ofJdkTypes() .coercingStrings(StringCoercion.strict().trimming().booleanWords()); age.readingWith(lenient).validate(" 25 "); // Valid[25] Yavi._boolean().readingWith(lenient).validate("Yes"); // Valid[true] ``` The rules belong to the reader, so they are chosen once per input (`readingParameters(coercion)` for a form or a CSV row) and not per field. `trimming()` trims a `String` value too; one whose white space is a part of it, such as a password, is read with `untrimmed()` of its validator (`Yavi._string("password").untrimmed()`). ### Domain primitives `map(f)` creates the domain type. A named validator is reused as a property: ```java record Email(String value) {} record Age(int value) {} record UserId(UUID value) {} StringValidator emailValidator = Yavi._string("email", c -> c.notBlank().email()).map(Email::new); IntegerValidator ageValidator = Yavi._integer("age", c -> c.greaterThanOrEqual(0).lessThanOrEqual(150)) .map(Age::new); ObjectValidator userIdValidator = Yavi._object("id", UUID.class).map(UserId::new); ``` ## Objects ### combine + field ```java record User(UserId id, Email email, Age age) {} ObjectInputValidator userValidator = Yavi.schema() ._object(userIdValidator) ._string(emailValidator) ._integer(ageValidator) .fromMap(User::new); userValidator.validate(Map.of("id", "not-uuid", "email", "invalid", "age", 300)); // id: "id" must be of type UUID // email: "email" must be a valid email address // age: "age" must be less than or equal to 150 ``` A property is also written in place and mapped there, as `field("email", string().email().map(Email::new))` is (`._string("email", c -> c.trim().toLowerCase().notBlank().email()).map(Email::new)`), and a validator without a name is given one with `_object(name, validator)`: `._object("email", normalizedEmail.map(Email::new))`. ### Nested objects `nested(decoder)` is `_object(name, validator)`: ```java record Address(String city, String zip) {} record Customer(String name, Address address) {} ObjectInputValidator
addressValidator = Yavi.schema() ._string("city", c -> c.notBlank()) ._string("zip", c -> c.pattern("^\\d{3}-\\d{4}$")) .fromMap(Address::new); ObjectInputValidator customerValidator = Yavi.schema() ._string("name", c -> c.notBlank()) ._object("address", addressValidator) .fromMap(Customer::new); customerValidator.validate(Map.of("name", "", "address", Map.of("city", "", "zip", "bad"))); // name, address.city, address.zip ``` ### Flat data `combine(flat(a), flat(b))` is `_embedded`: the embedded validators read the same map as the properties. ```java record UserName(String first, String last) {} record Department(String name, String code) {} record Employee(UserName name, Department dept) {} ObjectInputValidator userNameValidator = Yavi.schema() ._string("first_name", c -> c.notBlank()) ._string("last_name", c -> c.notBlank()) .fromMap(UserName::new); ObjectInputValidator departmentValidator = Yavi.schema() ._string("dept_name", c -> c.notBlank()) ._string("dept_code", c -> c.notBlank()) .fromMap(Department::new); ObjectInputValidator employeeValidator = Yavi.schema() ._embedded(userNameValidator) ._embedded(departmentValidator) .fromMap(Employee::new); ``` The result is a `ObjectInputValidator` like any other: it is nested, reads a JSON tree or request parameters and describes the four properties. Unlike `flat`, it can be strict: the properties of the embedded validators are known to `rejectingUnknownProperties()`. A name that two of them define is rejected when the validator is built. A LEFT JOIN whose columns are all `null` is an embedded validator that accepts `null`: it is given `null` when none of its properties has a value. ```java ObjectInputValidator employeeValidator = Yavi.schema() ._embedded(userNameValidator) ._embedded(departmentValidator).nullable() .fromMap(Employee::new); employeeValidator.validate(Map.of("first_name", "Taro", "last_name", "Yamada")); // Employee[name=UserName[first=Taro, last=Yamada], dept=null] ``` `ArgumentsValidators.combine(a, b)` combines validators of any input type, not only of a map, and for that reason knows neither the input type nor the properties. ### Lists `list(nested(decoder))` is `_list(name, elementValidator)`. Every element is validated and a violation is located under its index. ```java record OrderItem(String productId, int quantity) {} ObjectInputValidator orderItemValidator = Yavi.schema() ._string("productId", c -> c.notBlank()) ._integer("quantity", c -> c.positive()) .fromMap(OrderItem::new); ObjectInputValidator> itemsValidator = Yavi.schema() ._list("items", orderItemValidator) .fromMap(items -> items); itemsValidator.validate(Map.of("items", List.of( Map.of("productId", "A001", "quantity", 3), Map.of("productId", "", "quantity", -1)))); // items[1].productId, items[1].quantity ``` The constraints of the list itself (`nonempty()`, `minSize`, `maxSize`, `unique()`) are the third argument of `_list`. They are checked on the validated elements, only when every element is valid, and reported on the list (`tags`): ```java Yavi.schema() ._list("tags", Yavi._string(c -> c.trim().notBlank()), c -> c.notEmpty().lessThanOrEqual(10).unique()) .fromMap(tags -> tags); ``` A list that is not a property, such as the root of a document, is `Yavi._list(elementValidator, c -> ...)`. ### Maps `map(decoder)` is `_map(name, valueValidator)`; a violation is located under the key (`prices.apple`). The constraints of the map (`minSize`) are the third argument. ```java Yavi.schema() ._map("prices", Yavi._bigDecimal(c -> c.positive()), c -> c.notEmpty()) .fromMap(prices -> prices); ``` ### JSON stored in a string `pipe` is `andThen`. The parser is a validator that reports its failure as a violation, and the violations of the inner validator are located under the property: ```java ValueValidator> parseJson = (s, locale, context) -> { try { return Validated.successWith(objectMapper.readValue(s, new TypeReference<>() {})); } catch (JacksonException e) { return Validated.failureWith(ViolationMessage.of("json.invalid", "\"{0}\" cannot be parsed as JSON"), s, locale); } }; record Params(String kind, int count) {} ObjectInputValidator paramsValidator = Yavi.schema() ._string("kind") ._integer("count") .fromMap(Params::new); ObjectInputValidator validator = Yavi.schema() ._object("params", Yavi._string().andThen(parseJson).andThen(paramsValidator)) .fromMap(params -> params); validator.validate(Map.of("params", "not json")); // params: "params" cannot be parsed as JSON validator.validate(Map.of("params", "{\"kind\":\"like\"}")); // params.count: "params.count" is required ``` ### Optional and nullable | Raoh | YAVI | | --- | --- | | `field("email", string().email())` | `_string("email", c -> c.email())` | | `field("email", string().email().map(Email::new))` | `_string("email", c -> c.email()).map(Email::new)` | | `field("nickname", nullable(string()))` (`@Nullable String`) | `_string("nickname").nullable().required()` (`@Nullable String`) | | `optionalField("middleName", string())` (`Optional`) | `_string("middleName").optional().rejectingNull()` (`Optional`) | | `field("role", withDefault(decoder, value))` | `_enum("role", Role.class).defaultValue(value)` | | `field("size", recover(decoder, fallback))` | `_integer("size", c -> ...).recover(fallback)` | | `optionalNullableField("bio", string())` (`Presence`) | `_string("bio").nullable().presence()` (`Presence`) | As in Raoh, a property is required unless it says otherwise, and saying otherwise changes the type of its value, so a nullness checker that reads JSpecify (NullAway, Kotlin) rejects a function that takes a `nullable()` property as a value that is not `null`. An absent key is validated like `null`, so `optional()`, `nullable()` and `defaultValue(...)` accept both. Only the violation differs for a required property: `object.required` for an absent key and `object.notNull` for an explicit `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: `required()` rejects an absent key although `null` is accepted, and `rejectingNull()` rejects an explicit `null` although the key may be absent. The type of the value stays `@Nullable X`, `Optional` or `X` with a default value. ```java record Account(@Nullable Instant deletedAt, Optional middleName, int page) {} ObjectInputValidator accountValidator = Yavi.schema() ._instant("deletedAt").nullable().required() // field("deletedAt", nullable(...)) ._string("middleName").optional().rejectingNull() // optionalField("middleName", ...) ._integer("page").defaultValue(1).rejectingNull() .fromMap(Account::new); accountValidator.validate(Map.of()); // deletedAt: "deletedAt" is required accountValidator.validate(Collections.singletonMap("deletedAt", null)); // Account[deletedAt=null, middleName=Optional.empty, page=1] ``` `presence()` tells "leave unchanged" from "clear the value" in a PATCH request. The property is a `Presence` with the same three states as in Raoh: `Absent`, `PresentNull` and `Present(value)`. ```java record ProfilePatch(Presence nickname, Presence bio) {} ObjectInputValidator patchValidator = Yavi.schema() ._string("nickname", c -> c.lessThanOrEqual(50)).presence() ._string("bio", c -> c.lessThanOrEqual(500)).nullable().presence() .fromMap(ProfilePatch::new); patchValidator.validate(Map.of()); // Absent, Absent patchValidator.validate(Collections.singletonMap("bio", null)); // Absent, PresentNull patchValidator.validate(Collections.singletonMap("nickname", null)); // nickname: "nickname" must not be null ``` Unlike `optionalNullableField`, `presence()` adds only the absent state: a key that is present is validated by the property, which decides whether `null` is accepted. So a property may be omitted but not cleared, unless `nullable()` is written before `presence()`. ### Enums ```java enum Role { ADMIN, MEMBER, GUEST } ObjectInputValidator roleValidator = Yavi.schema() ._enum("role", Role.class).defaultValue(Role.MEMBER) .fromMap(role -> role); roleValidator.validate(Map.of("role", "ADMIN")); // Valid[ADMIN] roleValidator.validate(Map.of()); // Valid[MEMBER] roleValidator.validate(Map.of("role", "admin")); // object.oneOf: must be one of [ADMIN, MEMBER, GUEST] ``` The name of the constant is matched exactly, whereas `enumOf` ignores the ASCII case. `ignoringCase()` of the validator of the enum does the same for every reader: ```java ObjectInputValidator lenientRoleValidator = Yavi.schema() ._enum(Yavi._enum("role", Role.class).ignoringCase()).defaultValue(Role.MEMBER) .fromMap(role -> role); lenientRoleValidator.validate(Map.of("role", "admin")); // Valid[ADMIN] ``` The JSON Schema of the property keeps `"enum": ["ADMIN", "MEMBER", "GUEST"]`. ### Strict mode `strict(f)` is `rejectingUnknownProperties()`: ```java ObjectInputValidator 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, "extra", true)); // extra: "extra" is not a known property ``` ### Recursive structures Raoh's `lazy(() -> decoder)` refers to a decoder that is not built yet. `ValueValidator.lazy(() -> validator)` is the counterpart, and `ValueValidator.recursive(self -> ...)` gives the reference to the function that builds the validator, so that no variable is referred to before it is assigned: ```java record Comment(String body, List replies) {} ObjectInputValidator commentValidator = ValueValidator.recursive(self -> Yavi.schema() ._string("body", c -> c.notBlank()) ._list("replies", self).defaultValue(List.of()) .fromMap(Comment::new)); ``` A field refers to itself, or to a field declared later, by its qualified name: ```java static final ObjectInputValidator VALIDATOR = Yavi.schema() ._string("body", c -> c.notBlank()) ._list("replies", ValueValidator.lazy("Comment", () -> Comment.VALIDATOR)).defaultValue(List.of()) .fromMap(Comment::new); ``` The validator reads a map, request parameters and a JSON tree (`readingWith(reader)`), and `JsonSchema` writes the reference as `$ref`: to `#` for the validator itself, and to `$defs` under the given name (`Comment`) where the validator is nested in another. The depth of the input is not limited; that is the task of the JSON parser. `lazy()` of `ArgumentsNValidator` is unrelated: it defers the creation of the object (`Supplier`), for a validator called from a constructor. ## Unions ### oneOf `oneOf(a, b)` is `ValueValidator.anyOf(a, b)`, and `literal("email")` is the `equalTo` constraint: ```java sealed interface Contact {} record EmailContact(String address) implements Contact {} record PhoneContact(String number) implements Contact {} ValueValidator, 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))); ``` No cast to the supertype is needed. When no alternative matches, both report one issue: Raoh `one_of_failed` with the issues of each candidate in `meta.candidates`, and YAVI `object.anyOf`, a `ConstraintViolation.NoAlternativeMatched` with the violations of each alternative in `alternatives()` (`alternatives` of a `ViolationDetail.NoAlternativeMatched`). They are prefixed with the violation, as `rebase()` does for the candidates. ### discriminate `discriminate("type", variant(...), ...)` is `DiscriminatedUnionValidator`. An alternative does not define the discriminator. ```java sealed interface Shape {} record Circle(double radius) implements Shape {} record Rect(double width, double height) implements Shape {} ValueValidator, Shape> shapeValidator = DiscriminatedUnionValidator.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", "hexagon")); // type: "type" must be one of the following values: [circle, rect] ``` The conditional decoding of the tutorial (a lambda that reads `method` and switches) is the same validator: `DiscriminatedUnionValidator.of("method").when("credit_card", ...).when("bank_transfer", ...)`. ## Cross-field rules A rule that is a predicate on the created object is `constraintOnTarget`. It is evaluated only when all properties are valid, like `flatMap`, and its name locates the violation. Rules added one after another are all checked, and every violated rule is reported; a rule added after `map` or `andThen` is checked only when the rules before it hold. ```java record DateRange(LocalDate start, LocalDate end) {} ObjectInputValidator dateRangeValidator = Yavi.schema() ._localDate("start") ._localDate("end") .fromMap(DateRange::new) .constraintOnTarget(range -> range.start().isBefore(range.end()), "", ViolationMessage.of("dateRange.invalid", "start must be before end")); ``` With the empty name the violation is reported on the object itself, and under `period` when the validator is used as `_object("period", dateRangeValidator)`. Rules on values that are not kept in the result read an intermediate object, and `map` creates the result: ```java record PasswordForm(String current, String newPassword, String confirm) {} record PasswordChange(String current, String newPassword) {} ValueValidator, PasswordChange> 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())); ``` The rule of amount and currency is the same: ```java enum Currency { JPY, USD, EUR } record Money(BigDecimal amount, Currency currency) {} ObjectInputValidator moneyValidator = Yavi.schema() ._bigDecimal("amount", c -> c.positiveOrZero()) ._enum("currency", Currency.class) .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")); ``` A step that creates the result itself and can fail, such as a factory method, is given to `flatFromMap` (`flatApply` for arguments) in place of `fromMap`. It receives the validated properties and returns a `Validated`: ```java record DateRange(LocalDate start, LocalDate end) { static Validated parse(LocalDate start, LocalDate end) { return start.isBefore(end) ? Validated.successWith(new DateRange(start, end)) : Validated.failureWith(ViolationMessage.of("dateRange.invalid", "start must be before end")); } } ObjectInputValidator dateRangeValidator = Yavi.schema() ._localDate("start") ._localDate("end") .flatFromMap(DateRange::parse); ``` `Validated.failureWith(message, args...)` creates a violation with the empty name; `ConstraintViolation.of(message).prefixed("end")` locates it on a property. The function is given neither the violated value nor the locale of the validation, so the violation names neither: the validator reports it with the locale it is called with (`validate(input, locale)`), like the violations of the properties. A step on a single value is a validator given to `andThen`, as `parseJson` above, which passes on the value and the locale that it is given. ## Defaults and recovery `withDefault` is `defaultValue(...)`: it applies to an absent key and to `null`, and a value that is present but invalid is a violation. `recover(decoder, fallback)` is `recover(fallback)`: it applies to an absent key and to `null` like `defaultValue(...)`, and to a value that is present but invalid, so the property never fails. It is for a parameter that must not break a request. ```java ObjectInputValidator pageSizeValidator = Yavi.schema() ._integer("pageSize", c -> c.greaterThanOrEqual(1).lessThanOrEqual(100)).recover(20) .fromMap(pageSize -> pageSize); pageSizeValidator.validate(Map.of("pageSize", 50)); // Valid[50] pageSizeValidator.validate(Map.of("pageSize", 999)); // Valid[20] pageSizeValidator.validate(Map.of("pageSize", "many")); // Valid[20] pageSizeValidator.validate(Map.of()); // Valid[20] ``` The value is read by the reader before it is recovered: with `readingParameters()` the string `"50"` is the integer `50`, and with `readingWith(reader)` a node that is not a number gives the fallback. `recover` is on every `ValueValidator` (`Yavi._integer(c -> ...).recover(20)`, `addressValidator.recover(fallback)`), and it is described like `defaultValue` (`default` in the JSON Schema). `recoverWith(f)` computes the fallback from the violations, for example to log them. For an absent key or `null` there is no violation: ```java ._integer("pageSize", c -> c.greaterThanOrEqual(1).lessThanOrEqual(100)).recoverWith(violations -> { violations.forEach(violation -> log.debug("{}", violation.message())); return 20; }) ``` ## Several results and several rows ### Result.map2 Two results of different sources are combined with `combine`, which accumulates the violations of both: ```java Validated name = userNameValidator.validate(nameRow); Validated department = departmentValidator.validate(departmentRow); Validated employee = name.combine(department).apply(Employee::new); ``` ### Result.traverse `Result.traverse(rows, decoder::decode, Path.of("orders"))` is `liftList` with `prefixed`. The violations of a row are located under its index: ```java Validated> orders = orderValidator.liftList().prefixed("orders").validate(rows); // orders[1].order_id, orders[1].total ``` A one-to-many JOIN is validated row by row and grouped after: ```java Arguments1Validator, Map.Entry> rowValidator = ArgumentsValidators .combine(headerValidator, lineValidator) .apply((header, line) -> Map.entry(header, line)); Validated> 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(entry -> new OrderWithLines(entry.getKey(), entry.getValue())) .toList()); ``` ### Tuples `combine(...).map(Tuple2::new)` is `fromMap(Arguments::of)`, which produces an `Arguments2` with `arg1()` and `arg2()`. It is a record, so it is deconstructed in a `switch`: ```java ObjectInputValidator> validator = Yavi.schema() ._string("name", c -> c.notBlank()) ._integer("age") .fromMap(Arguments::of); switch (validator.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); } ``` ## Errors ```java Validated validated = userValidator.validate(input, Locale.JAPANESE); ConstraintViolations violations = validated.errors(); ``` | Raoh | YAVI | | --- | --- | | `issues.flatten()` | `violations.messagesByPointer()` (`/items/1/name`), `violations.messagesByName()` (`items[1].name`) | | `issues.toJsonList()` | `violations.details()`, a list of `ViolationDetail` (`name`, `pointer`, `messageKey`, `message`, `params`, and `alternatives` for `object.anyOf`) | | `issue.meta()` (`{"min": 0, "max": 150}`) | `violation.params()` (`{"max": 150}`), `params` of a `ViolationDetail`; the violated value is not in it | | `issues.resolve(resolver, locale)` with a `ResourceBundleMessageResolver` | `validator.formattingWith(new ResourceBundleMessageFormatter("messages")).validate(input, locale)`, or `violations.formattedWith(formatter)` afterwards | A message of YAVI holds the name of the property (`"age" must be less than or equal to 150`), a message of Raoh does not (`must be between 0 and 150`). The locale is given when validating; the message key and `args()` are kept in the violation, so a message is also formatted later. A message format of YAVI refers to its arguments by position (`{1}`), a template of Raoh by name (`{max}`); the names of `params()` are for the client that renders a message of its own. ## Scenarios ### User registration ```java record Password(String value) {} record UserRegistration(Email email, Password password, Role role, List contacts) {} ObjectInputValidator userRegistrationValidator = Yavi.schema() ._object("email", normalizedEmail.map(Email::new)) ._string("password", c -> c.greaterThanOrEqual(8).lessThanOrEqual(128)).map(Password::new) ._enum("role", Role.class).defaultValue(Role.MEMBER) ._list("contacts", contactValidator) .fromMap(UserRegistration::new); @PostMapping("/users") ResponseEntity register(@RequestBody JsonNode body) { return switch (userRegistrationValidator.readingWith(JsonNodeReader.INSTANCE).validate(body)) { case Validated.Valid(UserRegistration registration) -> ResponseEntity.status(201).body(userService.register(registration)); case Validated.Invalid(ConstraintViolations violations) -> ResponseEntity.badRequest().body(violations.details()); }; } ``` The same validator reads a map and a `JsonNode`; nothing is imported differently. The README shows `JsonNodeReader` and the two features of the mapper that keep a number as it is written and refuse a key written twice. ### Converting a list to a map ```java record Product(String id, BigDecimal price) {} ValueValidator, Map> priceMapValidator = Yavi.schema() ._list("products", productValidator, c -> c.unique(Product::id)) .fromMap() .map(products -> products.stream().collect(Collectors.toMap(Product::id, Product::price))); // products: "products" must be unique. [APPLE] is/are duplicated. ``` ### Known fields and the remaining fields `_rest` collects the keys that no property is defined for and gives them as a map. Its values are validated, with a violation located under the key, which the lambda of Raoh does not do: ```java record Item(String name, Map attrs) {} ObjectInputValidator itemValidator = Yavi.schema() ._string("name", c -> c.notBlank()) ._rest(Yavi._string(c -> c.notBlank())) .fromMap(Item::new); itemValidator.validate(Map.of("name", "pen", "color", "red")); // Item[name=pen, attrs={color=red}] itemValidator.validate(Map.of("name", "pen", "color", "")); // color: "color" must not be blank ``` `_rest()` without a validator takes the values as they are. ### Pagination and query parameters The tutorial of Raoh decodes a map that already holds numbers. Query parameters are strings, which `readingParameters()` reads with the same schema: ```java enum SortOrder { ASC, DESC } record PageRequest(int page, int size, SortOrder order) {} ValueValidator, PageRequest> pageRequestValidator = Yavi.schema() ._integer("page", c -> c.greaterThanOrEqual(0)).defaultValue(0) ._integer("size", c -> c.greaterThanOrEqual(1).lessThanOrEqual(100)).defaultValue(20) ._enum("sort", SortOrder.class).defaultValue(SortOrder.ASC) .fromMap(PageRequest::new) .readingParameters(); pageRequestValidator.validate(Map.of("page", "2", "size", "50", "sort", "DESC")); // PageRequest[page=2, size=50, order=DESC] pageRequestValidator.validate(Map.of()); // PageRequest[page=0, size=20, order=ASC] pageRequestValidator.validate(Map.of("page", "-1")); // page: "page" must be greater than or equal to 0 ``` `size=9999` and `sort=desc` are violations here. With `recover` in place of `defaultValue`, they fall back like an absent parameter: ```java ValueValidator, PageRequest> lenientPageRequestValidator = Yavi.schema() ._integer("page", c -> c.greaterThanOrEqual(0)).recover(0) ._integer("size", c -> c.greaterThanOrEqual(1).lessThanOrEqual(100)).recover(20) ._enum("sort", SortOrder.class).recover(SortOrder.ASC) .fromMap(PageRequest::new) .readingParameters(); lenientPageRequestValidator.validate(Map.of("page", "2", "size", "50", "sort", "DESC")); // PageRequest[page=2, size=50, order=DESC] lenientPageRequestValidator.validate(Map.of("page", "-1", "size", "9999", "sort", "desc")); // PageRequest[page=0, size=20, order=ASC] ``` ### CSV import The cells of a CSV file are strings too, so a row is read with `readingParameters()`, and the rows with `liftList`: ```java record MemberImport(String email, String name, int age) {} ValueValidator, MemberImport> rowValidator = Yavi.schema() ._string("email", c -> c.notBlank().email()) ._string("name", c -> c.notBlank().lessThanOrEqual(100)) ._integer("age", c -> c.greaterThanOrEqual(0).lessThanOrEqual(150)) .fromMap(MemberImport::new) .readingParameters(); List> rows = ...; // the rows of a CSV library Validated> members = rowValidator.liftList().prefixed("rows").validate(rows); // rows[1].email, rows[1].name, rows[1].age, rows[3].email, rows[3].age ``` A header that holds `.` or `[` is read as a path. A cell is not trimmed unless the row is read with `readingParameters(StringCoercion.strict().trimming())`, which trims every cell and takes a blank cell as `null`. ### Configuration files ```java record DbConfig(String host, int port, String database) {} record CacheConfig(String host, int port, int ttlSeconds) {} record AppConfig(DbConfig db, CacheConfig cache, String logLevel) {} ObjectInputValidator 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); ObjectInputValidator 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); ObjectInputValidator appConfigValidator = Yavi.schema() ._object("db", dbConfigValidator) ._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"))); // AppConfig[db=DbConfig[host=db.example.com, port=5432, database=myapp], // cache=CacheConfig[host=localhost, port=6379, ttlSeconds=300], logLevel=INFO] ``` ## Differences * **Input.** Raoh has one module of decoders per input (`MapDecoders`, `JsonDecoders`, `JooqRecordDecoders`). YAVI has one definition and an `InputReader` per input, and reads request parameters with paths and string coercion. It has no reader for a jOOQ `Record`; `record.intoMap()` is validated as a map. * **Numbers of a JSON document.** Raoh parses the document itself (`JsonDecoders.readTree`) so that a number is kept as it is written and a key written twice is refused. YAVI validates the tree the caller parsed: with Jackson, enable `DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS` and `StreamReadFeature.STRICT_DUPLICATE_DETECTION` on the mapper, as the README shows. Otherwise a number with a fraction is a `double` before it is validated. The sign of `-0.0` is not kept. * **Typed arguments.** The schema given to `fromMap(f)` also builds a validator of typed arguments with `apply(f)`. Raoh has no counterpart. * **Required.** Both reject `null` and an absent field unless the field says otherwise. In YAVI this holds for the properties of `Yavi.schema()` and the validators of a single value; `ValidatorBuilder`, which validates an object that exists, takes a property that is `null` as valid unless a constraint such as `notNull()` rejects it. * **Arity.** Both take up to 16 typed fields. Beyond that, YAVI groups the fields with `_embedded`, or has `ObjectInputValidator.of(parts, mapper)`, whose mapper takes a list of values. * **Description.** A YAVI validator describes its input (`description()`), from which `JsonSchema` generates a JSON Schema. * **Clock.** Raoh has no `past()` and `future()` on purpose. YAVI has them, with a `Clock` for a reproducible result. ## Encoders An encoder of Raoh (sections 29-32 of the tutorial) is written next to the decoder: `object(property("id", Item::id, long_().contramap(ItemId::value)), ...)`. In YAVI the schema that reads the map also writes it: `fromMapReversible` of `Yavi.reversibleSchema()` is `fromMap` with the accessors, and `toMap` is what Raoh calls encoding. ```java ObjectInputValidator.Reversible itemValidator = Yavi.reversibleSchema() ._long("id").map(ItemId::new, ItemId::value) // contramap ._string("name", c -> c.notBlank()) ._string("note").optional() .fromMapReversible(Item::new, Item::id, Item::name, Item::note); itemValidator.validate(row); // decodes itemValidator.toMap(item); // encodes: {id=1, name=pen, note=null} ``` * The names are written once, so the map that is written is the map that is read: `validate(toMap(x))` is `Valid(x)`. * A value object goes back with `map(f, g)`, a nested validator writes a nested map, an `_embedded` one the same map, and an `Optional` without a value `null`. * A property that cannot be written back does not compile: the schema takes a `ReversibleValueValidator` where `Yavi.schema()` takes a `ValueValidator`. * `ParameterTree.ofValues(validator.toMap(x))` holds the values as the text of a form. * Some of the properties are written by a view of the same schema, `validator.excluding("note").toMap(item)`, where Raoh writes a second encoder. The names are checked when the view is built. * A second encoder of Raoh lists what it writes, so a property that is added later is not written by it. A view that excludes would write it; a property that must not leave is therefore defined with `withheld()`, and is written by a view only if the view names it. See [New features in 0.18.0](NewFeatures_0.18.0.md#writing-an-object-back-as-the-map-it-is-read-from).