Glossary

[robrichard]

This discussion will be used to document terms related to incremental delivery being used in the GraphQL Spec text:

Response Format

The Response of a GraphQL request will contain a new union member called incremental stream. An incremental stream is made up of an Initial Execution Result, followed by one or more Execution Update Result.

Initial Execution Result:

• The first result yielded by the incremental stream.
• It contains all the same fields as an ExecutionResult, with the addition of new fields required for incremental delivery, hasNext, pending, incremental, completed.

Execution Update Result:

• The incremental stream will yield one or more Execution Update Result after the Initial Execution Result.
• Must not contain top level data or errors
• Must contain hasNext
• May contain pending, incremental, completed.

Pending Result

• These objects are included in the pending array in an initial execution result or execution update result

Incremental Result

• These objects are included in the incremental array in an initial execution result or execution update result

Completed Result

• These objects are included in the completed array in an initial execution result or execution update result

[benjie]

This currently doesn't take into consideration subscriptions:

The result of a GraphQL request can either a single initial response or an incremental stream. An incremental stream is made up of an initial response, followed by one or more subsequent responses.

Perhaps:

The result of a GraphQL request is either a response, a response stream (that is to say: a stream of responses), or an incremental stream. An incremental stream is made up of an initial response, followed by one or more incremental result.

(I've not pluralized "incremental results", because this allows the glossary feature to be used if we move this into the spec.)

To help think about this, here's a rough shape of the things I see in TS syntax:

/** A regular GraphQL response for a traditional GraphQL query/mutation */
interface Response {
  data?: object
  errors?: Error[]
}

/** A stream of responses returned from a GraphQL subscription - each event triggers a new response */
type ResponseStream = Response[];

/** A GraphQL operation that uses @stream/@defer may return an "incremental stream": an initial response followed by one more more incremental results */
type IncrementalStream = [InitialResponse, ...IncrementalResult[]];

interface InitialResponse extends Response {
  pending: ...
  hasNext: true;
}

type IncrementalResult =
  | {
      incremental: IncrementalSomething[]
      pending?: ...
      completed?: ...
      hasNext?: boolean
    }
  | { hasNext: false }

interface IncrementalSomething {
  ...
}

Not sure what to call IncrementalResult nor the nested IncrementalSomething type.

[benjie]

(Obviously some of these things are async iterables or whatever, but easier to represent as lists.)

[robrichard]

From 2025-02-20 wg discussion:

/** A regular GraphQL response for a traditional GraphQL query/mutation */
interface Response {
  data?: object
  errors?: Error[]
}

/** A stream of responses returned from a GraphQL subscription - each event triggers a new response */
type ResponseStream = Response[];

/** A GraphQL operation that uses @stream/@defer may return an "incremental stream": an initial response followed by one more more incremental results */
type IncrementalStream = [InitialResponse, ...SubsequentPayload[]];

interface InitialResponse extends Response {
  incremental: IncrementalResult[]
  pending?: Pending[]
  completed?: CompletedResult[],
  hasNext?: boolean;
}

type SubsequentPayload =
    {
      incremental?: IncrementalResult[]
      pending?: Pending[]
      completed?: CompletedResult[],
      hasNext?: boolean;
    }

type IncrementalResult = IncrementalObjectResult | IncrementalListResult

[robrichard]

In the June 2025 Secondary WG we merged: graphql/graphql-spec#1159 which defines "execution result" and "request error result". Based on this, I am updating the types to:

/** Currently defined types */
type RequestErrorResult = {
  errors: Error[] // request errors only
  extensions?: object
}
type ExecutionResult = {
  data: {} | null
  errors?: Error[] // execution errors only
  extensions?: object
}
type ResponseStream = ExecutionResult[]

/** New types that are yielded by an Incremental Stream */
interface InitialExecutionResult extends ExecutionResult {
  incremental: IncrementalResult[]
  pending?: Pending[]
  completed?: CompletedResult[],
  hasNext?: boolean;
}

type SubsequentExecutionResult = {
  incremental?: IncrementalResult[]
  pending?: Pending[]
  completed?: CompletedResult[],
  hasNext?: boolean;
}

type IncrementalStream = [InitialExecutionResult, ...SubsequentExecutionResult[]];

/** Response is updated to include IncrementalStream as a new member */
type Response = RequestErrorResult | ExecutionResult | ResponseStream | IncrementalStream;

type IncrementalResult = IncrementalObjectResult | IncrementalListResult

[robrichard]

Updated the top level comment to change Subsequent Execution Result > Execution Update Result based on the conversation here: graphql/graphql-spec#1132 (comment)

[martinbonnin]

What about adding those to the general Glossary?

[robrichard]

@martinbonnin i definitely think they should go in the glossary. However, I don't want to add it just yet as we might still iterate on them, but we can start by adding Response and Response Stream after this spec edit is accepted: graphql/graphql-spec#1135

[martinbonnin]

I've been discussing this with @benjie and I think we both agree that we don't want the Glossary to duplicate the spec.

Ultimately, the spec definitions should be the source of truth. I see the glossary as mostly a working document to reach consensus and/or a place to add extra information that's only useful to the spec contributors.

Reason I'm pushing for this is that outside perspective and broad consensus is often useful on naming beyond the scope of a single RFC so I'd like to make that Glossary a bit more of a working document.

But if you're already on good track there, no obligation to put it there, all goot ✅ .