Spec: Formal Subscriptions Definition

spec/Section 5 -- Validation.md

@@ -198,6 +198,70 @@ query getName {
 }
 ```
 
+### Subscription Operation Definitions
+
+#### Single root field
+
+**Formal Specification**
+
+  * For each subscription operation definition {subscription} in the document
+  * Let {rootFields} be the top level selection set on {subscription}.
+    * {rootFields} must be a set of one.
+
+**Explanatory Text**
+
+Subscription operations must have exactly one root field.
+
+Valid examples:
+
+```graphql
+subscription sub {
+  newMessage {
+    body
+    sender
+  }
+}
+```
+
+```graphql
+fragment newMessageFields on Message {
+  body
+  sender
+}
+
+subscription sub {
+  newMessage {
+    ... newMessageFields  
+  }
+}
+```
+
+Invalid:
+
+```!graphql
+subscription sub {
+  newMessage {
+    body
+    sender
+  }
+  # a second root field will cause this operation to fail validation
+  alarms {
+    name
+    snoozeCount
+  }
+}
+```
+
+```!graphql
+subscription sub {
+  newMessage {
+    body
+    sender
+  }
+  # this also applies to introspection fields
+  __typename
+}
+```
 
 ## Fields
 

spec/Section 6 -- Execution.md

@@ -143,6 +143,84 @@ ExecuteMutation(mutation, schema, variableValues, initialValue):
     selection set.
   * Return an unordered map containing {data} and {errors}.
 
+Unlike queries and mutations, subscriptions have a lifetime that consists of three
+phases. Between the the subscribe and unsubscribe phases, the subscription is
+considered to be in the "active" state.
+
+### Subscribe
+
+The result of executing a subscription operation is a subscription object with
+the following capabilities:
+
+  * **must** support observation of the associated publish stream (for example,
+  via iteration, callbacks, or reactive semantics).
+  * **must** support cancellation of the subscription (aka unsubscribe).
+  * **must** support a way to identify the subscriber/subscription pair (for
+    example, a GUID/callback table or closure over the callback).
+  * **may** include an initial response associated with executing the selection
+  set defined on the subscription operation.
+
+Subscribe(subscription, schema, variableValues, initialValue):
+
+  * Let {subscriptionType} be the root Subscription type in {schema}.
+  * Assert: {subscriptionType} is an Object type.
+  * Let {selectionSet} be the top level Selection Set in {subscription}.
+  * Let {rootField} be the first top level field in {selectionSet}.
+  * Let {eventStream} be the result of running {MapSubscriptionEvents(rootField, variableValues)}.
+  * Let {publishStream} be a mapping of {eventStream} where each {event} is
+    mapped via Publish().
+
+MapSubscriptionEvents(rootField, variableValues):
+
+  * *Application-specific logic to map from root field/variables to events*
+
+### Publish
+
+Publish(subscription, schema, variableValues, payload, publishStream)
+
+  * For each {eventStream} as {event} and {payload}:
+    * Let {data} be the result of running
+      {ExecuteSelectionSet(selectionSet, subscriptionType, payload, variableValues)}
+      *normally* (allowing parallelization).
+    * Let {errors} be any *field errors* produced while executing the
+      selection set.
+    * If {errors} is not empty, optionally terminate the subscription.
+    * Yield an unordered map containing {data} and, optionally, {errors} on
+      {publishStream}.
+
+### Unsubscribe
+
+The unsubscribe operation can be implemented in a number of ways. For example,
+by using a dedicated subscription manager, defining it as a method on the
+subscription object, or cancelling the iterator.
+
+Unsubscribe()
+
+  * Let {publishStream} be a mapping of {null}
+  * Terminate and clean up {eventStream}
+
+### Recommendations and Considerations for Supporting Subscriptions
+
+Supporting subscriptions is a large change for any GraphQL server. Query and
+mutation operations are stateless, allowing scaling via cloning GraphQL server
+instances. Subscriptions, by contrast, are stateful. The pieces of state for a
+subscription are:
+
+  * Subscriber/client channel
+  * Subscription document
+  * Variables
+  * Execution context (for example, current logged in user, locale, etc.)
+  * Event stream resulting from Subscribe step (above)
+
+We recommend thinking about the behavior of your system when this state is lost
+due to single-node failures. We can improve durability and availability by using
+dedicated sub-systems to manage this state. For example, event streams can be
+built using modern pub-sub systems, and client channels can be handled with a
+dedicated client gateway.
+
+Rather than mixing stateless (queries and mutations) and stateful
+(subscriptions), we recommend keeping the GraphQL server stateless and
+delegating all state persistence these sub-systems.
 
 ## Executing Selection Sets