From af713aacbab51f13f1a9d287e3b7daa8c39ddb79 Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Thu, 23 Jun 2016 17:15:20 -0700 Subject: [PATCH 01/12] Add error path to response Just like it is helpful to know the location in the query associated with an error, it's helpful to know the location in the response. --- spec/Section 7 -- Response.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 3c38df493..6d92ee20f 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -135,6 +135,12 @@ locations, where each location is a map with the keys `line` and `column`, both positive numbers starting from `1` which describe the beginning of an associated syntax element. +If an error can be associated to a particular field in the GraphQL response, it +should contain an entry with the key `path` with a list of path segments +starting at the root of the response and ending with the field associated with +the error. Path segments that represent object fields should be strings, and +path segments that represent array indices should be 0-indexed integers. + 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. From 775589bd516e7894d3645c8d6db16de066617f07 Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Fri, 28 Oct 2016 14:33:04 -0700 Subject: [PATCH 02/12] Updates to error result format Following up on @leebyron's comments: https://github.com/facebook/graphql/pull/187#issuecomment-256766580 --- spec/Section 7 -- Response.md | 76 ++++++++++++++++++++++++++++++----- 1 file changed, 67 insertions(+), 9 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 6d92ee20f..0a56e567b 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -125,6 +125,16 @@ error is a map. If no errors were encountered during the requested operation, the `errors` entry should not be present in the result. +If the `data` entry in the response is `null` or not present, the `errors` +entry in the response must not be empty. It must contain at least one error. +The errors it contains should indicate why no data was able to be returned. + +If the `data` entry in the response is not `null`, the `errors` entry in the +response may contain any errors that occurred during execution. If errors +occurred during execution, it should contain those errors. + +**Error result format** + Every error must contain an entry with the key `message` with a string description of the error intended for the developer as a guide to understand and correct the error. @@ -135,20 +145,68 @@ locations, where each location is a map with the keys `line` and `column`, both positive numbers starting from `1` which describe the beginning of an associated syntax element. -If an error can be associated to a particular field in the GraphQL response, it +If an error can be associated to a particular field in the GraphQL result, it should contain an entry with the key `path` with a list of path segments starting at the root of the response and ending with the field associated with the error. Path segments that represent object fields should be strings, and path segments that represent array indices should be 0-indexed integers. +If the error happens in an aliased field, the path to the error should use the +aliased name, since it represents a path in the response, not than the query. + +For example, if fetching one of the friends' names fails in the following +query: + +```graphql +{ + hero(episode: $episode) { + name + heroFriends: friends { + id + name + } + } +} +``` + +The response might look like: + +```js +{ + "data": { + "hero": { + "name": "R2-D2", + "heroFriends": [ + { + "id": "1000", + "name": "Luke Skywalker" + }, + { + "id": "1002", + "name": null + }, + { + "id": "1003", + "name": "Leia Organa" + } + ] + } + }, + "errors": [ + { + "message": "Name for character with ID 1002 could not be fetched.", + "locations": [ { "line": 6, "column": 7 }], + "path": [ "hero", "heroFriends", 3, "name" ] + } + ] +} +``` + +If the field which experienced an error was declared as `Non-Null`, the `null` +result will bubble up to the next nullable field. In that case, the `path` +for the error should include the full path to the result field where the error +occurred, even if that field is not present in the response. + 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. - -If the `data` entry in the response is `null` or not present, the `errors` -entry in the response must not be empty. It must contain at least one error. -The errors it contains should indicate why no data was able to be returned. - -If the `data` entry in the response is not `null`, the `errors` entry in the -response may contain any errors that occurred during execution. If errors -occurred during execution, it should contain those errors. From 72a9c2cc8bf78d15438505edbfb177dc8e7541df Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Fri, 28 Oct 2016 14:38:16 -0700 Subject: [PATCH 03/12] Improve organization --- spec/Section 7 -- Response.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 0a56e567b..53f2a1275 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -146,13 +146,15 @@ positive numbers starting from `1` which describe the beginning of an associated syntax element. If an error can be associated to a particular field in the GraphQL result, it -should contain an entry with the key `path` with a list of path segments -starting at the root of the response and ending with the field associated with -the error. Path segments that represent object fields should be strings, and -path segments that represent array indices should be 0-indexed integers. - -If the error happens in an aliased field, the path to the error should use the -aliased name, since it represents a path in the response, not than the query. +should contain an entry with the key `path` that details the path of the +response field which experienced the error. + +This field should be a list of path segments starting at the root of the +response and ending with the field associated with the error. Path segments +that represent object fields should be strings, and path segments that +represent array indices should be 0-indexed integers. If the error happens +in an aliased field, the path to the error should use the aliased name, since +it represents a path in the response, not than the query. For example, if fetching one of the friends' names fails in the following query: From 72d5ab951076dd6a9ca7e4328a2541c4a6a17df5 Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Fri, 28 Oct 2016 14:39:05 -0700 Subject: [PATCH 04/12] Clarify why this feature is useful --- spec/Section 7 -- Response.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 53f2a1275..0d2e8a337 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -147,7 +147,8 @@ associated syntax element. If an error can be associated to a particular field in the GraphQL result, it should contain an entry with the key `path` that details the path of the -response field which experienced the error. +response field which experienced the error. This allows clients to identify +whether a `null` result is intentional or caused by a runtime error. This field should be a list of path segments starting at the root of the response and ending with the field associated with the error. Path segments From fd3cdea0853245e6a059aba745e7ed5ea50b62d6 Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Fri, 28 Oct 2016 15:25:07 -0700 Subject: [PATCH 05/12] Fix typo --- 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 0d2e8a337..202c16352 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -155,7 +155,7 @@ response and ending with the field associated with the error. Path segments that represent object fields should be strings, and path segments that represent array indices should be 0-indexed integers. If the error happens in an aliased field, the path to the error should use the aliased name, since -it represents a path in the response, not than the query. +it represents a path in the response, not in the query. For example, if fetching one of the friends' names fails in the following query: From 70ae4041cacf5ae51d7f7bb3a274991489a165c9 Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Mon, 31 Oct 2016 09:40:46 -0700 Subject: [PATCH 06/12] Fix index in error path --- 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 202c16352..41aab3fa7 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -199,7 +199,7 @@ The response might look like: { "message": "Name for character with ID 1002 could not be fetched.", "locations": [ { "line": 6, "column": 7 }], - "path": [ "hero", "heroFriends", 3, "name" ] + "path": [ "hero", "heroFriends", 1, "name" ] } ] } From de1cc89dfc26c92026194a2192b5a403d737aaa3 Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Mon, 31 Oct 2016 09:40:53 -0700 Subject: [PATCH 07/12] Add example for non-null field --- spec/Section 7 -- Response.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 41aab3fa7..9d6888983 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -210,6 +210,38 @@ result will bubble up to the next nullable field. In that case, the `path` for the error should include the full path to the result field where the error occurred, even if that field is not present in the response. +For example, if the `name` field from above had declared a `Non-Null` return +type in the schema, the result would look different but the error reported would +be the same: + +```js +{ + "data": { + "hero": { + "name": "R2-D2", + "heroFriends": [ + { + "id": "1000", + "name": "Luke Skywalker" + }, + null, + { + "id": "1003", + "name": "Leia Organa" + } + ] + } + }, + "errors": [ + { + "message": "Name for character with ID 1002 could not be fetched.", + "locations": [ { "line": 6, "column": 7 }], + "path": [ "hero", "heroFriends", 1, "name" ] + } + ] +} +``` + 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. From 14f5e53b4c7addf59eee22d52be9257c53b9c06e Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Tue, 1 Nov 2016 16:18:52 -0700 Subject: [PATCH 08/12] Formatting, and change array to list --- spec/Section 7 -- Response.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 9d6888983..bfd9870fc 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -152,8 +152,8 @@ whether a `null` result is intentional or caused by a runtime error. This field should be a list of path segments starting at the root of the response and ending with the field associated with the error. Path segments -that represent object fields should be strings, and path segments that -represent array indices should be 0-indexed integers. If the error happens +that represent fields should be strings, and path segments that +represent list indices should be 0-indexed integers. If the error happens in an aliased field, the path to the error should use the aliased name, since it represents a path in the response, not in the query. @@ -198,7 +198,7 @@ The response might look like: "errors": [ { "message": "Name for character with ID 1002 could not be fetched.", - "locations": [ { "line": 6, "column": 7 }], + "locations": [ { "line": 6, "column": 7 } ], "path": [ "hero", "heroFriends", 1, "name" ] } ] @@ -235,7 +235,7 @@ be the same: "errors": [ { "message": "Name for character with ID 1002 could not be fetched.", - "locations": [ { "line": 6, "column": 7 }], + "locations": [ { "line": 6, "column": 7 } ], "path": [ "hero", "heroFriends", 1, "name" ] } ] From a8d7df1e36d7e7d9d5a7f41122504393ea4d4f18 Mon Sep 17 00:00:00 2001 From: Sashko Stubailo Date: Mon, 7 Nov 2016 17:39:51 -0800 Subject: [PATCH 09/12] Change "should" to "must" --- 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 bfd9870fc..f9a219742 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -146,7 +146,7 @@ positive numbers starting from `1` which describe the beginning of an associated syntax element. If an error can be associated to a particular field in the GraphQL result, it -should contain an entry with the key `path` that details the path of the +must contain an entry with the key `path` that details the path of the response field which experienced the error. This allows clients to identify whether a `null` result is intentional or caused by a runtime error. From 59aaa2282572e1b1647d673593a1ade0d2d5ffb2 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 12 May 2017 11:50:21 -0700 Subject: [PATCH 10/12] Clarify what's required when data is null. `{"data": null}` is a legal response when loading a top level field of a nullable type that intentionally returned null. Updating this language to ensure it remains legal. --- spec/Section 7 -- Response.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index f9a219742..bc0e4f260 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -125,13 +125,14 @@ error is a map. If no errors were encountered during the requested operation, the `errors` entry should not be present in the result. -If the `data` entry in the response is `null` or not present, the `errors` +If the `data` entry in the response is not present, the `errors` entry in the response must not be empty. It must contain at least one error. The errors it contains should indicate why no data was able to be returned. -If the `data` entry in the response is not `null`, the `errors` entry in the -response may contain any errors that occurred during execution. If errors -occurred during execution, it should contain those errors. +If the `data` entry in the response is present (including if it is the value +{null}), the `errors` entry in the response may contain any errors that +occurred during execution. If errors occurred during execution, it should +contain those errors. **Error result format** From f2eff647929f04cac93d54f0054663cec68c82d1 Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 12 May 2017 11:52:27 -0700 Subject: [PATCH 11/12] Move "errors" to top field. New convention for highlighting errors --- spec/Section 7 -- Response.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index bc0e4f260..5d10e8902 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -177,6 +177,13 @@ The response might look like: ```js { + "errors": [ + { + "message": "Name for character with ID 1002 could not be fetched.", + "locations": [ { "line": 6, "column": 7 } ], + "path": [ "hero", "heroFriends", 1, "name" ] + } + ], "data": { "hero": { "name": "R2-D2", @@ -195,14 +202,7 @@ The response might look like: } ] } - }, - "errors": [ - { - "message": "Name for character with ID 1002 could not be fetched.", - "locations": [ { "line": 6, "column": 7 } ], - "path": [ "hero", "heroFriends", 1, "name" ] - } - ] + } } ``` From b74fbb87e001139c3a5bd24f517672e14efbd95f Mon Sep 17 00:00:00 2001 From: Lee Byron Date: Fri, 12 May 2017 11:53:41 -0700 Subject: [PATCH 12/12] Another instance of errors over data --- spec/Section 7 -- Response.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 5d10e8902..d9fd4b02a 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -217,6 +217,13 @@ be the same: ```js { + "errors": [ + { + "message": "Name for character with ID 1002 could not be fetched.", + "locations": [ { "line": 6, "column": 7 } ], + "path": [ "hero", "heroFriends", 1, "name" ] + } + ], "data": { "hero": { "name": "R2-D2", @@ -232,14 +239,7 @@ be the same: } ] } - }, - "errors": [ - { - "message": "Name for character with ID 1002 could not be fetched.", - "locations": [ { "line": 6, "column": 7 } ], - "path": [ "hero", "heroFriends", 1, "name" ] - } - ] + } } ```