diff --git a/spec/Appendix B -- Grammar Summary.md b/spec/Appendix B -- Grammar Summary.md index 1cccaaf3d..00c9dc634 100644 --- a/spec/Appendix B -- Grammar Summary.md +++ b/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+ } diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index afc55c172..3252a0721 100644 --- a/spec/Section 2 -- Language.md +++ b/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 diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 046d14677..836f3d20f 100644 --- a/spec/Section 3 -- Type System.md +++ b/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". diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index b63255842..90b61e024 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -117,6 +117,7 @@ type __Schema { types: [__Type!]! queryType: __Type! mutationType: __Type + subscriptionType: __Type directives: [__Directive!]! } diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index 935fff9e3..18723d6fa 100644 --- a/spec/Section 6 -- Execution.md +++ b/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 diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 8a92498f0..65598a567 100644 --- a/spec/Section 7 -- Response.md +++ b/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.