Documentation

You are viewing the documentation for Play 1. The documentation for Play 2 is here.

Built-in validations

Play defines several built-in validations, each of which is used as described in the validation chapter.

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

ipv4Address

Checks that the value is an IP address that complies with the version 4 protocol; empty strings are considered valid.

validation.ipv4Address(value);

Annotation syntax:

@IPv4Address String ip

Message key: validation.ipv4

ipv6Address

Checks that the value is an IP address that complies with the version 6 protocol; empty strings are considered valid.

validation.ipv6Address(value);

Annotation syntax:

@IPv6Address String ip

Message key: validation.ipv6

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 past. 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:

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

Message key: validation.past

phone

Checks that the value is a valid phone number; empty strings are considered valid. The validation is relaxed and is intented to enforce a basic phone pattern. Please implement your own @Match for country specific validations.

validation.phone(value);

Annotation syntax:

@Phone String phone

Message key: validation.phone

Format: +CCC (SSSSSS)9999999999xEEEE

Examples:

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.range

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

unique

Checks that the value of the column which has the annotation is unique, by querying the database. (This only works with JPA.) You can define additional columns as a comma-separated list of annotation values. So annotating a property called c with @Unique(“a, b”) will check that the combination of the values of properties a, b and c is unique.

Annotation syntax:

@Unique(additionalColumns) String productCode
@Unique("postCode") String houseNumber

Message key: validation.unique

url

Checks that the value is a valid URL; empty strings are considered valid. Note that not all valid URLs (as defined by RFC 1738) are accepted; only URLs with an http, https or ftp scheme are considered valid.

validation.url(value);

Annotation syntax:

@URL String address

Message key: validation.url