Documentation

Browse versions

Browse APIs

Language

Browse

Contents

Books

Validating HTTP data with Play

Validations ensure that the data has certain values or meets specific requirements. You can use validation to verify that your models are correct before saving them to the database, or use them directly on HTTP parameters to validate a simple form.

The validation object maintains a collection of play.data.validation.Error objects. Each error has two properties:

The key. This helps you to determine which data element caused the error. The key value can be set arbitrarily but when Play generates errors, it uses default conventions that follow the Java variables’ names.

The message. This contains the error’s textual description. The message can be a plain message or refer to a key from a message bundle (typically for internationalization support).

Using the first approach, let’s see how to validate a simple HTTP parameter:

Validation message parameters

You can use a placeholder in the message for the error key:

validation.required=%s is required

This changes the output to:

name is required
age is required

Limitation: Play cannot determine the correct parameter name when more than one required-field validation using the validation.required(age) syntax fails. In this case, you must specify the field name directly, i.e. validation.required("age", age).

This error key defaults to the parameter name, and is itself used to look up a message. For example, the name parameter in the hello action method above could be localised with:

name = Customer name

This would result in the output:

Customer name is required
age is required

You can change also override the error key using the error.message(String key) method. For example:

Several of the built-in validations define additional message parameters that correspond to the validation parameters. For example, the ‘match’ validation defines a second String parameter for the specified regular expression, which differs from the %s placeholder above in that it specifies the parameter index ‘2’:

Custom literal (non-localised) validation messages

The Play message look-up just returns the message key if there is no message defined for the key, which means you can also just use a literal message instead of the message key if you prefer. Using the same examples as above, for manual validation:

But in a real application you want to redisplay the original form. So you will have two actions: one to display the form and another one to handle the POST.

Of course the validation will occur in the second action and if some error occurs you will have to redirect to the first action. In this case you need a special trick to keep your errors during the redirect. Use the validation.keep() method. This will save the errors collection for the next action.

The annotations in the play.data.validation package provide an alternative and more concise way to specify validation constraints, with an annotation that corresponds to each Validation object method. To use the validation annotations, just annotate the controller method parameters:

You can also use the validation annotations to easily add constraints to your model object’s properties, and then in the controller specify that all properties must be valid. Let’s rewrite the previous example using a User class.

You can also write your own annotation validations, which is more complex but makes your model code cleaner and allows you to introduce validator parameters.

For example, suppose we want a less restrictive version of the @URL validation, so we can allow URLs with any scheme such as a file:// URL, and with a parameter that lets us specify exactly which schemes are allowed.

First, we write a custom validation annotation, with a parameter for overriding the default message:

The isSatisfied method calls requireMessageVariablesRecreation() to instruct OVal to call createMessageVariables() before rendering the message. This returns an ordered map of variables that are passed to the message formatter. The map keys are not used; the "2" in this example indicates the message parameter index. As before, the first parameter is the field name.