fixes based on Benji's feedback - reversed several fixes to discuss them separately

romanivantsov · romanivantsov · commit a6a8e9188ffb · 2022-06-09T08:59:43.000-07:00
diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md
@@ -1172,8 +1172,8 @@ VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
 
 DefaultValue : = Value[Const]
 
-A GraphQL operation can be parameterized with variables
-maximizing reuse of parsed queries by the GraphQL service.
+A GraphQL operation can be parameterized with variables, maximizing reuse, and
+avoiding costly string building in clients at runtime.
 
 If not defined as constant (for example, in {DefaultValue}), a {Variable} can be
 supplied for an input value.
diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md
@@ -216,6 +216,14 @@ system definition language can omit the schema definition when the {`query`},
 {`mutation`}, and {`subscription`} root types are named {"Query"}, {"Mutation"},
 and {"Subscription"} respectively.
 
+Likewise, when representing a GraphQL schema using the type system definition
+language, a schema definition should be omitted if it only uses the default root
+operation type names.
+
+Likewise, when representing a GraphQL schema using the type system definition
+language, a schema definition should be omitted if it only uses the default root
+operation type names.
+
 This example describes a valid complete GraphQL schema, despite not explicitly
 including a {`schema`} definition. The {"Query"} type is presumed to be the
 {`query`} root operation type of the schema.
@@ -850,9 +858,8 @@ Produces the ordered result:
 
 **Result Coercion**
 
-Determining the result of coercing an object is a part of the GraphQL request execution,
-so this is covered in the [Coercing Results](#sec-Value-Completion.Coercing-Results)
-section within the Execution section.
+Determining the result of coercing an object is the heart of the GraphQL
+executor, so this is covered in that section of the spec.
 
 **Input Coercion**
 
diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md
@@ -574,16 +574,16 @@ fragment conflictingDifferingResponses on Pet {
 **Formal Specification**
 
 - For each {selection} in the document:
-  - Let {selectionType} be the result type of {selection}.
-  - If {selectionType} is a scalar, enum or list of those types:
+  - Let {selectionType} be the unwrapped result type of {selection}.
+  - If {selectionType} is a scalar or enum:
     - The subselection set of that selection must be empty.
   - If {selectionType} is an interface, union, object or list of those types:
     - The subselection set of that selection must NOT BE empty.
 
 **Explanatory Text**
 
-Field selections on scalars, enums or list of those types are never allowed, because they are the
-leaf nodes of any GraphQL operation.
+Scalars and enums are the underlying type of leaf nodes of any GraphQL
+operation. Field selections are never allowed on leaf nodes.
 
 The following is valid.
 
@@ -603,9 +603,9 @@ fragment scalarSelectionsNotAllowedOnInt on Dog {
 }
 ```
 
-Conversely the leaf field selections of GraphQL operations must be of type
-scalar, enum, or list of those types. Leaf selections on objects, interfaces, unions 
-or list of those types without subfields are disallowed.
+Conversely the underlying type of leaf field selections of GraphQL operations
+must be scalar or enum. Leaf selections without subfields on fields whose
+underlying type is object, interface, or union are disallowed.
 
 Let's assume the following additions to the query root operation type of the
 schema:
diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md
@@ -221,7 +221,7 @@ must receive no more events from that event stream.
 
 **Supporting Subscriptions at Scale**
 
-Supporting subscriptions is a significant challenge for a GraphQL service. Query
+Supporting subscriptions is a significant change for any GraphQL service. Query
 and mutation operations are stateless, allowing scaling via cloning of GraphQL
 service instances. Subscriptions, by contrast, are stateful and require
 maintaining the GraphQL document, variables, and other context over the lifetime
@@ -235,12 +235,12 @@ connectivity.
 **Delivery Agnostic**
 
 GraphQL subscriptions do not require any specific serialization format or
-transport mechanism. Subscriptions specify parameters for the creation of a
-stream, the content of each payload on that stream, and the closing of that
-stream. There are intentionally no specifications for message acknowledgement,
-buffering, resend requests, or any other quality of service (QoS) details.
-Message serialization, transport mechanisms, and quality of service details
-should be chosen by the implementing service.
+transport mechanism. GraphQL specifies algorithms for the creation of a
+subscription stream, the content of each payload on that stream, and the closing
+of that stream. There are intentionally no specifications for message
+acknowledgement, buffering, resend requests, or any other quality of service
+(QoS) details. Message serialization, transport mechanisms, and quality of
+service details should be chosen by the implementing service.
 
 #### Source Stream
 
@@ -395,7 +395,7 @@ completion before it continues on to the next item in the grouped field set:
 For example, given the following selection set to be executed serially:
 
 ```graphql example
-mutation {
+{
   changeBirthday(birthday: $newBirthday) {
     month
   }
@@ -417,7 +417,7 @@ As an illustrative example, let's assume we have a mutation field
 we execute the following selection set serially:
 
 ```graphql example
-mutation {
+{
   first: changeTheNumber(newNumber: 1) {
     theNumber
   }
diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md
@@ -61,7 +61,8 @@ contains should indicate why no data was able to be returned.
 
 If the `data` entry in the response is present (including if it is the value
 {null}), the `errors` entry in the response may contain any field errors that
-were raised during execution. 
+were raised during execution. If field errors were raised during execution, it
+should contain those errors.
 
 **Request Errors**
 
