[WIP] adding 'subscription' language to GraphQL spec

spec/Appendix B -- Grammar Summary.md

@@ -94,7 +94,7 @@ OperationDefinition :
   - SelectionSet
   - OperationType Name? VariableDefinitions? Directives? SelectionSet
 
-OperationType : one of query mutation
+OperationType : one of query mutation subscription
 
 SelectionSet : { Selection+ }
 

spec/Section 2 -- Language.md

@@ -2,8 +2,8 @@
 
 Clients use the GraphQL query language to make requests to a GraphQL service.
 We refer to these request sources as documents. A document may contain
-operations (queries and mutations are both operations) as well as fragments, a
-common unit of composition allowing for query reuse.
+operations (queries, mutations, and subscriptions are all operations) as well as
+fragments, a common unit of composition allowing for query reuse.
 
 A GraphQL document is defined as a syntactic grammar where terminal symbols are
 tokens (indivisible lexical units). These tokens are defined in a lexical
@@ -192,12 +192,13 @@ OperationDefinition :
   - OperationType Name? VariableDefinitions? Directives? SelectionSet
   - SelectionSet
 
-OperationType : one of `query` `mutation`
+OperationType : one of `query` `mutation` `subscription`
 
-There are two types of operations that GraphQL models:
+There are three types of operations that GraphQL models:
 
   * query - a read-only fetch.
   * mutation - a write followed by a fetch.
+  * subscription - a read-only fetch followed by a subscription.
 
 Each operation is represented by an optional operation name and a selection set.
 
@@ -214,6 +215,19 @@ mutation {
 }
 ```
 
+This subscription operation will retrieve the current number of likes and create
+a subscription to receive the new count as it is updated:
+
+```
+subscription {
+  subscribeToStoryLikes(storyID: 12345) {
+    story {
+      likeCount
+    }
+  }
+}
+```
+
 **Query shorthand**
 
 If a document contains only one query operation, and that query defines no

spec/Section 3 -- Type System.md

@@ -12,8 +12,8 @@ A given GraphQL schema must itself be internally valid. This section describes
 the rules for this validation process where relevant.
 
 A GraphQL schema is represented by a root type for each kind of operation:
-query and mutation; this determines the place in the type system where those
-operations begin.
+query, mutation, and subscription; this determines the place in the type system
+where those operations begin.
 
 All types within a GraphQL schema must have unique names. No two provided types
 may have the same name. No provided type may have a name which conflicts with
@@ -782,12 +782,13 @@ be provided in the same context.
 
 ## Starting types
 
-A GraphQL schema includes types, indicating where query and mutation
-operations start. This provides the initial entry points into the
+A GraphQL schema includes types, indicating where query, mutation, and
+subscription operations start. This provides the initial entry points into the
 type system. The query type must always be provided, and is an Object
-base type. The mutation type is optional; if it is null, that means
-the system does not support mutations. If it is provided, it must
-be an object base type.
+base type. The mutation and subscription types are optional; if either or both
+of these types are null, that means the system does not support that particular
+operation. If a mutation and/or subscription type is provided, it must be an
+object base type.
 
 The fields on the query type indicate what fields are available at
 the top level of a GraphQL query. For example, a basic GraphQL query
@@ -811,4 +812,19 @@ mutation setName {
 ```
 
 Is valid when the type provided for the mutation starting type is not null,
-and has a field named "setName" with a string argument named "name".
+and has a field named "setName" with a string argument named "name". A
+subscription is similar to a mutation in that
+
+```graphql
+subscription subscribeToNameChange {
+  subscribeToNameChange(id: 1) {
+    me {
+      name
+    }
+  }
+}
+```
+
+Is valid when the type provided for the subscription starting type is not null,
+and has a field name "subscribeToNameChange" with an integer argument named
+"id".

spec/Section 4 -- Introspection.md

@@ -117,6 +117,7 @@ type __Schema {
   types: [__Type!]!
   queryType: __Type!
   mutationType: __Type
+  subscriptionType: __Type
   directives: [__Directive!]!
 }
 

spec/Section 6 -- Execution.md

@@ -17,14 +17,16 @@ operations” section.
 ## Evaluating operations
 
 The type system, as described in the “Type System” part of the spec, must
-provide a “Query Root” and a “Mutation Root” object.
+provide a “Query Root” and a “Mutation Root” object, and can provide an optional
+“Subscription Root” object.
 
 If the operation is a mutation, the result of the operation is the result of
 evaluating the mutation’s top level selection set on the “Mutation Root”
 object. This selection set should be evaluated serially.
 
-If the operation is a query, the result of the operation is the result of
-evaluating the query’s top level selection set on the “Query Root” object.
+If the operation is a query or a subscription, the result of the operation is
+the result of evaluating the operation's top level selection set on the “Query
+Root” object or the “Subscription Root” object, respectively.
 
 ## Evaluating selection sets
 

spec/Section 7 -- Response.md

@@ -76,7 +76,9 @@ three described above.
 The `data` entry in the response will be the result of the execution of the
 requested operation. If the operation was a query, this output will be an
 object of the schema's query root type; if the operation was a mutation, this
-output will be an object of the schema's mutation root type.
+output will be an object of the schema's mutation root type; if the operation
+was a subscription, this output will be an object of the schema's subscription
+root type.
 
 If an error was encountered before execution begins, the `data` entry should
 not be present in the result.