An annotation is considered a constraint definition if its retention policy contains RUNTIME and if the annotation itself is annotated with javax.validation.Constraint Constraint annotations can target any of the following ElementTypes: FIELD, METHOD, TYPE, ANNOTATION_TYPE If a constraint definition is not valid, a ConstraintDefinitionException is raised either at validation time or when the metadata is requested Applying a constraint annotation to an incompatible type will raise a UnexpectedTypeException

A constraint definition may have attributes that are specified at the time the constraint is applied to a JavaBean. Annotation elements starting with valid are not allowed Every constraint annotation must define a message element of type String Every constraint annotation must define a groups element that specifies which processing groups the constraint definition is associated with. The default value for the groups element must be an empty array. If no group is specified when declaring the constraint on an element, the Default group is considered declared. The type of the groups parameter is Class<?>[]. Every constraint annotation must define a payload element that specifies which payload the constraint declaration is associated with. The default value for the payload parameter must be an empty array. Each attachable payload extends Payload.

The bean validation provider treats regular annotations (annotations not annotated by @Constraint) whose value element has a return type of an array of constraint annotations in a special way. Each element in the value array are processed by the Bean Validation implementation as regular constraint annotations.

Each constraint annotation hosted on a constraint annotation is applied to the target element and this recursively Note that the main annotation and its constraint validation implementation is also applied By default, each failing constraint generates an error report Groups from the main constraint annotation are inherited by the composing annotations Any groups definition on a composing annotation is ignored The property type a composed constraint is placed on must be compatible with all constraints (composing and composed) If a composed constraint is marked as @ReportAsSingleViolation, and if any of its composing constraint reports one or more violations, all reports from composing constraints are ignored and the error report corresponding to the composed constraint is generated Composing annotations can define the value of message and custom attributes (excluding groups) but these are fixed in the composed constraint definition It is possible to override attributes and messages defined on a composing annotation. An attribute from the main annotation is used to override one or more attributes of the composing annotations. Such an attribute is annotated with the @OverridesAttribute annotation or its multivalued equivalent @OverridesAttribute.List The types of the overridden and overriding attributes must be identical A composing constraint can itself be a composed constraint. In this case, attribute values are overridden recursively according to the described rules If a constraint is used more than once as a composing constraint, the multi value constraints model as described in Section 2.2 is used To select the appropriate composing constraint targeted, OverridesAttrib- ute.constraintIndex is used. It represents the constraint index in the value array If index is undefined, the single constraint declaration is targeted If the composition is invalid (infinite composition, wrong attribute overriding, a single attribute mapped to more than one source attribute etc), a ConstraintDefinitionException is raised either at validation time or when the metadata is requested Any payload definition on a composing annotation is ignored

A constraint validation implementation performs the validation of a given constraint annotation for a given type The implementation classes are specified by the validatedBy element of the @Constraint annotation that decorates the constraint definition The constraint validation implementation implements the ConstraintValidator interface T must resolve in a non parameterized type or generic parameters of T must be unbounded wildcard types The initialize method is called by the Bean validation provider prior to any use of the constraint implementation. The isValid method is evaluated by the Bean Validation provider each time a given value is validated It returns false if the value is not valid, true otherwise isValid implementations must be thread-safe If the property is of an unanticipated type, an UnexpectedTypeException is raised If an exception occurs either in the initialize or isValid method, the runtime exception is wrapped into a ValidationException by the Bean Validation engine The constraint validation implementation is not allowed to change the state of the value passed to isValid. By default, each invalid constraint leads to the generation of one error object represented by a ConstraintViolation object. This object is build from the default error message as defined by the constraint declaration and the context in which the constraint declaration is placed on (bean, property, attribute) The ConstraintValidatorContext methods let the constraint implementation disable the default error object generation and create one or more custom ones The non-interpolated message passed as a parameter is used to build the ConstraintViolation object (the message interpolation operation is applied to it) By default, the propertyPath exposed on the ConstraintViolation represents the path to the bean or property hosting the constraint You can point an error to a subpath of this default path by using the error builder fluent API. If disableDefaultError is called, no custom error is added (using the error builder) and if the constraint is not valid, a ValidationException is raised.

The default ConstraintValidatorFactory provided by the Bean Validation provider implementation uses the public constraint no-arg constructor If an exception occurs in the factory while retrieving the ConstraintValidator instance, the runtime exception is wrapped in a ValidationException If the instance returned by the factory is null, a ValidationException is raised

Properties to be validated must follow the method signature conventions for JavaBeans read properties, as defined by the JavaBeans specification Static fields and static methods are excluded from validation Constraints can be applied to interfaces and superclasses The target of an annotation definition can be a field, property, or type, provided that the constraint definition supports the specified target and the constraint supports the declared type of the target.

Constraint declarations can be applied to a class or an interface

Constraint declarations can be applied on both fields and properties for the same object type The same constraint should however not be duplicated between a field and its associated property (the constraint validation would be applied twice) When a field is annotated with a constraint declaration, field access strategy is used to access the state validated by such constraint When a property is annotated with a constraint declaration, property access strategy is used to access the state validated by such constraint The fields or methods visibility are not constrained Constraints on non getter methods are not supported

Consider the situation where bean X contains a field of type Y. By annotating field Y with the @Valid annotation, the Validator will validate Y (and its properties) when X is validated. The exact type Z of the value contained in the field declared of type Y (subclass, implementation) is determined at runtime. The constraint definitions of Z are used Array of objects is supported by @Valid. The content of the array is validated. java.util.Collection is supported by @Valid. The content of the collection is validated. java.util.Set is supported by @Valid. The content of the Set is validated. java.util.List is supported by @Valid. The content of the list is validated. java.util.Map is supported by @Valid java.lang.Iterable is supported by @Valid. The elements of the iterable are validated For Map, the value of each entry is validated (the key is not validated) Like regular references, the type of the collection, array or Iterable element is determined at runtime and the constraint definitions for this particular type are used The @Valid annotation is applied recursively

A constraint declaration can be placed on an interface For a given class, constraint declarations held on superclasses as well as interfaces are evaluated by the Bean Validation provider

If no group is explicitly declared, a constraint belongs to the Default group Groups are represented by interfaces A constraint can belong to one or more groups During the validation call, one or more groups are validated. All the constraints belonging to this set of group is evaluated on the object graph

A group can inherit one or more groups by using interface inheritance For a given interface Z, constraints marked as belonging to the group Z (ie where the annotation groups property contains the interface Z) or any of the super interfaces of Z (inherited groups) are considered part of the group Z

By default, constraints are evaluated in no particular order and this regardless of which groups they belong to Each group in a group sequence must be processed sequentially in the order defined by @GroupSequence.value when the group defined as a sequence is requested Note that a group member of a sequence can itself be composed of several groups via inheritance or sequence definition. In this case, each composed group must respect the sequence order as well. If one of the groups processed in the sequence generates one or more constraint violation, the groups following in the sequence must not be processed 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. Groups defining a sequence should not directly inherit other groups. In other words, the interface hosting the group sequence should not have any super interface. Groups defining a sequence should not be used directly in constraint declarations To define a group as a sequence, the interface must be annotated with the @GroupSequence annotation A given constraint can belong to two groups ordered by a sequence. In this case, the constraint is evaluated as part of the first group and ignored in the subsequent group(s)

To redefine Default for a class, place a @GroupSequence annotation on the class. this sequence expresses the sequence of groups that does substitute Default for this class. Constraints hosted on a class A and belonging to the Default group (by default or explicitly) implicitly belong to the group A A sequence defined on a class A (ie. redefining the Default groups for the class) must contain the group A If a @GroupSequence redefining the Default group for a class A does not contain the group A, a GroupDefinitionException is raised when the class is validated or when its metadata is requested

Every constraint hosted on an interface Z and part of the Default group (implicitly or explicitly) belongs to the group Z

If a class does have a @GroupSequence annotation, the group Default contains every constraint belonging to every group declared by the @GroupSequence annotation. If class X has no @GroupSequence annotation, the group Default contains every constraint in the group X and if X has a direct superclass Y, every constraint in the group Default of Y this rule

For a given group to validate, the validation routine applied on a given bean instance is expected to execute the constraint validations in no particular order Note that this implies that a given validation constraint will not be processed more than once per validation Unless ordered by group sequences, groups can be validated in no particular order

The @Valid annotation on a given association (i.e. object reference or collection, array, Iterable of objects), dictates the Bean Validator implementation to apply recursively the bean validation routine on (each of) the associated object(s) This mechanism is recursive Null references are ignored To prevent infinite loops, the Bean Validation implementation must ignore the cascading operation if the associated object instance has already been validated in the current navigation path (starting from the root object) @Valid is an orthogonal concept to the notion of group. If two groups are in sequence, the first group must pass for all associated objects before the second group is evaluated.

isReachable is called for every property about to be accessed either for validation or for cascading isCascadable is called for every property about to be cascaded (ie. marked as @Valid) isCascadable for a given property is only called if isReachable returns true. In other words, isReachable is always called before isCascadable for a given property The Bean Validation provider must not access the state of a property, nor validate its constraints if the property is not traversable. A property is traversable if TraversableResolver returns true for this property If an exception occurs when the TraversableResolver is called, the exception is wrapped into a ValidationException If Java Persistence is available in the runtime environment, a property is considered reachable if Java Persistence considers the property as loaded If Java Persistence is not available in the runtime environment, all properties are considered reachable If Java Persistence is not available in the runtime environment, all properties are considered cascadable

If the constraint declaration is hosted on a class or an interface, the targeted type is the class or the interface If the constraint is hosted on a class attribute, the type of the attribute is the targeted type If the constraint is hosted on a getter, the return type of the getter is the targeted type the ConstraintValidator chosen to validate a declared type T is the one where the type supported by the ConstraintValidator is a supertype of T and where there is no other ConstraintValidator whose supported type is a supertype of T and not a supertype of the chosen ConstraintValidator supported type If no ConstraintValidator compliant with T is found amongst the ConstraintValidators listed by the constraint A, a UnexpectedTypeException is raised If more than one maximally specific ConstraintValidator is found, a UnexpectedTypeException is raised

Validator implementations are thread-safe

validate(T object, Class... groups) is used to validate a given object An IllegalArgumentException is thrown when validateProperty is called and object is null or null is passed to the varargs groups. A Set containing all ConstraintViolation objects representing the failing constraints is returned, an empty Set is returned otherwise validateProperty(T object, String propertyName, Class... groups) validates a given field or property of an object An IllegalArgumentException is thrown when validateProperty is called and object is null or propertyName is null empty or invalid or null is passed to the varargs groups. The property name in validateProperty is the JavaBeans property name (as defined by the JavaBeans Introspector class) @Valid is not honored by a call to validateProperty. validateValue(Class beanType, String propertyName, Object value, Class... groups) validates the property referenced by propertyName present on beanType or any of its superclasses, if the property value were value. An IllegalArgumentException is thrown when validateValue is called and object is null or propertyName is null empty or invalid or null is passed to the varargs groups. @Valid is not honored by validateValue. If some unrecoverable failure happens during validation, a ValidationException is raised.

All constraints belonging to the targeted group are applied during the validation routine. If no group is passed, the Default group is assumed When more than one group is evaluated and passed to the various validate methods, order is not constrained

The getMessage method returns the interpolated (localized) message for the failing constraint The getMessageTemplate method returns the non-interpolated error message The getRootBean method returns the root object being validated that led to the failing constraint The getInvalidValue method returns the value (field, property or validated object) being passed to isValid getConstraintDescriptor provides access to the failing constraint metadata getPropertyPath returns the Path object representing the navigation path from the root object to the failing object If the failing object is the root object, the property path consists of a single Node with name set to null. If failing object is traversed, a Node object whose name equals the name of the association property (field name or Java Bean property name) is added to Path. If the traversed association is a List or an array, the added Node object contains the index value in getIndex. If the association is a Map, the added Node object (representing a given map entry) contains the key value in getKey For all Iterable or Map, the added Node object added is marked as inIterable (isInIterable) For a property level constraint (field and getter) a Node object is added to Path whose name equals the name of the property. For a class level constraint a Node object is added to Path whose name is null Bean Validation implementations should ensure that a ConstraintViolation implementation is Serializable provided that the root bean, the leaf bean, the invalid value and keys in the Path object are Serializable objects.

A conforming implementation includes a default message interpolator Each constraint defines a message descriptor via its message property Every constraint definition shall define a default message descriptor for that constraint. Messages can be overridden at declaration time in constraints by setting the property on the constraint. The message descriptor is a string literal and may contain one or more message parameters. Message parameters are string literals enclosed in braces \{ is considered as the literal { instead of being considered as the beginning of a message parameter \} is considered as the literal } instead of being considered as the end of a message parameter \\ is considered as the literal \ instead of being considered as the escaping character

Message parameters are extracted from the message string and used as keys to search the ResourceBundle named ValidationMessages (step1) Step 1 is applied recursively until no replacement is performed Message parameters are extracted from the message string and used as keys to search the Bean Validation provider's built-in ResourceBundle using the defined locale. If a property is found, the message parameter is replaced with the property value in the message string (step 2) Contrary to step 1, step 2 is not processed recursively If step 2 triggers a replacement, then step 1 is applied again As last step message parameters are extracted from the message string. Those matching the name of an attribute of the constraint declaration are replaced by the value of that attribute. If the locale is passed to the interpolator method interpolate(String, CosntraintDescriptor, Object, Locale), this Locale instance is used If the locale is not specified, the default Locale as provided by Locale.getDefault() is used.

A message interpolator implementation shall be thread-safe It is possible to override the MessageInterpolator implementation for a given Validator instance by invoking ValidatorFactory.usingContext().messageInterpolator(messageInterpolator).getValidator()

A bootstrap implementation must be able to bootstrap any Bean Validation provider implementation

The ValidatorFactory object is thread-safe

The MessageInterpolator or the TraversableResolver passed to the ValidatorContext are used instead of the ValidatorFactory's MessageInterpolator or TraversableResolver instances getMessageInterpolator() returns the MessageInterpolator instance configured during the initialization of the ValidatorFactory

A Bean Validation provider must define a sub interface of Configuration uniquely identifying the provider. Streams represented in the XML configuration and opened by the Configuration implementation must be closed by the Configuration implementation after the ValidatorFactory creation (or if an exception occurs) If no ValidationProviderResolver instance has been specified, the default ValidationProviderResolver is used

ValidationProviderResolver returns the list of Bean Validation providers available at runtime and more specifically a ValidationProvider instance for each provider available in the context Implementations must be thread-safe Bean Validation providers must supply a service provider configuration file by creating a text file javax.validation.spi.ValidationProvider and placing it in the META-INF/services directory of one of its jar files

A client can request a specific Bean Validation provider by using Validation.byProvider() or by defining the provider in the XML configuration file The provider discovery mechanism retrieve all available providers using ValidationProviderResolver.getValidationProviders() and returns the first ValidationProvider matching the requested provider When the default Bean Validation provider is requested, the first ValidationProvider returned by the ValidationProviderResolver strategy is returned Every Bean Validation provider must provide a ValidationProvider implementation containing a public no-arg constructor If a problem occurs while building the ValidatorFactory, a ValidationException is raised

Validation.buildDefaultValidatorFactory(), is considered to be the default ValidatorFactory and is equivalent to the ValidatorFactory returned by Validation.byDefaultProvider().configure().buildValidatorFactory() ValidationProvider.createGenericConfiguration(BootstrapState state) is the second bootstrapping entry point and let the client provide a custom ValidationProviderResolution instance ValidationProvider.createGenericConfiguration(BootstrapState state) is the third bootstrapping entry point and let the client define the specific Bean Validation provider requested as well as a custom ValidationProviderResolver implementation if needed The Validation implementation provided by the Bean Validation provider must not contain any non private attribute or method aside from the three public static bootstrap methods The bootstrap implementation must ensure it can bootstrap third party providers When building the Configuration object, if the ValidationProviderResolver fails or if the expected provider is not found, a ValidationException is raised

Unless explicitly ignored Configuration takes into account the configuration available in META-INF/validation.xml META-INF/validation.xml will be ignored if Configuration.ignoreXMLConfiguration() is called. This configuration file is optional. If more than one META-INF/validation.xml file is found in the classpath, a ValidationException is raised. Unless stated otherwise, XML based configuration settings are overridden by values explicitly set via the Configuration API default-provider represents the class name of the provider specific Configuration sub-interface. If defined, the provider suitable for this interface is used message-interpolator represents the fully qualified class name of the MessageInterpolator implementation. When defined in XML, the implementation must have a public no-arg constructor. traversable-resolver represents the fully qualified class name of the TraversableResolver implementation. When defined in XML, the implementation must have a public no-arg constructor. constraint-validator-factory represents the fully qualified class name of the ConstraintValidatorFactory implementation. When defined in XML, the implementation must have a public no-arg constructor. message-interpolator, traversable-resolver and constraint-validator-factory are optional. constraint-mapping represents the resource path of an XML mapping file More than one constraint-mapping element can be present Mappings provided via Configuration.addMapping(InputStream) are added to the list of mappings described via constraint-mapping The namespace javax.validation for properties is reserved for use by this specification Properties defined via Configuration.addProperty(String, String) are added to the properties defined via property If a property with the same name are defined in both XML and via the programmatic API, the value provided via programmatic API has priority If a public no-arg constructor is missing, a ValidationException is raised during the Configuration.buildValidatorFactory() call

ValidatorFactory is a thread-safe object that should be built once per deployment unit Validator is thread-safe too and should be considered a lightweight object

If a constraint definition or declaration hosted by the requested class (or any of it's superclasses and interfaces according to the constraint propagation rules) is invalid, a ValidationException is raised Validator.getConstraintsForClass returns a BeanDescriptor object describing the bean level constraints and providing access to the property level constraints metadata. Validator.getConstraintsForClass throws an IllegalArgumentException if the clazz parameter is null

getElementClass returns either the object type for a class, or the returned type for a property getConstraintDescriptors returns all the ConstraintDescriptors hosted on the given element in the class hierarchy, each ConstraintDescriptor describing one of the constraints declared on the given element. hasConstraints returns true if the given element (class, field or property) in the class hierarchy holds at least one constraint declaration. unorderedAndMatchingGroups restricts to the ConstraintDescriptors matching the set of groups passed as parameters and present on the element. Order is not respected but group inheritance and inheritance via sequence (including the Default group overriding at the class level) are honored. declaredOn lets you restrict the list of element types constraints are hosted on. lookingAt lets you restrict which constraints are considered. Either constraints belonging to the element but hosted on the class represented by BeanDescritptor (Scope.LOCAL_ELEMENT), or constraints belonging to the element but hosted anywhere in the class hierarchy (Scope.HIERARCHY).

isBeanConstrained returns true if the given class (and superclasses and interfaces) host at least one validation declaration (either constraint or @Valid annotation) getConstraintsForProperty returns a PropertyDescriptor object describing the property level constraints (See Section 3.1.2). The property is uniquely identified by its name as per the JavaBeans convention: field level and getter level constraints of the given name are all returned getConstraintsForProperty throws an IllegalArgumentException if the propertyName parameter is null

The isCascaded method returns true if the property is marked with @Valid getPropertyName returns the property name

If ConstraintDescriptor represents a composing annotation (see Section 2.3), the returned annotation must reflect parameter overriding getAttributes returns a map containing the annotation attribute names as a key, and the annotation attribute values as a value If ConstraintDescriptor represents a composing annotation (see Section 2.3), the returned Map must reflect attribute overriding getGroups returns the groups the constraint is supposed to be applied upon If no group is set on the constraint declaration, the Default group is returned The groups of a composing constraint are the groups of the composed constraint getPayload returns the payloads the constraint hosts or an empty set if none Likewise, payload from the main constraint annotation is inherited by the composing annotations. Any payload definition on a composing annotation is ignored isReportAsSingleViolation() returns true if the constraint is annotated with @ReportAsSingleViolation getComposingConstraints return a set of composing ConstraintDescriptors where each descriptor describes a composing constraint.

Each Bean Validation provider must recognize built-in constraint annotations as valid constraint definitions and provide compliant constraint implementations for each The built-in constraint validation implementation is having a lower priority than an XML mapping definition @Null constraint @NotNull constraint @AssertTrue constraint @AssertFalse constraint @Min constraint @Max constraint @DecimalMin constraint @DecimalMax constraint @Size constraint @Digits constraint @Past constraint @Future constraint @Pattern constraint

If the xml configuration file does not validate against the given xsd files a ValidationException is raised.

Specifically when exploring metadata, the Bean Validation provider must ensure that an annotation instance corresponding to the XML declaration is provided via ConstraintDescriptor.getAnnnotation() A given class must not be described more than once amongst all the XML mapping descriptors A given field or getter must not be described more than once on a given class description A given constraint definition must not be overridden more than once amongst all the XML mapping descriptors If any of these rule is violated in a given validation deployment, a ValidationException is raised during the creation of the ValidatorFactory

If default-package is set, all unqualified class names (including annotations) are considered part of the package described by default-package. A given JavaBean is described by the bean element. The name of the class in the bean node is mandatory By default, all constraint declarations expressed via annotation are ignored for classes described in XML You can force Bean Validation to consider both annotations and XML constraint declarations by using ignore-annotation="false" on bean If the name of the class does refer to a class not present in in the classpath, a ValidationException is raised

If ignore-annotations is declared, Bean Validation must honor the explicit value for this element If not declared, the default value defined in the encapsulating bean element is considered When ignore-annotations is true, class-level Bean Validation annotations are ignored for this class When ignore-annotations is false, constraints declared in XML and constraints declared in annotations are added and form the list of class-level declared constraints @GroupSequence is considered unless group-sequence element is explicitly used

If ignore-annotations is declared, Bean Validation must honor the explicit value for this element If not declared, the default value defined in the encapsulating bean element is considered When ignore-annotations is true, field-level Bean Validation annotations on the targeted field are ignored When ignore-annotations is false, constraints declared in XML and constraints declared in annotations are added and form the list of field-level declared constraints The only way to disable cascading on a field marked as @Valid is to use ignore-annotations=true If the name of the field does not correspond to a field in the given bean a ValidationException is raised

The name attribute correspond to the name of the property considered as defined in Section 3.1.2. If ignore-annotations is declared, Bean Validation must honor the explicit value for this element If not declared, the default value defined in the encapsulating bean element is considered When ignore-annotations is true, property-level Bean Validation annotations on the targeted property are ignored (including the @Valid) When ignore-annotations is false, constraints declared in XML and constraints declared in annotations are added and form the list of property-level declared constraints. The only way to disable cascading on a property marked as @Valid is to use ignore-annotations=true If the name of the property does not correspond to a property in the given bean a ValidationException is raised

The name attribute is mandatory and represents the name of the element in the constraint declaration "message" or "groups" are not permitted names, use the message or groups elements instead. Otherwise a ValidationException is raised If the element represents a primitive type, a class or an enum, the string representation of its value is placed in the element itself If the element represents a primitive type array, a class array or an enum array, the string representation of each value is placed in a element placed under the element itself If the element represents an annotation, the annotation element is used to represent the annotation and placed under element If the element represents an array of annotations, one or more annotation elements are placed under element Elements with default values in the annotation definition do not have to be represented in XML: the default value will be used in this case If an XML constraint declaration is missing mandatory elements, or if it contains elements not part of the constraint definition, a ValidationException is raised

A constraint definition is represented by a constraint-definition element If include-existing-validator is set to false, ConstraintValidator defined on the constraint annotation are ignored If set to true, the list of ConstraintValidators described in XML are concatenated to the list of ConstraintValidator described on the annotation to form a new array of ConstraintValidator evaluated Annotation based ConstraintValidator come before XML based ConstraintValidator in the array The validator list is returned by ConstraintDescriptor.getConstraintValidatorClasses()

Every (runtime) exception raised either at initialization time or execution time by any of the extension interfaces (ConstraintValidator, ConstraintValidatorFactory, MessageInterpolator, TraversableResolver, ValidationProviderResolver) is wrapped in a ValidationException

If a constraint definition does not respect the Bean Validation rules or is inconsistent, a ConstraintDefinitionException is raised.

When a constraint declaration is illegal, ConstraintDeclarationException is raised When the return type of a property cannot be processed for a given constraint, an UnexpectedTypeException is raised

When a group definition is illegal, GroupDefinitionException is raised