Hibernate.orgCommunity Documentation

Chapter 2. Declaring and validating bean constraints

In this chapter you will learn how to declare (see Section 2.1, “Declaring bean constraints”) and validate (see Section 2.2, “Validating bean constraints”) bean constraints. Section 2.3, “Built-in constraints” provides an overview of all built-in constraints coming with Hibernate Validator.

If you are interested in applying constraints to method parameters and return values, refer to Chapter 3, Declaring and validating method constraints.

2.1. Declaring bean constraints

Constraints in Bean Validation are expressed via Java annotations. In this section you will learn how to enhance an object model with these annotations. There are the following three types of bean constraints:

  • field constraints
  • property constraints
  • class constraints

Note

Not all constraints can be placed on all of these levels. In fact, none of the default constraints defined by Bean Validation can be placed at class level. The java.lang.annotation.Target annotation in the constraint annotation itself determines on which elements a constraint can be placed. See Chapter 6, Creating custom constraints for more information.

2.1.1. Field-level constraints

Constraints can be expressed by annotating a field of a class. Example 2.1, “Field-level constraints” shows a field level configuration example:

Example 2.1. Field-level constraints
package org.hibernate.validator.referenceguide.chapter02.fieldlevel;

public class Car {

	@NotNull
	private String manufacturer;

	@AssertTrue
	private boolean isRegistered;

	public Car(String manufacturer, boolean isRegistered) {
		this.manufacturer = manufacturer;
		this.isRegistered = isRegistered;
	}

	//getters and setters...
}

When using field-level constraints field access strategy is used to access the value to be validated. This means the validation engine directly accesses the instance variable and does not invoke the property accessor method even if such an accessor exists.

Constraints can be applied to fields of any access type (public, private etc.). Constraints on static fields are not supported, though.

Tip

When validating byte code enhanced objects property level constraints should be used, because the byte code enhancing library won’t be able to determine a field access via reflection.

2.1.2. Property-level constraints

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 constraints” uses the same entity as in Example 2.1, “Field-level constraints”, however, property level constraints are used.

Example 2.2. Property-level constraints
package org.hibernate.validator.referenceguide.chapter02.propertylevel;

public class Car {

	private String manufacturer;

	private boolean isRegistered;

	public Car(String manufacturer, boolean isRegistered) {
		this.manufacturer = manufacturer;
		this.isRegistered = isRegistered;
	}

	@NotNull
	public String getManufacturer() {
		return manufacturer;
	}

	public void setManufacturer(String manufacturer) {
		this.manufacturer = manufacturer;
	}

	@AssertTrue
	public boolean isRegistered() {
		return isRegistered;
	}

	public void setRegistered(boolean isRegistered) {
		this.isRegistered = isRegistered;
	}
}

Note

The property’s getter method has to be annotated, not its setter. That way also read-only properties can be constrained which have no setter method.

When using property level constraints property access strategy is used to access the value to be validated, i.e. the validation engine accesses the state via the property accessor method.

Tip

It is recommended to stick either to field or property annotations 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.

2.1.3. Type argument constraints

Starting from Java 8, it is possible to specify constraints directly on the type argument of a parameterized type. However, this requires that ElementType.TYPE_USE is specified via @Target in the constraint definition. To maintain backwards compatibility, built-in Bean Validation as well as Hibernate Validator specific constraints do not yet specify ElementType.TYPE_USE. To make use of type argument constraints, custom constraints must be used (see Chapter 6, Creating custom constraints).

Hibernate Validator validates type arguments constraints specified on collections, map values, java.util.Optional, and custom parameterized types.

2.1.3.1. With Iterable

When applying constraints on an Iterable type argument, Hibernate Validator will validate each element. Example 2.3, “Type argument constraint on List shows an example of a List with a type argument constraint.

In this example, @ValidPart is a custom constraint allowed to be used in the TYPE_USE context.

Example 2.3. Type argument constraint on List
package org.hibernate.validator.referenceguide.chapter02.typeargument;

public class Car {

	@Valid
	private List<@ValidPart String> parts = new ArrayList<>();

	public void addPart(String part) {
		parts.add( part );
	}

	//...
}
Car car = Car();
car.addPart( "Wheel" );
car.addPart( null );

Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );

assertEquals( 1, constraintViolations.size() );
assertEquals(
		"'null' is not a valid car part.",
		constraintViolations.iterator().next().getMessage()
);
assertEquals( "parts[1].<collection element>",
		constraintViolations.iterator().next().getPropertyPath().toString() );

2.1.3.2. With Map

Type argument constraints are also validated for map values. Constraints on the key are ignored. Example 2.4, “Type argument constraint on maps” shows an example of a Map value with a type argument constraint.

Example 2.4. Type argument constraint on maps
package org.hibernate.validator.referenceguide.chapter02.typeargument;

public class Car {

	public static enum FuelConsumption {
		CITY,
		HIGHWAY
	}

	@Valid
	private EnumMap<FuelConsumption, @MaxAllowedFuelConsumption Integer> fuelConsumption = new EnumMap<>( FuelConsumption.class );

	public void setFuelConsumption(FuelConsumption consumption, int value) {
		fuelConsumption.put( consumption, value );
	}

    //...
}
Car car = new Car();
car.setFuelConsumption( Car.FuelConsumption.HIGHWAY, 20 );

Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );

assertEquals( 1, constraintViolations.size() );
assertEquals( "20 is outside the max fuel consumption.", constraintViolations.iterator().next().getMessage() );

2.1.3.3. With java.util.Optional

When applying a constraint on the type argument of Optional, Hibernate Validator will automatically unwrap the type and validate the internal value. Example 2.5, “Type argument constraint on Optional” shows an example of an Optional with a type argument constraint.

Example 2.5. Type argument constraint on Optional
package org.hibernate.validator.referenceguide.chapter02.typeargument;

import java.util.ArrayList;
import java.util.EnumMap;
import java.util.List;
import java.util.Optional;
import javax.validation.Valid;

public class Car {

	private Optional<@MinTowingCapacity(1000) Integer> towingCapacity = Optional.empty();

	public void setTowingCapacity(Integer alias) {
		towingCapacity = Optional.of( alias );
	}

    //...
}
Car car = Car();
car.setTowingCapacity( 100 );

Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );

assertEquals( 1, constraintViolations.size() );
assertEquals( "Not enough towing capacity.", constraintViolations.iterator().next().getMessage() );
assertEquals( "towingCapacity", constraintViolations.iterator().next().getPropertyPath().toString() );

2.1.3.4. With custom parameterized types

Type arguments constraints can with two restrictions also be used with custom types. First, a ValidatedValueUnwrapper must be registered for the custom type allowing to retrieve the value to validate (see Section 11.13, “Unwrapping values”). Second, only types with one type arguments are supported. Parameterized types with two or more type arguments are not checked for type argument constraints. This limitation might change in future versions.

Example 2.6, “Type argument constraint on custom parameterized type” shows an example of a custom parameterized type with a type argument constraint.

Example 2.6. Type argument constraint on custom parameterized type
package org.hibernate.validator.referenceguide.chapter02.typeargument;

public class Car {

	private GearBox<@MinTorque(100) Gear> gearBox;

	public void setGearBox(GearBox<Gear> gearBox) {
		this.gearBox = gearBox;
	}

	//...
}
package org.hibernate.validator.referenceguide.chapter02.typeargument;

public class GearBox<T extends Gear> {

	private final T gear;

	public GearBox(T gear) {
		this.gear = gear;
	}

	public Gear getGear() {
		return this.gear;
	}
}
package org.hibernate.validator.referenceguide.chapter02.typeargument;

public class Gear {
	private final Integer torque;

	public Gear(Integer torque) {
		this.torque = torque;
	}

	public Integer getTorque() {
		return torque;
	}

	public static class AcmeGear extends Gear {
		public AcmeGear() {
			super( 100 );
		}
	}
}
package org.hibernate.validator.referenceguide.chapter02.typeargument;

public class GearBoxUnwrapper extends ValidatedValueUnwrapper<GearBox> {
	@Override
	public Object handleValidatedValue(GearBox gearBox) {
		return gearBox == null ? null : gearBox.getGear();
	}

	@Override
	public Type getValidatedValueType(Type valueType) {
		return Gear.class;
	}
}
Car car = Car();
car.setGearBox( new GearBox<>( new Gear.AcmeGear() ) );

Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );
assertEquals( 1, constraintViolations.size() );
assertEquals( "Gear is not providing enough torque.", constraintViolations.iterator().next().getMessage() );
assertEquals( "gearBox", constraintViolations.iterator().next().getPropertyPath().toString() );

2.1.4. Class-level constraints

Last but not least, a constraint can also be placed on the class level. In this case not a single property is subject of the validation but the complete object. Class-level constraints are useful if the validation depends on a correlation between several properties of an object.

The Car class in Example 2.7, “Class-level constraint” has the two attributes seatCount and passengers and it should be ensured that the list of passengers has not more entries than seats are available. For that purpose the @ValidPassengerCount constraint is added on the class level. The validator of that constraint has access to the complete Car object, allowing to compare the numbers of seats and passengers.

Refer to Section 6.2, “Class-level constraints” to learn in detail how to implement this custom constraint.

Example 2.7. Class-level constraint
package org.hibernate.validator.referenceguide.chapter02.classlevel;

@ValidPassengerCount
public class Car {

	private int seatCount;

	private List<Person> passengers;

	//...
}

2.1.5. Constraint inheritance

When a class implements an interface or extends another class, all constraint annotations declared on the super-type apply in the same manner as the constraints specified on the class itself. To make things clearer let’s have a look at the following example:

Example 2.8. Constraint inheritance
package org.hibernate.validator.referenceguide.chapter02.inheritance;

public class Car {

	private String manufacturer;

	@NotNull
	public String getManufacturer() {
		return manufacturer;
	}

	//...
}
package org.hibernate.validator.referenceguide.chapter02.inheritance;

public class RentalCar extends Car {

	private String rentalStation;

	@NotNull
	public String getRentalStation() {
		return rentalStation;
	}

	//...
}

Here the class RentalCar is a subclass of Car and adds the property rentalStation. If an instance of RentalCar is validated, not only the @NotNull constraint on rentalStation is evaluated, but also the constraint on manufacturer from the parent class.

The same would be true, if Car was not a superclass but an interface implemented by RentalCar.

Constraint annotations are aggregated if methods are overridden. So if RentalCar overrode the getManufacturer() method from Car, any constraints annotated at the overriding method would be evaluated in addition to the @NotNull constraint from the superclass.

2.1.6. Object graphs

The Bean Validation API does not only allow to validate single class instances but also complete object graphs (cascaded validation). To do so, just annotate a field or property representing a reference to another object with @Valid as demonstrated in Example 2.9, “Cascaded validation”.

Example 2.9. Cascaded validation
package org.hibernate.validator.referenceguide.chapter02.objectgraph;

public class Car {

	@NotNull
	@Valid
	private Person driver;

	//...
}
package org.hibernate.validator.referenceguide.chapter02.objectgraph;

public class Person {

	@NotNull
	private String name;

	//...
}

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.

The validation of object graphs is recursive, i.e. if a reference marked for cascaded validation points to an object which itself has properties annotated with @Valid, these references will be followed up by the validation engine as well. The validation engine will ensure that no infinite loops occur during cascaded validation, for example if two objects hold references to each other.

Note that null values are getting ignored during cascaded validation.

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.

Example 2.10. Cascaded validation of a collection
package org.hibernate.validator.referenceguide.chapter02.objectgraph.list;

public class Car {

	@NotNull
	@Valid
	private List<Person> passengers = new ArrayList<Person>();

	//...
}

So when validating an instance of the Car class shown in Example 2.10, “Cascaded validation of a collection”, a ConstraintViolation will be created, if any of the Person objects contained in the passengers list has a null name.

2.2. Validating bean constraints

The Validator interface is the most important object in Bean Validation. The next section shows how to obtain an Validator instance. Afterwards you’ll learn how to use the different methods of the Validator interface.

2.2.1. Obtaining a Validator instance

The first step towards validating an entity instance is to get hold of a Validator instance. The road to this instance leads via the Validation class and a ValidatorFactory. The easiest way is to use the static method Validation#buildDefaultValidatorFactory():

Example 2.11. Validation#buildDefaultValidatorFactory()
ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
Validator validator = factory.getValidator();

This bootstraps a validator in the default configuration. Refer to Chapter 8, Bootstrapping to learn more about the different bootstrapping methods and how to obtain a specifically configured Validator instance.

2.2.2. Validator methods

The Validator interface contains three methods that can be used to either validate entire entities or just 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) is used. The topic of validation groups is discussed in detail in Chapter 5, Grouping constraints.

2.2.2.1. Validator#validate()

Use the validate() method to perform validation of all constraints of a given bean. Example 2.12, “Using Validator#validate() shows the validation of an instance of the Car class from Example 2.2, “Property-level constraints” which fails to satisfy the @NotNull constraint on the manufacturer property. The validation call therefore returns one ConstraintViolation object.

Example 2.12. Using Validator#validate()
Car car = new Car( null, true );

Set<ConstraintViolation<Car>> constraintViolations = validator.validate( car );

assertEquals( 1, constraintViolations.size() );
assertEquals( "may not be null", constraintViolations.iterator().next().getMessage() );

2.2.2.2. Validator#validateProperty()

With help of the validateProperty() you can validate a single named property of a given object. The property name is the JavaBeans property name.

Example 2.13. Using Validator#validateProperty()
Car car = new Car( null, true );

Set<ConstraintViolation<Car>> constraintViolations = validator.validateProperty(
		car,
		"manufacturer"
);

assertEquals( 1, constraintViolations.size() );
assertEquals( "may not be null", constraintViolations.iterator().next().getMessage() );

2.2.2.3. Validator#validateValue()

By using the validateValue() method you can check whether a single property of a given class can be validated successfully, if the property had the specified value:

Example 2.14. Using Validator#validateValue()
Set<ConstraintViolation<Car>> constraintViolations = validator.validateValue(
		Car.class,
		"manufacturer",
		null
);

assertEquals( 1, constraintViolations.size() );
assertEquals( "may not be null", constraintViolations.iterator().next().getMessage() );
---

Note

@Valid is not honored by validateProperty() or validateValue().

Validator#validateProperty() is for example used in the integration of Bean Validation into JSF 2 (see Section 10.2, “JSF & Seam”) to perform a validation of the values entered into a form before they are propagated to the model.

2.2.3. ConstraintViolation methods

Now it is time to have a closer look at what a ConstraintViolation is. Using the different methods of ConstraintViolation a lot of useful information about the cause of the validation failure can be determined. Table 2.1, “The various ConstraintViolation methods” gives an overview of these methods. The values in the "Example" column refer to Example 2.12, “Using Validator#validate().

Table 2.1. The various ConstraintViolation methods
MethodUsageExample

getMessage()

The interpolated error message

"may not be null"

getMessageTemplate()

The non-interpolated error message

"{…​ NotNull.message}"

getRootBean()

The root bean being validated

car

getRootBeanClass()

The class of the root bean being validated

Car.class

getLeafBean()

If a bean constraint, the bean instance the constraint is applied on; If a property constraint, the bean instance hosting the property the constraint is applied on

car

getPropertyPath()

The property path to the validated value from root bean

contains one node with kind PROPERTY and name "manufacturer"

getInvalidValue()

The value failing to pass the constraint

null

getConstraintDescriptor()

Constraint metadata reported to fail

descriptor for @NotNull


2.3. Built-in constraints

Hibernate Validator comprises a basic set of commonly used constraints. These are foremost the constraints defined by the Bean Validation specification (see Table 2.2, “Bean Validation constraints”). Additionally, Hibernate Validator provides useful custom constraints (see Table 2.3, “Custom constraints” and Table 2.4, “Custom country specific constraints”).

2.3.1. Bean Validation constraints

Table 2.2, “Bean Validation constraints” shows purpose and supported data types of all constraints specified in the Bean Validation API. All these constraints apply to the field/property level, there are no class-level constraints defined in the Bean Validation specification. If you are using the Hibernate object-relational mapper, some of the constraints are taken into account when creating the DDL for your model (see column "Hibernate metadata impact").

Note

Hibernate Validator allows some constraints to be applied to more data types than required by the Bean Validation specification (e.g. @Max can be applied to strings). Relying on this feature can impact portability of your application between Bean Validation providers.

Table 2.2. Bean Validation constraints
AnnotationSupported data typesUseHibernate metadata impact

@AssertFalse

Boolean, boolean

Checks that the annotated element is false

None

@AssertTrue

Boolean, boolean

Checks that the annotated element is true

None

@DecimalMax(value=,inclusive=)

BigDecimal, BigInteger, CharSequence, byte, short, int, long and the respective wrappers of the primitive types; Additionally supported by HV: any sub-type of Number

Checks whether the annotated value is less than the specified maximum, when inclusive=false. Otherwise whether the value is less than or equal to the specified maximum. The parameter value is the string representation of the max value according to the BigDecimal string representation.

None

@DecimalMin(value=,inclusive=)

BigDecimal, BigInteger, CharSequence, byte, short, int, long and the respective wrappers of the primitive types; Additionally supported by HV: any sub-type of Number

Checks whether the annotated value is larger than the specified minimum, when inclusive=false. Otherwise whether the value is larger than 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=)

BigDecimal, BigInteger, CharSequence, byte, short, int, long and the respective wrappers of the primitive types; Additionally supported by HV: any sub-type of Number

Checks whether the annotated value is a number having up to integer digits and fraction fractional digits

Defines column precision and scale

@Future

java.util.Date, java.util.Calendar, java.time.chrono.ChronoZonedDateTime, java.time.Instant, java.time.OffsetDateTime; Additionally supported by HV, if the Joda Time date/time API is on the class path: any implementations of ReadablePartial and ReadableInstant

Checks whether the annotated date is in the future

None

@Max(value=)

BigDecimal, BigInteger, byte, short, int, long and the respective wrappers of the primitive types; Additionally supported by HV: any sub-type of CharSequence (the numeric value represented by the character sequence is evaluated), any sub-type of Number

Checks whether the annotated value is less than or equal to the specified maximum

Adds a check constraint on the column

@Min(value=)

BigDecimal, BigInteger, byte, short, int, long and the respective wrappers of the primitive types; Additionally supported by HV: any sub-type of CharSequence (the numeric value represented by the char sequence is evaluated), any sub-type of Number

Checks whether the annotated value is higher than or equal to the specified minimum

Adds a check constraint on the column

@NotNull

Any type

Checks that the annotated value is not null.

Column(s) are not nullable

@Null

Any type

Checks that the annotated value is null

None

@Past

java.util.Date, java.util.Calendar, java.time.chrono.ChronoZonedDateTime, java.time.Instant, java.time.OffsetDateTime; Additionally supported by HV, if the Joda Time date/time API is on the class path: any implementations of ReadablePartial and ReadableInstant

Checks whether the annotated date is in the past

None

@Pattern(regex=,flag=)

CharSequence

Checks if the annotated string matches the regular expression regex considering the given flag match

None

@Size(min=, max=)

CharSequence, Collection, Map and arrays

Checks if the annotated element’s size is between min and max (inclusive)

Column length will be set to max

@Valid

Any non-primitive type

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


Note

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

2.3.2. Additional constraints

In addition to the constraints defined by the Bean Validation API Hibernate Validator provides several useful custom constraints which are listed in Table 2.3, “Custom constraints”. With one exception also these constraints apply to the field/property level, only @ScriptAssert is a class- level constraint.

Table 2.3. Custom constraints
AnnotationSupported data typesUseHibernate metadata impact

@CreditCardNumber(ignoreNonDigitCharacters=)

CharSequence

Checks that the annotated character sequence passes the Luhn checksum test. Note, this validation aims to check for user mistakes, not credit card validity! See also Anatomy of Credit Card Numbers. ignoreNonDigitCharacters allows to ignore non digit characters. The default is false.

None

@EAN

CharSequence

Checks that the annotated character sequence is a valid EAN barcode. type determines the type of barcode. The default is EAN-13.

None

@Email

CharSequence

Checks whether the specified character sequence is a valid email address. The optional parameters regexp and flags allow to specify an additional regular expression (including regular expression flags) which the email must match.

None

@Length(min=,
max=)

CharSequence

Validates that the annotated character sequence is between min and max included

Column length will be set to max

@LuhnCheck(startIndex= ,
endIndex=,
checkDigitIndex=,
ignoreNonDigitCharacters=)

CharSequence

Checks that the digits within the annotated character sequence pass the Luhn checksum algorithm (see also Luhn algorithm). startIndex and endIndex allow to only run the algorithm on the specified sub-string. checkDigitIndex allows to use an arbitrary digit within the character sequence as the check digit. If not specified it is assumed that the check digit is part of the specified range. Last but not least, ignoreNonDigitCharacters allows to ignore non digit characters.

None

@Mod10Check(multiplier=,
weight=,
startIndex=,
endIndex=,
checkDigitIndex=,
ignoreNonDigitCharacters=)

CharSequence

Checks that the digits within the annotated character sequence pass the generic mod 10 checksum algorithm. multiplier determines the multiplier for odd numbers (defaults to 3), weight the weight for even numbers (defaults to 1). startIndex and endIndex allow to only run the algorithm on the specified sub-string. checkDigitIndex allows to use an arbitrary digit within the character sequence as the check digit. If not specified it is assumed that the check digit is part of the specified range. Last but not least, ignoreNonDigitCharacters allows to ignore non digit characters.

None

@Mod11Check(threshold=,
startIndex=,
endIndex=,
checkDigitIndex=,
ignoreNonDigitCharacters=,
treatCheck10As=,
treatCheck11As=)

CharSequence

Checks that the digits within the annotated character sequence pass the mod 11 checksum algorithm. threshold specifies the threshold for the mod11 multiplier growth; if no value is specified the multiplier will grow indefinitely. treatCheck10As and treatCheck11As specify the check digits to be used when the mod 11 checksum equals 10 or 11, respectively. Default to X and 0, respectively. startIndex, endIndex checkDigitIndex and ignoreNonDigitCharacters carry the same semantics as in @Mod10Check.

None

@NotBlank

CharSequence

Checks that the annotated character sequence 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 white-spaces are ignored.

None

@NotEmpty

CharSequence, Collection, Map and arrays

Checks whether the annotated element is not null nor empty

None

@Range(min=,
max=)

BigDecimal, BigInteger, CharSequence, byte, short, int, long and the respective wrappers of the primitive types

Checks whether the annotated value lies between (inclusive) the specified minimum and maximum

None

@SafeHtml(whitelistType= ,
additionalTags=,
additionalTagsWithAttributes=)

CharSequence

Checks whether the annotated value contains potentially malicious fragments such as <script/>. In order to use this constraint, the jsoup library must be part of the class path. With the whitelistType attribute a predefined whitelist type can be chosen which can be refined via additionalTags or additionalTagsWithAttributes. The former allows to add tags without any attributes, whereas the latter allows to specify tags and optionally allowed attributes using the annotation @SafeHtml.Tag.

None

@ScriptAssert(lang=,
script=,
alias=)

Any type

Checks 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. 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=,
regexp=,
flags=)

CharSequence

Checks if the annotated character sequence is a valid URL according to RFC2396. If any of the optional parameters protocol, host or port are specified, the corresponding URL fragments must match the specified values. The optional parameters regexp and flags allow to specify an additional regular expression (including regular expression flags) which the URL must match. Per default this constraint used the java.net.URL constructor to verify whether a given string represents a valid URL. A regular expression based version is also available - RegexpURLValidator - which can be configured via XML (see Section 7.2, “Mapping constraints via constraint-mappings) or the programmatic API (see Section 11.14.2, “Adding constraint definitions programmatically”).

None


2.3.2.1. Country specific constraints

Hibernate Validator offers also some country specific constraints, e.g. for the validation of social security numbers.

Note

If you have to implement a country specific constraint, consider making it a contribution to Hibernate Validator!

Table 2.4. Custom country specific constraints
AnnotationSupported data typesUseCountryHibernate metadata impact

@CNPJ

CharSequence

Checks that the annotated character sequence represents a Brazilian corporate tax payer registry number (Cadastro de Pessoa Juríeddica)

Brazil

None

@CPF

CharSequence

Checks that the annotated character sequence represents a Brazilian individual taxpayer registry number (Cadastro de Pessoa Fídsica)

Brazil

None

@TituloEleitoral

CharSequence

Checks that the annotated character sequence represents a Brazilian voter ID card number (Título Eleitoral)

Brazil

None


Tip

In some cases neither the Bean Validation constraints nor the custom constraints provided by Hibernate Validator will fulfill your requirements. In this case you can easily write your own constraint. You can find more information in Chapter 6, Creating custom constraints.