Merge branch 'main' into fragment-args-2024-amendments

Author: JoviDeCroock

spec/Section 3 -- Type System.md

@@ -58,7 +58,7 @@ via introspection.
 
 [Descriptions](#sec-Descriptions) allow GraphQL service designers to easily
 provide documentation which remains consistent with the capabilities of a
-GraphQL service. Descriptions provided as Markdown (as specified by
+GraphQL service. Descriptions should be provided as Markdown (as specified by
 [CommonMark](https://commonmark.org/)) for every definition in a type system.
 
 GraphQL schema and all other definitions (e.g. types, fields, arguments, etc.)
@@ -775,8 +775,8 @@ type Person {
 }
 ```
 
-Valid operations must supply a _selection set_ for every field of an object
-type, so this operation is not valid:
+Valid operations must supply a _selection set_ for every field whose return type
+is an object type, so this operation is not valid:
 
 ```graphql counter-example
 {

spec/Section 5 -- Validation.md

@@ -334,11 +334,11 @@ CollectSubscriptionFields(objectType, selectionSet, visitedFragments):
     - If {DoesFragmentTypeApply(objectType, fragmentType)} is {false}, continue
       with the next {selection} in {selectionSet}.
     - Let {fragmentSelectionSet} be the top-level selection set of {fragment}.
-    - Let {fragmentCollectedFieldMap} be the result of calling
+    - Let {fragmentCollectedFieldsMap} be the result of calling
       {CollectSubscriptionFields(objectType, fragmentSelectionSet,
       visitedFragments)}.
     - For each {responseName} and {fragmentFields} in
-      {fragmentCollectedFieldMap}:
+      {fragmentCollectedFieldsMap}:
       - Let {fieldsForResponseKey} be the _field set_ value in
         {collectedFieldsMap} for the key {responseName}; otherwise create the
         entry with an empty ordered set.
@@ -349,11 +349,11 @@ CollectSubscriptionFields(objectType, selectionSet, visitedFragments):
       fragmentType)} is {false}, continue with the next {selection} in
       {selectionSet}.
     - Let {fragmentSelectionSet} be the top-level selection set of {selection}.
-    - Let {fragmentCollectedFieldMap} be the result of calling
+    - Let {fragmentCollectedFieldsMap} be the result of calling
       {CollectSubscriptionFields(objectType, fragmentSelectionSet,
       visitedFragments)}.
     - For each {responseName} and {fragmentFields} in
-      {fragmentCollectedFieldMap}:
+      {fragmentCollectedFieldsMap}:
       - Let {fieldsForResponseKey} be the _field set_ value in
         {collectedFieldsMap} for the key {responseName}; otherwise create the
         entry with an empty ordered set.
@@ -591,7 +591,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()} before execution.
+name is accomplished by performing {CollectSubfields()} before their 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

@@ -376,9 +376,9 @@ continues until there are no more subfields to collect and execute.
 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 each field must be executed
-serially, or normally by executing all fields in parallel (see
-[Normal and Serial Execution](#sec-Normal-and-Serial-Execution).
+root type must be known, as well as whether the fields must be executed in a
+series, 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),
 mutations (serial), and subscriptions (where it is executed for each event in
@@ -403,10 +403,9 @@ executionMode):
 ### Field Collection
 
 Before execution, each _selection set_ is converted to a _collected fields map_
-by calling {CollectFields()} by collecting all fields with the same response
-name, including those in referenced fragments, into an individual _field set_.
-This ensures that multiple references to fields with the same response name will
-only be executed once.
+by collecting all fields with the same response name, including those in
+referenced fragments, into an individual _field set_. This ensures that multiple
+references to fields with the same response name will only be executed once.
 
 :: A _collected fields map_ is an ordered map where each entry is a _response
 name_ and its associated _field set_. A _collected fields map_ may be produced
@@ -443,8 +442,8 @@ fragment ExampleFragment on Query {
 }
 ```
 
-The depth-first-search order of the _field set_ produced by {CollectFields()} is
-maintained through execution, ensuring that fields appear in the executed
+The depth-first-search order of each _field set_ produced by {CollectFields()}
+is maintained through execution, ensuring that fields appear in the executed
 response in a stable and predictable order.
 
 CollectFields(objectType, selectionSet, variableValues, visitedFragments,
@@ -494,11 +493,11 @@ fragmentVariables):
     - Let {newFragmentVariables} be an unordered map containing {signatures} and
       {values}.
     - Let {fragmentSelectionSet} be the top-level selection set of {fragment}.
-    - Let {fragmentCollectedFieldMap} be the result of calling
+    - Let {fragmentCollectedFieldsMap} be the result of calling
       {CollectFields(objectType, fragmentSelectionSet, variableValues,
       visitedFragments, newFragmentVariables)}.
     - For each {responseName} and {fragmentFields} in
-      {fragmentCollectedFieldMap}:
+      {fragmentCollectedFieldsMap}:
       - Let {fieldsForResponseName} be the _field set_ value in
         {collectedFieldsMap} for the key {responseName}; otherwise create the
         entry with an empty ordered set.
@@ -509,11 +508,11 @@ fragmentVariables):
       fragmentType)} is {false}, continue with the next {selection} in
       {selectionSet}.
     - Let {fragmentSelectionSet} be the top-level selection set of {selection}.
-    - Let {fragmentCollectedFieldMap} be the result of calling
+    - Let {fragmentCollectedFieldsMap} be the result of calling
       {CollectFields(objectType, fragmentSelectionSet, variableValues,
       visitedFragments, fragmentVariables)}.
     - For each {responseName} and {fragmentFields} in
-      {fragmentCollectedFieldMap}:
+      {fragmentCollectedFieldsMap}:
       - Let {fieldsForResponseName} be the _field set_ value in
         {collectedFieldsMap} for the key {responseName}; otherwise create the
         entry with an empty ordered set.
@@ -537,8 +536,8 @@ directives may be applied in either order since they apply commutatively.
 
 **Merging 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
+In order to execute the sub-selections of an object typed field, all _selection
+sets_ of each field with the same response name in the parent _field set_ are
 merged together into a single _collected fields map_ representing the subfields
 to be executed next.
 
@@ -573,9 +572,9 @@ CollectSubfields(objectType, fields, variableValues):
 - 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 {fieldCollectedFieldMap} be the result of {CollectFields(objectType,
+  - Let {fieldCollectedFieldsMap} be the result of {CollectFields(objectType,
     fieldSelectionSet, variableValues)}.
-  - For each {responseName} and {subfieldInfos} in {fieldCollectedFieldMap}:
+  - For each {responseName} and {subfieldInfos} in {fieldCollectedFieldsMap}:
     - Let {fieldsForResponseName} be the _field set_ value in
       {collectedFieldsMap} for the key {responseName}; otherwise create the
       entry with an empty ordered set.