Spring GraphQL schema nullability: trace one field failure through the response

Treat the schema as an executable contract

The fixture declares receipt(id: ID!) as nullable because an ID can be absent or outside the tenant. It declares receipts(limit: Int!) as a non-null list of non-null Receipt values. A request without limit fails validation before the fetcher runs. A request selecting only id and available returns those fields; tenant is absent from the result, even though it exists on the server-side record. Field selection changes the response shape, not the authorization rule.

The source kit builds the schema from an in-memory resource through GraphQlSource. A deployed Boot endpoint would load schema files and register controller or fetcher beans separately. This fixture does not expose an HTTP route. The test-layer lesson separates schema execution from transport registration.

Follow non-null propagation

The list fetcher rejects limit 47. Because receipts is declared non-null, its failure bubbles through the root query and the execution result has errors with null data. A nullable receipt lookup instead returns receipt: null for a missing or cross-tenant ID without nulling the entire query. Design nullability around actual failure semantics; making every field non-null can turn one unavailable child into a much larger null result. Error handling is part of that choice.

Checked excerpt

type Query {
  receipt(id: ID!): Receipt
  receipts(limit: Int!): [Receipt!]!
}
type Receipt {
  id: ID!
  tenant: String!
  available: Int!
  version: Int!
}

Verification boundary

The Java 21 / Spring Boot 4 source kit checks selectedFieldsAreReturnedForAuthorizedTenant, missingRequiredArgumentIsRejectedBeforeFetcher and oversizedListRequestReturnsGraphQlError.

Cost and limits

GraphQL validates each operation against the schema before execution. The schema does not itself cap query depth, aliases or nested database work. This direct test has no HTTP endpoint or production query-cost policy.

Common Mistakes

• Do not equate a selected field with permission to see its value.
• Do not mark a failure-prone field non-null without tracing propagation.
• Do not assume required arguments are equivalent to business validation.

Read next

Spring GraphQL errors: distinguish validation, resolver failure and nullable data, Spring GraphQL list bounds: reject large arguments before reading rows, Spring GraphQL tenant reads: scope every resolver before returning a record, Spring GraphQL service tests: stop short of claiming an HTTP endpoint, Spring MVC validation errors: one public ProblemDetail for two failure paths.