diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index 8be4928ae..d88c685f9 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -165,11 +165,11 @@ ExecuteMutation(mutation, schema, variableValues, initialValue): ### Subscription If the operation is a subscription, the result is an _event stream_ called the -"Response Stream" where each event in the event stream is the result of -executing the operation for each new event on an underlying "Source Stream". +_response stream_ where each event in the event stream is the result of +executing the operation for each new event on an underlying _source stream_. Executing a subscription operation creates a persistent function on the service -that maps an underlying Source Stream to a returned Response Stream. +that maps an underlying _source stream_ to a returned _response stream_. Subscribe(subscription, schema, variableValues, initialValue): @@ -257,9 +257,9 @@ service details should be chosen by the implementing service. #### Source Stream -A Source Stream is an _event stream_ representing a sequence of root values, -each of which will trigger a GraphQL execution. Like field value resolution, the -logic to create a Source Stream is application-specific. +:: A _source stream_ is an _event stream_ representing a sequence of root +values, each of which will trigger a GraphQL execution. Like field value +resolution, the logic to create a _source stream_ is application-specific. CreateSourceEventStream(subscription, schema, variableValues, initialValue): @@ -294,7 +294,7 @@ operation type. #### Response Stream -Each event from the underlying Source Stream triggers execution of the +Each event from the underlying _source stream_ triggers execution of the subscription _selection set_ using that event's value as the {initialValue}. MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues): @@ -339,7 +339,7 @@ Note: The {ExecuteSubscriptionEvent()} algorithm is intentionally similar to #### Unsubscribe -Unsubscribe cancels the Response Stream when a client no longer wishes to +Unsubscribe cancels the _response stream_ when a client no longer wishes to receive payloads for a subscription. This in turn also cancels the Source Stream, which is a good opportunity to clean up any other resources used by the subscription. diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 8da86c586..daca5bb1f 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -10,7 +10,12 @@ 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. +A GraphQL request returns either a _response_ or a _response stream_. + +### Response + +:: A GraphQL request returns a _response_ when the GraphQL operation is a query +or mutation. A _response_ must be a map. If the request raised any errors, the response map must contain an entry with key `errors`. The value of this entry is described in the "Errors" section. If @@ -35,6 +40,11 @@ Note: When `errors` is present in the response, it may be helpful for it to appear first when serialized to make it more clear when errors are present in a response during debugging. +### Response Stream + +:: A GraphQL request returns a _response stream_ when the GraphQL operation is a +subscription. A _response stream_ must be a stream of _response_. + ### Data The `data` entry in the response will be the result of the execution of the