graphql · leebyron · May 17, 2017 · May 2, 2017 · May 2, 2017 · May 2, 2017
diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md
@@ -198,6 +198,67 @@ 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
+  }
+  disallowedSecondRootField
+}
+```
+
+Introspection fields are counted. The following example is also invalid:
+
+```!graphql
+subscription sub {
+  newMessage {
+    body
+    sender
+  }
+  __typename
+}
+```
 
 ## Fields
 

diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md
@@ -103,8 +103,9 @@ Note: This algorithm is very similar to {CoerceArgumentValues()}.
 ## Executing Operations
 
 The type system, as described in the “Type System” section of the spec, must
-provide a query root object type. If mutations are supported, it must also
-provide a mutation root object type.
+provide a query root object type. If mutations or subscriptions are supported, it must also provide a mutation and subscription root object type, respectively.
+
+### Query
 
 If the operation is a query, the result of the operation is the result of
 executing the query’s top level selection set with the query root object type.
@@ -123,6 +124,8 @@ ExecuteQuery(query, schema, variableValues, initialValue):
     selection set.
   * Return an unordered map containing {data} and {errors}.
 
+### Mutation
+
 If the operation is a mutation, the result of the operation is the result of
 executing the mutation’s top level selection set on the mutation root
 object type. This selection set should be executed serially.
@@ -143,6 +146,127 @@ ExecuteMutation(mutation, schema, variableValues, initialValue):
     selection set.
   * Return an unordered map containing {data} and {errors}.
 
+### Subscription
+
+If the operation is a subscription, the result of the operation is the creation
+of a persistent object on the server that exists for the lifetime of the
+subscription.
+
+#### 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 observation, see {Unsubscribe}.
+  * **Must** support a way to send data to the subscriber.
+  * **May** include an initial response associated with executing the selection
+  set defined on the subscription operation.
+
+Most subscriptions can only be evaluated when event data is available. For
+example, a subscription tells us when users log on and off would require event
+data that tells us *who* logged on or off. Without this event data, the
+subscription cannot be evaluated. However, it is possible to define
+subscriptions that can be evaluated without event data (for example, the current
+time on the server, synthetically triggered every second). Subscriptions that do
+not require event data for evaluation can optionally return an initial response
+to the Subscribe() operation.
+
+Subscribe(schema, subscription, operationName, 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)}.
+  * Optionally: let {data} be the result of running {ExecuteRequest(schema, document, operationName, variableValues, initialValue)}, and return {data} on the subscription object.
+
+MapSubscriptionEvents(rootField, variableValues):
+
+  * *Application-specific logic to map from root field/variables to events*
+
+#### Publish
+
+Once a subscription is created, we listen for events on its event stream. Each
+event carries an optional payload, which we combine with the arguments from
+Subscribe() to resolve the selection set.
+
+  * For each {event} and {eventData} on {eventStream}:
+    * Let {data} be the result of running
+      {ExecuteSelectionSet(selectionSet, subscriptionType, eventData, variableValues)}
+      *normally* (allowing parallelization).
+    * Let {errors} be any *field errors* produced while executing the
+      selection set.
+    * If {errors} is not empty, optionally, Unsubscribe() the subscription.
+    * Yield an unordered map containing {data} and, optionally, {errors} on
+      {publishStream}.
+  * Let {publishStream} be the sequence of outputs yielded above.
+
+#### 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()
+
+  * Terminate {publishStream} (For example, cancel iteration, detach mapping function)
+  * Terminate and clean up {eventStream}
+
+#### Example
+
+As an example, consider a chat application. To subscribe to new messages posted
+to the chat room, the client sends a request like so:
+
+```graphql
+subscription NewMessages {
+  newMessage(roomId: 123) {
+    sender
+    text
+  }
+}
+```
+
+While the client is subscribe, whenever new messages are posted to chat room
+with ID "123", the selection for "sender" and "text" will be evaluated and
+published to the client, for example:
+
+```js
+{
+  "data": {
+    "newMessage": {
+      "sender": "Hagrid",
+      "text": "You're a wizard!"
+    }
+  }
+}
+```
+
+#### 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 payload delivery to clients can be
+handled by a dedicated client gateway tier.
+
+For systems with high capacity, availability, and durability requirements, we
+recommend keeping the GraphQL server stateless and delegating all state
+persistence to sub-systems that are designed for stateful scaling. Note that
+subscription types are still defined in the original schema along with queries
+and mutations.
 
 ## Executing Selection Sets