PR feedback

Author: robrichard

spec/Section 3 -- Type System.md

@@ -1947,13 +1947,13 @@ GraphQL implementations that support the type system definition language must
 provide the `@deprecated` directive if representing deprecated portions of the
 schema.
 
-GraphQL services are not required to implement the `@defer` and `@stream`
-directives. If either or both of these directives are implemented, they must be
-implemented according to this specification. GraphQL services that do not
-support these directives must not make them available via introspection. The
-[Directives Are Defined](#sec-Directives-Are-Defined) validation rule will
-prevent GraphQL Operations containing the `@defer` or `@stream` directive from
-being executed by a GraphQL service that does not implement these directives.
+GraphQL implementations may provide the `@defer` and/or `@stream` directives. If
+either or both of these directives are provided, they must conform to the
+requirements defined in this specification.
+
+Note: The [Directives Are Defined](#sec-Directives-Are-Defined) validation rule
+ensures that GraphQL Operations containing the `@defer` or `@stream` directives
+cannot be executed by a GraphQL service that does not support them.
 
 GraphQL implementations that support the type system definition language should
 provide the `@specifiedBy` directive if representing custom scalar definitions.
@@ -2181,15 +2181,16 @@ directive @defer(
 ) on FRAGMENT_SPREAD | INLINE_FRAGMENT
 ```
 
-The `@defer` directive may be provided for fragment spreads and inline fragments
-to inform the executor to delay the execution of the current fragment to
-indicate deprioritization of the current fragment. A query with `@defer`
-directive will cause the request to potentially return multiple responses, where
-deferred data is delivered in subsequent responses. `@include` and `@skip` take
-precedence over `@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.
+
+The `@include` and `@skip` directives take precedence over `@defer`.
 
 ```graphql example
-query myQuery($shouldDefer: Boolean) {
+query myQuery($shouldDefer: Boolean! = true) {
   user {
     name
     ...someFragment @defer(label: "someLabel", if: $shouldDefer)
@@ -2208,12 +2209,12 @@ fragment someFragment on User {
 - `if: Boolean! = true` - When `true`, fragment _should_ be deferred (see
   related note below). When `false`, fragment will not be deferred and data will
   be included in the initial response. Defaults to `true` when omitted.
-- `label: String` - May be used by GraphQL clients to identify the data from
-  responses and associate it with the corresponding defer directive. If
-  provided, the GraphQL service must add it to the corresponding pending object
-  in the response. `label` must be unique label across all `@defer` and
-  `@stream` directives in a document. `label` must not be provided as a
-  variable.
+- `label: String` - An optional string literal (variables are disallowed) used
+  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
+  in the document.
 
 ### @stream
 
@@ -2225,19 +2226,25 @@ directive @stream(
 ) on FIELD
 ```
 
-The `@stream` directive may be provided for a field of `List` type so that the
-backend can leverage technology such as asynchronous iterators to provide a
-partial list in the initial response, and additional list items in subsequent
-responses. `@include` and `@skip` take precedence over `@stream`. The
-[Stream Directives Are Used On List Fields](#sec-Stream-Directives-Are-Used-On-List-Fields)
-validation rule is used to prevent the `@stream` directive from being applied to
-a field that is not a `List` type.
+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 in the initial payload,
+and additional list items in subsequent payloads.
+
+The `@include` and `@skip` directives take precedence over `@stream`.
+
+Note: The [Directives Are Defined](#sec-Directives-Are-Defined) validation rule
+ensures that GraphQL Operations containing the `@stream` directive cannot be
+executed by a GraphQL service that does not support this directive.
 
 ```graphql example
-query myQuery($shouldStream: Boolean) {
+query myQuery($shouldStream: Boolean! = true) {
   user {
     friends(first: 10) {
-      nodes @stream(label: "friendsStream", initialCount: 5, if: $shouldStream)
+      nodes
+        @stream(label: "friendsStream", initialCount: 5, if: $shouldStream) {
+        name
+      }
     }
   }
 }
@@ -2248,12 +2255,12 @@ query myQuery($shouldStream: Boolean) {
 - `if: Boolean! = true` - When `true`, field _should_ be streamed (see related
   note below). When `false`, the field will not be streamed and all list items
   will be included in the initial response. Defaults to `true` when omitted.
-- `label: String` - May be used by GraphQL clients to identify the data from
-  responses and associate it with the corresponding stream directive. If
-  provided, the GraphQL service must add it to the corresponding pending object
-  in the response. `label` must be unique label across all `@defer` and
-  `@stream` directives in a document. `label` must not be provided as a
-  variable.
+- `label: String` - An optional string literal (variables are disallowed) used
+  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.
 - `initialCount: Int` - The number of list items the service should return as
   part of the initial response. 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

@@ -11,10 +11,10 @@ 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 results. The response will be a stream of incrementally delivered
-results when the GraphQL service has deferred or streamed data as a result of
+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 results, the first value will be an initial
+contains incrementally delivered payloads, the first value will be an initial
 payload, followed by one or more subsequent payloads.
 
 If the request raised any errors, the response map must contain an entry with
@@ -28,14 +28,14 @@ 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
-results, both the initial payload and all subsequent payloads must contain an
+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
-results, both the initial payload and any subsequent payloads may contain
+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.
@@ -71,7 +71,7 @@ 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
-results, `data` may only be present in the initial payload. `data` must not be
+payloads, `data` may only be present in the initial payload. `data` must not be
 present in any subsequent payloads.
 
 ### Errors
@@ -185,9 +185,9 @@ The response might look like:
 ```
 
 If the field which experienced an error was declared as `Non-Null`, the `null`
-result will bubble up to the next nullable field. In that case, the `path` for
-the error should include the full path to the result field where the error was
-raised, even if that field is not present in the response.
+result will propagate to the next nullable parent field. In that case, the
+`path` for the error should include the full path to the result field where the
+error was raised, even if that field is not present in the response.
 
 For example, if the `name` field from above had declared a `Non-Null` return
 type in the schema, the result would look different but the error reported would
@@ -280,7 +280,7 @@ 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 results,
+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.
 
@@ -321,7 +321,7 @@ payload, or one of the Incremental Results in a prior payload.
 
 The `incremental` entry in the response is a non-empty list of Incremental
 Results. If the response of the GraphQL operation contains incrementally
-delivered results, this field may appear on both the initial and subsequent
+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.