# Jspecify Nullness

> JSpecify nullness annotations for Java APIs and tooling. Use when adopting or migrating JSpecify annotations, designing null-safe Java signatures, fixing generic bounds and type-use placement, or interpreting Kotlin interop, annotation-processor, and tool-conformance behavior.

- Skill: `alexandru/jspecify-nullness` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add alexandru/jspecify-nullness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alexandru/jspecify-nullness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: alexandru (https://skillmd.com/u/alexandru)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alexandru/jspecify-nullness

---


# JSpecify Nullness (Java)

## Quick start
- Add `org.jspecify:jspecify:1.0.0` as a visible API dependency for Java libraries.
- Prefer `@NullMarked` at package or class scope; add `@Nullable` only where `null` is allowed.
- Treat unannotated types outside `@NullMarked` as unspecified nullness, not non-null.
- Decide generic bounds deliberately: `<T extends @Nullable Object>` accepts nullable type arguments; `<T>` does not in a null-marked scope.
- Keep `@Nullable`/`@NonNull` in JSpecify-recognized type-use locations, especially for arrays, nested types, type arguments, and bounds.
- Read `references/jspecify-nullness.md` before substantial annotation, migration, or tooling advice.

## Workflow
1. Confirm consumer constraints: nullness checker, Kotlin compiler behavior, and annotation processors.
2. Add the JSpecify dependency without hiding it from downstream users.
3. Annotate nullable types first, then add `@NullMarked` at class or package scope.
4. Fix generics: choose nullable/non-null bounds and annotate type-variable uses only when the use differs from the type argument.
5. Compile examples for syntax, then run a JSpecify-aware nullness analyzer and fix findings before expanding scope.

## Rules of thumb
- Do not annotate local-variable root types or casts; annotate only nested type arguments/components there.
- For fields, parameters, and returns, `@Nullable String[]` means nullable elements; `String @Nullable []` means the array reference is nullable.
- For nested types, annotate the nested type as `Map.@Nullable Entry`, not the outer type.
- Use `@NonNull T` only to force a type-variable use non-null when the type argument may be nullable.
- Use `@NullUnmarked` only as an incremental escape hatch inside a null-marked scope.

## Output expectations
- Provide annotated signatures and call-site implications.
- Explain generic bound choices and type-use placement.
- Call out tool-conformance limits instead of promising specific diagnostics.
- For skill edits, run `jbang skills/jspecify-nullness/scripts/verify-examples.java`.

## References
- Load `references/jspecify-nullness.md` for source-backed guidance, examples, and representative prompts.