diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 18fda8224..f51fb5982 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -6,87 +6,7 @@ operation if successful, and describes any errors encountered during the request. A response may contain both a partial response as well as encountered errors in -the case that a field error occurred on a field which was replaced with null. - - -## Serialization Format - -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 at least support -representations of the following four primitives: - - * Map - * List - * String - * Null - -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 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 | -| ------------- | ----------------- | -| Map | Object | -| List | Array | -| Null | {null} | -| String | String | -| Boolean | {true} or {false} | -| Int | Number | -| Float | Number | -| Enum Value | String | - -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. - -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. +the case that a field error occurred on a field which was replaced with {null}. ## Response Format @@ -298,3 +218,83 @@ still discouraged. ] } ``` + + +## Serialization Format + +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 at least support +representations of the following four primitives: + + * Map + * List + * String + * Null + +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 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 | +| ------------- | ----------------- | +| Map | Object | +| List | Array | +| Null | {null} | +| String | String | +| Boolean | {true} or {false} | +| Int | Number | +| Float | Number | +| Enum Value | String | + +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. + +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.