Glossary

[robrichard]

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

Response Format

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.

Initial response:

• This is the GraphQL Response format we have today, pre @defer and @stream.
• data, errors, extensions.
• With the introduction of @defer and @stream, it may also be the first response from an incremental stream. If so, it must contain hasNext: true and may contain pending, incremental, completed.

Subsequent response:

• The incremental stream will yield one or more subsequent responses after the initial response
• 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 or subsequent response

Incremental Result

• These objects are included in the incremental array in an initial or subsequent response

Completed Result

• These objects are included in the completed array in an initial or subsequent response

[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

[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 ✅ .