Introduction

The aim of this guide is to assist you migrating an existing application using any version 9.0.x of Hibernate Validator to the latest of the 9.1.x series.

If you think something is missing or something does not work, please contact us.

If you’re looking to migrate from an earlier version, you should migrate step-by-step, from one minor version to the next, following the migration guide of each version.

As this release includes significant changes to the processed bean tracking, path implementation and related areas, we encourage users to give it a try and report any findings, especially if there are non-trivial validation scenarios.

Requirements

The requirements of Hibernate Validator 9.1 are the same as those of Hibernate Validator 9.0.

Artifacts

The coordinates of Maven artifacts in Hibernate Validator 9.1 are the same as in Hibernate Validator 9.0.

Configuration

The configuration properties in Hibernate Validator 9.1, in general, are backward-compatible with Hibernate Validator 9.0.

API

The API in Hibernate Validator 9.1 is, in general, backward-compatible with Hibernate Validator 9.0.

SPI

The SPI in Hibernate Validator 9.1 is, in general, backward-compatible with Hibernate Validator 9.0.

Behavior

The behavior of Hibernate Validator 9.1 is, in general, backward-compatible with Hibernate Validator 9.0.

Keep in mind that the internal representation of the Path and Node became mutable during validation process, so do not rely on these being immutable in your traversable resolvers. The Path and Node representations within the ConstraintViolation remains immutable.

Message parameter escaping enabled by default

Message parameters added via HibernateConstraintValidatorContext#addMessageParameter() are now escaped by default. Characters with special meaning in message interpolation (\, {, }, $) are automatically escaped to prevent injection into message interpolation expressions.

If your custom constraint validators rely on message parameters containing unescaped interpolation expressions (e.g. nested {paramName} references or ${expression} EL expressions), you can either:

  • Use the new overload addMessageParameter(String name, Object value, MessageParameterEscaping.NONE) to disable escaping per call. This is a recommended alternative, but only for the parameter values that you trust.

  • Set the hibernate.validator.message_parameter_escaping property to none to restore the previous behavior globally. Only consider this option if none of the validators add user input as parameters.