41. Nullness of the public API with JSpecify annotations
Date: 2026-10-13
Status
Accepted; the unmarked internal packages and the build without a checker are superseded by ADR 0048
Context
Public API signatures did not say which parameters and return values may be null: callers had to
read the Javadoc (“may be null”), and Kotlin saw every Java type as a platform type. Null is a
real value in several places (payloads, step results, cancel messages, the optional columns of the
admin records), so Optional everywhere is no option, and wrapping parameters in it is not
idiomatic Java anyway.
JSpecify is the common standard for nullness annotations, understood by IntelliJ IDEA, NullAway, the Checker Framework and the Kotlin compiler. Its jar contains only annotations.
Decision
bikesched marks the exported packages of bikesched-core with @NullMarked: types without an
annotation are non-null, and @Nullable marks exactly the places where null is a valid value.
- Type parameters of user values (payloads, step and poll results, event payloads, child results;
JobType<T>,StepHandler<T>,JobBuilder<P>, …) are declared<T extends @Nullable Object>, so they accept nullable type arguments (e.g. Kotlin’sstep<String?>). - Positions where
nulloccurs whatever the type argument are@Nullable T: a job without payload, a step returningnull,FailingStep.resolve(null),JobResult.orElse(null). Optional-returning lookups stay as they are; accessors of values that may be absent (JobInfo.parentJobId(),JobInfo.result(Class),Node.id()) return@Nullable.org.jspecify:jspecifyis anapidependency of core (requires transitive org.jspecify), as JSpecify recommends, so annotations are visible to consumers’ tools and to Kotlin.- The internal packages and the other modules are not marked yet, and the build has no nullness checker; the annotations are verified once with NullAway in JSpecify mode, which reports no errors on the marked packages.
Consequences
- IDEs and checkers warn about passing
nullwhere it is not allowed and about dereferencing values that may benull. - Kotlin sees real nullability instead of platform types: e.g.
job.payload()isString?, and a Java callback interface implemented in Kotlin gets its payload asT?. This is a source change for Kotlin code implementingTypedJobHandler,FailingStepand similar interfaces directly. - New API signatures must keep the annotations correct; without a checker in the build, reviews
have to catch a missing
@Nullable. - Follow-up: mark the internal packages and the other modules, and decide whether to enforce the
annotations with NullAway in the build (
IDEAS.md).