Bean Validation in Jakarta Faces

Faces has had its own validation model since 1.0: required="true", the standard validator tags f:validateLength, f:validateLongRange, f:validateRegex and friends, custom Validator classes, and validator methods. Those rules live on the page. That works for a single form and degrades as the application grows, because the same rule ("a rating is a whole number from 1 to 5") is then repeated in every view that edits a review, again in the REST resource that accepts one, and again in the persistence layer. The specification states the goal plainly: Bean Validation avoids that duplication by defining metadata that can be shared by any layer of the application, and Faces delegates field-level validation to it so that the page author does not have to write a validator per input.

There are three parts to the integration, and the rest of this page takes them in turn:

The two systems are complementary rather than competing. The standard Faces validators remain the right tool for rules that belong to one page only, for conversion-adjacent checks, and for required with a page-specific message. The validators page of this section covers them, the converters page covers the step that runs before validation, and the core tags page lists f:validateBean and f:validateWholeBean beside the other f: tags.

Faces does not ship Bean Validation. It looks for a Jakarta Validation provider on the class path and, if there is none, the integration is simply off. The specification’s activation rule has three parts:

On a Jakarta EE server (WildFly, GlassFish, Payara, Open Liberty, TomEE; none of them was run for this page, the statement follows the platform specification) the container supplies the Validation API, a provider, an Expression Language implementation and the ValidatorFactory attribute, so the application declares nothing. On Tomcat, or any plain servlet container, the application brings the provider. The Maven coordinates used for the scratch Bookshelf (a WAR whose Faces implementation, Weld and the provider are all packaged in WEB-INF/lib):

Source: Hibernate Validator 9.1 reference guide, Getting started and Jakarta Faces 4.1 specification, 3.5.6 Bean Validation Integration

Hibernate Validator needs an implementation of Jakarta Expression Language to evaluate expressions in violation messages. A server provides one, and Tomcat includes its own, so nothing is added in the example above. In a unit test that runs outside any container the test needs one (org.glassfish.expressly:expressly:6.0.0 in the test scope, the artifact the Hibernate Validator guide names), and for environments that cannot provide one at all the guide describes a non-compliant ParameterMessageInterpolator that handles only {...} parameters.

Two context parameters control the automatic installation:

A <default-validators> element in faces-config.xml can also list validator ids, and a configuration resource that declares the list overrides one from a previously processed resource. The jakarta.faces.Bean id is guaranteed to be in the result of Application.getDefaultValidatorInfo() regardless of that configuration unless DISABLE_DEFAULT_BEAN_VALIDATOR is true.

Source: Jakarta Faces 4.1 specification, 11.1.3 Application Configuration Parameters and 3.5 Validation Model

With DISABLE_DEFAULT_BEAN_VALIDATOR set to true, an input bound to a constrained property was no longer validated, while the same input with <f:validateBean/> nested inside it was. This is the escape hatch for an application that wants Bean Validation only on a few forms.

Constraints are annotations on a field, a getter or a type. The built-in ones live in the package jakarta.validation.constraints:

Every built-in constraint takes message, groups and payload, and every one is repeatable. Almost all of them treat null as valid, so that "the value is optional" and "the value, if present, has this shape" can be expressed separately. Presence is the job of @NotNull, @NotEmpty or @NotBlank, which is the single most important thing to remember when reading the rest of this page.

The Bookshelf review form edits a Review. It is an ordinary class, free of any Faces API:

Source: Jakarta EE Tutorial: Introduction to Jakarta Bean Validation

@Isbn and Publish are defined in Custom Constraints and Messages and Validation Groups and f:validateBean. The view binds each input to a property of that object. Note that nothing in the XHTML mentions Bean Validation:

Source: Jakarta EE Tutorial: Using the Standard Validators and Jakarta Faces 4.1 specification, 3.5.6 Bean Validation Integration

Submitting the form with an empty reviewer, a rating of 7, an ISBN of 123 and a future date produced, next to the respective inputs:

The save() action did not run and the bean was not changed. That is the behavior of every validator in Faces and the subject of the next section.

Bean Validation is a Faces validator, so it runs where every validator runs: in the Process Validations phase, on each input component of the submitted components in the order they appear in the tree. The sequence for one input is shown below, and the lifecycle page of this section places it among the six phases (see Process Validations there).

Four observations follow from the diagram, and each was confirmed on Mojarra and MyFaces:

Source: Jakarta EE Tutorial: The Lifecycle of a Jakarta Faces Application and Jakarta Faces 4.1 specification, 2.2 Standard Request Processing Lifecycle Phases

A text field that the user leaves empty is submitted as the empty string. Two context parameters decide what the validation machinery does with it, and getting them wrong is the commonest reason a @NotNull seems to be ignored.

The two interact with the constraints in a way that surprises people. The table shows what a blank title produced with @NotNull @Size(min = 3) on the property, on Mojarra 4.1.17 (the same on MyFaces 4.1.4):

The third row is the dangerous one: false is a configuration that was needed to keep old validators from receiving empty values, but it also switches off every @NotNull, @NotEmpty and @NotBlank in the application. Leave the parameter alone unless an existing validator cannot cope.

The validators page shows the same two parameters with the standard validator tags. The practical rule is to pick one convention and write constraints that match it:

Source: Jakarta EE Tutorial: Validating Null and Empty Strings and Jakarta Faces 4.1 specification, 11.1.3 Application Configuration Parameters

Numeric and date inputs behave differently from text. An empty Integer field is converted to null by the standard converter, so @NotNull on rating rejected it (must not be null) under the defaults. The parameter matters for String properties.

A validation group is an interface that tags constraints so that a validation call can select a subset of them. A constraint without groups belongs to the built-in group jakarta.validation.groups.Default. Groups answer questions the single-set model cannot, such as "a draft may be saved with an empty comment, but a published review needs one":

Source: Jakarta Validation 3.1 specification, Groups

Review.comment above carries @NotBlank(groups = Publish.class, ...). By default Faces validates the Default group only, so this constraint is dormant. f:validateBean chooses the groups for the inputs it applies to. Its attributes come from the VDL:

The tag works in two ways. Nested in one input, it applies to that input only. Wrapped around several inputs, it sets a branch default for every input inside it. The validation groups come from the nearest enclosing f:validateBean that has a value, and if there is none, the Default group is used. A page that edits a review in "publish" mode therefore wraps its inputs once instead of nesting a tag in each:

Source: Jakarta Faces 4.1 VDL, f:validateBean and BeanValidator API

The observed behaviors of this branch, with reviewer empty, rating 9 and comment empty:

Two consequences of the table. The group list replaces the default, it does not add to it, so a branch that lists only Publish stops validating the Default constraints; add jakarta.validation.groups.Default explicitly when you want both. And a group name is a class name, so a typo is an exception at the first submit, not a silently ignored rule. A @GroupSequence on a group interface, described in the Validation specification, orders groups so that expensive checks run only after cheap ones pass, and is selected through the same attribute.

The disabled attribute switches the validator off for the input or the branch it applies to. It takes a boolean or an EL expression. Two cases are worth knowing.

A form that edits only part of an object needs no disabled at all. Constraints are evaluated property by property for the inputs that are actually in the submitted form, never on the whole object, so a "quick rating" widget that binds only rating is not blocked by a missing title. This is a difference from calling Validator.validate(review) yourself, which checks every property.

Source: Jakarta Faces 4.1 VDL, f:validateBean

Field-level validation cannot express a rule over several properties. The specification explains why: Faces conversion and validation finish for every input before any value is pushed into the model, so at validation time the bean still holds the old values, and a constraint on the class would see yesterday’s data. Faces 2.3 added f:validateWholeBean for this case. It is activated by jakarta.faces.validator.ENABLE_VALIDATE_WHOLE_BEAN, which is false by default; with the parameter unset the tag is a no-op. The scratch Bookshelf confirms it: an invalid period was accepted when the parameter was missing and rejected when it was true.

The mechanism, from the VDL:

A class-level constraint is an annotation on the type plus a ConstraintValidator for it. The Bookshelf borrow form asks for a pick-up and a return date and requires the second to come after the first:

Source: Jakarta Faces 4.1 VDL, f:validateWholeBean

PeriodChecks is an empty marker interface like Publish. Notice that every constraint carries the group, and that isValid tests for null and treats a missing value as valid, because a missing value is the job of the @NotNull constraints. When f:validateWholeBean calls the validator, the specification guarantees that the individual properties have already passed, so the guard is never needed there; but other callers give no such guarantee. Anyone who calls Validator.validate(request) in the PeriodChecks group directly gets the validator called with whatever the object holds, and the same goes for the class-level check of OmniFaces o:validateBean (see the OmniFaces page): an earlier version of this listing without the guard failed with an HTTP 500 under o:validateBean in a scratch run made while writing that page (not repeated here). The guarded listing above was compiled with Hibernate Validator 9.1.4 and run directly: an empty request produced only the two @NotNull violations, a return date before the pick-up date produced The return date must be after the pick-up date, and a valid period produced none.

The view uses the group on each contributing input and on the tag. The VDL states that the groups attribute is required on f:validateWholeBean and that the feature requires it on the f:validateBean tags too:

Source: Jakarta Faces 4.1 VDL, f:validateWholeBean and Jakarta Faces 4.1 specification, 3.5.6.3 Class-Level Validation

With a pick-up of 2026-10-10 and a return of 2026-10-09 the request produced The return date must be after the pick-up date, attached to the period component. With the pick-up empty the result was From: must not be null only: the class-level check was skipped because a contributing field was invalid, as specified. With 2026-10-01 and 2026-10-09 the action ran.

The rules of the tag, each one a way the feature can fail:

The built-in annotations cover generic shapes. A domain rule, such as "this is a valid ISBN-13", is a custom constraint: an annotation plus a ConstraintValidator. The annotation must declare the three standard elements message, groups and payload:

Source: Jakarta EE Tutorial: Bean Validation: Advanced Topics and Jakarta Validation 3.1 specification, Constraint definition

Four rules make validators well-behaved:

A new constraint can also be composed from existing ones, with @Constraint(validatedBy = {}) and the building-block annotations on it, as in the tutorial’s @USPhoneNumber, which applies a @Pattern. A composed constraint needs no validator class.

Messages use two forms of interpolation: {key} looks up a bundle entry or an annotation attribute ({min}), and ${...} evaluates a Jakarta Expression Language expression, such as ${validatedValue} for the offending value.

A validator often needs a service: "this ISBN exists in the catalogue", "this username is free". The natural code injects it:

Source: Jakarta Validation 3.1 specification, Jakarta Context and Dependency Injection integration

@KnownIsbn is declared like @Isbn. On a Jakarta EE server it works as written, because the specification requires a Jakarta EE container’s Validation provider to integrate with CDI, so the ValidatorFactory is CDI-aware and validators are created through the bean manager. On Tomcat with Weld it does not: Faces asks for Validation.buildDefaultValidatorFactory(), which knows nothing about the bean manager, and the field stays null. The scratch run on Tomcat 11.0.26, Weld 6.0.4.Final, Mojarra 4.1.17 and Hibernate Validator 9.1.4.Final produced an HTTP 500 with NullPointerException: Cannot invoke "...Catalogue.contains(String)" because "this.catalogue" is null. Adding hibernate-validator-cdi to the class path by itself did not change that, because Faces still built its own default factory. The fix that worked is to give Faces the CDI-aware factory under the documented servlet context attribute, from a listener (Providing Your Own ValidatorFactory).

The ValidatorFactory that Faces uses is read from the servlet context attribute BeanValidator.VALIDATOR_FACTORY_KEY. Anything stored there wins over the default bootstrap, which makes it the extension point for a custom message interpolator, a custom ConstraintValidatorFactory, a configured clock or a ParameterMessageInterpolator. With hibernate-validator-cdi on the class path the extension registers a CDI-aware ValidatorFactory bean, which a @WebListener can inject (Weld on Tomcat supports injection in listeners) and publish:

With this listener the reservation form accepted 978-0-306-40615-7 (Reserved 978-0-306-40615-7) and rejected 978-1-4028-9462-6 with This ISBN is not in the catalogue, on Mojarra and on MyFaces. The same effect without the extra dependency was obtained by building the factory by hand with Validation.byDefaultProvider().configure().constraintValidatorFactory(...), where the factory creates each validator through BeanManager.getInjectionTargetFactory(...) (produce, inject, postConstruct) and releases it with preDestroy and dispose, which is the sequence the Validation specification prescribes. The provider owns the factory’s life cycle, so the injected variant needs no contextDestroyed; a hand-built factory should be closed there.

Source: Jakarta Validation 3.1 specification, Jakarta Context and Dependency Injection integration, Hibernate Validator 9.1 reference guide, CDI and Jakarta Faces 4.1 specification, 3.5.6.2 Obtaining a ValidatorFactory

Each ConstraintViolation becomes a FacesMessage whose summary and detail are both the violation’s interpolated message, and the whole set is carried by one ValidatorException. Three things shape what the user reads.

The message format. The text goes through the Faces message jakarta.faces.validator.BeanValidator.MESSAGE (BeanValidator.MESSAGE_ID). It has two placeholders: {0} is the interpolated Validation message and {1} is the label of the input. The default format is just {0}, so by default the Validation provider’s wording is shown untouched. An application that wants the label in front of every message, in line with the standard Faces messages that say Rating: Validation Error: ..., overrides it in a message bundle registered with <message-bundle>:

Source: Jakarta EE Tutorial: Registering Application Messages and BeanValidator API, MESSAGE_ID

With that bundle, the messages read Reviewer: must not be blank and Rating: must be less than or equal to 5, using the label attribute of each input. An input without a label shows its client id instead (f:rating: must be less than or equal to 5 in the scratch run), so give every input a label when you use {1}. Faces' own messages for conversion and required are separate keys in the same bundle. The messages and internationalization page lists the standard keys and builds the English and Spanish bundles.

Several violations on one input. The component receives all of them. h:message renders only the first one for a component, as its documentation says, while h:messages lists every one. An ISBN that was both malformed and unknown to the catalogue showed This ISBN is not in the catalogue in h:message and both lines in h:messages. The order of the violations is not specified by Validation, so do not write a page that depends on it.

Locale. The specification asks Faces to give the provider a message interpolator that resolves the Locale from the current UIViewRoot, and the BeanValidator does so (it decorates the factory’s interpolator). The messages therefore follow f:view locale or the browser’s negotiated locale, not the JVM default:

Source: Jakarta Faces 4.1 specification, 3.5.6.4 Localization of Bean Validation Messages

With ?lang=es the rating message came back as Rating: debe ser menor que o igual a 5, and the custom @Isbn message came from ValidationMessages_es.properties. One trap in the scratch run is a plain Java one: on a machine whose JVM default locale was Spanish, a request in English found no ValidationMessages_en.properties and the resource bundle lookup fell back to the JVM default locale (ValidationMessages_es) before the base file, so an English view showed the Spanish @Isbn text. Java’s ResourceBundle consults the default locale before the root bundle. Ship an explicit file for every locale you support, including the one in the base file (ValidationMessages_en.properties next to the unsuffixed one), or pin the default locale on servers.

Escaping and sensitive values. The message may contain the rejected value through ${validatedValue}. Faces escapes message text when h:message renders it: an ISBN of <script>alert(1)</script> came out as <script>... in the page (output escaping in general is on the security page). The risk lies in rendering messages with something that does not escape, such as a component or a custom renderer with escaping disabled, or in logging the message. Never echo the value of a password, token or card-number field in a message, and never use escape="false" on a component that renders messages built from user input.

Nothing about Bean Validation changes under f:ajax (see the Ajax page for execute and render): the Ajax request runs the same six phases on the components in its execute list, and the validators run in Process Validations. The scope of execute decides which constraints are evaluated. An input with <f:ajax event="blur" render="m_rating"/> has the default execute="@this", so a blur validates that single input and renders its message, and a button with <f:ajax execute="@form" render="panel"/> validates the whole form.

Source: Jakarta EE Tutorial: Using Ajax with Jakarta Faces Technology

Replaying both requests against Mojarra, the blur request returned a partial response whose update for f:m_rating was Rating: must be less than or equal to 5, and the save request re-rendered the panel with the same message. Three details matter in practice. The message component must be inside the render list, or the user sees nothing change. A message for an input that is not in execute is not produced, so a blur on field A never reports a problem with field B. And an invalid field in an Ajax submit skips the action exactly as in a full submit, which is why the Save button above shows messages and does not call save().

Validation in the web tier protects the user experience, not the data. A REST call, a batch job, a test or a future screen reaches the same model without a Faces form in front of it. The constraints on the model are the common ground, and Jakarta Validation offers two more places to enforce them.

A Faces form that catches ConstraintViolationException from the service and shows it is the right fallback for the cases the page-level constraints cannot see, such as a rule that depends on other rows. The rule of thumb is to keep the constraints on the model, let Faces enforce the field-level ones through the default validator, and let the service enforce the rest.

A constraint is plain Java and needs no container to test; the testing page covers the wider test strategy (constraints, converters, validators and the form itself). Build a Validator, validate an object and assert on the violations. Assert on the message template rather than the interpolated text: the text depends on the default locale of the machine running the build (a test that compared must be less than or equal to 5 failed on a Spanish-locale workstation in the scratch run).

The test needs junit-jupiter in the test scope and an Expression Language implementation, for instance org.glassfish.expressly:expressly:6.0.0 (the @Isbn message uses ${validatedValue}). All four tests passed. The validator under test is the very one that Faces uses, so a constraint that passes this test but fails in the form points at the form (the property path, a converter, a group) and not at the rule. A constraint on a validator that injects a CDI bean is tested with a stubbed field or with the validator’s constructor, since no container provides the injection in a plain test.

Source: Hibernate Validator 9.1 reference guide

The specification fixes the contract, and the scratch application was run on both implementations for the scenarios in this page. The results were the same for the default validator, the labelled message format, the Default and Publish groups, branch disabled, the validationGroups short-name failure (HTTP 500 with a FacesException on both), f:validateWholeBean including the non-copyable and the placed-before-the-inputs failures, the CDI-injected validator, and the localized messages. Mojarra and MyFaces differ in the following small respects only:

Anything that depends on the wording of a Faces-generated message (the Validation Error: Value is required. text, the converter message) belongs to the implementation’s message bundle, not to Bean Validation, and is overridden through the <message-bundle> mechanism on both.

Source: Jakarta Validation 3.1 specification, What’s new and BeanValidator API

The older Faces books cover validation in the JSF 2.0 era, and the concepts they teach (that conversion precedes validation, that validators queue messages and short-circuit the lifecycle, that custom validators are classes or methods) still hold. Compared with the current specification:

These statements about the books rest on the scope and edition data recorded for the section’s bibliography and on the official specifications; the books themselves were consulted only for coverage. The official documentation wins on any point where they differ.

Source: Ed Burns, Chris Schalk and Neil Griffin, JavaServer Faces 2.0: The Complete Reference (McGraw-Hill, 2010, ISBN 978-0-07-162509-8) and Anghel Leonard, JSF 2.0 Cookbook (Packt, 2010, ISBN 978-1-847199-52-2), with the Jakarta Validation 3.1 specification