diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index b84eabaf3..d497d49fd 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -248,6 +248,45 @@ be the same: } ``` -GraphQL servers may provide additional entries to error as they choose to -produce more helpful or machine-readable errors, however future versions of the -spec may describe additional entries to errors. +GraphQL services may provide an additional entry to errors with key `extensions`. +This entry, if set, must have a map as its value. This entry is reserved for +implementors to add additional information to errors however they see fit, and +there are no additional restrictions on its contents. + +```json example +{ + "errors": [ + { + "message": "Name for character with ID 1002 could not be fetched.", + "locations": [ { "line": 6, "column": 7 } ], + "path": [ "hero", "heroFriends", 1, "name" ], + "extensions": { + "code": "CAN_NOT_FETCH_BY_ID", + "timestamp": "Fri Feb 9 14:33:09 UTC 2018" + } + } + ] +} +``` + +GraphQL services should not provide any additional entries to the error format +since they could conflict with additional entries that may be added in future +versions of this specification. + +> Note: Previous versions of this spec did not describe the `extensions` entry +> for error formatting. While non-specified entries are not violations, they are +> still discouraged. + +```json counter-example +{ + "errors": [ + { + "message": "Name for character with ID 1002 could not be fetched.", + "locations": [ { "line": 6, "column": 7 } ], + "path": [ "hero", "heroFriends", 1, "name" ] + "code": "CAN_NOT_FETCH_BY_ID", + "timestamp": "Fri Feb 9 14:33:09 UTC 2018" + } + ] +} +```