The Play framework provides flexible and easy-to-use functionality for HTTP request data validation, for validating form data. This article provides an overview of the framework's built-in validation rules.

Validation overview

The Play validation guide describes three ways to validate form (HTTP request) data in a Play web application.

1. In the controller method, call methods on the controller's validation field directly.
2. Add validation annotations to the controller method's parameter declarations.
3. Add the @Valid annotation to the controller method's POJO parameters, and add validation annotations to the POJO properties.

In all three cases, the usual pattern is to then check the controller's validation field for validation failures, save the request parameters and validation errors in flash scope, and then redirect back to the edit page to display validation error messages. Retrieving and displaying these messages is outside the scope of this article.

For example, this controller method validates that a required value is not empty using the first approach - calling a play.data.validation.Validation method.

public static void save(String value) {
    
    validation.required(value);
    
    if (validation.hasErrors()) {
        params.flash();
        validation.keep();
    }
    details();
}

The second approach - adding a play.data.validation annotation:

public static void save(@Required String value) {
    
    if (validation.hasErrors()) {
        params.flash();
        validation.keep();
    }
    details();
}

The third approach - putting on the annotations on a JavaBean's properties, and annotating the parameter with the @Valid annotation:

public static void save(@Valid Data data) {
    
    if (validation.hasErrors()) {
        params.flash();
        validation.keep();
    }
    details();
}

public class Data extends Model {
    @Required public String value;
}

Built-in validations

Play defines several built-in validations, in addition to the 'required' validation used in the above examples.

1. email
2. equals
3. future
4. isTrue
5. match
6. max
7. maxSize
8. min
9. minSize
10. past
11. range
12. required
13. url

Each validation has an associated error message, defined in $PLAY_HOME/resources/messages, whose key is validation. followed by the validation name. You can override this message by using the same key in your application's conf/messages file, and localise it using message files for other languages.

email

Checks that the value is a valid e-mail address.

validation.email(address);

Annotation syntax:

@Email String address

Message key: validation.email

equals

Checks that the value is equal to another parameter's value, using the value's equals method, e.g. for checking for a password confirmation field.

validation.equals(password, passwordConfirmation);

Annotation syntax:

@Equals("passwordConfirmation") String password

Message key: validation.equals

future

Checks that the value is a date in the future. If a second date is specified as a reference, then the value must be in the future with respect to the reference date - i.e. after it.

validation.future(dueDate);
validation.future(dueDate, shipmentDate);

Annotation syntax:

@InFuture String dueDate
@InFuture("1979-12-31") String birthDate

Message key: validation.future

isTrue

Checks that the value is a String or Boolean that evaluates to true, e.g. for an 'I agree to the terms' checkbox that must be checked, or a non-zero Number. Null values are considered false/invalid.

validation.isTrue(agree);

Annotation syntax:

@IsTrue String agree

Message key: validation.isTrue

match

Checks that the value is a string that matches the given regular expression. Empty strings are considered valid.

validation.match(abbreviation, "[A-Z]{3}"); // TLA

Annotation syntax:

@Match("[A-Z]{3}") String abbreviation

Message key: validation.match

max

Checks that the value is a String or Number that is no greater than the given number. Null values are considered valid.

validation.max(wordCount, 7500); // Short story

Annotation syntax:

@Max(7500) String wordCount

Message key: validation.max

maxSize

Checks that the value is a String whose length is no greater than the given length. Empty strings are considered valid.

validation.maxSize(url, 2083); // IE 4.0 - 8

Annotation syntax:

@MaxSize(2083) String value

Message key: validation.maxSize

min

Checks that the value is a String or Number that is no less than the given number. Null values are considered valid.

validation.min(age, 18); // Adult

Annotation syntax:

@Min(18) Long age

Message key: validation.min

minSize

Checks that the value is a String whose length is no less than the given length. Empty strings are considered valid.

validation.minSize(value, 42);

Annotation syntax:

@MinSize(42) String value

Message key: validation.minSize

past

Checks that the value is a date in the future. If a second date is specified as a reference, then the value must be in the past with respect to the reference date - i.e. before it.

validation.past(actualDepartureDate);
validation.past(expectedDepartureDate, expectedArrivalDate);

Annotation syntax:

@Past String actualDepartureDate
@Past("1980-01-01") String birthDate

Message key: validation.past

range

Checks that the value is a number within the range (inclusive) specified by the two given numbers.

validation.range(wordCount, 17500, 40000); // Novella

Annotation syntax:

@Range(min = 17500, max = 40000) String wordCount

Message key: validation.past

required

Checks that the value is a non-empty String, Collection, File or array.

validation.required(value);

Annotation syntax:

@Required String value

Message key: validation.required

url

Checks that the value is a valid URL; empty strings are considered valid. There is no play.data.validation.Validation method for this validation.

@URL String address

Message key: validation.url

Peter Hilton is a senior software developer at Lunatech Research and committer on the Play open-source project.

Please send comments on this article to editorial@lunatech.com.