From ca7eea6f5cf26773d94fe94e97ee3b508bba89e1 Mon Sep 17 00:00:00 2001 From: Ivan Goncharov Date: Fri, 9 Feb 2018 21:54:43 +0200 Subject: [PATCH 1/5] Add optional 'extensions' entry to errors --- spec/Section 7 -- Response.md | 42 ++++++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 3 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index b84eabaf3..667955934 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -248,6 +248,42 @@ 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 servers may provide an additional entry with key `extensions`. This +entry, if set, must have a map as its value. This entry is reserved for +implementors to extend errors however they see fit, and hence there are no +additional restrictions on its contents. + +To provide compatibility with the previous versions of this spec, it is allowed +to add additional entries to error itself. However such non-standard entries are +highly discouraged since they may conflict with additional entries that can be +added in the future versions of the spec. + +```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" + } + } + ] +} +``` + +```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" + } + ] +} +``` From d3c86ee098c246999b0fc70c3f209b79f94f5094 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 5 Mar 2018 19:45:34 -0800 Subject: [PATCH 2/5] Some minor formatting changes --- spec/Section 7 -- Response.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 667955934..85d4f2461 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -248,15 +248,10 @@ be the same: } ``` -GraphQL servers may provide an additional entry with key `extensions`. This +GraphQL services may provide an additional entry with key `extensions`. This entry, if set, must have a map as its value. This entry is reserved for -implementors to extend errors however they see fit, and hence there are no -additional restrictions on its contents. - -To provide compatibility with the previous versions of this spec, it is allowed -to add additional entries to error itself. However such non-standard entries are -highly discouraged since they may conflict with additional entries that can be -added in the future versions of the spec. +implementors to add additional information to errors however they see fit, and +there are no additional restrictions on its contents. ```json example { @@ -274,6 +269,14 @@ added in the future versions of the spec. } ``` +GraphQL services should not provide any additional entries to the error format, +since they may 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": [ From 69e2fc263931302722114340783fcb035cc421b4 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 5 Mar 2018 19:46:16 -0800 Subject: [PATCH 3/5] Specify additional entry to errors --- spec/Section 7 -- Response.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 85d4f2461..ebb86ac1a 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -248,8 +248,8 @@ be the same: } ``` -GraphQL services may provide an additional entry with key `extensions`. This -entry, if set, must have a map as its value. This entry is reserved for +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. From 78ccccb4a70fc5bb26959dd6479e9a5ae407f9c8 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 5 Mar 2018 19:47:18 -0800 Subject: [PATCH 4/5] Update Section 7 -- Response.md --- spec/Section 7 -- Response.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index ebb86ac1a..b78f81424 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -270,7 +270,7 @@ there are no additional restrictions on its contents. ``` GraphQL services should not provide any additional entries to the error format, -since they may conflict with additional entries that may be added in future +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 From 6b81cb649746dbe9f437337b12a960b671ab8773 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Mon, 5 Mar 2018 19:47:57 -0800 Subject: [PATCH 5/5] Update Section 7 -- Response.md --- spec/Section 7 -- Response.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index b78f81424..d497d49fd 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -248,9 +248,9 @@ be the same: } ``` -GraphQL services may provide an additional entry to errors with key `extensions`. +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 +implementors to add additional information to errors however they see fit, and there are no additional restrictions on its contents. ```json example @@ -269,11 +269,11 @@ there are no additional restrictions on its contents. } ``` -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 +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 +> 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.