Object Validation
am.ik.yavi.builder.ValidatorBuilder builds a Validator<T> that validates an object that already exists. A property of the object is valid when it is null unless a constraint such as notNull() rejects it; this is the difference from a property of Yavi.schema().
Validator<User> validator = ValidatorBuilder.<User>of()
.constraint(User::name, "name", c -> c.notNull().lessThanOrEqual(20))
.constraint(User::email, "email", c -> c.notNull().greaterThanOrEqual(5).lessThanOrEqual(50).email())
.constraint(User::age, "age", c -> c.greaterThanOrEqual(0).lessThanOrEqual(200))
.build();
ConstraintViolations violations = validator.validate(user);
Use the typed method of a constraint rather than constraint when the type of the property would be ambiguous. _string, _integer, _bigDecimal and the other methods take a Function that reads the property, so a record accessor, a getter or a lambda works.
Validator<User> validator = ValidatorBuilder.<User>of()
._string(User::name, "name", c -> c.notNull().lessThanOrEqual(20))
._string(User::email, "email", c -> c.notNull().email())
._integer(User::age, "age", c -> c.greaterThanOrEqual(0))
.build();
A validator is thread-safe and may be reused. All violations are accumulated by default; see Fail-fast mode to stop at the first one.
Nested objects
nest applies a validator to a nested object. A nested validator can be passed in, or defined inline.
Validator<Address> addressValidator = ValidatorBuilder.<Address>of()
.nest(Address::country, "country", countryValidator)
.nest(Address::city, "city",
b -> b._string(City::name, "name", c -> c.notBlank().lessThanOrEqual(100)))
.build();
The violations of a nested object are located under its name (country.name). nestIfPresent validates a nested object only when it is not null.
Validator<Order> validator = ValidatorBuilder.<Order>of()
.nestIfPresent(Order::customer, "customer", customerValidator)
.build();
Collection, map and array elements
forEach applies a validator to every element of a collection, map value or array. The name of an element is its index in the violation name (histories[0].revision).
Validator<Histories> validator = ValidatorBuilder.<Histories>of()
.forEach(Histories::value, "histories", historyValidator)
.build();
An inline validator and forEachIfPresent are available as for nested objects.
Validator<Histories> validator = ValidatorBuilder.<Histories>of()
.forEach(Histories::value, "histories",
b -> b._integer(History::revision, "revision", c -> c.greaterThanOrEqual(1)))
.build();
Only map values are validated out of the box. To validate map keys, read them as a collection:
Validator<CodeMap> validator = ValidatorBuilder.<CodeMap>of()
.forEach(codeMap -> codeMap.asMap().keySet(), "codeMap",
b -> b._string(k -> k, "value", c -> c.notEmpty()))
.build();
A ValidatorBuilder with a message key separator other than . uses it in the names under forEach too:
new ValidatorBuilder<Order>("/")
.forEach(Order::addresses, "addresses", b -> b._string(Address::street, "street", c -> c.notBlank()))
.build();
// addresses[0]/street
The program below nests a validator and applies an element validator, then prints the violation names.
Conditional constraints
constraintOnCondition applies a validator only when a condition holds. A condition receives the target and the ConstraintContext of the validation call, so it can read the attributes of the request.
Validator<User> validator = ValidatorBuilder.<User>of()
.constraintOnCondition((user, context) -> "IT".equals(context.attribute("country").value()),
b -> b._string(User::taxId, "taxId", c -> c.notBlank()))
.build();
ConstraintContext context = ConstraintContext.from(Map.of("country", "IT"));
ConstraintViolations violations = validator.validate(user, context);
ConstraintCondition.hasAttribute and ConstraintCondition.hasAttributeWithValue are shortcuts for the common attribute checks.
Validator<User> validator = ValidatorBuilder.<User>of()
.constraintOnCondition(ConstraintCondition.hasAttributeWithValue("country", "IT"),
b -> b._string(User::taxId, "taxId", c -> c.notBlank()))
.build();
Constraint groups
A ConstraintGroup is a ConstraintContext that carries a name. Constraints added with constraintOnGroup are applied only when that group is validated.
enum Group implements ConstraintGroup {
CREATE, UPDATE
}
Validator<User> validator = ValidatorBuilder.<User>of()
.constraintOnGroup(Group.CREATE, b -> b._integer(User::id, "id", c -> c.isNull()))
.constraintOnGroup(Group.UPDATE, b -> b._integer(User::id, "id", c -> c.notNull()))
.build();
ConstraintViolations violations = validator.validate(user, Group.CREATE);
A group can be created without an enum, with ConstraintGroup.of("CREATE"). A constraint without a group is applied for every group, and ConstraintGroup.DEFAULT is used when validate is given no group. Groups match by name.
Cross-field validation
constraintOnTarget adds a rule that spans several properties. The violation is reported under the given name.
Validator<Range> validator = ValidatorBuilder.<Range>of()
._integer(Range::from, "from", c -> c.greaterThan(0))
._integer(Range::to, "to", c -> c.greaterThan(0))
.constraintOnTarget(range -> range.to() > range.from(), "to", "to.isGreaterThanFrom",
"\"to\" must be greater than \"from\"")
.build();
The rule is evaluated after the properties. A CustomConstraint<T> can supply the predicate and the message too; see Custom Constraints.
Overriding messages
message replaces the message of the constraint it follows. {0} is the name of the property, the other placeholders are the arguments of the constraint, and the last argument is the value that violated it.
Validator<User> validator = ValidatorBuilder.<User>of()
._string(User::name, "name", c -> c.notNull().message("{0} is required!")
.greaterThanOrEqual(1).message("{0} is too small!")
.lessThanOrEqual(20).message("{0} is too large!"))
.build();
A text given to message(String) is the message. A MessageFormatter does not replace it with the message of a resource bundle; it only substitutes the arguments, and the violation keeps its message key. To let a bundle localize a message of your own, give it a key:
c -> c.notBlank().message(ViolationMessage.of("user.name.notBlank", "Enter your name"))
Install a MessageFormatter on the builder to format the messages of the other constraints.
Validator<User> validator = ValidatorBuilder.<User>of()
.messageFormatter(new MessageSourceMessageFormatter(messageSource::getMessage))
._string(User::name, "name", c -> c.notBlank())
.build();
Fail-fast mode
failFast(true) returns from the validation at the first violation. The mode is passed down to nested, element and conditional validators.
Validator<User> validator = ValidatorBuilder.<User>of()
._string(User::name, "name", c -> c.notNull().lessThanOrEqual(20))
._string(User::email, "email", c -> c.notNull().email())
.failFast(true)
.build();
Validator<User> failFastValidator = validator.failFast(true);
boolean failFast = failFastValidator.isFailFast();
Conflicting constraint names
conflictStrategy(ConflictStrategy) decides what happens when the same constraint name is added more than once. The default, ConflictStrategy.NOOP, appends the new constraints. ConflictStrategy.OVERRIDE removes the existing ones.
Validator<User> validator = ValidatorBuilder.<User>of()
.conflictStrategy(ConflictStrategy.OVERRIDE)
._string(User::name, "name", c -> c.notNull())
._string(User::name, "name", c -> c.notBlank()) // replaces the previous "name" constraint
.build();
A custom strategy mutates the list of existing predicates; the new predicate is appended after it returns.
Handling violations
validate returns a ConstraintViolations, which is a List<ConstraintViolation> and is empty when the object is valid. Iterate it to read each violation.
for (ConstraintViolation violation : violations) {
String name = violation.name(); // tags[1]
String key = violation.messageKey(); // charSequence.notBlank
String message = violation.message();
Object[] args = violation.args();
Object value = violation.violatedValue();
String pointer = violation.pointer(); // /tags/1
}
ConstraintViolation has no name when the value itself is validated; its message then says "The value".
messagesByName and messagesByPointer return the messages in the shape a form or an API response needs, and details returns records that a JSON library serializes as they are.
Map<String, List<String>> byName = violations.messagesByName();
Map<String, List<String>> byPointer = violations.messagesByPointer();
List<ViolationDetail> details = violations.details();
// [{"name": "items[1].quantity", "pointer": "/items/1/quantity",
// "messageKey": "numeric.lessThanOrEqual", "message": "...", "params": {"max": 99}}]
A ViolationDetail is a sealed interface of records. Its accessors are name(), pointer(), messageKey(), message() and params(); the positional arguments are on ConstraintViolation#args(). The value that violated the constraint is not in a detail, which makes a detail safe to return. details() returns an unmodifiable list.