Lee editorial + manual merge #1161

Author: leebyron

spec/Section 3 -- Type System.md

@@ -757,7 +757,7 @@ type Person {
 }
 ```
 
-Valid operations must supply a selection of fields for any field that returns an
+Valid operations must supply a _selection set_ for any field which returns an
 object, so this operation is not valid:
 
 ```graphql counter-example

spec/Section 5 -- Validation.md

@@ -468,7 +468,7 @@ should be unambiguous. Therefore any two field selections which might both be
 encountered for the same object are only valid if they are equivalent.
 
 During execution, the simultaneous execution of fields with the same response
-name is accomplished by {CollectSubfields()}.
+name is accomplished by {CollectSubfields()} before execution.
 
 For simple hand-written GraphQL, this rule is obviously a clear developer error,
 however nested fragments can make this difficult to detect manually.

spec/Section 6 -- Execution.md

@@ -348,21 +348,20 @@ Unsubscribe(responseStream):
 
 ## Executing Selection Sets
 
-The process of executing a GraphQL operation is to recursively execute every
-selected field in the operation. To do this, first all initially selected fields
-from the operation's top most _root selection set_ are collected, then each
-executed. As each field completes, all its subfields are collected, then each
-executed. This process continues until there are no more subfields to collect
-and execute.
+Executing a GraphQL operation recursively collects and executes every selected
+field in the operation. First all initially selected fields from the operation's
+top most _root selection set_ are collected, then each executed. As each field
+completes, all its subfields are collected, then each executed. This process
+continues until there are no more subfields to collect and execute.
 
 ### Executing the Root Selection Set
 
 :: A _root selection set_ is the top level _selection set_ provided by a GraphQL
 operation. A root selection set always selects from a _root operation type_.
 
 To execute the root selection set, the initial value being evaluated and the
-root type must be known, as well as whether it must be executed serially, or may
-be executed in parallel (see
+root type must be known, as well as whether each field must be executed
+serially, or normally by executing all fields in parallel (see
 [Normal and Serial Execution](#sec-Normal-and-Serial-Execution).
 
 Executing the root selection set works similarly for queries (parallel),
@@ -386,22 +385,23 @@ executionMode):
 
 ### Field Collection
 
-Before execution, the _root selection set_ is converted to a _grouped field set_
-by calling {CollectFields()}. This ensures all fields with the same response
-name, including those in referenced fragments, are executed at the same time.
+Before execution, each _selection set_ is converted to a _grouped field set_ by
+calling {CollectFields()}. This ensures all fields with the same response name,
+including those in referenced fragments, are executed at the same time.
 
 :: A _grouped field set_ is a map where each entry is a _response name_ and its
 associated _field set_. A _grouped field set_ may be produced from a selection
 set via {CollectFields()} or from the selection sets of a _field set_ via
 {CollectSubfields()}.
 
-:: A _field set_ is a list of selected fields that share the same _response
-name_ (the field alias if defined, otherwise the field's name).
+:: A _field set_ is an ordered set of selected fields that share the same
+_response name_ (the field alias if defined, otherwise the field's name).
+Validation ensures each field in the set has the same name and arguments,
+however each may have different subfields (see:
+[Field Selection Merging](#sec-Field-Selection-Merging)).
 
 Note: The order of field selections in a _field set_ is significant, hence the
-algorithms in this specification model it as a list. Any later duplicated field
-selections in a field set will not impact its interpretation, so using an
-ordered set would yield equivalent results.
+algorithms in this specification model it as an ordered set.
 
 As an example, collecting the fields of this query's selection set would result
 in a grouped field set with two entries, `"a"` and `"b"`, with two instances of
@@ -430,7 +430,7 @@ response in a stable and predictable order.
 CollectFields(objectType, selectionSet, variableValues, visitedFragments):
 
 - If {visitedFragments} is not provided, initialize it to the empty set.
-- Initialize {groupedFields} to an empty ordered map of lists.
+- Initialize {groupedFieldSet} to an empty ordered map of ordered sets.
 - For each {selection} in {selectionSet}:
   - If {selection} provides the directive `@skip`, let {skipDirective} be that
     directive.
@@ -445,9 +445,9 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):
   - If {selection} is a {Field}:
     - Let {responseName} be the _response name_ of {selection} (the alias if
       defined, otherwise the field name).
-    - Let {groupForResponseName} be the list in {groupedFields} for
-      {responseName}; if no such list exists, create it as an empty list.
-    - Append {selection} to the {groupForResponseName}.
+    - Let {fieldsForResponseName} be the _field set_ in {groupedFieldSet} for
+      {responseName}; if no such set exists, create it as an empty set.
+    - Append {selection} to the {fieldsForResponseName}.
   - If {selection} is a {FragmentSpread}:
     - Let {fragmentSpreadName} be the name of {selection}.
     - If {fragmentSpreadName} is in {visitedFragments}, continue with the next
@@ -467,9 +467,9 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):
     - For each {fragmentGroup} in {fragmentGroupedFieldSet}:
       - Let {responseName} be the response name shared by all fields in
         {fragmentGroup}.
-      - Let {groupForResponseName} be the list in {groupedFields} for
-        {responseName}; if no such list exists, create it as an empty list.
-      - Append all items in {fragmentGroup} to {groupForResponseName}.
+      - Let {fieldsForResponseName} be the _field set_ in {groupedFieldSet} for
+        {responseName}; if no such set exists, create it as an empty set.
+      - Append all items in {fragmentGroup} to {fieldsForResponseName}.
   - If {selection} is an {InlineFragment}:
     - Let {fragmentType} be the type condition on {selection}.
     - If {fragmentType} is not {null} and {DoesFragmentTypeApply(objectType,
@@ -482,32 +482,32 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):
     - For each {fragmentGroup} in {fragmentGroupedFieldSet}:
       - Let {responseName} be the response name shared by all fields in
         {fragmentGroup}.
-      - Let {groupForResponseName} be the list in {groupedFields} for
-        {responseName}; if no such list exists, create it as an empty list.
-      - Append all items in {fragmentGroup} to {groupForResponseName}.
-- Return {groupedFields}.
+      - Let {fieldsForResponseName} be the _field set_ in {groupedFieldSet} for
+        {responseName}; if no such set exists, create it as an empty set.
+      - Append all items in {fragmentGroup} to {fieldsForResponseName}.
+- Return {groupedFieldSet}.
 
 DoesFragmentTypeApply(objectType, fragmentType):
 
 - If {fragmentType} is an Object Type:
   - If {objectType} and {fragmentType} are the same type, return {true},
     otherwise return {false}.
 - If {fragmentType} is an Interface Type:
-  - If {objectType} is an implementation of {fragmentType}, return {true}
+  - If {objectType} is an implementation of {fragmentType}, return {true},
     otherwise return {false}.
 - If {fragmentType} is a Union:
-  - If {objectType} is a possible type of {fragmentType}, return {true}
+  - If {objectType} is a possible type of {fragmentType}, return {true},
     otherwise return {false}.
 
 Note: The steps in {CollectFields()} evaluating the `@skip` and `@include`
 directives may be applied in either order since they apply commutatively.
 
 **Merging Selection Sets**
 
-When a field is executed, during value completion the _selection set_ of each of
-the related field selections with the same response name are collected together
-to produce a single _grouped field set_ in order to continue execution of the
-sub-selection sets.
+In order to execute the sub-selections of a object typed field, all _selection
+sets_ of each field with the same response name of the parent _field set_ are
+merged together into a single _grouped field set_ representing the subfields to
+be executed next.
 
 An example operation illustrating parallel fields with the same name with
 sub-selections.
@@ -536,16 +536,16 @@ phase with the same value.
 
 CollectSubfields(objectType, fields, variableValues):
 
-- Let {groupedFieldSet} be an empty map.
+- Let {groupedFieldSet} be an empty ordered map of ordered sets.
 - For each {field} in {fields}:
   - Let {fieldSelectionSet} be the selection set of {field}.
   - If {fieldSelectionSet} is null or empty, continue to the next field.
   - Let {fieldGroupedFieldSet} be the result of {CollectFields(objectType,
     fieldSelectionSet, variableValues)}.
   - For each {fieldGroupedFieldSet} as {responseName} and {subfields}:
-    - Let {groupForResponseName} be the list in {groupedFieldSet} for
-      {responseName}; if no such list exists, create it as an empty list.
-    - Append all fields in {subfields} to {groupForResponseName}.
+    - Let {fieldsForResponseName} be the _field set_ in {groupedFieldSet} for
+      {responseName}; if no such set exists, create it as an empty set.
+    - Add each fields in {subfields} to {fieldsForResponseName}.
 - Return {groupedFieldSet}.
 
 Note: All the {fields} passed to {CollectSubfields()} share the same _response
@@ -558,10 +558,8 @@ the field selections from a _selection set_ or the associated selection sets of
 a _field set_ respectively, and split them into groups by their _response name_
 to produce a _grouped field set_.
 
-To execute a _grouped field set_, the object value being evaluated and the
-object type need to be known, as well as whether it must be executed serially,
-or may be executed in parallel (see
-[Normal and Serial Execution](#sec-Normal-and-Serial-Execution).
+To execute a _grouped field set_, the object type being evaluated and the
+runtime value need to be known, as well as the runtime values for any variables.
 
 Each entry in the grouped field set represents a _response name_ which produces
 an entry into a result map.