payload -> response

Author: robrichard

spec/Appendix C -- Examples.md

@@ -21,13 +21,13 @@ fragment HomeWorldFragment on Person {
 }
 ```
 
-The response stream might look like:
+The incremental stream might look like:
 
-Payload 1, the initial response does not contain any deferred or streamed
-results in the `data` entry. The initial response contains a `hasNext` entry,
-indicating that subsequent payloads will be delivered. There are two Pending
-Responses indicating that results for both the `@defer` and `@stream` in the
-query will be delivered in the subsequent payloads.
+The initial response does not contain any deferred or streamed results in the
+`data` entry. The initial response contains a `hasNext` entry, indicating that
+subsequent responses will be delivered. There are two Pending Responses
+indicating that results for both the `@defer` and `@stream` in the query will be
+delivered in the subsequent responses.
 
 ```json example
 {
@@ -45,9 +45,9 @@ query will be delivered in the subsequent payloads.
 }
 ```
 
-Payload 2, contains the deferred data and the first streamed list item. There is
-one Completed Result, indicating that the deferred data has been completely
-delivered.
+Subsequent response 1, contains the deferred data and the first streamed list
+item. There is one Completed Result, indicating that the deferred data has been
+completely delivered.
 
 ```json example
 {
@@ -68,10 +68,10 @@ delivered.
 }
 ```
 
-Payload 3, contains the final stream payload. In this example, the underlying
-iterator does not close synchronously so {hasNext} is set to {true}. If this
-iterator did close synchronously, {hasNext} would be set to {false} and this
-would be the final response.
+Subsequent response 2, contains the final stream results. In this example, the
+underlying iterator does not close synchronously so {hasNext} is set to {true}.
+If this iterator did close synchronously, {hasNext} would be set to {false} and
+this would be the final response.
 
 ```json example
 {
@@ -85,9 +85,9 @@ would be the final response.
 }
 ```
 
-Payload 4, contains no incremental data. {hasNext} set to {false} indicates the
-end of the response stream. This response is sent when the underlying iterator
-of the `films` field closes.
+Subsequent response 3, contains no incremental data. {hasNext} set to {false}
+indicates the end of the incremental stream. This response is sent when the
+underlying iterator of the `films` field closes.
 
 ```json example
 {
@@ -121,14 +121,14 @@ fragment NameAndHomeWorldFragment on Person {
 }
 ```
 
-The response stream might look like:
+The incremental stream might look like:
 
-Payload 1, the initial response contains the results of the `firstName` field.
-Even though it is also present in the `HomeWorldFragment`, it must be returned
-in the initial payload because it is also defined outside of any fragments with
-the `@defer` directive. Additionally, There are two Pending Responses indicating
+The initial response contains the results of the `firstName` field. Even though
+it is also present in the `HomeWorldFragment`, it must be returned in the
+initial response because it is also defined outside of any fragments with the
+`@defer` directive. Additionally, There are two Pending Responses indicating
 that results for both `@defer`s in the query will be delivered in the subsequent
-payloads.
+responses.
 
 ```json example
 {
@@ -145,10 +145,10 @@ payloads.
 }
 ```
 
-Payload 2, contains the deferred data from `HomeWorldFragment`. There is one
-Completed Result, indicating that `HomeWorldFragment` has been completely
-delivered. Because the `homeWorld` field is present in two separate `@defer`s,
-it is separated into its own Incremental Result.
+Subsequent response 1, contains the deferred data from `HomeWorldFragment`.
+There is one Completed Result, indicating that `HomeWorldFragment` has been
+completely delivered. Because the `homeWorld` field is present in two separate
+`@defer`s, it is separated into its own Incremental Result.
 
 The second Incremental Result contains the data for the `terrain` field. This
 incremental result contains a `subPath` property to indicate to clients that the
@@ -173,9 +173,9 @@ Result with id `"0"` and this `subPath` entry.
 }
 ```
 
-Payload 3, contains the remaining data from the `NameAndHomeWorldFragment`.
-`lastName` is the only remaining field that has not been delivered in a previous
-payload.
+Subsequent response 2, contains the remaining data from the
+`NameAndHomeWorldFragment`. `lastName` is the only remaining field that has not
+been delivered in a previous response.
 
 ```json example
 {

spec/Section 3 -- Type System.md

@@ -2182,9 +2182,9 @@ directive @defer(
 
 The `@defer` directive may be provided on a fragment spread or inline fragment
 to indicate that execution of the related selection set should be deferred. When
-a request includes the `@defer` directive, the response may consist of multiple
-payloads: the initial payload containing all non-deferred data, while subsequent
-payloads include deferred data.
+a request includes the `@defer` directive, the result may consist of multiple
+responses: the initial response containing all non-deferred data, while
+subsequent responses include deferred data.
 
 The `@include` and `@skip` directives take precedence over `@defer`.
 
@@ -2209,7 +2209,7 @@ fragment someFragment on User {
   related note below). When `false`, fragment will not be deferred. Defaults to
   `true` when omitted.
 - `label: String` - An optional string literal (variables are disallowed) used
-  by GraphQL clients to identify data from payloads and associate it with the
+  by GraphQL clients to identify data from responses and associate it with the
   corresponding defer directive. If provided, the GraphQL service must include
   this label in the corresponding pending object within the response. The
   `label` argument must be unique across all `@defer` and `@stream` directives
@@ -2228,7 +2228,7 @@ directive @stream(
 The `@stream` directive may be provided for a field whose type incorporates a
 `List` type modifier; the directive enables the backend to leverage technology
 such as asynchronous iterators to provide a partial list initially, and
-additional list items in subsequent payloads.
+additional list items in subsequent responses.
 
 The `@include` and `@skip` directives take precedence over `@stream`.
 
@@ -2255,11 +2255,11 @@ query myQuery($shouldStream: Boolean! = true) {
   note below). When `false`, the field will not be streamed and all list items
   will be initially included. Defaults to `true` when omitted.
 - `label: String` - An optional string literal (variables are disallowed) used
-  by GraphQL clients to identify data from payloads and associate it with the
+  by GraphQL clients to identify data from responses and associate it with the
   corresponding stream directive. If provided, the GraphQL service must include
-  this label in the corresponding pending object within the response. The
-  `label` argument must be unique across all `@defer` and `@stream` directives
-  in the document.
+  this label in the corresponding pending object within the result. The `label`
+  argument must be unique across all `@defer` and `@stream` directives in the
+  document.
 - `initialCount: Int` - The number of list items the service should return
   initially. If omitted, defaults to `0`. A field error will be raised if the
   value of this argument is less than `0`.

spec/Section 7 -- Response.md

@@ -10,53 +10,74 @@ the case that any _field error_ was raised on a field and was replaced with
 
 ## Response Format
 
-A response to a GraphQL request must be a map or a stream of incrementally
-delivered payloads. The response will be a stream of incrementally delivered
-payloads when the GraphQL service has deferred or streamed data as a result of
-the `@defer` or `@stream` directives. When the response of the GraphQL operation
-contains incrementally delivered payloads, the first value will be an initial
-payload, followed by one or more subsequent payloads.
+The result of a GraphQL request must be either a single initial response or an
+incremental stream. The response will be an incremental stream when the GraphQL
+service has deferred or streamed data as a result of the `@defer` or `@stream`
+directives. When the result of the GraphQL operation is an incremental stream,
+the first value will be an initial response, followed by one or more subsequent
+responses.
+
+### Initial Response
+
+An initial response must be a map.
 
 If the request raised any errors, the response map must contain an entry with
 key `errors`. The value of this entry is described in the "Errors" section. If
 the request completed without raising any errors, this entry must not be
 present.
 
-If the request included execution, the response map must contain an entry with
-key `data`. The value of this entry is described in the "Data" section. If the
-request failed before execution, due to a syntax error, missing information, or
-validation error, this entry must not be present.
-
-When the response of the GraphQL operation contains incrementally delivered
-payloads, both the initial payload and all subsequent payloads must contain an
-entry with key `hasNext`. The value of this entry must be {true} for all but the
-last response in the stream. The value of this entry must be {false} for the
-last response of the stream. This entry must not be present for GraphQL
-operations that return a single response map.
-
-When the response of the GraphQL operation contains incrementally delivered
-payloads, both the initial payload and any subsequent payloads may contain
-entries with the keys `pending`, `incremental`, and/or `completed`. The value of
-these entries are described in the "Pending", "Incremental", and "Completed"
-sections below.
-
-The response map may also contain an entry with key `extensions`. This entry, if
-set, must have a map as its value. This entry is reserved for implementers to
-extend the protocol however they see fit, and hence there are no additional
-restrictions on its contents. When the response of the GraphQL operation is a
-response stream, the initial payload and any subsequent payloads may contain an
-entry with the key `extensions`, also reserved for implementers to extend the
-protocol however they see fit. Additionally, implementers may send subsequent
-payloads containing only `hasNext` and `extensions` entries.
+If the request included execution, the initial response map must contain an
+entry with key `data`. The value of this entry is described in the "Data"
+section. If the request failed before execution, due to a syntax error, missing
+information, or validation error, this entry must not be present.
+
+When the result of the GraphQL operation is an incremental stream, the initial
+response must contain an entry with key `hasNext`. The value of this entry must
+be {true}. This entry must not be present for GraphQL operations that result in
+a single initial response.
+
+When the result of the GraphQL operation is an incremental stream, the initial
+response may contain entries with the keys `pending`, `incremental`, and/or
+`completed`. The value of these entries are described in the "Pending",
+"Incremental", and "Completed" sections below.
+
+The initial response map may also contain an entry with key `extensions`. This
+entry, if set, must have a map as its value. This entry is reserved for
+implementers to extend the protocol however they see fit, and hence there are no
+additional restrictions on its contents.
 
 To ensure future changes to the protocol do not break existing services and
-clients, the top level response map must not contain any entries other than the
+clients, the initial response map must not contain any entries other than the
 entries described above.
 
-Note: When `errors` is present in the response, it may be helpful for it to
-appear first when serialized to make it more clear when errors are present in a
+Note: When `errors` is present in a response, it may be helpful for it to appear
+first when serialized to make it more clear when errors are present in a
 response during debugging.
 
+### Subsequent Response
+
+When the result of the GraphQL operation is an incremental stream, the first
+value will be an initial response, followed by one or more subsequent responses.
+A subsequent response must be a map.
+
+Each subsequent response must contain an entry with key `hasNext`. The value of
+this entry must be {true} for all but the last response in the stream. The value
+of this entry must be {false} for the last response of the stream.
+
+Each subsequent response may contain entries with the keys `pending`,
+`incremental`, and/or `completed`. The value of these entries are described in
+the "Pending", "Incremental", and "Completed" sections below.
+
+The subsequent response map may also contain an entry with key `extensions`.
+This entry, if set, must have a map as its value. This entry is reserved for
+implementers to extend the protocol however they see fit, and hence there are no
+additional restrictions on its contents. Implementers may send subsequent
+responses containing only `hasNext` and `extensions` entries.
+
+To ensure future changes to the protocol do not break existing services and
+clients, the initial response map must not contain any entries other than the
+entries described above.
+
 ### Data
 
 The `data` entry in the response will be the result of the execution of the
@@ -70,9 +91,9 @@ present in the result.
 If an error was raised during the execution that prevented a valid response, the
 `data` entry in the response should be `null`.
 
-When the response of the GraphQL operation contains incrementally delivered
-payloads, `data` may only be present in the initial payload. `data` must not be
-present in any subsequent payloads.
+When the response of the GraphQL operation is an incremental stream, `data` may
+only be present in the initial response. `data` must not be present in any
+subsequent responses.
 
 ### Errors
 
@@ -280,24 +301,24 @@ field which experienced the error.
 ### Pending
 
 The `pending` entry in the response is a non-empty list of Pending Results. If
-the response of the GraphQL operation contains incrementally delivered payloads,
-this field may appear on both the initial and subsequent payloads. If present,
-the `pending` entry must contain at least one Pending Result.
+the response of the GraphQL operation is an incremental stream, this field may
+appear on both the initial and subsequent responses. If present, the `pending`
+entry must contain at least one Pending Result.
 
 Each Pending Result corresponds to either a `@defer` or `@stream` directive
 located at a specific path in the response data. The Pending Result is used to
 communicate that the GraphQL service has chosen to incrementally deliver the
 data associated with this `@defer` or `@stream` directive and clients should
-expect the associated data in either the current payload, or one of the
-following payloads.
+expect the associated data in either the current response, or one of the
+following responses.
 
 **Pending Result Format**
 
 Every Pending Result must contain an entry with the key `id` with a string
 value. This `id` should be used by clients to correlate Pending Results with
 Completed Results. The `id` value must be unique for the entire response stream.
-There must not be any other Pending Result in any payload that contains the same
-`id`.
+There must not be any other Pending Result in any response that contains the
+same `id`.
 
 Every Pending Result must contain an entry with the key `path`. When the Pending
 Result is associated with a `@stream` directive, it indicates the response list
@@ -315,15 +336,14 @@ argument.
 If a Pending Result is not returned for a `@defer` or `@stream` directive,
 clients must assume that the GraphQL service chose not to incrementally deliver
 this data, and the data can be found either in the `data` entry in the initial
-payload, or one of the Incremental Results in a prior payload.
+response, or one of the Incremental Results in a prior subsequent response.
 
 ### Incremental
 
 The `incremental` entry in the response is a non-empty list of Incremental
-Results. If the response of the GraphQL operation contains incrementally
-delivered payloads, this field may appear on both the initial and subsequent
-values. If present, the `incremental` entry must contain at least one
-Incremental Result.
+Results. If the response of the GraphQL operation is an incremental stream, this
+field may appear on both the initial and subsequent responses. If present, the
+`incremental` entry must contain at least one Incremental Result.
 
 The Incremental Result is used to deliver data that the GraphQL service has
 chosen to incrementally deliver. An Incremental Result may be ether an
@@ -410,14 +430,14 @@ the "Errors" section.
 ### Completed
 
 The `completed` entry in the response is a non-empty list of Completed Results.
-If the response of the GraphQL operation contains incrementally delivered
-results, this field may appear on both the initial and subsequent payloads. If
-present, the `completed` entry must contain at least one Completed Result.
+If the response of the GraphQL operation is an incremental stream, this field
+may appear on both the initial and subsequent responses. If present, the
+`completed` entry must contain at least one Completed Result.
 
 Each Completed Result corresponds to a prior Pending Result. The Completed
 Result is used to communicate that the GraphQL service has completed the
 incremental delivery of the data associated with the corresponding Pending
-Result. The associated data must have been completed in the current payload.
+Result. The associated data must have been completed in the current response.
 
 **Completed Result Format**