While 9.1 is, in general, a drop-in replacement for 9.0, it may produce warnings at the metadata building stageif cascading is applied to the container instead of the container type arguments.It is a good time to finally move away from the Bean Validation 1.0/1.1 legacy approaches.

No migration concerns.

Removals

Behaviour

Removals

Upgrades

Removals

• TheGetterPropertySelectionStrategy SPI contract has been adjusted.ThegetGetterMethodNameCandidates() method now returns aList instead of aSet.

No migration concerns.

No migration concerns.

• Jakarta EE 10

• The EL implementation to use is noworg.glassfish.expressly:expressly:

  <dependency>
  <groupId>org.glassfish.expressly</groupId>
  <artifactId>expressly</artifactId>
  <version>5.0.0-M1</version>
  </dependency>

• Jakarta EE 9 (a.k.a. the bigjakarta.* package change)

• XML namespaces changed

• @SafeHtml constraint dropped

• Expression Language disabled for custom violations by default

• Expression Language Bean methods execution disabled for constraints by default

Seehttps://in.relation.to/2020/12/08/hibernate-validator-700-62-cr1-released/ for more details.

• @SafeHtml constraint dropped

• Expression Language disabled for custom violations by default

• Expression Language Bean methods execution disabled for constraints by default

Seehttps://in.relation.to/2020/12/08/hibernate-validator-700-62-cr1-released/ for more details.

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

• @SafeHtml has been deprecated and marked for future removal.

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

• @SafeHtml has been deprecated and marked for future removal.

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

• If you are using our CDI integration, be sure that all the beans you want to validate have a Bean Validation annotation (be it a constraint,@Valid or@ValidateOnExecution). If you need to add an annotation, just add a simple@ValidateOnExecution to the class. This limitation was present until 6.0.10.Final and is now back due to a nasty startup time regression of CDI applications.

• We removed theStaticFieldELResolver from ourjavax.el resolver list. This feature was added during the 6.x cycle and never documented. If you want to call methods from your EL expressions, just inject an object containing the methods as a variable.

• A few validation messages have been changed to be more consistent. That being said, you should rely on the constraint annotation to categorize your violations rather than on the message.

• We fixed an issue with theJPATraversableResolver not being initialized correctly (and thus we we using the default one): theJPATraversableResolver is now used by default in any JPA environment as it should be (thus Hibernate Validator will not validate or cascade lazily loaded properties not already loaded). If it is not the behavior you want, you can override theTraversableResolver for yourValidatorFactory. This regression was introduced in 6.0.3.Final.

• We fixed the CDI extension to properly consider the annotations in the hierarchy of a class. Prior to 6.0.10.Final, if the considered class didn’t have any validation related annotations but its class hierarchies did, the annotations in the class hierarchy were ignored. This is no longer the case. Note: it worked OK if the considered class itself had at least one validation related annotation.

• The constraint validator payload (incubating feature introduced in 6.0.8.Final) has been moved from theHibernateConstraintValidatorInitializationContext to theHibernateConstraintValidatorContext. Seethe documentation for more information.

No migration concerns.

No migration concerns.

No migration concerns.

• To improve the compatibility with the version previously shipped in WildFly, we reintroduced a few things removed in earlier versions of 6.0:

  • thehibernate.validator.constraint_mapping_contributor property (you may now use thehibernate.validator.constraint_mapping_contributors property)

  • ignoreAnnotations() in the constraint declaration API (you may now useignoreAnnotations(boolean))

  • These features are deprecated and planned for removal so they will be removed at some point

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

• Hibernate Validator now throws an exception in every case if trying to perform validation on a property or a method not present in a bean (before this version, no errors were thrown if the bean was totally unconstrained and an error was thrown when validating method parameters but not when validating return values). More generally, sanity checks on the variousValidator#validate…​() methods parameters are now always applied, even if the bean is unconstrained.

• The group id of Hibernate Validator has changed fromorg.hibernate toorg.hibernate.validator. Refer to the artifacts viaorg.hibernate.validator:hibernate-validator:6.0.0.Final,org.hibernate.validator:hibernate-validator-cdi:6.0.0.Final andorg.hibernate.validator:hibernate-validator-annotation-processor:6.0.0.Final, respectively.

  To ease migration, relocation artifacts will be provided for the HV 6 release family. Examine the output of your build, if you see messages like "[WARNING] The artifact org.hibernate:hibernate-validator:jar:6.0.0.Alpha1 has been relocated to org.hibernate.validator:hibernate-validator:jar:6.0.0.Alpha1", you are still using the old GAV coordinates and should upgrade to the new ones.

  Also make sure to not depend on HV 5.x and HV 6.x at the same time (as the group ids are different, the dependency resolution algorithm of your build tool fails to detect that these are two versions of the same logical artifact).

• Removal/change of experimental features in the favor of equivalent functionality standardized in Bean Validation 2.0:

  • The experimental contractorg.hibernate.validator.spi.time.TimeProvider and related methodsHibernateValidatorConfiguration#timeProvider(),HibernateValidatorContext#timeProvider() andHibernateConstraintValidatorContext#getTimeProvider() and related constantHibernateValidatorConfiguration#TIME_PROVIDER have been removed. Usejavax.validation.ClockProvider as defined by BV 2.0 instead (HV-1135).

  • The experimental annotationorg.hibernate.validator.valuehandling.UnwrapValidatedValue, enumorg.hibernate.validator.valuehandling.UnwrapMode and the corresponding methodunwrapValidatedValue() in the constraint declaration API have been removed in the favor of the newjavax.validation.valueextraction.Unwrapping constraint payloads (HV-1207).

  • The experimental contractorg.hibernate.validator.spi.valuehandling.ValidatedValueUnwrapper, related methodsHibernateValidatorConfiguration#addValidationValueHandler() andHibernateValidatorContext#addValidationValueHandler() and related constantHibernateValidatorConfiguration.VALIDATED_VALUE_HANDLERS have been removed. Implement the standardized interfacejavax.validation.valueextraction.ValueExtractor instead (HV-1166).

  • When you have the following constraint definition@NotNull Optional<@NotNull String> value and setvalue to null, HV used to report 2 violations, one for each@NotNull defined. This is not the case anymore in HV 6.x, the value in the container is not extracted and validated anymore if the container is null (HV-1240).

  • Property path nodes representing the element of a validated container (e.g. when validatingList<@Email String emails) are represented by the standardized node typeCONTAINER_ELEMENT instead ofPROPERTY* Further changes:

  • org.hibernate.validator.cfg.defs.NotBlankDef,NotEmptyDef andEmailDef create the standardized constraints@NotBlank,@NotEmpty and@Email now instead of the legacy HV-specific counter-parts (HV-1368)

  • The parameter name provider implementationorg.hibernate.validator.parameternameprovider.ReflectionParameterNameProvider has been removed as it got obsolete with Bean Validation 2.0 where retrieval of parameter names via reflection is the default behavior (HV-1118).

  • An implementation of Expression Language 3.0 (JSR 341) is required now. EL 3.0 was the only version mandated by the BV 1.1 spec also before, but HV 5.x could work with EL 2 implementations. E.g. add the following dependency to your project:org.glassfish:javax.el:3.0.1-b08.

  • The configuration optionhibernate.validator.constraint_mapping_contributor (deprecated in 5.3) has been removed. It was replaced byhibernate.validator.constraint_mapping_contributors which accepts a comma separated list of contributors. The constanto.h.v.HibernateValidatorConfiguration#CONSTRAINT_MAPPING_CONTRIBUTOR has also been removed and replaced byo.h.v.HibernateValidatorConfiguration#CONSTRAINT_MAPPING_CONTRIBUTORS.

  • The deprecated methodignoreAnnotations() has been removed from the constraint declaration API in favor ofignoreAnnotations(boolean) (HV-1120)

  • All the implementation classes of the annotation-processor module have been relocated to theorg.hibernate.validator.ap.internal package. These classes had never been intended for public usage, no migration impact is expected. The only user facing class of that module,org.hibernate.validator.ap.ConstraintValidationProcessor, remains unchanged (HV-1396).

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

No migration concerns.

• We changed slightly the way thejavax.el ExpressionFactory is initialized. Before this release, if you used aResourceBundleMessageInterpolator, HV could be initialized with only a dependency to thejavax.el API as theExpressionFactory was not initialized at bootstrap (and it would have failed at message interpolation). As we now initialize theExpressionFactory at bootstrap, if theResourceBundleMessageInterpolator is used, you also need to have ajavax.el implementation available. So, in the end, either you don’t useResourceBundleMessageInterpolator at all and then you don’t need anyjavax.el dependency or you use aResourceBundleMessageInterpolator and thejavax.el API and an implementation are required by HV.

No migration concerns.

• The (experimental) notion ofConstraintDefinitionContributor has been removed from the public API. Instead the new methodConstraintMapping#constraintDefinition() should be used when constraint definitions need to be added programmatically. This change makes the API for programmatic constraint definition and declaration consistent with the XML approach for achieving the same. The following elements have been removed:

  • Interfaceo.h.v.spi.constraintdefinition.ConstraintDefinitionContributor

  • Constanto.h.v.HibernateValidatorConfiguration#CONSTRAINT_DEFINITION_CONTRIBUTORS

  • Methodo.h.v.HibernateValidatorConfiguration#addConstraintDefinitionContributor()

  • Methodo.h.v.HibernateValidatorConfiguration#getDefaultConstraintDefinitionContributor()

• The possibility to add constraint validators by means of the Java service loader mechanism (via aMETA-INF/services/javax.validation.ConstraintValidator file) remains in place.

• The configuration optionhibernate.validator.constraint_mapping_contributor has been deprecated in favor ofhibernate.validator.constraint_mapping_contributors which accepts a comma separated list of contributors. The constanto.h.v.HibernateValidatorConfiguration#CONSTRAINT_MAPPING_CONTRIBUTOR has been deprecated in favor ofo.h.v.HibernateValidatorConfiguration#CONSTRAINT_MAPPING_CONTRIBUTORS (HV-1065)

No migration concerns.

No migration concerns.

The methodAnnotationProcessingOptions#ignoreAnnotations() has been deprecated and scheduled for removal in a future release. UseAnnotationIgnoreOptions#ignoreAnnotations(boolean) instead.

No migration concerns.

No migration concerns.

• The@Mod10Check and@Mod11Check constraints introduced in 5.1.0.Beta1 got an overhaul. Indeces are now always inclusive (especially theendIndex) and are always relative to the validated value, independent ofignoreNonDigitCharacters. AlsocheckDigitPosition got renamed intocheckDigitIndex.

• The programmatic constraint declaration API raises aValidationException now in case the same element (type, property, method etc.) is configured more than once within the mappings used to configure one validator factory. While this was possible before, it was not recommended as it may have caused issues when e.g. configuring conflicting annotation ignore options (HV-716). Instead select any element to be configured once and apply all required configurations subsequently.

• When building Hibernate Validator from the sources yourself, you need to use now JDK 7 and Maven 3.0.3 or later. Note that the created binaries are still Java 6 compatible (HV-619,HV-797).

No migration concerns.

No migration concerns.

• The Hibernate Validator CDI portable extension has been extracted from the main JAR into a separate module (HV-778). To make use of the extension, the dependencyorg.hibernate:hibernate-validator-cdi:5.0.0.CR5 must be added to the classpath.

No migration concerns.

• @ValidateExecutable is reamed to@ValidateOnExecution and theExecutableType.IMPLICIT is introduced -BVAL-437

• MethodDescriptor#areParametersConstrained got renamed intoMethodDescriptor#hasConstrainedParameters andMethodDescriptor#isReturnValueConstrained intoMethodDescriptor#hasConstrainedReturnValue -BVAL-432

• XML config element<validated-executables></validated> is renamed to<default-validated-executable-types></default> and matchingBootstrapConfiguration#getValidatedExecutableTypes toBootstrapConfiguration#getDefaultValidatedExecutableTypes -BVAL-435

No migration concerns.

• Methods ofParameterNameProvider interface return nowList instead ofString[] -BVAL-409

• @CrossParameterConstraint got replaced by@SupportValidationTarget -BVAL-391

• Renamedjavax.validation.MethodValidator toExecutableValidator;j.v.Validator#forMethods() renamed toforExecutables() (BVAL-355)

• Made methodsj.v.ExecutableValidator#validateConstructorParameters() andvalidateConstructorReturnValue() more usable (BVAL-358)

• Deprecatedorg.hibernate.validator.messageinterpolation.ValueFormatterMessageInterpolator; the validated value can now be used within EL expressions (BVAL-223)

• Removed annotationjavax.validation.cdi.MethodValidated (BVAL-376)

• Removed Maven archetype (HV-650)

• This release requires Bean Validation 1.1.0.Beta2

• Methods for method validation moved fromjavax.validation.Validator toMethodValidator (BVAL-310)

• javax.validation.ConfigurationSource renamed toBootstrapConfiguration (BVAL-293)

• Removed types deprecated in Hibernate Validator 4.3.0 (HV-584)

• This release requires Bean Validaton 1.1 as a dependency (more concretely 1.1.0.Alpha1)

• The custom method validation feature has been replaced by the method validation specfied by Bean Validation 1.1

• The deprecated classes and methods fromHV-561 have been removed. This means if you are using any of the affected APIs you will need to migrate

HV-561 introduced several deprecations (see the Javadoc fora complete deprecation list):

• org.hibernate.validator.group.DefaultGroupSequenceProvider is deprecated and replaced byorg.hibernate.validator.group.spi.DefaultGroupSequenceProvider

• org.hibernate.validator.resourceloading.ResourceBundleLocator is deprecated and replaced byorg.hibernate.validator.spi.resourceloading.ResourceBundleLocator

• The constructor oforg.hibernate.validator.cfg.ConstraintMapping is deprecated. Instances ofConstraintMapping are now created viaHibernateValidatorConfiguration#createConstraintMapping()

• The packageorg.hibernate.validator.method with its containing classes is deprecated without alternative for now. In Hibernate Validator 5 this package will be removed to align with Bean Validation 1.1. The method level validation methods will then be available viajavax.validation.Validator.

• org.hibernate.validator.internal.util.LazyValidatorFactory is deprecated and will be removed in HV 5

This is the first release after Hibernate Validator 4.2.0.Final and backwards compatible. However, the used logging framework has changed to JBoss Logging. This meansorg.jboss.logging:jboss-logging is now a required runtime dependency replacingorg.slf4j:slf4j-api. You can still use slf4j, log4j or Java Logging though. JBoss Logging is only an additional layer which allows to internationalize (i18n) the logging and exception messages as well as provinding unique ids for these messages. Under the hood JBoss Logging will use the logging framework of your choice to log the messages.

Hibernate Validator now requires a Java 6 runtime.

This release doesn’t introduce modifications which can break your existing code if you have already migrated to version 4.2.0.CR1. If you migrate from version 4.1.0.Final the following sections gives you the changes introduced in the different releases leading to this Final version.

As you already know Hibernate Validator allows the configuration of constraints programmatically. The main feature of this release is the programmatic API allowing constraint configuration on method (HV-431). To implement this in an unambiguous way we had to make yet some more changes to the programmatic API.

Another minor modification which can impact your existing code (if you migrate from Beta2) isHV-488. If you use the method metadata API you will see that the method ofMethodDescriptor namedgetParameterConstraints() was renamed togetParameterDescriptors() to avoid confusion.

The version Beta1 has introduced the possibility to specify constraints on methods. If you use this functionality the following changes will impact your code.

A big change introduced in this release isHV-421 which defines the behavior of parameter constraint validation. Generally a logical AND is used to combine all constraints defined within a class hierarchy on a given field or method. Doing the same for method parameter constraints, however, causes ambiguities with the definition of Programming by contract where subtypes may only weaken preconditions defined by supertypes. For this release we chose a conservative alternative which prohibit multiple parameter constraints on the same parameter within a class hierarchy.

Another minor modification is that the methodMethodValidator#validateParameters() (allowing to validate all parameters of a method) was renamed toMethodValidator#validateAllParameters() (HV-415).

BVTCK-12 resp.HV-395 required a change in thejavax.validation.Path implementation. Unless you iterate over thePath instance returned byConstraint.getPropertyPath() you are not affected by this change.

When creating own subclasses ofConstraintDef is it not necessary anymore to repeat the definitions of message, payload and groups.ConstraintDef uses now self-referential generic types.