We are excited to announce the release of Hibernate Validator 9.2.0.Final.
Compared to 9.2.0.CR2, this release updates Hibernate Accessor to 0.1.0. The 9.2 series adds password validation, new constraints for text and optional values, a bean resolution API for integrating application services, and configurable property access.
|
Many of the new constraints and extension points are incubating. We welcome feedback as you try them in your applications. |
What’s new since 9.1
Password validation
Hibernate Validator now provides three constraints for validating passwords:
@PasswordStrength, @NotCompromised and @PasswordPolicy.
All three support CharSequence and char[] values and consider null valid.
Use @NotNull to require a value or @NotBlank to require a nonblank CharSequence.
|
Passwords are sensitive data. You must handle them securely in your
Never log passwords or include them in validation messages, and never send
plaintext passwords or their complete hashes to external breach-checking services.
Minimize password copies and clear password Provide appropriate error handling and timeouts for external services. |
Strength and compromised passwords
@PasswordStrength checks a password against a minimum strength score,
while @NotCompromised checks whether it has appeared in a known data breach.
import jakarta.validation.constraints.NotBlank;
import org.hibernate.validator.constraints.NotCompromised;
import org.hibernate.validator.constraints.PasswordStrength;
class RegistrationForm {
@NotBlank
@PasswordStrength(min = 3) (1)
@NotCompromised (2)
private String password;
}
| 1 | Require a score of at least 3. The score scale depends on the strength estimator;
for an estimator using a scale of 0 to 4, this selects the upper part of that scale. |
| 2 | Reject passwords that the configured checker identifies as compromised. |
Applications supply implementations of PasswordStrengthEstimator and CompromisedPasswordChecker,
allowing them to choose a strength estimation library and a breach data source.
Both services receive the password as a char[].
For example, an adapter for the com.nulabinc.zxcvbn library can return its score and warning:
import com.nulabinc.zxcvbn.Strength;
import com.nulabinc.zxcvbn.Zxcvbn;
import org.hibernate.validator.spi.password.PasswordStrengthEstimator;
import org.hibernate.validator.spi.password.PasswordStrengthResult;
public class ZxcvbnPasswordStrengthEstimator implements PasswordStrengthEstimator {
private final Zxcvbn zxcvbn = new Zxcvbn();
@Override
public PasswordStrengthResult estimate(char[] password) {
Strength strength = zxcvbn.measure( new String( password ) );
String warning = strength.getFeedback() == null
? null : strength.getFeedback().getWarning();
return PasswordStrengthResult.simple( strength.getScore(), warning );
}
}
Register the services using the new bean configuration API:
import jakarta.validation.Validation;
import jakarta.validation.ValidatorFactory;
import org.hibernate.validator.HibernateValidator;
import org.hibernate.validator.bean.BeanReference;
import org.hibernate.validator.spi.password.CompromisedPasswordChecker;
import org.hibernate.validator.spi.password.PasswordStrengthEstimator;
ValidatorFactory createValidatorFactory(CompromisedPasswordChecker breachChecker) {
return Validation.byProvider( HibernateValidator.class )
.configure()
.addBeanConfigurer( context -> {
context.define( PasswordStrengthEstimator.class,
BeanReference.ofInstance( new ZxcvbnPasswordStrengthEstimator() ) );
context.define( CompromisedPasswordChecker.class,
BeanReference.ofInstance( breachChecker ) );
} )
.buildValidatorFactory();
}
Here, breachChecker is an application-provided implementation backed by the chosen breach data source.
The reference guide
includes example adapters for strength estimation and compromised password checking.
Reusable password policies
@PasswordPolicy brings multiple rules together in a reusable PasswordPolicyDefinition.
The builder supports length limits, character requirements, whitespace checks,
repeating characters, sequences, keyboard walks, strength estimation, compromised
password checks and custom rules.
For example, an application with specific password composition requirements can express them as follows:
import jakarta.validation.constraints.NotNull;
import org.hibernate.validator.constraints.PasswordPolicy;
import org.hibernate.validator.constraintvalidation.HibernateConstraintValidatorInitializationContext;
import org.hibernate.validator.spi.password.CharacterType;
import org.hibernate.validator.spi.password.PasswordPolicyBuilder;
import org.hibernate.validator.spi.password.PasswordPolicyDefinition;
public class AccountPasswordPolicy implements PasswordPolicyDefinition {
@Override
public void configure(PasswordPolicyBuilder builder,
HibernateConstraintValidatorInitializationContext context) {
builder.minLength( 12 )
.requireCharacters( CharacterType.UPPERCASE, 1 )
.requireCharacters( CharacterType.DIGIT, 1 )
.noWhitespace();
}
}
class Account {
@NotNull
@PasswordPolicy(AccountPasswordPolicy.class)
private char[] password;
}
Each failing rule produces its own constraint violation.
For the policy above, short fails the minimum length, uppercase and digit rules,
so validation reports three violations instead of a single generic policy failure.
Policy classes with a public no-argument constructor can be instantiated automatically.
Policies can also resolve application services through the initialization context. For example, the following configuration combines a length rule with the same strength estimator and breach checker registered above:
configure() methodvar resolver = context.getBeanResolver();
builder.minLength( 12 )
.strengthEstimator( 3, resolver.resolve(
PasswordStrengthEstimator.class,
org.hibernate.validator.bean.BeanRetrieval.ANY ).get() )
.compromisedChecker( resolver.resolve(
CompromisedPasswordChecker.class,
org.hibernate.validator.bean.BeanRetrieval.ANY ).get() );
For application-specific checks, use addRule(message, predicate) or implement PasswordPolicyRule.
Policies can also be applied to custom types through AbstractPasswordPolicyValidator,
allowing rules to access additional properties, such as a username.
See the password policy documentation
for further examples.
Constraints for optional values
@NullOrNotBlank and @NullOrNotEmpty are alternatives to @NotBlank and @NotEmpty
when an absent value is allowed but an empty value is not.
They are particularly useful with Optional:
class Profile {
Optional<@NullOrNotBlank String> displayName;
Optional<@NullOrNotEmpty List<String>> interests;
}
An empty Optional is valid. A present display name must contain a non-whitespace character,
and a present list of interests must contain at least one element.
These constraints can also be applied directly to nullable properties.
Text and date/time constraints
@Contains checks for specified substrings. By default, all substrings must be present.
minRequired changes this to a minimum number of matches.
@DateTimeFormat validates date and time strings using DateTimeFormatter patterns,
including localized month or day names.
class Submission {
@Contains(value = { "Hibernate", "Jakarta" },
minRequired = 1, ignoreCase = true) (1)
String description;
@DateTimeFormat(pattern = "dd MMMM uuuu",
locale = { "en-US", "fr-FR" }) (2)
String publicationDate;
}
| 1 | Accept descriptions containing either Hibernate or Jakarta, ignoring case. |
| 2 | Accept dates such as 13 October 2026 or 13 octobre 2026.
Parsing is strict by default, so invalid calendar dates are rejected. |
The release also adds these text constraints.
-
@Alphabeticchecks that every character is a letter. -
@Alphanumericchecks that every character is a letter or a digit. -
@Numericchecks that every character is a decimal digit in the Basic Multilingual Plane, including digits outside ASCII. -
@Encodingchecks whether text can be encoded in a specified character set. For example,@Encoding(charset = "US-ASCII")checks text before export to a system that expects ASCII. -
@StartsWithand@EndsWithrequire one of the specified prefixes or suffixes, with optional case-insensitive matching. -
@UpperCaseand@LowerCasecheck the case of letters, ignoring non-letter characters. -
@Trimmedrejects leading or trailing whitespace, using the same whitespace definition asString.strip(). -
@Hexadecimalvalidates hexadecimal text, with options for letter case, fullwidth characters, empty values and a required prefix.
Network and identifier constraints
-
@Portvalidates numeric values or strings representing a port between0and65535, inclusive. -
@IBANvalidates International Bank Account Numbers, including country-specific lengths and check digits. -
@BICvalidates Bank Identifier Codes (SWIFT codes). -
@ISSNvalidates International Standard Serial Numbers. -
@CUITvalidates Argentine tax identification codes. -
@CUILvalidates Argentine labor identification codes. -
@RUCvalidates Paraguayan taxpayer registration numbers. -
@RENAVAMvalidates Brazilian vehicle registration numbers in their current or legacy representation.
See the reference guide for supported types and programmatic constraint definitions.
Bean resolution and dependency injection
Applications can register services by type and optionally by name through a BeanConfigurer.
Custom constraint validators can resolve those services through
HibernateConstraintValidatorInitializationContext#getBeanResolver().
Framework integrations can supply a BeanProvider, and the hibernate-validator-cdi extension
provides a CDI-backed provider.
See the bean resolution documentation for registration and lookup examples.
Configurable property access
Hibernate Validator uses Hibernate Accessor to read bean properties during validation. On JDK 24 and later, it defaults to generating accessors using the Class-File API. On earlier JDKs, it defaults to reflection. You can also select an accessor factory explicitly, including the optional ASM and ByteBuddy implementations.
See the reference guide for configuration examples.
Other improvements and bug fixes
-
HV-2291 automatically includes types with programmatic constraint mappings in the predefined scope validator factory.
-
HV-2280 resolves programmatic getter mappings when the validator factory is built, using that factory’s getter selection strategy and property node name provider.
-
HV-2283 adds support for accessing record components in Jakarta Expression Language message expressions.
-
HV-1316 checks property paths passed to
validateProperty()andvalidateValue()even when the bean has no constraints. -
Performance improvements include reusing constraint validator contexts, reducing interface constraint tracking overhead, and parsing property paths in a single pass.
For the full list of changes, see the release notes for 9.2.0.Final, 9.2.0.CR2, 9.2.0.CR1, and 9.2.0.Beta1.
How to get this release
Hibernate Validator 9 targets Jakarta EE 11.
The Maven coordinates for this release are org.hibernate.validator:hibernate-validator:9.2.0.Final.
More details are available on the
dedicated page on hibernate.org.
Getting started, migrating
For new applications, see the getting started guide.
When upgrading from 9.1, review the
migration guide.
It covers changes to PropertyNodeNameProvider, property path validation, programmatic mappings,
built-in constraint composition, message parameter escaping, and @CPF formatting.
If you manage your runtime class path manually, add the new core dependency
org.hibernate.accessor:hibernate-accessor.
Feedback, issues, ideas?
To get in touch, use the usual channels:
-
hibernate-validator tag on Stack Overflow (usage questions)
-
User forum (usage questions, general feedback)
-
Issue tracker (bug reports, feature requests)
-
Mailing list (development-related discussions)
-
Jakarta Validation development mailing list (discussions about the Jakarta Validation specification)