Add @Nullable for explicit communication of nullability


JSR-303 released constraint annotations @NotNull and @Null, but not @Nullable.

@NotNull is no doubt useful, as the first thing someone asks when he sees a method or field of a non-primitive type is "Can that thing be null?" @NotNull answers that question clearly.

@Null seems to be not very useful, but I understand its symmetry to @NotNull, so it makes sense.

What's missing, IMHO, is an annotation that *explicitly* declares that the annotated element can be null or non-null, which is why I'm proposing that @Nullable be added to JSR 303 (or its successor). Without it, the developer that sees a nullable type will still ask "Can that thing be null?" They may assume so, since it's not annotated with @NotNull, but it's not guaranteed. In the world since JSR 303's release, one would expect to be able to clearly know whether something is explicitly allowed to be null, to be non-null, or to be either, without having to resort to RTFMing.

There would be no explicit validator implementation corresponding to @Nullable, as it would always return true (or the validator impl could be hardcoded to always return true, but that seems a waste).

I'm also asking that JSR 303 publish this annotation in the javax.validation.constraints package, so as not to be confused with JSR 305's @javax.annotation.Nullable annotation, which is used for static code analysis.




Matthew Adams
December 27, 2012, 7:56 PM

I don't really know what the "'dynamic' land of JSR 303" is, so I can't really answer in any other way than this: the purpose of @Nullable would simply be to remove ambiguity.

Before JSR-303, any time you saw a reference type, you had to ask yourself "Can that be null?" and then dig to find out, either in javadoc, other docs, or code.

After the first release of JSR-303, at least you knew when something was *not* supposed to be null, thanks to the @NotNull annotation (and its opposite, @Null, which I still find a bit odd). However, the lack of a @Nullable annotation leaves an ambiguity that the developer must still resolve as to whether or not a reference is nullable. The developer is left to wonder whether or not the author really meant that the reference should be nullable or whether they just forgot to include the @NotNull annotation or didn't know about JSR-303. With the introduction of a @Nullable annotation, it would be explicit that the annotated reference is allowed to be null.

I could see a nice tooling addition, similar to eclipse's save action "add @Deprecated to elements marked in javadoc as @deprecated", that would add @Nullable to any reference that is not marked @NotNull or @Null.

Now, if that means that we'll have @Nullable everywhere and it's just noise, then fine, close this request as "won't fix", and we'll all go on in our post-JSR-303 world, interpreting an unqualified reference type as necessarily nullable. That seems like a fine default once you know you're in a codebase whose authors know about JSR-303 and have added @NotNull (& @Null) where they should. If, however, being explicit about nullability is valuable, despite the extra characters, then provide the annotation and its validation implementation of always returning true.

I'll leave it to the expert group to discuss & decide. I'm fine with the outcome either way.

Gunnar Morling
September 16, 2015, 3:05 PM

Is this still an issue with the advent of Optional in Java 8? It an be used in many places to convey "nullability" of an element. Plus, @Nullable seems not actionable for a BV implementation (it would never raise a constraint violation, as the element may be null or not), so I am tempted to close this one. Any thoughts, ?

Emmanuel Bernard
September 16, 2015, 3:22 PM

To me that's not really Bean Validation's job to express nullability. That's why I'm reluctant.

Gunnar Morling
September 16, 2015, 3:36 PM

Yes, my thinking, too. Let's close it then.

Gunnar Morling
September 16, 2015, 3:37 PM

Closing, as it appears not as a suitable functionality to be implemented by BV.

Won't Fix




Matthew Adams


Feedback Requested


Feedback Requested By




Suitable for new contributors

Yes, likely

Pull Request