Editorial: Define _response payload_

[robrichard]

Follow up from #1135, Based on top of #1148

Alternative name Response Map: #1143

This creates a definition for Response Payload, defined as the map normally returned by GraphQL queries and mutations containing data and/or errors.

The definition of Response is updated to include both Response Payload, and Response Stream (for subscriptions).

I like using Payload as i think it extends naturally for incremental delivery. If this change is approved I plan to add two additional types, InitialResponsePayload and SubsequentResponsePayload as well as IncrementalStream, the stream of those types.

Proposal for incremental delivery (roughly):

type ResponsePayload = {
  data?: object
  errors?: Error[]
  extensions?: object
}
type ResponseStream = ResponsePayload[]
type IncrementalStream = [InitialResponsePayload, ...SubsequentResponsePayload];
type Response = ResponsePayload | ResponseStream | IncrementalStream;

I went through every mention of response and most of the remaining usages are around response key or response field, referring to the object property name (ie for aliases and error paths). This could also likely be standardized in a follow up. See https://github.com/graphql/graphql-spec/pull/1147/files

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	d9bbd4e
🔍 Latest deploy log	https://app.netlify.com/sites/graphql-spec-draft/deploys/67ee75d4924a5b0008a0b7a9
😎 Deploy Preview	https://deploy-preview-1149--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[benjie]

I approve, I think this makes it a lot clearer.

[benjie]

The term "payload" is used twice in the spec currently, each time to refer to the {data,errors} object that a subscription stream may yield on each event. This is consistent with our use of "response payload" here, so I approve 👍

[benjie]

Note to other reviewers: this line contains a subtle fix to the wording. 👍

[Keweiqu]

This sentence is no longer accurate. A GraphQL query with incremental delivery no longer returns a response payload.

[robrichard]

Yes, this section will be updated in the Incremental Delivery spec draft: #1124. I'll update it once we have settled on the terms here.

[robrichard]

Superseded by #1159