Bean Validation 2.0 is a spec!

by Gunnar Morling on 07 Aug 2017 release

It is done — after one year of hard work, and a bit more than four years after the previous revision, the final release of Bean Validation 2.0 (JSR 380) is out!

Last week, the JSR passed the Final Approval Ballot by the executive committee of the JCP unanimously with 25 "Yes" votes. After the ballot we’ve released version 2.0.0.Final of the specification, the API as well as the TCK. At the same time, the final version of the reference implementation, Hibernate Validator 6, was released, too.

Within the next few days, the final specification will also be available on the JSR 380 page on jcp.org, after which the work on this JSR is complete and the expert group officially will disband.

What’s new in Bean Validation 2.0?

By now, you’ll probably have heard about all the new features added in Bean Validation 2.0. Just in case you haven’t, here’s a quick summary:

  • Support for validating container elements by annotating type arguments of parameterized types, e.g. List<@Positive Integer> positiveNumbers; this also includes:

    • More flexible cascaded validation of collection types; e.g. values and keys of maps can be validated now: Map<@Valid CustomerType, @Valid Customer> customersByType

    • Support for java.util.Optional

    • Support for the property types declared by JavaFX

    • Support for custom container types by plugging in additional value extractors

  • Support for the JSR 310 date/time types for @Past and @Future; fine-grained control over the current time and time zone used for validation

  • New built-in constraints: @Email, @NotEmpty, @NotBlank, @Positive, @PositiveOrZero, @Negative, @NegativeOrZero, @PastOrPresent and @FutureOrPresent

  • All built-in constraints are marked as repeatable

  • Parameter names are retrieved using reflection

  • ConstraintValidator#initialize() is a default method

Bean Validation 2.0 will also be part of the Java EE 8 platform, to be released later this summer.

To learn more about all the new features in Bean Validation 2.0, check out this presentation which I recently gave at the jdk.io conference.

Thank you!

I’d like to shout out a huge "Thank you" to everyone helping with the work on Bean Validation 2.0:

  • The fantastic JSR 380 expert group (thanks to Christian, Hendrik, Marco, Otavio and everyone else for their great input, proposals and much more) as well as the BV community at large (thanks to Hardy, Matt and everyone else for making themselves heard and providing feedback)

  • The former spec lead Emmanuel for his continued support with everything JCP-related and going through the details of container element validation again and again

  • My dear fellow Guillaume for his tireless work on the TCK, the reference implementation, the website and the spec; merci beaucoup!

  • Marko Bekhta who stepped up to work on the TCK which has been a very much appreciated contribution

  • Everyone participating in our polls and surveys; your replies and comments helped very much to arrive on good decisions on the different options on the table

  • The friendly folks of Oracle’s GlassFish team for all their work on integrating Bean Validation 2.0 into the Java EE 8 reference implementation

It has been a true pleasure and honor for me to make the new spec a reality together with such a fantastic community!

Give it a try

Don’t wait and try out the new release yourself! Just download the reference implementation Hibernate Validator and read the Getting started section of its reference guide. You also can read the complete specification as well as the API docs.

Comments

Bean Validation 2.0 CR 3 released and submitted to Final Approval Ballot

by Gunnar Morling on 12 Jul 2017 release

It’s my great pleasure to announce the CR 3 release of the Bean Validation 2.0 spec!

This release of the spec and the API as well as accompanying releases of the TCK and the reference implementation (release announcement) have been handed over to the JCP for the Final Approval Ballot last night. It’s this ballot where the Executive Committee of the JCP will cast its final go/no-go vote on the Bean Validation 2.0 JSR.

Since the CR 2 release, only a few things have changed after reviewing the spec changes one more time:

  • Clarifying the semantics of ConstraintViolation#getLeafBean() in case a container element constraint is violated (BVAL-690)

  • Making the order of the <container-element-type> and <constraint> elements consistent in the schema for XML constraint mapping files (BVAL-693)

  • Minor wording and JavaDoc improvements (BVAL-692)

The updated spec document can be found here. To see the changes applied since the CR 2, check out this colored diff. If you’d like to see all the changes since Bean Validation 1.1, take a look at this diff. The updated API is available on Maven Central, using the GAV coordinates are javax.validation:validation-api:2.0.0.CR3.

Some TCK stats

Thanks to Guillaume’s tireless work, the Bean Validation TCK has grown substantially since 1.1. There are now 685 assertions overall, out of which 627 are testable. 99.04% of them are covered by 2133 tests overall. The added tests cover all the new Bean Validation 2.0 features, so we feel very confident that the TCK ensures correctness of implementations passing it.

Also the tooling for producing the TCK has been improved significantly: sentences or phrases of the spec document can be marked as relevant for the TCK with the help of AsciiDoc roles. A special Maven plug-in then is used to generate a report of all those marked assertions, allowing to link them to tests of the TCK and making it easy to identify assertions without corresponding tests yet.

We’ll discuss the entire TCK tool chain in more depth in a separate blog post. If you are interested in the TCK and would like to learn more about its development, the appeals process and other related things, check out the TCK reference guide.

What’s new in Bean Validation 2.0?

The focus of Bean Validation 2.0 is supporting and taking advantage of Java SE 8.

For instance type annotations are used to validate the elements of generic containers: List<@NotNull @Email String> emails. There are new built-in constraints (@NotBlank, @NotEmpty, @Email, @FutureOrPresent, @PastOrPresent, @Positive, @PositiveOrZero, @Negative and @NegativeOrZero) and all built-in constraints are repeatable annotations now. Bean Validation 2.0 also supports the new Java 8 date and time types (JSR 310), the property types defined by JavaFX (StringProperty etc.) as well as java.util.Optional.

To learn more about all the new features in Bean Validation 2.0, check out this presentation which I recently gave at the jdk.io conference.

What can you do to help?

With the submission of the specification to the JCP for the Final Approval Ballot, the work on Bean Validation 2.0 is done more or less. If you’d like to help, reviewing the specification changes would be the best thing to do at this point. You also could try out the reference implementation Hibernate Validator in your applications and let us know how it works.

Also tell us about ideas and wishes for a future 2.1 release of the spec. We are eager to learn about your requirements, so we can explore any new features in the reference implementation.

To post your feedback, just add a comment below, send a message to our mailing list or post in the Bean Validation forum. If you find a bug or have a specific feature request, please raise it in the issue tracker.

Everything in Bean Validation is open source, so you also can send in actual patches: be it to the API, the spec document, the TCK or the reference implementation. If you are interested, you can find out all the details to get started in the contribution guide.

Comments

Bean Validation 2.0 CR 2 released

by Gunnar Morling on 05 Jul 2017 release

I’m very happy to announce the CR 2 release of the Bean Validation 2.0 spec!

The CR 2 is an update to the Proposed Final Draft (CR 1), addressing remarks and comments from reviewing all the changes. The updated spec document can be found here. To see the changes applied since the CR 1, check out this colored diff. If you’d like to see all the changes since Bean Validation 1.1, take a look at this diff. The updated API is available on Maven Central, using the GAV coordinates are javax.validation:validation-api:2.0.0.CR2.

What’s new since CR 1?

Given we are in the CR phase, most of the changes of this release naturally fall into the category of bug fixes, wording clarifications, formatting and other similar improvements. Reviewing the work done so far, and also working on the reference implementation and the TCK, we’ve decided to include two improvements to the API, too:

  • ConstraintDescriptor#validateUnwrappedValue() got renamed into getValueUnwrapping() (BVAL-674). The original method name sounded like a "command", whereas the new name makes clear it’s a "query" kind of method; also the members of the returned enum have been adapted to be in sync with the corresponding Unwrapping payload type names. We’ve also added a method ConstraintDescriptor#unwrap(Class), which will let providers expose additional functionality via extension interfaces, e.g. to explore new features which then can be standardized in a future spec revision.

  • @ConvertGroup#from() has a default value of Default.class now (BVAL-689). This simplifies group conversions in the common case where the default group is converted into another group.

Another interesting change is BVAL-613: when using the reference API JAR with the Java 9 module system, it will have the module name "java.validation" (following the recommendation in the spec appendix). This is done using the Automatic-Module-Name manifest header defined by Java 9.

Other changes include JavaDoc improvements and more clearly separating API types from examples in the spec. The complete list of all issues resolved for the CR 2 release can be found in the BVAL JIRA project. Corresponding releases of our reference implementation Hibernate Validator 6 and the TCK are also done today.

What’s new in Bean Validation 2.0?

The focus of Bean Validation 2.0 is supporting and taking advantage of Java SE 8.

For instance type annotations are used to validate the elements of generic containers: List<@NotNull @Email String> emails. There are new built-in constraints (@NotBlank, @NotEmpty, @Email, @FutureOrPresent, @PastOrPresent, @Positive, @PositiveOrZero, @Negative and @NegativeOrZero) and all built-in constraints are repeatable annotations now. Bean Validation 2.0 also supports the new Java 8 date and time types (JSR 310), the property types defined by JavaFX (StringProperty etc.) as well as java.util.Optional.

To learn more about all the new features in Bean Validation 2.0, check out this presentation which I recently gave at the jdk.io conference.

What can you do to help?

We’ll hand over the specification to the JCP for the Final Approval Ballot early next week. For the FAB release, we don’t expect any significant changes over today’s CR 2. If you’d like to help, reviewing the specification changes would be the best thing to do at this point. Also it’d be of great help if you tried out the reference implementation in your applications and let us know how it works. Any feedback is welcomed!

To post your feedback, just add a comment below, send a message to our mailing list or post in the Bean Validation forum. If you find a bug or have a specific feature request, please raise it in the issue tracker.

Everything in Bean Validation is open source, so you also can send in actual patches: be it to the API, the spec document, the TCK or the reference implementation. If you are interested, you can find out all the details to get started in the contribution guide.

Comments

Proposed Final Draft of Bean Validation 2.0 released

by Gunnar Morling on 26 Jun 2017 release

I’m very happy to announce that Bean Validation 2.0 has published its Proposed Final Draft (CR 1)!

You can find the PFD right here on beanvalidation.org as well as on JSR 380’s pages on jcp.org. We’ve also prepared a colored diff with all the changes since Bean Validation 1.1. The updated API is available on Maven Central, using the GAV coordinates are javax.validation:validation-api:2.0.0.CR1. Alternatively, it’s part of the ZIP that can be downloaded from from jcp.org.

What’s new in Bean Validation 2.0?

The focus of Bean Validation 2.0 is supporting and taking advantage of Java SE 8.

For instance type annotations are used to validate the elements of generic containers: List<@NotNull @Email String> emails. There are new built-in constraints (e.g. @NotBlank, @NotEmpty, @Email, @Positive and @Negative) and all built-in constraints are repeatable annotations now. Bean Validation 2.0 also supports the new Java 8 date and time types (JSR 310), the property types defined by JavaFX (StringProperty etc.) as well as java.util.Optional.

To learn more about all the new features in Bean Validation 2.0, check out this presentation which I recently gave at the jdk.io conference.

What’s new since the Public Review Draft?

Since the Public Review Draft (Beta 2) we’ve primarily focused on improving the new Bean Validation 2.0 features, e.g. by clarifying ambiguities in the spec, fixing bugs in the API, adding more examples etc.

In terms of API changes, we’ve followed up on our community survey on the new built-in constraints @Positive and @Negative and removed the strict() attribute in favor of separate annotations: @PositiveOrZero and @NegativeOrZero. As suggested by the community feedback, we’ve found that those separate annotations improve readability of code using the constraints. In order to stay consistent, we’ve also removed orPresent() from @Past and @Future in favor of @PastOrPresent and @FutureOrPresent. We think the same argument of readability applies; if you have any thoughts on these changes, please let us know.

Another API change (BVAL-655) relates to how container element constraints are exposed in the constraint metadata API. In case an overriding method of a sub-type specializes the return type of the overridden method (co-variant return type) it’s now possible to obtain the constraint metadata for the return type of the super-type method as well as of the sub-type method. Refer to the spec for the complete metadata API definition and an extensive example of its usage.

The complete list of all 38 issues resolved for the CR 1 release can be found in the BVAL JIRA project. Corresponding releases of our reference implementation Hibernate Validator 6 and the TCK can be expected within the next few days.

What can you do to help?

The Proposed Final Draft is pretty much what the expert group thinks should make up Bean Validation 2.0, i.e. it should be considered feature-complete. Any further changes will essentially be bug fixes, further clarifications in the wording, formatting and other polishing. If you’d like to help, reviewing the specification changes would be the best thing to do at this point. Also it’d be of great help if you tried out the reference implementation in your applications and let us know how it works. Any feedback is welcomed!

To post your feedback, just add a comment below, send a message to our mailing list or post in the Bean Validation forum. If you find a bug or have a specific feature request, please raise it in the issue tracker.

Everything in Bean Validation is open source, so you also can send in actual patches: be it to the API, the spec document, the TCK or the reference implementation. If you are interested, you can find out all the details to get started in the contribution guide.

Finally, let me say a huge "Thank You" to all the fine folks who helped to deliver this Proposed Final Draft:

  • Matt Benson, Emmanuel Bernard, Yoann Rodiere, Marco Molteni, Otávio Gonçalves de Santana, Michael Nascimento and everyone else who sent in comments and review remarks on the spec

  • Guillaume Smet who worked tirelessly to keep up the TCK and the reference implementation with the latest changes

Your efforts are greatly appreciated!

Comments

Update to the Bean Validation 2.0 Public Review Draft

by Gunnar Morling on 24 May 2017 release

While the Bean Validation 2.0 spec (JSR 380) has been put up for Public Review last month, we’ve continued to address some more outstanding issues, added some clarifications etc.

Of course we wanted to get out these improvements as quickly as possible, so we’ve published an update to the Public Review draft (the JCP rules explicitly foresee the possibility of updates during the Public Review phase). The updated draft can be found here on beanvalidation.org or you can download it from jcp.org.

As always the updated API is deployed to Maven Central, using the GAV coordinates are javax.validation:validation-api:2.0.0.Beta2. Alternatively, it’s part of the ZIP that can be downloaded from from jcp.org.

What has changed since the original Public Review Draft?

Value extractors got more flexible and can extract values from non-generic wrapper types now.

This allows to put all the constraints for numeric types (e.g. @Min, @Max, @DecimalMin, @DecimalMax etc.) to the optional numeric wrapper types in Java 8: OptionalInt, OptionalLong and OptionalDouble (BVAL-579). Also other JVM languages with their own numeric types benefit from that, as one can define value extractors for such types and apply all existing numeric constraints to them. The key to this is the new attribute @ExtractedValue#type() which allows to specify the type of the wrapped element for extractors of non-generic types.

Another improvement related to constraints on the elements of (generic) containers is the possibility to build property paths leading to a container element using the node builder API exposed via ConstraintValidatorContext (BVAL-592). For instance this will let you declare the container type and type argument index of a container element from within a custom class-level constraint validator.

The following validator for the ValidUser constraint will ensure that an entry for the WORK key is in the addresses map if the user’s type is EMPLOYEE. If not, it will create a property path pointing to the map’s value, with the container type (Map.class) and type argument index (1, representing the V type parameter, as it’s about the map value):

@ValidUser
public class User {

    private UserType type;
    private Map<AddressType, Address> addressesByType;

    // getters, setters etc. ...
}
@Constraint(validatedBy=UserValidator.class)
public @interface ValidUser {
    // constraint attributes ...
}
public class UserValidator implements ConstraintValidator<ValidUser, User> {

    @Override
    public boolean isValid(User user, ConstraintValidatorContext context) {
        context.disableDefaultConstraintViolation();

        if ( user.getType() == UserType.EMPLOYEE &&
                user.getAddressesByType().get( AddressType.WORK ) == null ) {
            context.buildConstraintViolationWithTemplate( "Work address needed for employee" )
                .addContainerElementNode( "addressesByType", Map.class, 1 )
                    .inIterable()
                        .atKey( AddressType.WORK )
                .addConstraintViolation();

            return false;
        }

        return true;
    }
}

One further improvement to mention is that the specification now recommends the module name "java.validation" (BVAL-517), should Bean Validation providers wish to distribute the API as a module for the Java Platform Module System (JPMS) as currently developed under JSR 376. This could be used within a module-info.java descriptor or via the manifest entry "Automatic-Module-Name" when preparing the module to be used as an automatic module.

Note that this is a non-binding recommendation as of Bean Validation 2.0. A mandatory module name (which could be "java.validation" or something else) — and potentially other requirements relating to the module system — will be mandated in a future revision of the spec, once the module module system has been finalized and best practices around modules have emerged.

The complete list of all issues can be found in the release notes. There are also HTML diffs which highlight what has changed since the original Public Review Draft (2.0.0.Beta1) and since Bean Validation 1.1.

New releases of reference implementation and TCK

Together with the specification we’ve also released a corresponding version of the reference implementation Hibernate Validator 6. Refer to the announcement blog post for more details. This release lets you try out all the new features added in Bean Validation 2.0.

Also the TCK (test compatibility kit) has been updated and released. You can learn more in the TCK documentation and the release notes.

What can you do to help?

The Public Review phase still runs for a few more days, followed by the Public Review Ballot (the voting by the JCP executive committee) until June 12th. So it’s the perfect time for reviewing the spec changes, we are very curious about your feedback. Also it’d be of great help if you tried out the reference implementation in your applications and let us know how it works. Any feedback is appreciated!

To post your feedback, just add a comment below, send a message to our mailing list or post in the Bean Validation forum. If you find a bug or have a specific feature request, please raise it in the issue tracker.

Everything in Bean Validation is open source, so you also can send in actual patches: to the API, the spec document or the TCK. If you are interested, you can find out all the details to get started in the contribution guide.

Comments