From a54c25a830bf005d6b108726c57af098cf45dd75 Mon Sep 17 00:00:00 2001 From: twof Date: Sat, 8 Mar 2025 16:53:24 -0800 Subject: [PATCH] initial spec edits --- spec/Section 3 -- Type System.md | 34 +++++++++++++++++++++++++++++++- spec/Section 6 -- Execution.md | 4 ++++ 2 files changed, 37 insertions(+), 1 deletion(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 04e4fa450..b42ca14cc 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1818,7 +1818,9 @@ must be raised. Note: When a _field error_ is raised on a non-null value, the error propagates to the parent field. For more information on this process, see [Errors and Non-Null Fields](#sec-Executing-Selection-Sets.Errors-and-Non-Null-Fields) -within the Execution section. +within the Execution section. This error propagation behavior can be modified using the +`@disableErrorPropagation` directive, which prevents errors from propagating upward through +parent fields. See [`@disableErrorPropagation`](#sec-disableErrorPropagation) for more details. **Input Coercion** @@ -1944,6 +1946,8 @@ by a validator, executor, or client tool such as a code generator. GraphQL implementations should provide the `@skip` and `@include` directives. +GraphQL implementations should provide the `@disableErrorPropagation` directive to allow clients to control error propagation behavior for specific operations. + GraphQL implementations that support the type system definition language must provide the `@deprecated` directive if representing deprecated portions of the schema. @@ -2164,3 +2168,31 @@ to the relevant IETF specification. ```graphql example scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") ``` + +### @disableErrorPropagation + +```graphql +directive @disableErrorPropagation on QUERY | MUTATION | SUBSCRIPTION +``` + +The `@disableErrorPropagation` _built-in directive_ can be used to disable error propagation during execution of operations. When this directive is applied to an operation, errors in non-null fields will not propagate to their parent fields. Instead, the error is reported in the response's `errors` list while the field simply returns `null`, even if it's a non-null field. + +Without this directive, GraphQL follows the default error propagation behavior: when a field error occurs on a non-null field, the error propagates to the parent field, potentially nullifying the entire response if the parent field is also non-null. + +In this example, error propagation is disabled for the query: + +```graphql example +query getUser @disableErrorPropagation { + user { + id + name + email + } +} +``` + +If the `email` field (which may be defined as `String!` in the schema) throws an error, it would return `null` instead of causing the entire `user` object to become `null`. + +This directive is particularly useful for clients that want more granular control over error handling and prefer partial data with errors rather than having entire objects or responses nullified due to a single field error. + +Note: The `@disableErrorPropagation` directive only affects error propagation during execution. It does not affect how errors are validated or included in the response's `errors` list. \ No newline at end of file diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index d88c685f9..f14db03f6 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -386,6 +386,8 @@ either resolving to {null} if allowed or further propagated to a parent field. If this occurs, any sibling fields which have not yet executed or have not yet yielded a value may be cancelled to avoid unnecessary work. +This default error propagation behavior can be modified by using the `@disableErrorPropagation` directive on an operation. If this directive is present, field errors in non-null fields will not propagate to their parent fields. Instead, the field that experienced the error will return `null` (even if it's a non-null field) and the error will be added to the response's `errors` list, but parent fields will continue to be resolved normally. This allows clients to receive partial data with localized errors rather than having errors propagate and potentially nullify large portions of the response. + Note: See [Handling Field Errors](#sec-Handling-Field-Errors) for more about this behavior. @@ -835,3 +837,5 @@ upwards. If all fields from the root of the request to the source of the field error return `Non-Null` types, then the {"data"} entry in the response should be {null}. + +Note: The error propagation behavior described above can be modified by using the `@disableErrorPropagation` directive on an operation. See [Errors and Non-Null Fields](#sec-Executing-Selection-Sets.Errors-and-Non-Null-Fields) for details.