Skip to content

Commit f8994fc

Browse files
committed
Update note to normative section
1 parent 391caaa commit f8994fc

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
@@ -2366,8 +2366,8 @@ fragment someFragment on User {
23662366
#### @defer Arguments
23672367

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

24102410
#### @stream Arguments
24112411

2412-
- `if: Boolean! = true` - When `true`, field _should_ be streamed (see related
2413-
note below). When `false`, the field must behave as if the `@stream` directive
2414-
is not presentit must not be streamed and all of the list items must be
2415-
included. Defaults to `true` when omitted.
2412+
- `if: Boolean! = true` - When `true`, field _should_ be streamed (see
2413+
[Client handling of `@defer`/`@stream`](#sec-Client-handling-of-defer-stream-)).
2414+
When `false`, the field must behave as if the `@stream` directive is not
2415+
presentit must not be streamed and all of the list items must be included.
2416+
Defaults to `true` when omitted.
24162417
- `label: String` - An optional string literal (variables are disallowed) used
24172418
by GraphQL clients to identify data in the _incremental stream_ and associate
24182419
it with the corresponding stream directive. If provided, the GraphQL service
@@ -2424,22 +2425,27 @@ query myQuery($shouldStream: Boolean! = true) {
24242425
error will be raised if the value of this argument is less than `0`. When the
24252426
size of the list is greater than or equal to the value of `initialCount`, the
24262427
GraphQL service _must_ initially include at least as many list items as the
2427-
value of `initialCount` (see related note below).
2428+
value of `initialCount` (see
2429+
[Client handling of `@defer`/`@stream`](#sec-Client-handling-of-defer-stream-)).
24282430

24292431
Note: The
24302432
[Defer And Stream Directive Labels Are Unique](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
24312433
validation rule ensures uniqueness of the values passed to `label` on both the
24322434
`@defer` and `@stream` directives. Variables are disallowed in the `label`
24332435
because their values may not be known during validation.
24342436

2435-
Note: The ability to defer and/or stream data can have a potentially significant
2437+
### Client handling of `@defer`/`@stream`
2438+
2439+
The ability to defer and/or stream data can have a potentially significant
24362440
impact on application performance. Developers generally need clear, predictable
24372441
control over their application's performance. It is highly recommended that
24382442
GraphQL services honor the `@defer` and `@stream` directives on each execution.
24392443
However, the specification allows advanced use cases where the service can
2440-
determine that it is more performant to not defer and/or stream. Therefore,
2441-
GraphQL clients _must_ be able to process a _response_ that ignores individual
2442-
`@defer` and/or `@stream` directives. This also applies to the `initialCount`
2443-
argument on the `@stream` directive. Clients must be able to process a streamed
2444-
field result that contains more initial list items than what was specified in
2445-
the `initialCount` argument.
2444+
determine that it is more performant to not defer and/or stream. Services can
2445+
make this determination on case by case basis; e.g. in a single operation, one
2446+
or more `@defer` and/or `@stream` may be acted upon while others are ignored.
2447+
Therefore, GraphQL clients _must_ be able to process a _response_ that ignores
2448+
individual `@defer` and/or `@stream` directives. This also applies to the
2449+
`initialCount` argument on the `@stream` directive. Clients must be able to
2450+
process a streamed field result that contains more initial list items than what
2451+
was specified in the `initialCount` argument.

0 commit comments

Comments
 (0)