graphql-java · dondonz · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026
diff --git a/src/main/java/graphql/analysis/QueryTransformer.java b/src/main/java/graphql/analysis/QueryTransformer.java
@@ -84,7 +84,7 @@ public Node transform(QueryVisitor queryVisitor) {
 
             @Override
             public TraversalControl enter(TraverserContext<Node> context) {
-                return context.thisNode().accept(context, nodeVisitor);
+                return assertNotNull(context.thisNode(), "thisNode should not be null").accept(context, nodeVisitor);
             }
 
             @Override
@@ -93,7 +93,7 @@ public TraversalControl leave(TraverserContext<Node> context) {
                 return TraversalControl.CONTINUE;
             }
         };
-        return new TreeTransformer<>(AST_NODE_ADAPTER).transform(root, nodeTraverserVisitor, rootVars);
+        return assertNotNull(new TreeTransformer<>(AST_NODE_ADAPTER).transform(root, nodeTraverserVisitor, rootVars), "transform result should not be null");
     }
 
     public static Builder newQueryTransformer() {

diff --git a/src/main/java/graphql/analysis/QueryTraverser.java b/src/main/java/graphql/analysis/QueryTraverser.java
@@ -23,7 +23,9 @@
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
 
 import static graphql.Assert.assertNotNull;
 import static graphql.Assert.assertShouldNeverHappen;
@@ -42,6 +44,7 @@
  * visitField calls.
  */
 @PublicApi
+@NullMarked
 public class QueryTraverser {
 
     private final Collection<? extends Node> roots;
@@ -186,7 +189,7 @@ private List<Node> childrenOf(Node<?> node) {
         return singletonList(fragmentsByName.get(fragmentSpread.getName()));
     }
 
-    private Object visitImpl(QueryVisitor visitFieldCallback, Boolean preOrder) {
+    private Object visitImpl(QueryVisitor visitFieldCallback, @Nullable Boolean preOrder) {
         Map<Class<?>, Object> rootVars = new LinkedHashMap<>();
         rootVars.put(QueryTraversalContext.class, new QueryTraversalContext(rootParentType, null, null, GraphQLContext.getDefault()));
 

diff --git a/src/main/java/graphql/extensions/ExtensionsBuilder.java b/src/main/java/graphql/extensions/ExtensionsBuilder.java
@@ -3,7 +3,7 @@
 import com.google.common.collect.ImmutableMap;
 import graphql.ExecutionResult;
 import graphql.PublicApi;
-import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 import java.util.Collections;
@@ -26,6 +26,7 @@
  * is placed in the {@link ExecutionResult}
  */
 @PublicApi
+@NullMarked
 public class ExtensionsBuilder {
 
     // thread safe since there can be many changes say in DFs across threads
@@ -69,7 +70,7 @@ public int getChangeCount() {
      *
      * @return this builder for fluent style reasons
      */
-    public ExtensionsBuilder addValues(@NonNull Map<Object, Object> newValues) {
+    public ExtensionsBuilder addValues(Map<Object, Object> newValues) {
         assertNotNull(newValues);
         if (!newValues.isEmpty()) {
             changes.add(newValues);
@@ -85,7 +86,7 @@ public ExtensionsBuilder addValues(@NonNull Map<Object, Object> newValues) {
      *
      * @return this builder for fluent style reasons
      */
-    public ExtensionsBuilder addValue(@NonNull Object key, @Nullable Object value) {
+    public ExtensionsBuilder addValue(Object key, @Nullable Object value) {
         assertNotNull(key);
         return addValues(Collections.singletonMap(key, value));
     }

diff --git a/src/main/java/graphql/incremental/DeferPayload.java b/src/main/java/graphql/incremental/DeferPayload.java
@@ -3,6 +3,8 @@
 import graphql.ExecutionResult;
 import graphql.ExperimentalApi;
 import graphql.GraphQLError;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
 import org.jspecify.annotations.Nullable;
 
 import java.util.LinkedHashMap;
@@ -14,10 +16,11 @@
  * Represents a defer payload
  */
 @ExperimentalApi
+@NullMarked
 public class DeferPayload extends IncrementalPayload {
-    private final Object data;
+    private final @Nullable Object data;
 
-    private DeferPayload(Object data, List<Object> path, String label, List<GraphQLError> errors, Map<Object, Object> extensions) {
+    private DeferPayload(@Nullable Object data, List<Object> path, @Nullable String label, @Nullable List<GraphQLError> errors, @Nullable Map<Object, Object> extensions) {
         super(path, label, errors, extensions);
         this.data = data;
     }
@@ -48,7 +51,7 @@ public int hashCode() {
     }
 
     @Override
-    public boolean equals(Object obj) {
+    public boolean equals(@Nullable Object obj) {
         if (this == obj) return true;
         if (obj == null || getClass() != obj.getClass()) return false;
         if (!super.equals(obj)) return false;
@@ -63,6 +66,7 @@ public static DeferPayload.Builder newDeferredItem() {
         return new DeferPayload.Builder();
     }
 
+    @NullUnmarked
     public static class Builder extends IncrementalPayload.Builder<Builder> {
         private Object data = null;
 

diff --git a/src/main/java/graphql/incremental/DelayedIncrementalPartialResult.java b/src/main/java/graphql/incremental/DelayedIncrementalPartialResult.java
@@ -1,6 +1,7 @@
 package graphql.incremental;
 
 import graphql.ExperimentalApi;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 import java.util.List;
@@ -13,6 +14,7 @@
  * {@link DelayedIncrementalPartialResult}
  */
 @ExperimentalApi
+@NullMarked
 public interface DelayedIncrementalPartialResult {
     /**
      * @return a list of defer and/or stream payloads.

diff --git a/src/main/java/graphql/incremental/DelayedIncrementalPartialResultImpl.java b/src/main/java/graphql/incremental/DelayedIncrementalPartialResultImpl.java
@@ -2,17 +2,21 @@
 
 import graphql.ExperimentalApi;
 import graphql.util.FpKit;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 
 @ExperimentalApi
+@NullMarked
 public class DelayedIncrementalPartialResultImpl implements DelayedIncrementalPartialResult {
-    private final List<IncrementalPayload> incrementalItems;
+    private final @Nullable List<IncrementalPayload> incrementalItems;
     private final boolean hasNext;
-    private final Map<Object, Object> extensions;
+    private final @Nullable Map<Object, Object> extensions;
 
     private DelayedIncrementalPartialResultImpl(Builder builder) {
         this.incrementalItems = builder.incrementalItems;
@@ -21,7 +25,7 @@ private DelayedIncrementalPartialResultImpl(Builder builder) {
     }
 
     @Override
-    public List<IncrementalPayload> getIncremental() {
+    public @Nullable List<IncrementalPayload> getIncremental() {
         return this.incrementalItems;
     }
 
@@ -31,7 +35,7 @@ public boolean hasNext() {
     }
 
     @Override
-    public Map<Object, Object> getExtensions() {
+    public @Nullable Map<Object, Object> getExtensions() {
         return this.extensions;
     }
 
@@ -62,6 +66,7 @@ public static Builder newIncrementalExecutionResult() {
         return new Builder();
     }
 
+    @NullUnmarked
     public static class Builder {
         private boolean hasNext = false;
         private List<IncrementalPayload> incrementalItems = Collections.emptyList();

diff --git a/src/main/java/graphql/incremental/IncrementalExecutionResult.java b/src/main/java/graphql/incremental/IncrementalExecutionResult.java
@@ -2,6 +2,7 @@
 
 import graphql.ExecutionResult;
 import graphql.ExperimentalApi;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 import org.reactivestreams.Publisher;
 
@@ -83,6 +84,7 @@
  * The execution behaviour should match what we get from running Apollo Server 4.9.5 with graphql-js v17.0.0-alpha.2
  */
 @ExperimentalApi
+@NullMarked
 public interface IncrementalExecutionResult extends ExecutionResult {
     /**
      * Indicates whether there are pending incremental data.

diff --git a/src/main/java/graphql/incremental/IncrementalExecutionResultImpl.java b/src/main/java/graphql/incremental/IncrementalExecutionResultImpl.java
@@ -3,6 +3,8 @@
 import graphql.ExecutionResult;
 import graphql.ExecutionResultImpl;
 import graphql.ExperimentalApi;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
 import org.jspecify.annotations.Nullable;
 import org.reactivestreams.Publisher;
 
@@ -13,9 +15,10 @@
 import java.util.function.Consumer;
 
 @ExperimentalApi
+@NullMarked
 public class IncrementalExecutionResultImpl extends ExecutionResultImpl implements IncrementalExecutionResult {
     private final boolean hasNext;
-    private final List<IncrementalPayload> incremental;
+    private final @Nullable List<IncrementalPayload> incremental;
     private final Publisher<DelayedIncrementalPartialResult> incrementalItemPublisher;
 
     private IncrementalExecutionResultImpl(Builder builder) {
@@ -79,6 +82,7 @@ public Map<String, Object> toSpecification() {
         return map;
     }
 
+    @NullUnmarked
     public static class Builder extends ExecutionResultImpl.Builder<Builder> {
         private boolean hasNext = true;
         public List<IncrementalPayload> incremental;

diff --git a/src/main/java/graphql/incremental/IncrementalPayload.java b/src/main/java/graphql/incremental/IncrementalPayload.java
@@ -4,6 +4,8 @@
 import graphql.GraphQLError;
 import graphql.execution.ResultPath;
 import graphql.util.FpKit;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
 import org.jspecify.annotations.Nullable;
 
 import java.util.ArrayList;
@@ -16,13 +18,14 @@
  * Represents a payload that can be resolved after the initial response.
  */
 @ExperimentalApi
+@NullMarked
 public abstract class IncrementalPayload {
     private final List<Object> path;
-    private final String label;
-    private final List<GraphQLError> errors;
-    private final transient Map<Object, Object> extensions;
+    private final @Nullable String label;
+    private final @Nullable List<GraphQLError> errors;
+    private final transient @Nullable Map<Object, Object> extensions;
 
-    protected IncrementalPayload(List<Object> path, String label, List<GraphQLError> errors, Map<Object, Object> extensions) {
+    protected IncrementalPayload(List<Object> path, @Nullable String label, @Nullable List<GraphQLError> errors, @Nullable Map<Object, Object> extensions) {
         this.path = path;
         this.errors = errors;
         this.label = label;
@@ -90,7 +93,7 @@ public int hashCode() {
         return Objects.hash(path, label, errors, extensions);
     }
 
-    public boolean equals(Object obj) {
+    public boolean equals(@Nullable Object obj) {
         if (this == obj) {
             return true;
         }
@@ -104,6 +107,7 @@ public boolean equals(Object obj) {
                 Objects.equals(extensions, that.extensions);
     }
 
+    @NullUnmarked
     protected static abstract class Builder<T extends Builder<T>> {
         protected List<Object> path;
         protected String label;

diff --git a/src/main/java/graphql/incremental/StreamPayload.java b/src/main/java/graphql/incremental/StreamPayload.java
@@ -2,6 +2,8 @@
 
 import graphql.ExperimentalApi;
 import graphql.GraphQLError;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
 import org.jspecify.annotations.Nullable;
 
 import java.util.LinkedHashMap;
@@ -13,10 +15,11 @@
  * Represents a stream payload
  */
 @ExperimentalApi
+@NullMarked
 public class StreamPayload extends IncrementalPayload {
-    private final List<Object> items;
+    private final @Nullable List<Object> items;
 
-    private StreamPayload(List<Object> items, List<Object> path, String label, List<GraphQLError> errors, Map<Object, Object> extensions) {
+    private StreamPayload(@Nullable List<Object> items, List<Object> path, @Nullable String label, @Nullable List<GraphQLError> errors, @Nullable Map<Object, Object> extensions) {
         super(path, label, errors, extensions);
         this.items = items;
     }
@@ -47,7 +50,7 @@ public int hashCode() {
     }
 
     @Override
-    public boolean equals(Object obj) {
+    public boolean equals(@Nullable Object obj) {
         if (this == obj) return true;
         if (obj == null || getClass() != obj.getClass()) return false;
         if (!super.equals(obj)) return false;
@@ -62,6 +65,7 @@ public static StreamPayload.Builder newStreamedItem() {
         return new StreamPayload.Builder();
     }
 
+    @NullUnmarked
     public static class Builder extends IncrementalPayload.Builder<Builder> {
         private List<Object> items = null;