graphql-java · dondonz · Mar 22, 2026 · Jan 24, 2026 · Jan 24, 2026 · Jan 24, 2026
diff --git a/.claude/commands/jspecify-annotate.md b/.claude/commands/jspecify-annotate.md
diff --git a/build.gradle b/build.gradle
@@ -90,7 +90,7 @@ def getDevelopmentVersion() {
     gitRevParse.waitForProcessOutput(gitRevParseOutput, gitRevParseError)
     def branchName = gitRevParseOutput.toString().trim().replaceAll('[/\\\\]', '-')
 
-    return makeDevelopmentVersion(["0.0.0", branchName, "SNAPSHOT"])
+    return makeDevelopmentVersion(["0.0.0", sanitizedBranchName, "SNAPSHOT"])
 }
 
 def reactiveStreamsVersion = '1.0.3'

diff --git a/src/main/java/graphql/language/Comment.java b/src/main/java/graphql/language/Comment.java
@@ -1,18 +1,21 @@
 package graphql.language;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.io.Serializable;
 
 /**
  * A single-line comment. These are comments that start with a {@code #} in source documents.
  */
 @PublicApi
+@NullMarked
 public class Comment implements Serializable {
     public final String content;
-    public final SourceLocation sourceLocation;
+    public final @Nullable SourceLocation sourceLocation;
 
-    public Comment(String content, SourceLocation sourceLocation) {
+    public Comment(String content, @Nullable SourceLocation sourceLocation) {
         this.content = content;
         this.sourceLocation = sourceLocation;
     }
@@ -21,7 +24,7 @@ public String getContent() {
         return content;
     }
 
-    public SourceLocation getSourceLocation() {
+    public @Nullable SourceLocation getSourceLocation() {
         return sourceLocation;
     }
 }
diff --git a/src/main/java/graphql/language/Definition.java b/src/main/java/graphql/language/Definition.java
@@ -2,8 +2,10 @@
 
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
 
 @PublicApi
+@NullMarked
 public interface Definition<T extends Definition> extends Node<T> {
 
 }
diff --git a/src/main/java/graphql/language/IgnoredChar.java b/src/main/java/graphql/language/IgnoredChar.java
@@ -1,6 +1,8 @@
 package graphql.language;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.io.Serializable;
 import java.util.Objects;
@@ -12,6 +14,7 @@
  * This costs more memory but for certain use cases (like editors) this maybe be useful
  */
 @PublicApi
+@NullMarked
 public class IgnoredChar implements Serializable {
 
     public enum IgnoredCharKind {
@@ -51,7 +54,7 @@ public String toString() {
     }
 
     @Override
-    public boolean equals(Object o) {
+    public boolean equals(@Nullable Object o) {
         if (this == o) {
             return true;
         }

diff --git a/src/main/java/graphql/language/IgnoredChars.java b/src/main/java/graphql/language/IgnoredChars.java
@@ -3,6 +3,7 @@
 import com.google.common.collect.ImmutableList;
 import graphql.PublicApi;
 import graphql.collect.ImmutableKit;
+import org.jspecify.annotations.NullMarked;
 
 import java.io.Serializable;
 import java.util.List;
@@ -14,6 +15,7 @@
  * This costs more memory but for certain use cases (like editors) this maybe be useful
  */
 @PublicApi
+@NullMarked
 public class IgnoredChars implements Serializable {
 
     private final ImmutableList<IgnoredChar> left;

diff --git a/src/main/java/graphql/language/Node.java b/src/main/java/graphql/language/Node.java
@@ -4,6 +4,7 @@
 import graphql.PublicApi;
 import graphql.util.TraversalControl;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
 import java.io.Serializable;
@@ -21,6 +22,7 @@
  * Every Node is immutable
  */
 @PublicApi
+@NullMarked
 public interface Node<T extends Node> extends Serializable {
 
     /**

diff --git a/src/main/java/graphql/language/NodeChildrenContainer.java b/src/main/java/graphql/language/NodeChildrenContainer.java
@@ -1,6 +1,9 @@
 package graphql.language;
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.NullUnmarked;
+import org.jspecify.annotations.Nullable;
 
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
@@ -15,6 +18,7 @@
  * Container of children of a {@link Node}.
  */
 @PublicApi
+@NullMarked
 public class NodeChildrenContainer {
 
     private final Map<String, List<Node>> children = new LinkedHashMap<>();
@@ -27,7 +31,7 @@ public <T extends Node> List<T> getChildren(String key) {
         return (List<T>) children.getOrDefault(key, emptyList());
     }
 
-    public <T extends Node> T getChildOrNull(String key) {
+    public <T extends Node> @Nullable T getChildOrNull(String key) {
         List<? extends Node> result = children.getOrDefault(key, emptyList());
         if (result.size() > 1) {
             throw new IllegalStateException("children " + key + " is not a single value");
@@ -61,6 +65,7 @@ public boolean isEmpty() {
         return this.children.isEmpty();
     }
 
+    @NullUnmarked
     public static class Builder {
         private final Map<String, List<Node>> children = new LinkedHashMap<>();
 

diff --git a/src/main/java/graphql/language/NodeVisitor.java b/src/main/java/graphql/language/NodeVisitor.java
@@ -3,11 +3,13 @@
 import graphql.PublicApi;
 import graphql.util.TraversalControl;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Used by {@link NodeTraverser} to visit {@link Node}.
  */
 @PublicApi
+@NullMarked
 public interface NodeVisitor {
     TraversalControl visitArgument(Argument node, TraverserContext<Node> data);
 

diff --git a/src/main/java/graphql/language/NodeVisitorStub.java b/src/main/java/graphql/language/NodeVisitorStub.java
@@ -3,11 +3,13 @@
 import graphql.PublicApi;
 import graphql.util.TraversalControl;
 import graphql.util.TraverserContext;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Convenient implementation of {@link NodeVisitor} for easy subclassing methods handling different types of Nodes in one method.
  */
 @PublicApi
+@NullMarked
 public class NodeVisitorStub implements NodeVisitor {
     @Override
     public TraversalControl visitArgument(Argument node, TraverserContext<Node> context) {

diff --git a/src/main/java/graphql/language/SourceLocation.java b/src/main/java/graphql/language/SourceLocation.java
@@ -7,24 +7,27 @@
 import graphql.schema.GraphQLSchemaElement;
 import graphql.schema.GraphQLTypeUtil;
 import graphql.schema.idl.SchemaGenerator;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 import java.io.Serializable;
 import java.util.Objects;
 
 @PublicApi
+@NullMarked
 public class SourceLocation implements Serializable {
 
     public static final SourceLocation EMPTY = new SourceLocation(-1, -1);
 
     private final int line;
     private final int column;
-    private final String sourceName;
+    private final @Nullable String sourceName;
 
     public SourceLocation(int line, int column) {
         this(line, column, null);
     }
 
-    public SourceLocation(int line, int column, String sourceName) {
+    public SourceLocation(int line, int column, @Nullable String sourceName) {
         this.line = line;
         this.column = column;
         this.sourceName = sourceName;
@@ -38,12 +41,12 @@ public int getColumn() {
         return column;
     }
 
-    public String getSourceName() {
+    public @Nullable String getSourceName() {
         return sourceName;
     }
 
     @Override
-    public boolean equals(Object o) {
+    public boolean equals(@Nullable Object o) {
         if (this == o) {
             return true;
         }
@@ -91,7 +94,7 @@ public String toString() {
      *
      * @return the source location if available or null if it's not.
      */
-    public static SourceLocation getLocation(GraphQLSchemaElement schemaElement) {
+    public static @Nullable SourceLocation getLocation(GraphQLSchemaElement schemaElement) {
         if (schemaElement instanceof GraphQLModifiedType) {
             schemaElement = GraphQLTypeUtil.unwrapAllAs((GraphQLModifiedType) schemaElement);
         }

diff --git a/src/main/java/graphql/language/Type.java b/src/main/java/graphql/language/Type.java
@@ -2,8 +2,10 @@
 
 
 import graphql.PublicApi;
+import org.jspecify.annotations.NullMarked;
 
 @PublicApi
+@NullMarked
 public interface Type<T extends Type> extends Node<T> {
 
 }
diff --git a/src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy b/src/test/groovy/graphql/archunit/JSpecifyAnnotationsCheck.groovy
@@ -99,8 +99,6 @@ class JSpecifyAnnotationsCheck extends Specification {
             "graphql.language.AstSignature",
             "graphql.language.AstSorter",
             "graphql.language.AstTransformer",
-            "graphql.language.Comment",
-            "graphql.language.Definition",
             "graphql.language.DescribedNode",
             "graphql.language.Description",
             "graphql.language.Directive",
@@ -115,8 +113,6 @@ class JSpecifyAnnotationsCheck extends Specification {
             "graphql.language.FieldDefinition",
             "graphql.language.FragmentDefinition",
             "graphql.language.FragmentSpread",
-            "graphql.language.IgnoredChar",
-            "graphql.language.IgnoredChars",
             "graphql.language.ImplementingTypeDefinition",
             "graphql.language.InlineFragment",
             "graphql.language.InputObjectTypeDefinition",
@@ -125,21 +121,15 @@ class JSpecifyAnnotationsCheck extends Specification {
             "graphql.language.InterfaceTypeDefinition",
             "graphql.language.InterfaceTypeExtensionDefinition",
             "graphql.language.ListType",
-            "graphql.language.Node",
-            "graphql.language.NodeChildrenContainer",
             "graphql.language.NodeDirectivesBuilder",
             "graphql.language.NodeParentTree",
-            "graphql.language.NodeVisitor",
-            "graphql.language.NodeVisitorStub",
             "graphql.language.ScalarTypeDefinition",
             "graphql.language.ScalarTypeExtensionDefinition",
             "graphql.language.SchemaDefinition",
             "graphql.language.SchemaExtensionDefinition",
             "graphql.language.Selection",
             "graphql.language.SelectionSet",
             "graphql.language.SelectionSetContainer",
-            "graphql.language.SourceLocation",
-            "graphql.language.Type",
             "graphql.language.TypeKind",
             "graphql.language.TypeName",
             "graphql.language.UnionTypeDefinition",