Writing an Object Back
A schema names the properties of an input once. Yavi.reversibleSchema() builds a validator that also writes the created object back as the map it is read from, so the names are not written again for the parameters of a statement or for a form that shows a stored object.
record Employee(Integer id, UserName name, Email email, Optional<String> nickname, Role role) {}
ObjectInputValidator.Reversible<Employee> employeeValidator = Yavi.reversibleSchema()
._integer("id")
._embedded(userNameValidator) // first_name, last_name
._string(Yavi._string("email", c -> c.notBlank().email()).map(Email::new, Email::value))
._string("nickname").optional()
._enum("role", Role.class)
.fromMapReversible(Employee::new, Employee::id, Employee::name, Employee::email,
Employee::nickname, Employee::role);
employeeValidator.toMap(employee);
// {id=1, first_name=Taro, last_name=Yamada, email=taro@example.com, nickname=null, role=ADMIN}
The following complete program builds a reversible schema, creates an object, and prints the map that toMap writes back and validates again.
Reversible schemas
Yavi.reversibleSchema() has the same methods as Yavi.schema(), but takes a ReversibleValueValidator where a schema takes a ValueValidator: a validator that knows its reverse by its type. A validator that maps its value without saying how to go back does not compile where it is added.
fromMapReversible(f, accessor1, ..., accessorN)isfromMap(f)with one accessor per argument, which returns the validated value of that argument from the object.map(f, g)ismap(f)with the function that goes from the mapped value back to the input. It returns aReversibleValueValidator, whosereverse(x)is the input thatxis read from.flatFromMapReversibleandflatOfReversibleare the counterparts offlatFromMapandof.ReversibleValueValidator.recursive(self -> ...)isrecursivefor a structure that contains itself.Yavi.reversibleDynamicSchema()writes back the map of validated values.ObjectInputValidator.ofReversible(parts, mapper)takes a list ofReversiblePart: a part with its reverse and its accessor.
toMap(x) writes the object; reverse(x) writes every property, including withheld ones. The validator reads input as fromMap does, and is nested, embedded and read with readingWith and readingParameters as before.
Writing nested and optional values
| Property | toMap |
|---|---|
a value of constraints, defaultValue, recover | the value |
| an enum constant | its name |
no value of nullable(), optional() | an entry with null, because a named parameter needs its key |
no value after rejectingNull() | no entry |
presence() | no entry for Absent, null for PresentNull |
_embedded | in the same map; null for every property if it has no value |
_object | a nested map |
_list, _map, _rest | every element |
splitBy(",") | the joined text; an empty list is null |
a validator with map(f, g) | the result of g |
withheld() | no entry |
A list with splitBy is one field of a form, so it is written as the text of that field. A pattern does not tell the text that separates the elements, so the text that joins them is given with it:
ObjectInputValidator.Reversible<Feed> feedSchema = Yavi.reversibleSchema()
._string("title")
._list("urls", Yavi._string(c -> c.url())).splitBy(Pattern.compile("\\s*\\R\\s*"), "\n")
.defaultValue(List.of())
.fromMapReversible(Feed::new, Feed::title, Feed::urls);
feedSchema.toMap(new Feed("News", List.of("https://a.example", "https://b.example")));
// {title=News, urls="https://a.example\nhttps://b.example"}
splitBy(pattern) without the joining text does not compile in Yavi.reversibleSchema(). The pattern must match the text: splitBy(Pattern.compile("\\R"), ", ") fails when the schema is built, because the written text would not be split where it was joined.
Views
including and excluding build a PropertyView that writes the chosen properties. A view is built once, and its names are checked against what the validator describes when it is built: a name that the validator does not define is an IllegalArgumentException, where a key removed from the map that toMap returns is checked by nobody.
static final PropertyView<AccountUser> SUMMARY = userValidator.including("id", "name", "address.city");
static final PropertyView<AccountUser> LISTED = userValidator.excluding("address");
SUMMARY.toMap(user); // {id=1, name=Taro, address={city=Tokyo}}
LISTED.toMap(user); // {id=1, name=Taro}
- A property that is not in the view has no entry; it is not written as
null. The accessor of a property that is not written is not called. - A view only writes. It is not a validator and not a
ReversibleValueValidator, so it is rejected where the round trip is needed. - A view is narrowed with its own
includingandexcluding. renaming(function)writes a property under another key, at every depth;renaming(path, key)renames one property. Only the key changes. A renamed view is for a response: it is not read back and not described by the JSON Schema.
Withheld properties
A property that must not be shown is marked where it is defined:
._string("password_hash").withheld()
toMap and a view that excludes do not write it, at any depth. A view that includes writes it only if it is named. reverse writes every property, so the round trip holds. The same mark keeps what was sent for a password out of a form that is shown again, and makes the property writeOnly in a JSON Schema. It does not change what is read, and a violation still holds the rejected value.
A password is often stored in another form, as a hash the application computes. The schema of the form withholds it, and the statement is given the hash as one more parameter.
Parameters and Forms
ParameterTree returns parameters in the shape of the schema, and ParameterTree.ofValues holds the values that a validator writes as the text of parameters. The first display of a stored object and a form that is shown again are then one code path.
ParameterTree tree = stored != null ? ParameterTree.ofValues(signupSchema.toMap(stored))
: ParameterTree.of(request.getParameterMap());
Map<String, Object> form = tree.toMap(signupSchema.description());
// {name="Taro", age="30", birthday="2000-01-02", address={city="Tokyo", street=""}}
ParameterTree.of(parameters)takes aMap<String, String>, aMap<String, List<String>>or aMap<String, String[]>, in the forms thatreadingParameters()validates.toMap(description)returns a tree ofMap,Listand the text that was sent, for a template engine.toParameters(description)returns the same values under the names of the violations (address.city,items[0].name), for aMapBindingResultof Spring.- A value is not trimmed, coerced or validated. A value that was not sent is an empty string; a
Booleanthat was not sent has no entry. - A key that no property is defined for is left out. A schema with
_restreturns the other keys. - A withheld property is written as one that was not sent.
ParameterTree.parametersOf(tree)is the reverse ofParameterTree.of(parameters)for any tree ofMapandList.ParameterTree.of(parameters, maxIndex)gives another index limit;ParameterTree.DEFAULT_MAX_INDEXis 255.
Round trip
validator.validate(validator.toMap(x)) is Valid(x) for every x that the validator creates. reverse keeps the round trip for a withheld property, because it writes it. A validator that is not a ReversibleValueValidator, such as map(f) without a reverse, a lambda or anyOf, is rejected by the schema at compile time.
The map is new; add what a statement needs (map.put("updated_by", user)). A nested map cannot be bound to a statement: read the columns of a row with _embedded, or bind the map under the names of the violations with ParameterTree.parametersOf.