Editorialize change sites

I went through this editorial in two passes. One where I tuned the usage of "operation", "request", and "selection set". I hopefully made these spots slightly clearer, but I'm open to feedback. Second pass was more freeform prose edits in cases where I thought the intended ideas could have been clearer and avoid the query ambiguity in the first place.

Author: leebyron

CONTRIBUTING.md

@@ -51,7 +51,7 @@ move forward. See editor Lee Byron talk about
 
   Once a query is written, it should always mean the same thing and return the
   same shaped result. Future changes should not change the meaning of existing
-  schema or operations or in any other way cause an existing compliant GraphQL
+  schema or requests or in any other way cause an existing compliant GraphQL
   service to become non-compliant for prior versions of the spec.
 
 * **Performance is a feature**

spec/Section 2 -- Language.md

@@ -337,8 +337,8 @@ under-fetching data.
 }
 ```
 
-In this query operation, the `id`, `firstName`, and `lastName` fields form a selection
-set. Selection sets may also contain fragment references.
+In this query operation, the `id`, `firstName`, and `lastName` fields form a
+selection set. Selection sets may also contain fragment references.
 
 
 ## Fields
@@ -408,7 +408,7 @@ Fields are conceptually functions which return values, and occasionally accept
 arguments which alter their behavior. These arguments often map directly to
 function arguments within a GraphQL service's implementation.
 
-In this example, we want to fetch a specific user (requested via the `id`
+In this example, we want to query a specific user (requested via the `id`
 argument) and their profile picture of a specific `size`:
 
 ```graphql example
@@ -1096,7 +1096,9 @@ If not defined as constant (for example, in {DefaultValue}), a {Variable} can be
 supplied for an input value.
 
 Variables must be defined at the top of an operation and are in scope
-throughout the execution of that operation.
+throughout the execution of that operation. Values for those variables are
+provided to a GraphQL service as part of a request so they may be substituted
+in during execution.
 
 In this example, we want to fetch a profile picture size based on the size
 of a particular device:
@@ -1111,10 +1113,8 @@ query getZuckProfile($devicePicSize: Int) {
 }
 ```
 
-Values for those variables are provided to a GraphQL service along with a
-request so they may be substituted during execution. If providing JSON for the
-variables' values, we could run this operation and fetch profilePic of
-size `60` width:
+If providing JSON for the variables' values, we could request a `profilePic` of
+size `60`:
 
 ```json example
 {
@@ -1124,11 +1124,10 @@ size `60` width:
 
 **Variable use within Fragments**
 
-Operation variables can be used within fragments. Operation variables have global scope
-with a given operation, so a variable used within a fragment must be declared
-in any top-level operation that transitively consumes that fragment. If
-a variable is referenced in a fragment and is included by an operation that does
-not define that variable, the operation cannot be executed.
+Variables can be used within fragments. Variables have global scope with a given operation, so a variable used within a fragment must be declared in any
+top-level operation that transitively consumes that fragment. If a variable is
+referenced in a fragment and is included by an operation that does not define
+that variable, that operation is invalid (see [All Variable Uses Defined](#sec-All-Variable-Uses-Defined)).
 
 
 ## Type References
@@ -1146,9 +1145,9 @@ NonNullType :
   - NamedType !
   - ListType !
 
-GraphQL describes the types of data expected by operation variables. Input types
-may be lists of another input type, or a non-null variant of any other
-input type.
+GraphQL describes the types of data expected by arguments and variables.
+Input types may be lists of another input type, or a non-null variant of any
+other input type.
 
 **Semantics**
 
@@ -1188,8 +1187,8 @@ including or skipping a field. Directives provide this by describing additional
 Directives have a name along with a list of arguments which may accept values
 of any input type.
 
-Directives can be used to describe additional information for types, fields, fragments
-and operations.
+Directives can be used to describe additional information for types, fields,
+fragments and operations.
 
 As future versions of GraphQL adopt new configurable execution capabilities,
 they may be exposed via directives. GraphQL services and tools may also provide

spec/Section 3 -- Type System.md

@@ -1,9 +1,9 @@
 # Type System
 
 The GraphQL Type system describes the capabilities of a GraphQL service and is
-used to determine if a request is valid. The type system also describes the
-input types of operation variables to determine if values provided at runtime
-are valid.
+used to determine if a requested operation is valid, to guarantee the type of
+response results, and describes the input types of variables to determine if
+values provided at request time are valid.
 
 TypeSystemDocument : TypeSystemDefinition+
 
@@ -424,8 +424,8 @@ raised (input values are validated before execution begins).
 
 GraphQL has different constant literals to represent integer and floating-point
 input values, and coercion rules may apply differently depending on which type
-of input value is encountered. GraphQL may be parameterized by operation variables,
-the values of which are often serialized when sent over a transport like HTTP. Since
+of input value is encountered. GraphQL may be parameterized by variables, the
+values of which are often serialized when sent over a transport like HTTP. Since
 some common serializations (ex. JSON) do not discriminate between integer
 and floating-point values, they are interpreted as an integer input value if
 they have an empty fractional part (ex. `1.0`) and otherwise as floating-point
@@ -601,14 +601,15 @@ FieldsDefinition : { FieldDefinition+ }
 
 FieldDefinition : Description? Name ArgumentsDefinition? : Type Directives[Const]?
 
-GraphQL operations are hierarchical and composed, describing a tree of information.
-While Scalar types describe the leaf values of these hierarchical operations, Objects
-describe the intermediate levels.
+GraphQL operations are hierarchical and composed, describing a tree of
+information. While Scalar types describe the leaf values of these hierarchical
+operations, Objects describe the intermediate levels.
 
 GraphQL Objects represent a list of named fields, each of which yield a value of
 a specific type. Object values should be serialized as ordered maps, where the
-requested field names (or aliases) are the keys and the result of evaluating
-the field is the value, ordered by the order in which they appear in the operation.
+selected field names (or aliases) are the keys and the result of evaluating
+the field is the value, ordered by the order in which they appear in
+the selection set.
 
 All fields defined within an Object type must not have a name which begins with
 {"__"} (two underscores), as this is used exclusively by GraphQL's
@@ -687,8 +688,8 @@ type Person {
 }
 ```
 
-Valid operations must supply a nested field set for a field that returns
-an object, so this operation is not valid:
+Valid operations must supply a nested field set for any field that returns an
+object, so this operation is not valid:
 
 ```graphql counter-example
 {
@@ -722,7 +723,7 @@ And will yield the subset of each object type queried:
 **Field Ordering**
 
 When querying an Object, the resulting mapping of fields are conceptually
-ordered in the same order in which they were encountered during request execution,
+ordered in the same order in which they were encountered during execution,
 excluding fragments for which the type does not apply and fields or
 fragments that are skipped via `@skip` or `@include` directives. This ordering
 is correctly produced when using the {CollectFields()} algorithm.
@@ -920,7 +921,7 @@ type Person {
 }
 ```
 
-GraphQL operations can optionally specify arguments to their fields to provide
+Operations can optionally specify arguments to their fields to provide
 these arguments.
 
 This example operation:
@@ -932,7 +933,7 @@ This example operation:
 }
 ```
 
-May yield the result:
+May return the result:
 
 ```json example
 {
@@ -948,9 +949,9 @@ Object, Interface, or Union type).
 ### Field Deprecation
 
 Fields in an object may be marked as deprecated as deemed necessary by the
-application. It is still legal to fetch these fields (to ensure existing
-clients are not broken by the change), but the fields should be appropriately
-treated in documentation and tooling.
+application. It is still legal to include these fields in a selection set
+(to ensure existing clients are not broken by the change), but the fields should
+be appropriately treated in documentation and tooling.
 
 When using the type system definition language, `@deprecated` directives are
 used to indicate that a field is deprecated:
@@ -1294,11 +1295,9 @@ type SearchQuery {
 }
 ```
 
-When querying the `firstSearchResult` field of type `SearchQuery`, the
-request would ask for all fields inside of a fragment indicating the appropriate
-type. If the request wanted the name if the result was a Person, and the height if
-it was a photo, the following document is invalid, because the union itself
-defines no fields:
+In this example, a query operation wants the name if the result was a Person,
+and the height if it was a photo. However because a union itself defines no
+fields, this could be ambiguous and is invalid.
 
 ```graphql counter-example
 {
@@ -1309,7 +1308,7 @@ defines no fields:
 }
 ```
 
-Instead, the document would be:
+A valid operation includes typed fragments (in this example, inline fragments):
 
 ```graphql example
 {
@@ -1415,7 +1414,7 @@ reasonable coercion is not possible they must raise a field error.
 GraphQL has a constant literal to represent enum input values. GraphQL string
 literals must not be accepted as an enum input and instead raise a request error.
 
-Operation variable transport serializations which have a different representation
+Variable transport serializations which have a different representation
 for non-string symbolic values (for example, [EDN](https://github.com/edn-format/edn))
 should only allow such values as enum input values. Otherwise, for most
 transport serializations that do not, strings may be interpreted as the enum
@@ -1709,9 +1708,9 @@ exclamation mark is used to denote a field that uses a Non-Null type like this:
 
 **Nullable vs. Optional**
 
-Fields are *always* optional within the context of a selection set, a field may be
-omitted and the selection set is still valid. However fields that return Non-Null types
-will never return the value {null} if queried.
+Fields are *always* optional within the context of a selection set, a field may
+be omitted and the selection set is still valid. However fields that return
+Non-Null types will never return the value {null} if queried.
 
 Inputs (such as field arguments), are always optional by default. However a
 non-null input type is required. In addition to not accepting the value {null},

spec/Section 4 -- Introspection.md

@@ -16,7 +16,7 @@ type User {
 }
 ```
 
-The operation
+A request containing the operation:
 
 ```graphql example
 {
@@ -32,7 +32,7 @@ The operation
 }
 ```
 
-would return
+would produce the result:
 
 ```json example
 {
@@ -259,7 +259,7 @@ Fields
 * `kind` must return `__TypeKind.OBJECT`.
 * `name` must return a String.
 * `description` may return a String or {null}.
-* `fields`: The set of fields request-able on this type.
+* `fields`: The set of fields that can be selected for this type.
   * Accepts the argument `includeDeprecated` which defaults to {false}. If
     {true}, deprecated fields are also returned.
 * `interfaces`: The set of interfaces that an object implements.

spec/Section 5 -- Validation.md

@@ -606,7 +606,8 @@ Conversely the leaf field selections of GraphQL operations
 must be of type scalar or enum. Leaf selections on objects, interfaces,
 and unions without subfields are disallowed.
 
-Let's assume the following additions to the query root operation type of the schema:
+Let's assume the following additions to the query root operation type of
+the schema:
 
 ```graphql example
 extend type Query {
@@ -861,7 +862,7 @@ fragment fragmentOne on Dog {
 
 Fragments must be specified on types that exist in the schema. This
 applies for both named and inline fragments. If they are
-not defined in the schema, the request does not validate.
+not defined in the schema, the fragment is invalid.
 
 For example the following fragments are valid:
 
@@ -1506,7 +1507,8 @@ query ($foo: Boolean = true, $bar: Boolean = false) {
 ```
 
 However the following example is valid because `@skip` has been used only once
-per location, despite being used twice in the document and on the same named field:
+per location, despite being used twice in the operation and on the same
+named field:
 
 ```raw graphql example
 query ($foo: Boolean = true, $bar: Boolean = false) {

spec/Section 6 -- Execution.md

@@ -118,7 +118,8 @@ it must also provide a mutation or subscription root operation type, respectivel
 ### Query
 
 If the operation is a query, the result of the operation is the result of
-executing the operation’s top level selection set with the query root operation type.
+executing the operation’s top level selection set with the query root
+operation type.
 
 An initial value may be provided when executing a query operation.
 
@@ -562,8 +563,8 @@ Fields may include arguments which are provided to the underlying runtime in
 order to correctly produce a value. These arguments are defined by the field in
 the type system to have a specific input type.
 
-At each argument position in an operation may be a literal {Value}, or a {Variable}
-to be provided at runtime.
+At each argument position in an operation may be a literal {Value}, or a
+{Variable} to be provided at runtime.
 
 CoerceArgumentValues(objectType, field, variableValues):
   * Let {coercedValues} be an empty unordered Map.

spec/Section 7 -- Response.md

@@ -38,8 +38,9 @@ in a response during debugging.
 
 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 operation type; if the operation was a mutation, this
-output will be an object of the schema's mutation root operation type.
+object of the schema's query root operation type; if the operation was a
+mutation, this output will be an object of the schema's mutation root
+operation type.
 
 If an error was raised before execution begins, the `data` entry should
 not be present in the result.
@@ -296,8 +297,8 @@ JSON format throughout this document.
 
 Since the result of evaluating a selection set is ordered, the serialized Map of
 results should preserve this order by writing the map entries in the same order
-as those fields were requested as defined by request execution. Producing a
-serialized response where fields are represented in the same order in which
+as those fields were requested as defined by selection set execution. Producing
+a serialized response where fields are represented in the same order in which
 they appear in the request improves human readability during debugging and
 enables more efficient parsing of responses if the order of properties can
 be anticipated.