Messages are defined and configured using the <message> element.
A <message> element may contain <arg> children to specify message arguments. An argument may specify its value in one of the following ways:
- the value attribute directly contains the message argument. Since it is dynamic, it may be given as an expression.
- the bundle and key attributes specify a localized resource containing the argument value.
- the property attribute specifies a validator property, containing the argument value (only allowed for messages inside validators and field validations).
Validators, defined in the <validators> section, are used by validations, defined in a <form> element. Correspondingly, a message, that has been defined for a validator, may be customized by messages, defined in validations, that use this validator. For example, if a message contains the field name as an argument, this is usually not known by the validator. It is, however, known inside the form, where we use the validator in a field validation.
To enable customization of validator message arguments, <arg> elements in validator messages may have a name attribute, meaning "the value for this argument may be specified or overridden by validation messages". On the other hand, validation message arguments must have the name attribute set to reference an argument in the base validator message.
Additionally, we allow <message> elements within fields. A field message is used to "factor out" message arguments which are shared across several field validation messages inside that field. For example, most predefined validators declare an argument named field to denote the field name. Though rarely used, field messages can also completely override all validator messages for that field by specifying a key.
We therefore distinguish three semantically and syntactically different ways to use the <message> element.
- A simple message definition may appear in <input>, <assert>, <match>, <convert> and <check> elements. In this case, the message and its arguments are always fully described. Both, the bundle and key attributes, are required. Nested <arg> elements do not have name attributes.
- A base message definition may appear inside validator elements <matcher>, <converter> and <checker> as well as in <field> elements. Parts of the message details may be left open: the key attribute is required, but the bundle attribute may be omitted. Nested <arg> elements may specify a name attribute. If they do so, they may also leave their values unspecified (abstract argument). A base message inside a <field> element shadows (completely overrides) a base message in a validator.
- A message configuration may appear inside validation elements <match>, <convert> and <check> as well as in <field> elements. Here, parts of a base message definition are added or overridden. The key attribute is forbidden, but the bundle attribute may be specified. Nested <arg> elements must specify a name attribute. named arguments from their base definition.