JSpecify Support

JSpecify is an effort to standardize annotations for Java static analysis, and JSpecify 1.0 includes nullability annotations. Out of the box, NullAway supports JSpecify annotations in its standard mode of checking. If you are a current NullAway user, you should just be able to swap in JSpecify annotations for whatever nullability annotations you were using before, and you should not get any new NullAway errors. If you see problems, please report an issue.

A caveat to the above is that starting with NullAway 0.12.0, NullAway by default requires that JSpecify annotations be written in the correct place on qualified and array types. So, e.g., if we have a field String[] x, to mark x itself as @Nullable, you must write String @Nullable [] x if using JSpecify's @Nullable annotation or another type-use @Nullable annotation. And, if you have a varargs argument foo(Object... args) and you would like the args array itself to be @Nullable, you must write foo(Object @Nullable... args). See here for further details on type-use annotation syntax, and here and here for the gory details on how NullAway interprets different types of annotations. This change may lead to NullAway reporting new errors in existing code. We provide a compatibility flag -XepOpt:NullAway:LegacyAnnotationLocations to use NullAway's old logic for interpreting annotations to ease the transition, but we expect to remove this flag in a future release.

We are also working on adding support for full JSpecify semantics for these annotations, including annotations on generic types. You can enable our work-in-progress checking by passing the configuration flag -XepOpt:NullAway:JSpecifyMode=true when running NullAway. This mode is still very much under development and may crash or report false positive warnings on your code. Please report these cases and we will address them. Major outstanding features still to be supported include:

• pulling in JDK annotations from https://github.com/jspecify/jdk. This will enable much better checking of uses of types like Collections.
• generic methods
• wildcard types
• checking of generic class implementations (i.e., checking that generic type variables are used correctly). Thus far we have focused on supporting uses of generic classes, but not on checking their internals.

Not supporting the above features may lead to false negatives (missed issues). We are slowly working towards supporting them, and any help from the community is appreciated, from issue reports to pull requests.

When building with JSpecify mode enabled, we strongly recommend compiling using the most recent released JDK build (JDK 23.0.1 as of 2024-10-15). Bugs in javac related to visibility of JSpecify annotations are actively being fixed, and these bug fixes currently have an impact on NullAway's support for JSpecify semantics. See this discussion of using annotation processors with JSpecify for details of one relevant issue, and also https://github.com/uber/NullAway/issues/1005 and https://github.com/uber/NullAway/issues/1022.