Hibernate Validator is the reference implementation for the Bean Validation specification. For more information, see Hibernate Validator on hibernate.org.

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 PasswordStrengthEstimator, CompromisedPasswordChecker and custom PasswordPolicyRule implementations.

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 char[] arrays when they are no longer needed. Copies held in String instances cannot be cleared.

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.

Example 1. Applying password constraints
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:

Example 2. Adapting a password strength estimator
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:

Example 3. Registering application-provided password services
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:

Example 4. Defining and applying a password policy
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:

Example 5. Using application services in a policy’s configure() method
var 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:

Example 6. Validating optional values
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.

Example 7. Validating text and localized dates
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.

  • @Alphabetic checks that every character is a letter.

  • @Alphanumeric checks that every character is a letter or a digit.

  • @Numeric checks that every character is a decimal digit in the Basic Multilingual Plane, including digits outside ASCII.

  • @Encoding checks 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.

  • @StartsWith and @EndsWith require one of the specified prefixes or suffixes, with optional case-insensitive matching.

  • @UpperCase and @LowerCase check the case of letters, ignoring non-letter characters.

  • @Trimmed rejects leading or trailing whitespace, using the same whitespace definition as String.strip().

  • @Hexadecimal validates hexadecimal text, with options for letter case, fullwidth characters, empty values and a required prefix.

Network and identifier constraints

  • @Port validates numeric values or strings representing a port between 0 and 65535, inclusive.

  • @IBAN validates International Bank Account Numbers, including country-specific lengths and check digits.

  • @BIC validates Bank Identifier Codes (SWIFT codes).

  • @ISSN validates International Standard Serial Numbers.

  • @CUIT validates Argentine tax identification codes.

  • @CUIL validates Argentine labor identification codes.

  • @RUC validates Paraguayan taxpayer registration numbers.

  • @RENAVAM validates 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() and validateValue() 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:


Back to top