From 5eaa640c8ef5c1c043ee87d223e4f4b04a306d11 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 1 Jul 2016 14:49:02 -0700 Subject: [PATCH] Loosen must to should for serialization supporting ordered maps. GraphQL should work correctly with many serialization techniques, not just JSON. Even within JSON, the GraphQL spec mentions ordered maps while the JSON spec describes unordered maps. This changes the language in the GraphQL spec to: * Use should instead of must where ordered map support might not be possible, thus supporting more environments. * Add clarifying language to JSON encoding section describing expectations for ordering. Fixes #168 --- spec/Section 3 -- Type System.md | 12 ++++++------ spec/Section 7 -- Response.md | 18 +++++++++++++++--- 2 files changed, 21 insertions(+), 9 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 74163fd1b..c80d6a5d0 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -241,7 +241,7 @@ While Scalar types describe the leaf values of these hierarchical queries, Objec describe the intermediate levels. GraphQL Objects represent a list of named fields, each of which yield a value of -a specific type. Object values are serialized as ordered maps, where the +a specific type. Object values should be represented as ordered maps, where the queried 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 query. @@ -261,8 +261,9 @@ that will yield an `Int` value, and `picture` a field that will yield a A query of an object value must select at least one field. This selection of fields will yield an ordered map containing exactly the subset of the object -queried, in the order in which they were queried. Only fields that are declared -on the object type may validly be queried on that object. +queried, which should be represented in the order in which they were queried. +Only fields that are declared on the object type may validly be queried on +that object. For example, selecting all the fields of `Person`: @@ -357,9 +358,8 @@ 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. -Response formats which support ordered maps (such as JSON) must maintain this -ordering. Response formats which do not support ordered maps may disregard -this ordering. +Response formats and runtime environments capable of representing ordered maps +should maintain this ordering. If a fragment is spread before other fields, the fields that fragment specifies occur in the response before the following fields. diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 14c950cf7..84b223763 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -21,9 +21,8 @@ representations of the following four primitives: * String * Null -Serialization formats which only support an ordered map (such as JSON) must -preserve ordering as it is defined by query execution. Serialization formats -which only support an unordered map may omit this ordering information. +Serialization formats which can represent an ordered map should preserve the +order of requested fields as defined by query execution. A serialization format may support the following primitives, however, strings may be used as a substitute for those primitives. @@ -53,6 +52,19 @@ the following JSON concepts: | Float | Number | | Enum Value | String | +**Object Property Ordering** + +While JSON Objects are specified as an +[unordered collection of key-value pairs][rfc7159-sec4] the pairs are +grammatically 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 grammatical property +orderings. While not every JSON generator allows for control over the order in +which properties are written, many do and if so should produce JSON objects with +properties in the same grammatical order as those fields were requested as +defined by query execution. + +[rfc7159-sec4]: https://tools.ietf.org/html/rfc7159#section-4 ## Response Format