From 4cb62b2137c0f3406eb787696fdb124909016a6e Mon Sep 17 00:00:00 2001 From: Rob Richard <rob@1stdibs.com> Date: Tue, 3 Dec 2024 10:25:00 -0500 Subject: [PATCH 1/4] Editorial: move "Path" to it's own section --- spec/Section 7 -- Response.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 59c6bbb80..7d07dc2cb 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -107,14 +107,8 @@ syntax element. If an error can be associated to a particular field in the GraphQL result, it 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. - -If present, this field must 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 fields must be strings, and path segments that represent list -indices must be 0-indexed integers. If the error happens in an aliased field, -the path to the error must use the aliased name, since it represents a path in -the response, not in the request. +`null` result is intentional or caused by a runtime error. The value of this +field is described in the [Path](#sec-Path) section. For example, if fetching one of the friends' names fails in the following operation: @@ -244,6 +238,19 @@ discouraged. } ``` +### Path + +A `path` field allows for the association to a particular field in a GraphQL +result. This field must be a list of path segments starting at the root of the +response and ending with the field to be associated with. Path segments that +represent fields must be strings, and path segments that represent list indices +must be 0-indexed integers. If the path is associated to an aliased field, the +path must use the aliased name, since it represents a path in the response, not +in the request. + +When the `path` field is present on an "Error result", it indicates the response +field which experienced the error. + ## Serialization Format GraphQL does not require a specific serialization format. However, clients From f3e00c616d32f8920e523206408f9e58340fc0ed Mon Sep 17 00:00:00 2001 From: Rob Richard <rob@1stdibs.com> Date: Thu, 5 Dec 2024 15:57:47 -0500 Subject: [PATCH 2/4] Define _path field_ --- 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 7d07dc2cb..a077b3c3d 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -240,7 +240,7 @@ discouraged. ### Path -A `path` field allows for the association to a particular field in a GraphQL +:: A _path field_ allows for the association to a particular field in a GraphQL result. This field must be a list of path segments starting at the root of the response and ending with the field to be associated with. Path segments that represent fields must be strings, and path segments that represent list indices @@ -248,7 +248,7 @@ must be 0-indexed integers. If the path is associated to an aliased field, the path must use the aliased name, since it represents a path in the response, not in the request. -When the `path` field is present on an "Error result", it indicates the response +When the _path field_ is present on an "Error result", it indicates the response field which experienced the error. ## Serialization Format From 2087016d8d71aa5b8d4a6fc13b4335e1ab3adf9e Mon Sep 17 00:00:00 2001 From: Rob Richard <robrichard87@gmail.com> Date: Thu, 9 Jan 2025 10:07:41 -0500 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Benjie <benjie@jemjie.com> --- spec/Section 7 -- Response.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index a077b3c3d..1d278f319 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -108,7 +108,7 @@ If an error can be associated to a particular field in the GraphQL result, it 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. The value of this -field is described in the [Path](#sec-Path) section. +entry is described in the [Path](#sec-Path) section. For example, if fetching one of the friends' names fails in the following operation: @@ -240,16 +240,16 @@ discouraged. ### Path -:: A _path field_ allows for the association to a particular field in a GraphQL -result. This field must be a list of path segments starting at the root of the -response and ending with the field to be associated with. Path segments that -represent fields must be strings, and path segments that represent list indices -must be 0-indexed integers. If the path is associated to an aliased field, the -path must use the aliased name, since it represents a path in the response, not -in the request. +:: A _path entry_ allows for the association with a particular field reached +during GraphQL execution. The value for this entry must be a list of path +segments starting at the root of the response and ending with the field to be +associated with. Path segments that represent fields must be strings, and path +segments that represent list indices must be 0-indexed integers. If a path +segment is associated with an aliased field it must use the aliased name, since +it represents a path in the response, not in the request. -When the _path field_ is present on an "Error result", it indicates the response -field which experienced the error. +When the _path entry_ is present on an "Error result", it identifies the +response field which experienced the error. ## Serialization Format From c99e323de1d2c073b73c67bf9d2953edff12e854 Mon Sep 17 00:00:00 2001 From: Rob Richard <robrichard87@gmail.com> Date: Fri, 10 Jan 2025 12:00:46 -0500 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Benjie <benjie@jemjie.com> --- spec/Section 7 -- Response.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index 1d278f319..8da86c586 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -108,7 +108,7 @@ If an error can be associated to a particular field in the GraphQL result, it 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. The value of this -entry is described in the [Path](#sec-Path) section. +_path entry_ is described in the [Path](#sec-Path) section. For example, if fetching one of the friends' names fails in the following operation: @@ -240,15 +240,17 @@ discouraged. ### Path -:: A _path entry_ allows for the association with a particular field reached -during GraphQL execution. The value for this entry must be a list of path -segments starting at the root of the response and ending with the field to be -associated with. Path segments that represent fields must be strings, and path -segments that represent list indices must be 0-indexed integers. If a path -segment is associated with an aliased field it must use the aliased name, since -it represents a path in the response, not in the request. +:: A _path entry_ is an entry within an _error result_ that allows for +association with a particular field reached during GraphQL execution. -When the _path entry_ is present on an "Error result", it identifies the +The value for a _path entry_ must be a list of path segments starting at the +root of the response and ending with the field to be associated with. Path +segments that represent fields must be strings, and path segments that represent +list indices must be 0-indexed integers. If a path segment is associated with an +aliased field it must use the aliased name, since it represents a path in the +response, not in the request. + +When the _path entry_ is present on an _error result_, it identifies the response field which experienced the error. ## Serialization Format