Spec edits for incremental delivery, Section 3 & 7 only

spec/Appendix C -- Examples.md

@@ -0,0 +1,191 @@
+# C. Appendix: Examples
+
+## Incremental Delivery Examples
+
+### Example 1 - A query containing both defer and stream
+
+```graphql example
+query {
+  person(id: "cGVvcGxlOjE=") {
+    ...HomeWorldFragment @defer(label: "homeWorldDefer")
+    name
+    films @stream(initialCount: 1, label: "filmsStream") {
+      title
+    }
+  }
+}
+fragment HomeWorldFragment on Person {
+  homeWorld {
+    name
+  }
+}
+```
+
+The incremental stream might look like:
+
+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 Results indicating
+that results for both the `@defer` and `@stream` in the query will be delivered
+in the subsequent responses.
+
+```json example
+{
+  "data": {
+    "person": {
+      "name": "Luke Skywalker",
+      "films": [{ "title": "A New Hope" }]
+    }
+  },
+  "pending": [
+    { "id": "0", "path": ["person"], "label": "homeWorldDefer" },
+    { "id": "1", "path": ["person", "films"], "label": "filmsStream" }
+  ],
+  "hasNext": true
+}
+```
+
+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
+{
+  "incremental": [
+    {
+      "id": "0",
+      "data": { "homeWorld": { "name": "Tatooine" } }
+    },
+    {
+      "id": "1",
+      "items": [{ "title": "The Empire Strikes Back" }]
+    }
+  ],
+  "completed": [
+    {"id": "0"}
+  ]
+  "hasNext": true
+}
+```
+
+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
+{
+  "incremental": [
+    {
+      "id": "1",
+      "items": [{ "title": "Return of the Jedi" }]
+    }
+  ],
+  "hasNext": true
+}
+```
+
+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
+{
+  "hasNext": false
+}
+```
+
+### Example 2 - A query containing overlapping defers
+
+```graphql example
+query {
+  person(id: "cGVvcGxlOjE=") {
+    ...HomeWorldFragment @defer(label: "homeWorldDefer")
+    ...NameAndHomeWorldFragment @defer(label: "nameAndWorld")
+    firstName
+  }
+}
+fragment HomeWorldFragment on Person {
+  homeWorld {
+    name
+    terrain
+  }
+}
+
+fragment NameAndHomeWorldFragment on Person {
+  firstName
+  lastName
+  homeWorld {
+    name
+  }
+}
+```
+
+The incremental stream might look like:
+
+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 Results indicating that
+results for both `@defer`s in the query will be delivered in the subsequent
+responses.
+
+```json example
+{
+  "data": {
+    "person": {
+      "firstName": "Luke"
+    }
+  },
+  "pending": [
+    { "id": "0", "path": ["person"], "label": "homeWorldDefer" },
+    { "id": "1", "path": ["person"], "label": "nameAndWorld" }
+  ],
+  "hasNext": true
+}
+```
+
+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
+path of this result can be determined by concatenating the path from the Pending
+Result with id `"0"` and this `subPath` entry.
+
+```json example
+{
+  "incremental": [
+    {
+      "id": "0",
+      "data": { "homeWorld": { "name": "Tatooine" } }
+    },
+    {
+      "id": "0",
+      "subPath": ["homeWorld"],
+      "data": { "terrain": "desert" }
+    }
+  ],
+  "completed": [{ "id": "0" }],
+  "hasNext": true
+}
+```
+
+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
+{
+  "incremental": [
+    {
+      "id": "1",
+      "data": { "lastName": "Skywalker" }
+    }
+  ],
+  "completed": [{ "id": "1" }],
+  "hasNext": false
+}
+```

spec/GraphQL.md

@@ -139,3 +139,5 @@ Note: This is an example of a non-normative note.
 # [Appendix: Notation Conventions](Appendix%20A%20--%20Notation%20Conventions.md)
 
 # [Appendix: Grammar Summary](Appendix%20B%20--%20Grammar%20Summary.md)
+
+# [Appendix: Examples](Appendix%20C%20--%20Examples.md)

spec/Section 3 -- Type System.md

@@ -794,8 +794,8 @@ And will yield the subset of each object type queried:
 When querying an Object, the resulting mapping of fields are conceptually
 ordered in the same order in which they were encountered during execution,
 excluding fragments for which the type does not apply and fields or fragments
-that are skipped via `@skip` or `@include` directives. This ordering is
-correctly produced when using the {CollectFields()} algorithm.
+that are skipped via `@skip` or `@include` directives or postponed via `@defer`.
+This ordering is correctly produced when using the {CollectFields()} algorithm.
 
 Response serialization formats capable of representing ordered maps should
 maintain this ordering. Serialization formats which can only represent unordered
@@ -1948,6 +1948,15 @@ GraphQL implementations that support the type system definition language must
 provide the `@deprecated` directive if representing deprecated portions of the
 schema.
 
+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 can only include directives available on the
+schema; thus operations including `@defer` or `@stream` directives can only be
+executed by a GraphQL service that supports them.
+
 GraphQL implementations that support the type system definition language should
 provide the `@specifiedBy` directive if representing custom scalar definitions.
 
@@ -2164,3 +2173,115 @@ to the relevant IETF specification.
 ```graphql example
 scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")
 ```
+
+### @defer
+
+```graphql
+directive @defer(
+  if: Boolean! = true
+  label: String
+) on FRAGMENT_SPREAD | INLINE_FRAGMENT
+```
+
+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.
+
+The `@include` and `@skip` directives take precedence over `@defer`.
+
+```graphql example
+query myQuery($shouldDefer: Boolean! = true) {
+  user {
+    name
+    ...someFragment @defer(label: "someLabel", if: $shouldDefer)
+  }
+}
+fragment someFragment on User {
+  id
+  profile_picture {
+    uri
+  }
+}
+```
+
+#### @defer Arguments
+
+- `if: Boolean! = true` - When `true`, fragment _should_ be deferred (see
+  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.
+
+### @stream
+
+```graphql
+directive @stream(
+  initialCount: Int! = 0
+  if: Boolean! = true
+  label: String
+) on FIELD
+```
+
+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
+incorporate multiple `List` type modifiers, only the outermost list is streamed.
+
+Note: The mechanism through which items are streamed is implementation-defined
+and may use technologies such as asynchronous iterators.
+
+The `@include` and `@skip` directives take precedence over `@stream`.
+
+```graphql example
+query myQuery($shouldStream: Boolean! = true) {
+  user {
+    friends(first: 10)
+      @stream(label: "friendsStream", initialCount: 5, if: $shouldStream) {
+      name
+    }
+  }
+}
+```
+
+#### @stream Arguments
+
+- `initialCount: Int! = 0` - The number of list items to include initially. If
+  omitted, defaults to `0`. A field error will be raised if the value of this
+  argument is less than `0`. When the size of the list is greater than or equal
+  to the value of `initialCount`, the GraphQL service _must_ initially include
+  at least as many list items as the value of `initialCount` (see related note
+  below).
+- `if: Boolean! = true` - When `true`, field _should_ be streamed (see related
+  note below). When `false`, the field must behave as if the `@stream` directive
+  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.
+
+Note: The
+[Defer And Stream Directive Labels Are Unique](#sec-Defer-And-Stream-Directive-Labels-Are-Unique)
+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
+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.