graphql-java · dondonz · Aug 21, 2025 · Aug 21, 2025 · Aug 21, 2025 · Aug 21, 2025
diff --git a/.claude/commands/jspecify-annotate.md b/.claude/commands/jspecify-annotate.md
@@ -0,0 +1,25 @@
+I have already asked IntelliJ to infer nullity on this class. Can you help me make this more accurate.
+
+Note that JSpecify is already used in this repository so it's already imported.
+
+If you see a builder static class, you can label it `@NullUnmarked` and not need to do anymore for this static class in terms of annotations.
+
+Analyze this Java class and add JSpecify annotations based on:
+1. Set the class to be `@NullMarked`
+2. Remove all the redundant `@NonNull` annotations that IntelliJ added
+3. Check Javadoc @param tags mentioning "null", "nullable", "may be null"
+4. Check Javadoc @return tags mentioning "null", "optional", "if available"
+5. GraphQL specification semantics (nullable fields, non-null by default)
+6. Method implementations that return null or check for null
+
+IntelliJ's infer nullity code analysis isn't comprehensive so feel free to make corrections.
+
+Finally, please check all of this works, by running the NullAway compile check.
+
+If you find NullAway errors, try and make the smallest possible change to fix them. If you must, you can use assertNotNull. Make sure to include a message as well.
+
+Finally, can you remove this class from the JSpecifyAnnotationsCheck as an exemption. Thanks
+
+You do not need to run the JSpecifyAnnotationsCheck. Removing the completed class is enough.
+
+Remember to delete all unused imports wehn you're done from the class you've just annotated.
diff --git a/src/main/java/graphql/AssertException.java b/src/main/java/graphql/AssertException.java
@@ -1,7 +1,10 @@
 package graphql;
 
 
+import org.jspecify.annotations.NullMarked;
+
 @PublicApi
+@NullMarked
 public class AssertException extends GraphQLException {
 
     public AssertException(String message) {

diff --git a/src/main/java/graphql/Directives.java b/src/main/java/graphql/Directives.java
@@ -6,6 +6,7 @@
 import graphql.language.DirectiveDefinition;
 import graphql.language.StringValue;
 import graphql.schema.GraphQLDirective;
+import org.jspecify.annotations.NullMarked;
 
 import java.util.concurrent.atomic.AtomicBoolean;
 
@@ -34,6 +35,7 @@
  * The directives that are understood by graphql-java
  */
 @PublicApi
+@NullMarked
 public class Directives {
 
     private static final String DEPRECATED = "deprecated";

diff --git a/src/main/java/graphql/ErrorClassification.java b/src/main/java/graphql/ErrorClassification.java
@@ -1,5 +1,7 @@
 package graphql;
 
+import org.jspecify.annotations.NullMarked;
+
 /**
  * Errors in graphql-java can have a classification to help with the processing
  * of errors.  Custom {@link graphql.GraphQLError} implementations could use
@@ -8,6 +10,7 @@
  * graphql-java ships with a standard set of error classifications via {@link graphql.ErrorType}
  */
 @PublicApi
+@NullMarked
 public interface ErrorClassification {
 
     /**

diff --git a/src/main/java/graphql/ErrorType.java b/src/main/java/graphql/ErrorType.java
@@ -1,10 +1,13 @@
 package graphql;
 
 
+import org.jspecify.annotations.NullMarked;
+
 /**
  * All the errors in graphql belong to one of these categories
  */
 @PublicApi
+@NullMarked
 public enum ErrorType implements ErrorClassification {
     InvalidSyntax,
     ValidationError,

diff --git a/src/main/java/graphql/ExceptionWhileDataFetching.java b/src/main/java/graphql/ExceptionWhileDataFetching.java
@@ -3,6 +3,8 @@
 
 import graphql.execution.ResultPath;
 import graphql.language.SourceLocation;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.Collections;
 import java.util.LinkedHashMap;
@@ -16,13 +18,14 @@
  * This graphql error will be used if a runtime exception is encountered while a data fetcher is invoked
  */
 @PublicApi
+@NullMarked
 public class ExceptionWhileDataFetching implements GraphQLError {
 
     private final String message;
     private final List<Object> path;
     private final Throwable exception;
     private final List<SourceLocation> locations;
-    private final Map<String, Object> extensions;
+    private final @Nullable Map<String, Object> extensions;
 
     public ExceptionWhileDataFetching(ResultPath path, Throwable exception, SourceLocation sourceLocation) {
         this.path = assertNotNull(path).toList();
@@ -41,7 +44,7 @@ private String mkMessage(ResultPath path, Throwable exception) {
      * exception into the ExceptionWhileDataFetching error and hence have custom "extension attributes"
      * per error message.
      */
-    private Map<String, Object> mkExtensions(Throwable exception) {
+    private @Nullable Map<String, Object> mkExtensions(Throwable exception) {
         Map<String, Object> extensions = null;
         if (exception instanceof GraphQLError) {
             Map<String, Object> map = ((GraphQLError) exception).getExtensions();
@@ -73,7 +76,7 @@ public List<Object> getPath() {
     }
 
     @Override
-    public Map<String, Object> getExtensions() {
+    public @Nullable Map<String, Object> getExtensions() {
         return extensions;
     }
 

diff --git a/src/main/java/graphql/ExecutionResult.java b/src/main/java/graphql/ExecutionResult.java
@@ -1,6 +1,10 @@
 package graphql;
 
 
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
+
 import java.util.List;
 import java.util.Map;
 import java.util.function.Consumer;
@@ -9,6 +13,7 @@
  * This simple value class represents the result of performing a graphql query.
  */
 @PublicApi
+@NullMarked
 @SuppressWarnings("TypeParameterUnusedInFormals")
 public interface ExecutionResult {
 
@@ -22,16 +27,16 @@ public interface ExecutionResult {
      *
      * @return the data in the result or null if there is none
      */
-    <T> T getData();
+    <T> @Nullable T getData();
 
     /**
      * The graphql specification specifies:
-     *
+     * <p>
      * "If an error was encountered before execution begins, the data entry should not be present in the result.
      * If an error was encountered during the execution that prevented a valid response, the data entry in the response should be null."
-     *
+     * <p>
      * This allows to distinguish between the cases where {@link #getData()} returns null.
-     *
+     * <p>
      * See : <a href="https://graphql.github.io/graphql-spec/June2018/#sec-Data">https://graphql.github.io/graphql-spec/June2018/#sec-Data</a>
      *
      * @return <code>true</code> if the entry "data" should be present in the result
@@ -42,14 +47,14 @@ public interface ExecutionResult {
     /**
      * @return a map of extensions or null if there are none
      */
-    Map<Object, Object> getExtensions();
+    @Nullable Map<Object, Object> getExtensions();
 
 
     /**
      * The graphql specification says that result of a call should be a map that follows certain rules on what items
      * should be present.  Certain JSON serializers may or may interpret {@link ExecutionResult} to spec, so this method
      * is provided to produce a map that strictly follows the specification.
-     *
+     * <p>
      * See : <a href="https://spec.graphql.org/October2021/#sec-Response-Format">https://spec.graphql.org/October2021/#sec-Response-Format</a>
      *
      * @return a map of the result that strictly follows the spec
@@ -88,6 +93,7 @@ static Builder<?> newExecutionResult() {
         return ExecutionResultImpl.newExecutionResult();
     }
 
+    @NullUnmarked
     interface Builder<B extends Builder<B>> {
 
         /**

diff --git a/src/main/java/graphql/GraphQL.java b/src/main/java/graphql/GraphQL.java
@@ -559,14 +559,14 @@ private PreparsedDocumentEntry parseAndValidate(AtomicReference<ExecutionInput>
 
         ParseAndValidateResult parseResult = parse(executionInput, graphQLSchema, instrumentationState);
         if (parseResult.isFailure()) {
-            return new PreparsedDocumentEntry(parseResult.getSyntaxException().toInvalidSyntaxError());
+            return new PreparsedDocumentEntry(assertNotNull(parseResult.getSyntaxException(), () -> "Parse result syntax exception cannot be null when failed").toInvalidSyntaxError());
         } else {
             final Document document = parseResult.getDocument();
             // they may have changed the document and the variables via instrumentation so update the reference to it
             executionInput = executionInput.transform(builder -> builder.variables(parseResult.getVariables()));
             executionInputRef.set(executionInput);
 
-            final List<ValidationError> errors = validate(executionInput, document, graphQLSchema, instrumentationState);
+            final List<ValidationError> errors = validate(executionInput, assertNotNull(document, () -> "Document cannot be null when parse succeeded"), graphQLSchema, instrumentationState);
             if (!errors.isEmpty()) {
                 return new PreparsedDocumentEntry(document, errors);
             }
@@ -599,7 +599,7 @@ private List<ValidationError> validate(ExecutionInput executionInput, Document d
         validationCtx.onDispatched();
 
         Predicate<Class<?>> validationRulePredicate = executionInput.getGraphQLContext().getOrDefault(ParseAndValidate.INTERNAL_VALIDATION_PREDICATE_HINT, r -> true);
-        Locale locale = executionInput.getLocale() != null ? executionInput.getLocale() : Locale.getDefault();
+        Locale locale = executionInput.getLocale();
         List<ValidationError> validationErrors = ParseAndValidate.validate(graphQLSchema, document, validationRulePredicate, locale);
 
         validationCtx.onCompleted(validationErrors, null);

diff --git a/src/main/java/graphql/GraphQLContext.java b/src/main/java/graphql/GraphQLContext.java
@@ -1,5 +1,9 @@
 package graphql;
 
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
+
 import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
@@ -32,12 +36,13 @@
  * You can set this up via {@link ExecutionInput#getGraphQLContext()}
  *
  * All keys and values in the context MUST be non null.
- *
+ * <p>
  * The class is mutable via a thread safe implementation but it is recommended to try to use this class in an immutable way if you can.
  */
 @PublicApi
 @ThreadSafe
 @SuppressWarnings("unchecked")
+@NullMarked
 public class GraphQLContext {
 
     private final ConcurrentMap<Object, Object> map;
@@ -66,7 +71,7 @@ public GraphQLContext delete(Object key) {
      *
      * @return a value or null
      */
-    public <T> T get(Object key) {
+    public <T> @Nullable T get(Object key) {
         return (T) map.get(assertNotNull(key));
     }
 
@@ -210,7 +215,7 @@ public GraphQLContext putAll(Consumer<GraphQLContext.Builder> contextBuilderCons
      *
      * @return the new value associated with the specified key, or null if none
      */
-    public <T> T compute(Object key, BiFunction<Object, ? super T, ? extends T> remappingFunction) {
+    public <T> @Nullable T compute(Object key, BiFunction<Object, ? super T, ? extends T> remappingFunction) {
         assertNotNull(remappingFunction);
         return (T) map.compute(assertNotNull(key), (k, v) -> remappingFunction.apply(k, (T) v));
     }
@@ -226,7 +231,7 @@ public <T> T compute(Object key, BiFunction<Object, ? super T, ? extends T> rema
      * @return the current (existing or computed) value associated with the specified key, or null if the computed value is null
      */
 
-    public <T> T computeIfAbsent(Object key, Function<Object, ? extends T> mappingFunction) {
+    public <T> @Nullable T computeIfAbsent(Object key, Function<Object, ? extends T> mappingFunction) {
         return (T) map.computeIfAbsent(assertNotNull(key), assertNotNull(mappingFunction));
     }
 
@@ -241,7 +246,7 @@ public <T> T computeIfAbsent(Object key, Function<Object, ? extends T> mappingFu
      * @return the new value associated with the specified key, or null if none
      */
 
-    public <T> T computeIfPresent(Object key, BiFunction<Object, ? super T, ? extends T> remappingFunction) {
+    public <T> @Nullable T computeIfPresent(Object key, BiFunction<Object, ? super T, ? extends T> remappingFunction) {
         assertNotNull(remappingFunction);
         return (T) map.computeIfPresent(assertNotNull(key), (k, v) -> remappingFunction.apply(k, (T) v));
     }
@@ -254,7 +259,7 @@ public Stream<Map.Entry<Object, Object>> stream() {
     }
 
     @Override
-    public boolean equals(Object o) {
+    public boolean equals(@Nullable Object o) {
         if (this == o) {
             return true;
         }
@@ -315,6 +320,7 @@ public static Builder newContext() {
         return new Builder();
     }
 
+    @NullUnmarked
     public static class Builder {
         private final ConcurrentMap<Object, Object> map = new ConcurrentHashMap<>();