Skip to content

Commit d1383e4

Browse files
committed
Update note to normative section
1 parent d8c8844 commit d1383e4

File tree

1 file changed

+20
-14
lines changed

1 file changed

+20
-14
lines changed

spec/Section 3 -- Type System.md

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2235,8 +2235,8 @@ fragment someFragment on User {
22352235
#### @defer Arguments
22362236

22372237
- `if: Boolean! = true` - When `true`, fragment _should_ be deferred (see
2238-
related note below). When `false`, fragment must not be deferred. Defaults to
2239-
`true` when omitted.
2238+
[Client handling of `@defer`/`@stream`](#sec-Client-handling-of-defer-stream-)).
2239+
When `false`, fragment must not be deferred. Defaults to `true` when omitted.
22402240
- `label: String` - An optional string literal (variables are disallowed) used
22412241
by GraphQL clients to identify data in the _incremental stream_ and associate
22422242
it with the corresponding defer directive. If provided, the GraphQL service
@@ -2278,10 +2278,11 @@ query myQuery($shouldStream: Boolean! = true) {
22782278

22792279
#### @stream Arguments
22802280

2281-
- `if: Boolean! = true` - When `true`, field _should_ be streamed (see related
2282-
note below). When `false`, the field must behave as if the `@stream` directive
2283-
is not presentit must not be streamed and all of the list items must be
2284-
included. Defaults to `true` when omitted.
2281+
- `if: Boolean! = true` - When `true`, field _should_ be streamed (see
2282+
[Client handling of `@defer`/`@stream`](#sec-Client-handling-of-defer-stream-)).
2283+
When `false`, the field must behave as if the `@stream` directive is not
2284+
present—it must not be streamed and all of the list items must be included.
2285+
Defaults to `true` when omitted.
22852286
- `label: String` - An optional string literal (variables are disallowed) used
22862287
by GraphQL clients to identify data in the _incremental stream_ and associate
22872288
it with the corresponding stream directive. If provided, the GraphQL service
@@ -2293,22 +2294,27 @@ query myQuery($shouldStream: Boolean! = true) {
22932294
error will be raised if the value of this argument is less than `0`. When the
22942295
size of the list is greater than or equal to the value of `initialCount`, the
22952296
GraphQL service _must_ initially include at least as many list items as the
2296-
value of `initialCount` (see related note below).
2297+
value of `initialCount` (see
2298+
[Client handling of `@defer`/`@stream`](#sec-Client-handling-of-defer-stream-)).
22972299

22982300
Note: The
22992301
[Defer And Stream Directive Labels Are Unique](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
23002302
validation rule ensures uniqueness of the values passed to `label` on both the
23012303
`@defer` and `@stream` directives. Variables are disallowed in the `label`
23022304
because their values may not be known during validation.
23032305

2304-
Note: The ability to defer and/or stream data can have a potentially significant
2306+
### Client handling of `@defer`/`@stream`
2307+
2308+
The ability to defer and/or stream data can have a potentially significant
23052309
impact on application performance. Developers generally need clear, predictable
23062310
control over their application's performance. It is highly recommended that
23072311
GraphQL services honor the `@defer` and `@stream` directives on each execution.
23082312
However, the specification allows advanced use cases where the service can
2309-
determine that it is more performant to not defer and/or stream. Therefore,
2310-
GraphQL clients _must_ be able to process a _response_ that ignores individual
2311-
`@defer` and/or `@stream` directives. This also applies to the `initialCount`
2312-
argument on the `@stream` directive. Clients must be able to process a streamed
2313-
field result that contains more initial list items than what was specified in
2314-
the `initialCount` argument.
2313+
determine that it is more performant to not defer and/or stream. Services can
2314+
make this determination on case by case basis; e.g. in a single operation, one
2315+
or more `@defer` and/or `@stream` may be acted upon while others are ignored.
2316+
Therefore, GraphQL clients _must_ be able to process a _response_ that ignores
2317+
individual `@defer` and/or `@stream` directives. This also applies to the
2318+
`initialCount` argument on the `@stream` directive. Clients must be able to
2319+
process a streamed field result that contains more initial list items than what
2320+
was specified in the `initialCount` argument.

0 commit comments

Comments
 (0)