NonNullApi

NonNullApi is a package-level annotation in the Spring Framework (org.springframework.lang.NonNullApi) that marks all public API elements within a package as non-null by default. This means that method parameters and return values are considered non-null unless explicitly annotated otherwise. The annotation helps formalize null-safety contracts across a codebase and reduces the need to annotate every member individually.

Usage typically involves placing the annotation on a package via a package-info.java file, so that all types in that package inherit the non-null default. When a particular method, parameter, or return type should permit null, it can be overridden by annotating that element with @Nullable. There is also a related annotation, NonNullFields, which applies a non-null-by-default principle to fields within a type, with @Nullable used to opt out on a per-field basis.

Impact and tooling: NonNullApi is not enforced at runtime; it is intended as a compile-time and tooling aid. Integrated development environments and static analysis tools use the annotation to provide nullability hints, warnings, and improved IDE experience. It complements other nullability constructs in Spring, such as @Nullable, and supports cross-language interoperability, including Kotlin, by clarifying API contracts.

Related concepts include @Nullable, and the NonNullFields annotation for fields. These annotations are part of Spring’s broader effort to standardize nullability semantics across its APIs, improving readability and reducing null-related errors without altering runtime behavior.