Hibernate.orgCommunity Documentation

Chapter 2. Validation step by step

2.1. Defining constraints
2.1.1. Field-level constraints
2.1.2. Property-level constraints
2.1.3. Class-level constraints
2.1.4. Constraint inheritance
2.1.5. Object graphs
2.2. Validating constraints
2.2.1. Obtaining a Validator instance
2.2.2. Validator methods
2.2.3. ConstraintViolation methods
2.2.4. Message interpolation
2.3. Validating groups
2.3.1. Group sequences
2.3.2. Redefining the default group sequence of a class
2.4. Built-in constraints

In this chapter we will see in more detail how to use Hibernate Validator to validate constraints for a given entity model. We will also learn which default constraints the Bean Validation specification provides and which additional constraints are only provided by Hibernate Validator. Let's start with how to add constraints to an entity.

Constraints in Bean Validation are expressed via Java annotations. In this section we show how to annotate an object model with these annotations. We have to differentiate between three different type of constraint annotations - field-, property-, and class-level annotations.

If your model class adheres to the JavaBeans standard, it is also possible to annotate the properties of a bean class instead of its fields. Example 2.2, “Property level constraint” uses the same entity as in Example 2.1, “Field level constraint”, however, property level constraints are used.


The property's getter method has to be annotated, not its setter.

When using property level constraints property access strategy is used to access the value to be validated. This means the bean validation provider accesses the state via the property accessor method.


It is recommended to stick either to field or property annotation within one class. It is not recommended to annotate a field and the accompanying getter method as this would cause the field to be validated twice.

Last but not least, a constraint can also be placed on class level. When a constraint annotation is placed on this level the class instance itself passed to the ConstraintValidator. Class level constraints are useful if it is necessary to inspect more than a single property of the class to validate it or if a correlation between different state variables has to be evaluated. In Example 2.3, “Class level constraint” we add the property passengers to the class Car. We also add the constraint PassengerCount on the class level. We will later see how we can actually create this custom constraint (see Chapter 3, Creating custom constraints). For now we it is enough to know that PassengerCount will ensure that there cannot be more passengers in a car than there are seats.

When validating an object that implements an interface or extends another class, all constraint annotations on the implemented interface and parent class apply in the same manner as the constraints specified on the validated object itself. To make things clearer let's have a look at the following example:

Our well-known class Car is now extended by RentalCar with the additional property rentalStation. If an instance of RentalCar is validated, not only the @NotNull constraint on rentalStation is validated, but also the constraint on manufacturer from the parent class.

The same would hold true, if Car were an interface implemented by RentalCar.

Constraint annotations are aggregated if methods are overridden. If RentalCar would override the getManufacturer() method from Car any constraints annotated at the overriding method would be evaluated in addition to the @NotNull constraint from the super-class.

The Bean Validation API does not only allow to validate single class instances but also complete object graphs. To do so, just annotate a field or property representing a reference to another object with @Valid. If the parent object is validated, all referenced objects annotated with @Valid will be validated as well (as will be their children etc.). See Example 2.6, “Adding a driver to the car”.

If an instance of Car is validated, the referenced Person object will be validated as well, as the driver field is annotated with @Valid. Therefore the validation of a Car will fail if the name field of the referenced Person instance is null.

Object graph validation also works for collection-typed fields. That means any attributes that

  • are arrays

  • implement java.lang.Iterable (especially Collection, List and Set)

  • implement java.util.Map

can be annotated with @Valid, which will cause each contained element to be validated, when the parent object is validated.

If a Car instance is validated, a ConstraintValidation will be created, if any of the Person objects contained in the passengers list has a null name.


null values are getting ignored when validating object graphs.

The Validator interface is the main entry point to Bean Validation. In Section 5.1, “Configuration and ValidatorFactory” we will first show how to obtain an Validator instance. Afterwards we will learn how to use the different methods of the Validator interface.

The Validator interface contains three methods that can be used to either validate entire entities or just a single properties of the entity.

All three methods return a Set<ConstraintViolation>. The set is empty, if the validation succeeds. Otherwise a ConstraintViolation instance is added for each violated constraint.

All the validation methods have a var-args parameter which can be used to specify, which validation groups shall be considered when performing the validation. If the parameter is not specified the default validation group (javax.validation.groups.Default) will be used. We will go into more detail on the topic of validation groups in Section 2.3, “Validating groups”

As we will see in Chapter 3, Creating custom constraints each constraint definition must define a default message descriptor. This message can be overridden at declaration time using the message attribute of the constraint. You can see this in Example 2.13, “Driver”. This message descriptors get interpolated when a constraint validation fails using the configured MessageInterpolator. The interpolator will try to resolve any message parameters, meaning string literals enclosed in braces. In order to resolve these parameters Hibernate Validator's default MessageInterpolator first recursively resolves parameters against a custom ResourceBundle called ValidationMessages.properties at the root of the classpath (It is up to you to create this file). If no further replacements are possible against the custom bundle the default ResourceBundle under /org/hibernate/validator/ValidationMessages.properties gets evaluated. If a replacement occurs against the default bundle the algorithm looks again at the custom bundle (and so on). Once no further replacements against these two resource bundles are possible remaining parameters are getting resolved against the attributes of the constraint to be validated.

Since the braces { and } have special meaning in the messages they need to be escaped if they are used literally. The following The following rules apply:

  • \{ is considered as the literal {

  • \} is considered as the literal }

  • \\ is considered as the literal \

If the default message interpolator does not fit your requirements it is possible to plug a custom MessageInterpolator when the ValidatorFactory gets created. This can be seen in Chapter 5, Bootstrapping.

Groups allow you to restrict the set of constraints applied during validation. This makes for example wizard like validation possible where in each step only a specified subset of constraints get validated. The groups targeted are passed as var-args parameters to validate, validateProperty and validateValue. Let's have a look at an extended Car with Driver example. First we have the class Person (Example 2.12, “Person”) which has a @NotNull constraint on name. Since no group is specified for this annotation its default group is javax.validation.groups.Default.


When more than one group is requested, the order in which the groups are evaluated is not deterministic. If no group is specified the default group javax.validation.groups.Default is assumed.

Next we have the class Driver (Example 2.13, “Driver”) extending Person. Here we are adding the properties age and hasDrivingLicense. In order to drive you must be at least 18 (@Min(18)) and you must have a driving license (@AssertTrue). Both constraints defined on these properties belong to the group DriverChecks. As you can see in Example 2.14, “Group interfaces” the group DriverChecks is just a simple tagging interface. Using interfaces makes the usage of groups type safe and allows for easy refactoring. It also means that groups can inherit from each other via class inheritance.


The Bean Validation specification does not enforce that groups have to be interfaces. Non interface classes could be used as well, but we recommend to stick to interfaces.

Last but not least we add the property passedVehicleInspection to the Car class (Example 2.15, “Car”) indicating whether a car passed the road worthy tests.

Overall three different groups are used in our example. Person.name, Car.manufacturer, Car.licensePlate and Car.seatCount all belong to the Default group. Driver.age and Driver.hasDrivingLicense belong to DriverChecks and last but not least Car.passedVehicleInspection belongs to the group CarChecks. Example 2.16, “Drive away” shows how passing different group combinations to the Validator.validate method result in different validation results.

Example 2.16. Drive away

public class GroupTest {

    private static Validator validator;
    public static void setUp() {
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        validator = factory.getValidator();
    public void driveAway() {
        // create a car and check that everything is ok with it.
        Car car = new Car( "Morris", "DD-AB-123", 2 );
        Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );
        assertEquals( 0, constraintViolations.size() );
        // but has it passed the vehicle inspection?
        constraintViolations = validator.validate( car, CarChecks.class );
        assertEquals( 1, constraintViolations.size() );
        assertEquals("The car has to pass the vehicle inspection first", constraintViolations.iterator().next().getMessage());
        // let's go to the vehicle inspection
        car.setPassedVehicleInspection( true );
        assertEquals( 0, validator.validate( car ).size() );
        // now let's add a driver. He is 18, but has not passed the driving test yet
        Driver john = new Driver( "John Doe" );
        john.setAge( 18 );
        car.setDriver( john );
        constraintViolations = validator.validate( car, DriverChecks.class );
        assertEquals( 1, constraintViolations.size() );
        assertEquals( "You first have to pass the driving test", constraintViolations.iterator().next().getMessage() );
        // ok, John passes the test
        john.passedDrivingTest( true );
        assertEquals( 0, validator.validate( car, DriverChecks.class ).size() );
        // just checking that everything is in order now
        assertEquals( 0, validator.validate( car, Default.class, CarChecks.class, DriverChecks.class ).size() );

First we create a car and validate it using no explicit group. There are no validation errors, even though the property passedVehicleInspection is per default false. However, the constraint defined on this property does not belong to the default group. Next we just validate the CarChecks group which will fail until we make sure that the car passes the vehicle inspection. When we then add a driver to the car and validate against DriverChecks we get again a constraint violation due to the fact that the driver has not yet passed the driving test. Only after setting passedDrivingTest to true the validation against DriverChecks will pass.

Last but not least, we show that all constraints are passing by validating against all defined groups.

By default, constraints are evaluated in no particular order and this regardless of which groups they belong to. In some situations, however, it is useful to control the order of the constraints evaluation. In our example from Section 2.3, “Validating groups” we could for example require that first all default car constraints are passing before we check the road worthiness of the car. Finally before we drive away we check the actual driver constraints. In order to implement such an order one would define a new interface and annotate it with @GroupSequence defining the order in which the groups have to be validated.


If at least one constraints fails in a sequenced group none of the constraints of the following groups in the sequence get validated.


Groups defining a sequence and groups composing a sequence must not be involved in a cyclic dependency either directly or indirectly, either through cascaded sequence definition or group inheritance. If a group containing such a circularity is evaluated, a GroupDefinitionException is raised.

The usage of the new sequence could then look like in Example 2.18, “Usage of a group sequence”.

The @GroupSequence annotation also fulfills a second purpose. It allows you to redefine what the Default group means for a given class. To redefine Default for a class, place a @GroupSequence annotation on the class. The defined groups in the annotation express the sequence of groups that substitute Default for this class. Example 2.19, “RentalCar” introduces a new class RentalCar with a redfined default group. With this definition the check for all three groups can be rewritten as seen in Example 2.20, “testOrderedChecksWithRedefinedDefault”.


Due to the fact that there cannot be a cyclic dependency in the group and group sequence definitions one cannot just add Default to the sequence redefining Default for a class. Instead the class itself should be added!

Hibernate Validator implements all of the default constraints specified in Bean Validation as well as some custom ones. Table 2.2, “Built-in constraints” list all constraints available in Hibernate Validator.

Table 2.2. Built-in constraints

AnnotationPart of Bean Validation SpecificationApply onUseHibernate Metadata impact
@AssertFalseyesfield/propertyCheck that the annotated element is false.none
@AssertTrueyesfield/propertyCheck that the annotated element is true.none
@CreditCardNumbernofield/property. The supported type is String.Check that the annotated string passes the Luhn checksum test. Note, this validation aims to check for user mistake, not credit card validity! See also Anatomy of Credit Card Numbers.none
@DecimalMaxyesfield/property. Supported types are BigDecimal, BigInteger, String, byte, short, int, long and the respective wrappers of the primitive types.The annotated element must be a number whose value must be lower or equal to the specified maximum. The parameter value is the string representation of the max value according to the BigDecimal string representation.none
@DecimalMinyesfield/property. Supported types are BigDecimal, BigInteger, String, byte, short, int, long and the respective wrappers of the primitive types.The annotated element must be a number whose value must be higher or equal to the specified minimum. The parameter value is the string representation of the min value according to the BigDecimal string representation.none
@Digits(integer=, fraction=)yesfield/property. Supported types are BigDecimal, BigInteger, String, byte, short, int, long and the respective wrappers of the primitive types.Check whether the property is a number having up to integer digits and fraction fractional digits.Define column precision and scale.
@Emailnofield/property. Needs to be a string.Check whether the specified string is a valid email address.none
@Futureyesfield/property. Supported types are java.util.Date and java.util.Calendar.Checks whether the annotated date is in the future.none
@Length(min=, max=)nofield/property. Needs to be a string.Validate that the annotated string is between min and max included.Column length will be set to max.
@Maxyesfield/property. Supported types are BigDecimal, BigInteger, String, byte, short, int, long and the respective wrappers of the primitive types.Checks whether the annotated value is less than or equal to the specified maximum.Add a check constraint on the column.
@Minyesfield/property. Supported types are BigDecimal, BigInteger, String, byte, short, int, long and the respective wrappers of the primitive types.Checks whether the annotated value is higher than or equal to the specified minimum.Add a check constraint on the column.
@NotNullyesfield/propertyCheck that the annotated value is not null.Column(s) are not null.
@NotBlanknofield/propertyCheck that the annotated string is not null and the trimmed length is greater than 0. The difference to @NotEmpty is that this constraint can only be applied on strings and that trailing whitespaces are ignored.none
@NotEmptynofield/property. Supported types are String, Collection, Map and arrays.Check whether the annotated element is not null nor empty.none
@Nullyesfield/propertyCheck that the annotated value is null.none
@Pastyesfield/property. Supported types are java.util.Date and java.util.Calendar.Checks whether the annotated date is in the past.none
@Pattern(regex=, flag=)yesfield/property. Needs to be a string.Checks if the annotated string matches the regular expression regex considering the given flag match.none
@Range(min=, max=)nofield/property. Supported types are BigDecimal, BigInteger, String, byte, short, int, long and the respective wrappers of the primitive types.Check whether the annotated value lies between (inclusive) the specified minimum and maximum.none
@Size(min=, max=)yesfield/property. Supported types are String, Collection, Map and arrays.Check if the annotated element size is between min and max (inclusive).Column length will be set to max.
@ScriptAssert(lang=, script=, alias=)notypeChecks whether the given script can successfully be evaluated against the annotated element. In order to use this constraint, an implementation of the Java Scripting API as defined by JSR 223 ("Scripting for the JavaTM Platform") must part of the class path. This is automatically the case when running on Java 6. For older Java versions, the JSR 223 RI can be added manually to the class path.The expressions to be evaluated can be written in any scripting or expression language, for which a JSR 223 compatible engine can be found in the class path.none
@URL(protocol=, host=, port=)nofield/property. The supported type is String.Check if the annotated string is a valid URL. If any of parameters protocol, host or port is specified the URL must match the specified values in the according part.none
@Validyesfield/property. Any non-primitive types are supported.Performs validation recursively on the associated object. If the object is a collection or an array, the elements are validated recursively. If the object is a map, the value elements are validated recursively.none


On top of the parameters indicated in Table 2.2, “Built-in constraints” each constraint supports the parameters message, groups and payload. This is a requirement of the Bean Validation specification.

In some cases these built-in constraints will not fulfill your requirements. In this case you can literally in a minute write your own constraints. We will discuss this in Chapter 3, Creating custom constraints