NextStack
EN 中

graphql-java v26.0

major PublishedApr 23, 2026 Sourcegraphql-java/graphql-java

graphql-java v26.0

This is the 26.0 release of graphql-java. Highlights are summarized below; the full list of merged PRs is at the end.

⚠️ Breaking Changes

Query complexity limits are now enforced by default

New QueryComplexityLimits validation checks maxDepth (default 100) and maxFieldsCount (default 100,000) as part of standard validation. Queries exceeding these limits will now fail with new MaxQueryDepthExceeded / MaxQueryFieldsExceeded validation errors.

  • Set custom limits via GraphQLContext using QueryComplexityLimits.KEY.
  • Disable entirely with QueryComplexityLimits.NONE.

Introduced in #4256.

Validation rule filtering API changed

In #4228 the rule-filter predicate changed from Predicate<Class<?>> to Predicate<OperationValidationRule> in Validator.validateDocument(...) and ParseAndValidate.parseAndValidate(...). Callers that filtered by class (e.g. rule -> rule != NoUnusedFragments.class) must migrate to the enum (rule -> rule != OperationValidationRule.NO_UNUSED_FRAGMENTS). The @Internal classes AbstractRule and RulesVisitor were removed.

Built-in directive handling consolidated (#4229)

  • DirectiveInfo was removed. Replace usages:
    • DirectiveInfo.isGraphqlSpecifiedDirective(...) → Directives.isBuiltInDirective(...)
    • DirectiveInfo.GRAPHQL_SPECIFICATION_DIRECTIVES → Directives.BUILT_IN_DIRECTIVES
    • DirectiveInfo.GRAPHQL_SPECIFICATION_DIRECTIVE_MAP → Directives.BUILT_IN_DIRECTIVES_MAP
  • Directive ordering is now consistent: all 7 built-in directives appear first, followed by user-defined directives.
  • GraphQLSchema.Builder.clearDirectives() was initially removed then re-added in #4276 with new semantics — it clears all additionalDirectives, but built-in directives are always re-added automatically at build time.

OneOf inhabitability validation (#4248)

New validator rejects OneOf input types that cannot be populated with a finite value (e.g. input A @oneOf { a: A }). Schemas that previously validated may now be rejected.

Non-null field validation for code-built schemas (#4194)

Code-built schemas now perform the same deprecated-on-non-null field validation as SDL-built ones. Schemas relying on the gap may now fail validation.

GraphQLSchema.getCodeRegistry() is no longer @Nullable (#4247)

The return type was incorrectly annotated nullable. Callers may now drop redundant null checks; downstream nullness tooling will reflect the change.

JSpecify nullability annotations rolled out broadly

Waves 2 and 3 (#4184, #4274) plus many individual PRs annotated hundreds of classes across graphql.analysis, graphql.execution, graphql.language, graphql.schema and others with @NullMarked/@NullUnmarked/@Nullable. Kotlin and other null-aware callers will now see stricter nullability contracts; code that relied on previously-permissive signatures may need adjustment.

✨ New Features

  • GraphQLSchema.FastBuilder (#4197) — a more restrictive but ~5× faster schema builder that reduces both time and memory for large schemas.
  • Query complexity limits (#4256) — depth/field-count guardrails baked into validation (see breaking changes above for the enforcement side).
  • QueryAppliedDirective on operations and documents (#4297) — directives applied at the operation/document level are now exposed as QueryAppliedDirectives.
  • New instrumentation hook for post-exception-handling results (#4206, #4207) — observe the DataFetcherResult after DataFetcherExceptionHandler has mapped exceptions to errors. ChainedInstrumentation delegates the new hook correctly.
  • Generic DataFetcherResult.newBuilder(T data) (#4254) — removes the need for explicit type witnesses on the common DataFetcherResult.<T>newResult().data(x)... pattern.
  • Re-added GraphQLSchema.Builder.clearDirectives() (#4276) — useful with GraphQLSchema.transform to rewrite non-built-in directives; built-ins are always re-added.
  • toString() on AST directives holders (#4195).

⚡ Performance

  • Incremental @defer execution starts earlier (#4174) — begins processing deferred payloads as soon as the first incremental call is detected instead of waiting for the initial result to complete.
  • Validation consolidation (#4228) — all operation validation rules run in a single OperationValidator pass, significantly cutting validation overhead.
  • Reduced allocations on the execution hot path (#4252):
    • Async$Many.materialisedList() — replaced ArrayList copy with a zero-copy Arrays.asList() wrapper.
    • ResultPath.toStringValue — lazy computation; the string form is only built on first toString() (typically only during error reporting).
    • New GraphQLCodeRegistry.getDataFetcher(String, String, GraphQLFieldDefinition) overload avoiding per-fetch FieldCoordinates allocations (~54 KB/op reduction).
  • FastBuilder for schema construction (#4197) — see New Features.
  • Fixed ShallowTypeRefCollector to also resolve type refs inside applied directive arguments and enum value definitions (#4288) — correctness fix enabling FastBuilder to be used on more schemas.

🐛 Other Noteworthy Changes

Execution / data fetching

  • DataLoader dispatch with multiple @defer fragments (#4270) — fixes a case where DataLoaders were not dispatched correctly when multiple deferred fragments were in play.
  • CompletionStageSubscriber race condition (#4296) — completion signal could be lost if an in-flight CompletionStage resolved concurrently. Fix is backed by new jcstress stress tests.
  • PropertyDataFetcher on non-public classes (#4287) — properties on non-public classes that implement public interfaces (e.g. TreeMap.Entry) now fetch correctly on Java 16+ by searching public interfaces.
  • ExecutableNormalizedField respects GraphqlFieldVisibility (#4204) — selection-set APIs now use the schema’s configured visibility instead of going straight to the type.
  • ScheduledDataLoaderRegistry “dispatch all” fix (#4164).
  • ChainedInstrumentation onExceptionHandled delegation (#4207).

Schema / field visibility

  • Fixes for complex field-visibility transformer cases and schema transformation when deletions cascade (#4203, #4205, #4208, #4209, #4212, #4213, #4275).
  • Overlapping-fields null-type regression fixed (#4291).
  • GraphQLTypeCollectingVisitor now recursively traverses indirect strong references (#4213).
  • SchemaTraverser::depthFirst overload signature fix (#4165).

Build / packaging / security

  • Bytecode-modified classes no longer ship in published JARs (#4343) — the @Generated annotation injected for coverage reporting was leaking into published artifacts. JARs now contain pristine compiler output.
  • Trojan Source / glassworm Unicode detection (#4344) — pre-commit hook and CI workflow now reject dangerous BiDi/zero-width/control characters in source.
  • Windows compatibility (#4239) — removed colons from performance-results/ filenames, split the oversized large-schema-5.graphqls, added pre-commit + CI checks.

Tooling / DX

  • getDataLoader type bounds improved (#4180).
  • Build and test on Java 25 (#4173, #4330).
  • Many dependency updates (Reactor, Jackson, Kotlin, Groovy, Gradle, ByteBuddy, errorprone, etc.) across the release.

Full PR list

Expand to see all merged PRs

New Contributors

Full Changelog: https://github.com/graphql-java/graphql-java/compare/v25.0…v26.0

Source graphql-java/graphql-java · v26.0 · 2026-04-23 · upstream release

Mirrored verbatim for indexing. All rights belong to the upstream project.

Release notes are published by the upstream project and mirrored here for indexing. All rights belong to their authors.