From 176172f6c9e37a3d5f995c80416e76ac44f3867c Mon Sep 17 00:00:00 2001 From: Rob Richard Date: Mon, 24 Feb 2025 14:25:21 -0500 Subject: [PATCH] Address PR feedback --- spec/Section 3 -- Type System.md | 46 ++++++++++++++++---------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 8861f3846..8f7a25183 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2185,9 +2185,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 result may consist of multiple -responses: the initial response containing all non-deferred data, while -subsequent responses include deferred data. +a request includes the `@defer` directive, it may return an _incremental stream_ +consisting of an _intitial response_ containing all non-deferred data, followed +by one or more _subsequent payloads_ including the deferred data. The `@include` and `@skip` directives take precedence over `@defer`. @@ -2212,11 +2212,11 @@ fragment someFragment on User { related note below). When `false`, fragment must 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 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. + by GraphQL clients to identify data in the _incremental stream_ and associate + it with the corresponding defer directive. If provided, the GraphQL service + must include this label in the corresponding pending object within the + _incremental stream_. The `label` argument must be unique across all `@defer` + and `@stream` directives in the document. ### @stream @@ -2230,7 +2230,7 @@ directive @stream( The `@stream` directive may be provided for a field whose type incorporates a `List` type modifier. The directive enables returning a partial list initially, -followed by additional items in subsequent responses. Should the field type +followed by additional items in subsequent payloads. Should the field type incorporate multiple `List` type modifiers, only the outermost list is streamed. Note: The mechanism through which items are streamed is implementation-defined @@ -2262,11 +2262,11 @@ query myQuery($shouldStream: Boolean! = true) { is not present—it must not be streamed and all of the list items must be included. Defaults to `true` when omitted. - `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. + by GraphQL clients to identify data in the _incremental stream_ and associate + it with the corresponding stream directive. If provided, the GraphQL service + must include this label in the corresponding pending object within the + _incremental stream_. The `label` argument must be unique across all `@defer` + and `@stream` directives in the document. Note: The [Defer And Stream Directive Labels Are Unique](#sec-Defer-And-Stream-Directive-Labels-Are-Unique) @@ -2274,14 +2274,14 @@ validation rule ensures uniqueness of the values passed to `label` on both the `@defer` and `@stream` directives. Variables are disallowed in the `label` because their values may not be known during validation. -Note: The ability to defer and/or stream parts of a response can have a -potentially significant impact on application performance. Developers generally -need clear, predictable control over their application's performance. It is -highly recommended that GraphQL services honor the `@defer` and `@stream` -directives on each execution. However, the specification allows advanced use -cases where the service can determine that it is more performant to not defer -and/or stream. Therefore, GraphQL clients _must_ be able to process a response +Note: The ability to defer and/or stream data can have a potentially significant +impact on application performance. Developers generally need clear, predictable +control over their application's performance. It is highly recommended that +GraphQL services honor the `@defer` and `@stream` directives on each execution. +However, the specification allows advanced use cases where the service can +determine that it is more performant to not defer and/or stream. Therefore, +GraphQL clients _must_ be able to process a _response_ or _incremental stream_ that ignores individual `@defer` and/or `@stream` directives. This also applies to the `initialCount` argument on the `@stream` directive. Clients must be able -to process a streamed response that contains more initial list items than what -was specified in the `initialCount` argument. +to process a streamed field result that contains more initial list items than +what was specified in the `initialCount` argument.