Request Parameters and Forms
readingParameters() reads a flat map of strings, as a servlet request or a submitted form provides it, with the schema that reads a map or a JSON document. A string is text that stands for a value of the type of its property, and a key is the path of a nested value.
record SearchForm(String q, Integer page, Boolean includeArchived, @Nullable LocalDate since, List<String> tags,
@Nullable Address address) {}
ValueValidator<Map<String, ?>, SearchForm> searchFormValidator = Yavi.schema()
._string("q", c -> c.notBlank())
._integer("page", c -> c.greaterThanOrEqual(1)).defaultValue(1)
._boolean("includeArchived").defaultValue(false)
._localDate("since").nullable()
._list("tags", Yavi._string(c -> c.notBlank())).defaultValue(List.of())
._object("address", addressValidator).nullable()
.fromMap(SearchForm::new)
.readingParameters();
// ?q=yavi&page=2&since=&tags=a&tags=b&address.city=Tokyo
Validated<SearchForm> validated = searchFormValidator.validate(params);
Every form of such a map is accepted: a Map<String, String>, a Map<String, List<String>> such as Spring's MultiValueMap, and the Map<String, String[]> of the Servlet API. The type is ValueValidator<Map<String, ?>, X> whatever it is assigned to.
Keys and paths
address.cityandaddress[city]are the propertycityof the objectaddress;tags[]istags.- A key with several values is a list (
tags=a&tags=b). Several values for a scalar property are reported withobject.type; none is picked. - Keys with indexes are a list in the order of the indexes:
items[0].name=pen&items[1].name=ink. - A skipped index is an element that is
null, so a violation keeps the index it was sent with (items[2].name). - A name that holds a dot is written in brackets (
scores[a.b]). - A key that has both values and nested keys (
a=1&a.b=2) is reported withobject.type, and a key that is not written as a path (a..b,a[0) matches no property. - With
rejectingUnknownProperties(), an unknown key is reported by the validator of the object that has it (address.zip).
Coercion and StringCoercion
The rules are strict by default:
- A number is a decimal number in the grammar of
new BigDecimal(String): an optional sign, digits, an optional fraction and an optional exponent, without surrounding white space or grouping separators."30"and"30.0"are anInteger;"30.5"," 30"and"1,000"are not. - A boolean is
"true"or"false". - A string that does not stand for the type is reported with
object.type("page" must be of type integer), never with an exception. Nothing is converted to a string.
StringCoercion relaxes the rules for text written by a person, such as the fields of a form:
StringCoercion form = StringCoercion.strict().trimming().booleanWords();
ValueValidator<Map<String, ?>, Signup> signupValidator = Yavi.schema()
._integer("age")
._boolean("subscribed").defaultValue(false) // an unchecked checkbox sends nothing
.fromMap(Signup::new)
.readingParameters(form);
signupValidator.validate(Map.of("age", " 30 ", "subscribed", "on")); // Signup[age=30, subscribed=true]
trimming()reads every text without its surrounding white space, whatever its property is, and validates a blank string likenull. The constraints see the trimmed text.booleanWords()takestrue,1,yes,onandfalse,0,no,offin any case.booleanWords(trueWords, falseWords)takes the words of the application instead.- A
Stringwhose white space is part of it, such as a password, says so withuntrimmed()of its validator:._string(Yavi._string("password", c -> c.greaterThanOrEqual(8)).untrimmed()). - Each rule is given once:
reader.coercingStrings(rules).coercingStrings()andbooleanWords(...).booleanWords()do not compile. - A validator reads with the last reader it is given:
readingWith(reader)afterreadingParameters()coerces no string.
Empty values and defaults
- An empty string is validated like
null, whatever the type of its property is.optional(),nullable()anddefaultValue(...)apply to it. GivedefaultValue("")to a string property that must receive"". - Text has no
null, so a property that would reject an empty string withobject.notNullreportsobject.required("page" is required), as it does for an absent key. The violation of a constraint that rejectsnull, such asnotBlank(), is reported as it is. - An empty list or object cannot be sent: its key is absent, which is validated like
null. GivedefaultValue(List.of())to a list that may be empty, such as checkboxes. recoversuits a parameter that must not fail a request:._integer("size", c -> c.greaterThanOrEqual(1).lessThanOrEqual(100)).recover(20).
Labels and messages
A form calls a field by its label. label changes {0} of every message of the property and of its elements; the name, the path and the pointer of a violation are unchanged. typeMessage replaces the message of object.type, and required the message of object.required.
record Token(String name, Integer ttl, List<String> roles) {}
ValueValidator<Map<String, ?>, Token> tokenValidator = Yavi.schema()
._string("name", c -> c.notBlank()).label("Token name")
._integer("ttl", c -> c.positive()).typeMessage("\"{0}\" must be a number of seconds")
._list("roles", Yavi._string(c -> c.notBlank())).label("Roles").required("Select at least one role")
.fromMap(Token::new)
.readingParameters()
.formattingWith(new MessageSourceMessageFormatter(messageSource::getMessage));
See Messages and Localization for the formatter and the rule about messages written in code.
A list in one parameter
splitBy after _list reads one parameter as a list: ?tags=java,yavi, ?ids=1,2,3, or one URI per line of a textarea.
ValueValidator<Map<String, ?>, Article> articleValidator = Yavi.schema()
._string("title", c -> c.notBlank())
._list("tags", Yavi._string(c -> c.notBlank().lessThanOrEqual(10)), c -> c.unique()).splitBy(",")
._list("related", Yavi._integer(c -> c.positive())).splitBy(",").defaultValue(List.of())
._list("links", Yavi._object(URI.class)).splitBy(Pattern.compile("\\R")).defaultValue(List.of())
.fromMap(Article::new)
.readingParameters();
- The separator is a text taken literally or a
Pattern. The elements are text that stands for a value, and their violations are located under their index (tags[1]). - Every text is split, also the values of a repeated key:
tags=a,b&tags=cis[a, b, c]. - No element is dropped or trimmed.
a,,bhas three elements, and the second has no value. A separator at the end starts no element:a,b,is[a, b]. - An empty parameter (
tags=) has no value. splitByis written after_list, before the other modifiers; onlylabelandtypeMessagemay be written before it.- A value that is neither text nor a list is reported with
object.type("tags" must be of type array or string), not taken for a list of one element.
Limits and security
- An index is at most 255 (
ParameterTree.DEFAULT_MAX_INDEX). A greater number is a name, sotags[999999999]is reported withobject.typeand allocates nothing. ParameterTree.of(map, maxIndex)gives another limit. Give the same limit to the reader if the validator reads a tree with another one.- A skipped index is an element that is
null; the list has the length of the largest index sent, so the limit bounds what an untrusted request can allocate. - A key that is not a path matches no property and is ignored, or reported by
rejectingUnknownProperties(). readingParameters()validates theParameterTreeof the map, which any validator reads withreadingWith(ParameterTree.reader()).
Writing parameters back
A form that is not valid is shown again with the text that was sent, without copying the fields by hand. ParameterTree returns the parameters in the shape of the schema, and the same call gives the empty form for a request that lacks a parameter. See Writing an Object Back.