Apply edits along the lines suggested by Lee

Author: benjie

spec/GraphQL.md

@@ -92,10 +92,14 @@ Conformance requirements expressed as algorithms can be fulfilled by an
 implementation of this specification in any way as long as the perceived result
 is equivalent. Algorithms described in this document are written to be easy to
 understand. Implementers are encouraged to include equivalent but optimized
-implementations.
+implementations. Similarly, data collections such as _list_, _set_ and _map_
+also introduce conformance requirements. Implementers are free to use
+alternative data collections as long as the perceived result remains equivalent.
 
 See [Appendix A](#sec-Appendix-Notation-Conventions) for more details about the
-definition of algorithms and other notational conventions used in this document.
+definition of algorithms and other notational conventions used in this document,
+and [Appendix A: Data Collections](#sec-Data-Collections) for specifics of data
+collections and their ordering.
 
 **Non-Normative Portions**
 
@@ -122,11 +126,6 @@ explicitly in prose (e.g. "Note: ") or are set apart in a note block, like this:
 
 Note: This is an example of a non-normative note.
 
-**Lists Are Ordered**
-
-Unless otherwise stated (for example, "an unordered list"), any mention of the
-term "list" in this document indicates an ordered collection.
-
 # [Overview](Section%201%20--%20Overview.md)
 
 # [Language](Section%202%20--%20Language.md)

spec/Section 3 -- Type System.md

@@ -312,7 +312,7 @@ types which implement this Interface are guaranteed to implement those fields.
 Whenever a field claims it will return an Interface type, it will return a valid
 implementing Object type during execution.
 
-A `Union` defines a list of possible types; similar to interfaces, whenever the
+A `Union` defines a set of possible types; similar to interfaces, whenever the
 type system claims a union will be returned, one of the possible types will be
 returned.
 
@@ -1409,7 +1409,7 @@ A valid operation includes typed fragments (in this example, inline fragments):
 ```
 
 Union members may be defined with an optional leading `|` character to aid
-formatting when representing a longer list of possible types:
+formatting when representing a longer set of possible types:
 
 ```raw graphql example
 union SearchResult =
@@ -1474,7 +1474,7 @@ EnumValuesDefinition : { EnumValueDefinition+ }
 EnumValueDefinition : Description? EnumValue Directives[Const]?
 
 GraphQL Enum types, like Scalar types, also represent leaf values in a GraphQL
-type system. However Enum types describe the list of possible values.
+type system. However Enum types describe the set of possible values.
 
 Enums are not references for a numeric value, but are unique values in their own
 right. They may serialize as a string: the name of the represented value.
@@ -1492,7 +1492,7 @@ enum Direction {
 
 **Result Coercion**
 
-GraphQL services must return one of the defined list of possible values. If a
+GraphQL services must return one of the defined set of possible values. If a
 reasonable coercion is not possible they must raise a _field error_.
 
 **Input Coercion**
@@ -1988,7 +1988,7 @@ fragment SomeFragment on SomeType {
 ```
 
 Directive locations may be defined with an optional leading `|` character to aid
-formatting when representing a longer list of possible locations:
+formatting when representing a longer set of possible locations:
 
 ```raw graphql example
 directive @example on

spec/Section 4 -- Introspection.md

@@ -117,6 +117,17 @@ Tools built using GraphQL introspection should respect deprecation by
 discouraging deprecated use through information hiding or developer-facing
 warnings.
 
+**Ordering**
+
+When possible implementations should preserve observable order for unordered
+data collections. For example, if a schema was produced from a source
+{TypeSystemDocument} then introspection of fields, input fields, arguments, enum
+values, directives and so on should produce the same order as found in the
+source.
+
+Note: This recommendation is to improve legibility and stability of schema
+representations.
+
 **Schema Introspection Schema**
 
 The schema introspection system is itself represented as a GraphQL schema. Below