Clarify: serialization formats (#437)

Factors out a section on Map ordering which was duplicated between the previous two subsections.

Also clarifies that a different serialization format may use whichever natively supported primitives it likes.

Closes #337

Author: leebyron

spec/Section 7 -- Response.md

@@ -13,42 +13,36 @@ the case that a field error occurred on a field which was replaced with null.
 
 GraphQL does not require a specific serialization format. However, clients
 should use a serialization format that supports the major primitives in the
-GraphQL response. In particular, the serialization format must support
+GraphQL response. In particular, the serialization format must at least support
 representations of the following four primitives:
 
  * Map
  * List
  * String
  * Null
 
-Serialization formats which can represent an ordered map should preserve the
-order of requested fields as defined by {CollectFields()} in the Execution
-section. Serialization formats which can only represent unordered maps
-(such as JSON) should retain this order textually. That is, if two fields
-`{foo, bar}` were queried in that order, the resulting JSON serialization
-should contain `{"foo": "...", "bar": "..."}` in the same order.
-
-Producing a 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.
-
-A serialization format may support the following primitives, however, strings
-may be used as a substitute for those primitives.
+A serialization format should also support the following primitives, each
+representing one of the common GraphQL scalar types, however a string or simpler
+primitive may be used as a substitute if any are not directly supported:
 
  * Boolean
  * Int
  * Float
  * Enum Value
 
+This is not meant to be an exhaustive list of what a serialization format may
+encode. For example custom scalars representing a Date, Time, URI, or number
+with a different precision may be represented in whichever relevant format a
+given serialization format may support.
+
 
 ### JSON Serialization
 
-JSON is the preferred serialization format for GraphQL, though as noted above,
-GraphQL does not require a specific serialization format. For consistency and
-ease of notation, examples of the response are given in JSON throughout the
-spec. In particular, in our JSON examples, we will represent primitives using
-the following JSON concepts:
+JSON is the most common serialization format for GraphQL. Though as mentioned
+above, GraphQL does not require a specific serialization format.
+
+When using JSON as a serialization of GraphQL responses, the following JSON
+values should be used to encode the related GraphQL values:
 
 | GraphQL Value | JSON Value        |
 | ------------- | ----------------- |
@@ -61,23 +55,37 @@ the following JSON concepts:
 | Float         | Number            |
 | Enum Value    | String            |
 
-**Object Property Ordering**
+Note: For consistency and ease of notation, examples of responses are given in
+JSON format throughout this document.
+
+
+### Serialized Map Ordering
+
+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 query 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.
+
+Serialization formats which represent an ordered map should preserve the
+order of requested fields as defined by {CollectFields()} in the Execution
+section. Serialization formats which only represent unordered maps but where
+order is still implicit in the serialization's textual order (such as JSON)
+should preserve the order of requested fields textually.
+
+For example, if the request was `{ name, age }`, a GraphQL service responding in
+JSON should respond with `{ "name": "Mark", "age": 30 }` and should not respond
+with `{ "age": 30, "name": "Mark" }`.
 
 While JSON Objects are specified as an
 [unordered collection of key-value pairs](https://tools.ietf.org/html/rfc7159#section-4)
 the pairs are represented in an ordered manner. In other words, while the JSON
 strings `{ "name": "Mark", "age": 30 }` and `{ "age": 30, "name": "Mark" }`
 encode the same value, they also have observably different property orderings.
 
-Since the result of evaluating a selection set is ordered, the JSON object
-serialized should preserve this order by writing the object properties in the
-same order as those fields were requested as defined by query execution.
-
-For example, if the query was `{ name, age }`, a GraphQL server responding in
-JSON should respond with `{ "name": "Mark", "age": 30 }` and should not respond
-with `{ "age": 30, "name": "Mark" }`.
-
-NOTE: This does not violate the JSON spec, as clients may still interpret
+Note: This does not violate the JSON spec, as clients may still interpret
 objects in the response as unordered Maps and arrive at a valid value.