Skip to content

Commit d554d12

Browse files
Sashko Stubailoleebyron
Sashko Stubailo
authored andcommitted
[RFC] Add error path to response (#230)
* 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. * Updates to error result format Following up on @leebyron's comments: #187 (comment) * Improve organization * Clarify why this feature is useful * Fix typo * Fix index in error path * Add example for non-null field * Formatting, and change array to list * Change "should" to "must" * 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. * Move "errors" to top field. New convention for highlighting errors * Another instance of errors over data
1 parent 6e66601 commit d554d12

File tree

1 file changed

+108
-8
lines changed

1 file changed

+108
-8
lines changed

spec/Section 7 -- Response.md

Lines changed: 108 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,17 @@ error is a map.
125125
If no errors were encountered during the requested operation, the `errors`
126126
entry should not be present in the result.
127127

128+
If the `data` entry in the response is not present, the `errors`
129+
entry in the response must not be empty. It must contain at least one error.
130+
The errors it contains should indicate why no data was able to be returned.
131+
132+
If the `data` entry in the response is present (including if it is the value
133+
{null}), the `errors` entry in the response may contain any errors that
134+
occurred during execution. If errors occurred during execution, it should
135+
contain those errors.
136+
137+
**Error result format**
138+
128139
Every error must contain an entry with the key `message` with a string
129140
description of the error intended for the developer as a guide to understand
130141
and correct the error.
@@ -135,14 +146,103 @@ locations, where each location is a map with the keys `line` and `column`, both
135146
positive numbers starting from `1` which describe the beginning of an
136147
associated syntax element.
137148

149+
If an error can be associated to a particular field in the GraphQL result, it
150+
must contain an entry with the key `path` that details the path of the
151+
response field which experienced the error. This allows clients to identify
152+
whether a `null` result is intentional or caused by a runtime error.
153+
154+
This field should be a list of path segments starting at the root of the
155+
response and ending with the field associated with the error. Path segments
156+
that represent fields should be strings, and path segments that
157+
represent list indices should be 0-indexed integers. If the error happens
158+
in an aliased field, the path to the error should use the aliased name, since
159+
it represents a path in the response, not in the query.
160+
161+
For example, if fetching one of the friends' names fails in the following
162+
query:
163+
164+
```graphql
165+
{
166+
hero(episode: $episode) {
167+
name
168+
heroFriends: friends {
169+
id
170+
name
171+
}
172+
}
173+
}
174+
```
175+
176+
The response might look like:
177+
178+
```js
179+
{
180+
"errors": [
181+
{
182+
"message": "Name for character with ID 1002 could not be fetched.",
183+
"locations": [ { "line": 6, "column": 7 } ],
184+
"path": [ "hero", "heroFriends", 1, "name" ]
185+
}
186+
],
187+
"data": {
188+
"hero": {
189+
"name": "R2-D2",
190+
"heroFriends": [
191+
{
192+
"id": "1000",
193+
"name": "Luke Skywalker"
194+
},
195+
{
196+
"id": "1002",
197+
"name": null
198+
},
199+
{
200+
"id": "1003",
201+
"name": "Leia Organa"
202+
}
203+
]
204+
}
205+
}
206+
}
207+
```
208+
209+
If the field which experienced an error was declared as `Non-Null`, the `null`
210+
result will bubble up to the next nullable field. In that case, the `path`
211+
for the error should include the full path to the result field where the error
212+
occurred, even if that field is not present in the response.
213+
214+
For example, if the `name` field from above had declared a `Non-Null` return
215+
type in the schema, the result would look different but the error reported would
216+
be the same:
217+
218+
```js
219+
{
220+
"errors": [
221+
{
222+
"message": "Name for character with ID 1002 could not be fetched.",
223+
"locations": [ { "line": 6, "column": 7 } ],
224+
"path": [ "hero", "heroFriends", 1, "name" ]
225+
}
226+
],
227+
"data": {
228+
"hero": {
229+
"name": "R2-D2",
230+
"heroFriends": [
231+
{
232+
"id": "1000",
233+
"name": "Luke Skywalker"
234+
},
235+
null,
236+
{
237+
"id": "1003",
238+
"name": "Leia Organa"
239+
}
240+
]
241+
}
242+
}
243+
}
244+
```
245+
138246
GraphQL servers may provide additional entries to error as they choose to
139247
produce more helpful or machine-readable errors, however future versions of the
140248
spec may describe additional entries to errors.
141-
142-
If the `data` entry in the response is `null` or not present, the `errors`
143-
entry in the response must not be empty. It must contain at least one error.
144-
The errors it contains should indicate why no data was able to be returned.
145-
146-
If the `data` entry in the response is not `null`, the `errors` entry in the
147-
response may contain any errors that occurred during execution. If errors
148-
occurred during execution, it should contain those errors.

0 commit comments

Comments
 (0)