diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 532588c2e..8124f9d98 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -280,7 +280,7 @@ A GraphQL schema may describe that a field represents a list of another type; the `List` type is provided for this reason, and wraps another type. Similarly, the `Non-Null` type wraps another type, and denotes that the -resulting value will never be {null} (and that an error cannot result in a +resulting value will never be {null} (and that a field error cannot result in a {null} value). These two types are referred to as "wrapping types"; non-wrapping types are @@ -375,7 +375,8 @@ all built-in scalars must be omitted for brevity. A GraphQL service, when preparing a field of a given scalar type, must uphold the contract the scalar type describes, either by coercing the value or producing a -field error if a value cannot be coerced or if coercion may result in data loss. +[field error](#sec-Errors.Field-errors) if a value cannot be coerced or if +coercion may result in data loss. A GraphQL service may decide to allow coercing different internal types to the expected return type. For example when coercing a field of type {Int} a boolean @@ -399,7 +400,8 @@ information on the serialization of scalars in common JSON and other formats. If a GraphQL service expects a scalar type as input to an argument, coercion is observable and the rules must be well defined. If an input value does not -match a coercion rule, a query error must be raised. +match a coercion rule, a [request error](#sec-Errors.Request-errors) must be +raised (input values are validated before execution begins). GraphQL has different constant literals to represent integer and floating-point input values, and coercion rules may apply differently depending on which type @@ -438,10 +440,10 @@ greater than or equal to 231, a field error should be raised. **Input Coercion** When expected as an input type, only integer input values are accepted. All -other input values, including strings with numeric content, must raise a query +other input values, including strings with numeric content, must raise a request error indicating an incorrect type. If the integer input value represents a value less than -231 or greater than or equal to 231, a -query error should be raised. +request error should be raised. Note: Numeric integer values larger than 32-bit should either use String or a custom-defined Scalar type, as not all platforms and transports support @@ -473,10 +475,10 @@ coerced to {Float} and must raise a field error. When expected as an input type, both integer and float input values are accepted. Integer input values are coerced to Float by adding an empty fractional part, for example `1.0` for the integer input value `1`. All -other input values, including strings with numeric content, must raise a query +other input values, including strings with numeric content, must raise a request error indicating an incorrect type. If the input value otherwise represents a value not representable by finite IEEE 754 (e.g. {NaN}, {Infinity}, or a value -outside the available precision), a query error must be raised. +outside the available precision), a request error must be raised. ### String @@ -498,7 +500,7 @@ string `"1"` for the integer `1`. **Input Coercion** When expected as an input type, only valid UTF-8 string input values are -accepted. All other input values must raise a query error indicating an +accepted. All other input values must raise a request error indicating an incorrect type. @@ -519,7 +521,7 @@ this may include returning `true` for non-zero numbers. **Input Coercion** When expected as an input type, only boolean input values are accepted. All -other input values must raise a query error indicating an incorrect type. +other input values must raise a request error indicating an incorrect type. ### ID @@ -544,7 +546,7 @@ When coercion is not possible they must raise a field error. When expected as an input type, any string (such as `"4"`) or integer (such as `4` or `-4`) input value should be coerced to ID as appropriate for the ID formats a given GraphQL service expects. Any other input value, including float -input values (such as `4.0`), must raise a query error indicating an incorrect +input values (such as `4.0`), must raise a request error indicating an incorrect type. @@ -1386,7 +1388,7 @@ reasonable coercion is not possible they must raise a field error. **Input Coercion** GraphQL has a constant literal to represent enum input values. GraphQL string -literals must not be accepted as an enum input and instead raise a query error. +literals must not be accepted as an enum input and instead raise a request error. Query variable transport serializations which have a different representation for non-string symbolic values (for example, [EDN](https://github.com/edn-format/edn)) @@ -1514,10 +1516,10 @@ type of an Object or Interface field. **Input Coercion** The value for an input object should be an input object literal or an unordered -map supplied by a variable, otherwise a query error must be thrown. In either +map supplied by a variable, otherwise a request error must be raised. In either case, the input object literal or unordered map must not contain any entries -with names not defined by a field of this input object type, otherwise an error -must be thrown. +with names not defined by a field of this input object type, otherwise a +response error must be raised. The result of coercion is an unordered map with an entry for each field both defined by the input object type and for which a value exists. The resulting map @@ -1526,7 +1528,7 @@ is constructed with the following rules: * If no value is provided for a defined input object field and that field definition provides a default value, the default value should be used. If no default value is provided and the input object field's type is non-null, an - error should be thrown. Otherwise, if the field is not required, then no entry + error should be raised. Otherwise, if the field is not required, then no entry is added to the coerced unordered map. * If the value {null} was provided for an input object field, and the field's @@ -1540,7 +1542,7 @@ is constructed with the following rules: * If a variable is provided for an input object field, the runtime value of that variable must be used. If the runtime value is {null} and the field type - is non-null, a field error must be thrown. If no runtime value is provided, + is non-null, a field error must be raised. If no runtime value is provided, the variable definition's default value should be used. If the variable definition does not provide a default value, the input object field definition's default value should be used. @@ -1632,12 +1634,12 @@ implementation. If a list's item type is nullable, then errors occurring during preparation or coercion of an individual item in the list must result in a the value {null} at -that position in the list along with an error added to the response. If a list's -item type is non-null, an error occurring at an individual item in the list must -result in a field error for the entire list. +that position in the list along with a field error added to the response. +If a list's item type is non-null, a field error occurring at an individual item +in the list must result in a field error for the entire list. -Note: For more information on the error handling process, see "Errors and -Non-Nullability" within the Execution section. +Note: See [Handling Field Errors](#sec-Handling-Field-Errors) for more about +this behavior. **Input Coercion** @@ -1706,7 +1708,7 @@ the parent field. For more information on this process, see If an argument or input-object field of a Non-Null type is not provided, is provided with the literal value {null}, or is provided with a variable that was either not provided a value at runtime, or was provided the value {null}, then -a query error must be raised. +a request error must be raised. If the value provided to the Non-Null type is provided with a literal value other than {null}, or a Non-Null variable value, it is coerced using the input diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index 97f3f0951..ce819e28b 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -2013,4 +2013,4 @@ query booleanArgQueryWithDefault($booleanArg: Boolean = true) { ``` Note: The value {null} could still be provided to such a variable at runtime. -A non-null argument must produce a field error if provided a {null} value. +A non-null argument must raise a field error if provided a {null} value. diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index 0706825f9..7d04d19ee 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -41,10 +41,10 @@ GetOperation(document, operationName): * If {operationName} is {null}: * If {document} contains exactly one operation. * Return the Operation contained in the {document}. - * Otherwise produce a query error requiring {operationName}. + * Otherwise raise a request error requiring {operationName}. * Otherwise: * Let {operation} be the Operation named {operationName} in {document}. - * If {operation} was not found, produce a query error. + * If {operation} was not found, raise a request error. * Return {operation}. @@ -71,7 +71,7 @@ result to avoid validating the same request again in the future. If the operation has defined any variables, then the values for those variables need to be coerced using the input coercion rules -of variable's declared type. If a query error is encountered during +of variable's declared type. If a request error is encountered during input coercion of variable values, then the operation fails without execution. @@ -92,14 +92,14 @@ CoerceVariableValues(schema, operation, variableValues): * Add an entry to {coercedValues} named {variableName} with the value {defaultValue}. * Otherwise if {variableType} is a Non-Nullable type, and either {hasValue} - is not {true} or {value} is {null}, throw a query error. + is not {true} or {value} is {null}, raise a request error. * Otherwise if {hasValue} is true: * If {value} is {null}: * Add an entry to {coercedValues} named {variableName} with the value {null}. * Otherwise: * If {value} cannot be coerced according to the input coercion - rules of {variableType}, throw a query error. + rules of {variableType}, raise a request error. * Let {coercedValue} be the result of coercing {value} according to the input coercion rules of {variableType}. * Add an entry to {coercedValues} named {variableName} with the @@ -253,7 +253,7 @@ CreateSourceEventStream(subscription, schema, variableValues, initialValue): * Let {selectionSet} be the top level Selection Set in {subscription}. * Let {groupedFieldSet} be the result of {CollectFields(subscriptionType, selectionSet, variableValues)}. - * If {groupedFieldSet} does not have exactly one entry, throw a query error. + * If {groupedFieldSet} does not have exactly one entry, raise a request error. * Let {fields} be the value of the first entry in {groupedFieldSet}. * Let {fieldName} be the name of the first entry in {fields}. Note: This value is unaffected if an alias is used. @@ -340,15 +340,15 @@ is explained in greater detail in the Field Collection section below. **Errors and Non-Null Fields** -If during {ExecuteSelectionSet()} a field with a non-null {fieldType} throws a +If during {ExecuteSelectionSet()} a field with a non-null {fieldType} raises a field error then that error must propagate to this entire selection set, 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. -See the [Errors and Non-Nullability](#sec-Errors-and-Non-Nullability) section -of Field Execution for more about this behavior. +Note: See [Handling Field Errors](#sec-Handling-Field-Errors) for more about +this behavior. ### Normal and Serial Execution @@ -590,7 +590,7 @@ CoerceArgumentValues(objectType, field, variableValues): * Add an entry to {coercedValues} named {argumentName} with the value {defaultValue}. * Otherwise if {argumentType} is a Non-Nullable type, and either {hasValue} - is not {true} or {value} is {null}, throw a field error. + is not {true} or {value} is {null}, raise a field error. * Otherwise if {hasValue} is true: * If {value} is {null}: * Add an entry to {coercedValues} named {argumentName} with the @@ -600,7 +600,7 @@ CoerceArgumentValues(objectType, field, variableValues): value {value}. * Otherwise: * If {value} cannot be coerced according to the input coercion - rules of {argumentType}, throw a field error. + rules of {argumentType}, raise a field error. * Let {coercedValue} be the result of coercing {value} according to the input coercion rules of {argumentType}. * Add an entry to {coercedValues} named {argumentName} with the @@ -645,12 +645,12 @@ CompleteValue(fieldType, fields, result, variableValues): * Let {innerType} be the inner type of {fieldType}. * Let {completedResult} be the result of calling {CompleteValue(innerType, fields, result, variableValues)}. - * If {completedResult} is {null}, throw a field error. + * If {completedResult} is {null}, raise a field error. * Return {completedResult}. * If {result} is {null} (or another internal value similar to {null} such as {undefined}), return {null}. * If {fieldType} is a List type: - * If {result} is not a collection of values, throw a field error. + * If {result} is not a collection of values, raise a field error. * Let {innerType} be the inner type of {fieldType}. * Return a list where each list item is the result of calling {CompleteValue(innerType, fields, resultItem, variableValues)}, where @@ -714,19 +714,27 @@ MergeSelectionSets(fields): * Return {selectionSet}. -### Errors and Non-Nullability +### Handling Field Errors -If an error is thrown while resolving a field, it should be treated as though -the field returned {null}, and an error must be added to the {"errors"} list -in the response. +["Field errors"](#sec-Errors.Field-errors) are raised from a particular field +during value resolution or coercion. While these errors should be reported in +the response, they are "handled" by producing a partial response. + +Note: This is distinct from ["request errors"](#sec-Errors.Request-errors) which +are raised before execution begins. If a request error is encountered, execution +does not begin and no data is returned in the response. + +If a field error is raised while resolving a field, it is handled as though the +field returned {null}, and the error must be added to the {"errors"} list in +the response. If the result of resolving a field is {null} (either because the function to -resolve the field returned {null} or because an error occurred), and that -field is of a `Non-Null` type, then a field error is thrown. The +resolve the field returned {null} or because a field error was raised), and that +field is of a `Non-Null` type, then a field error is raised. The error must be added to the {"errors"} list in the response. -If the field returns {null} because of an error which has already been added to -the {"errors"} list in the response, the {"errors"} list must not be +If the field returns {null} because of a field error which has already been +added to the {"errors"} list in the response, the {"errors"} list must not be further affected. That is, only one error should be added to the errors list per field. diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index c8e317ff1..959749ea3 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -2,25 +2,23 @@ When a GraphQL service receives a request, it must return a well-formed response. The service's response describes the result of executing the requested -operation if successful, and describes any errors encountered during the -request. - -A response may contain both a partial response as well as encountered errors in -the case that a field error occurred on a field which was replaced with {null}. +operation if successful, and describes any errors raised during the request. +A response may contain both a partial response as well as any field errors in +the case that a field error was raised on a field and was replaced with {null}. ## Response Format -A response to a GraphQL operation must be a map. +A response to a GraphQL request must be a map. -If the operation encountered any errors, the response map must contain an +If the request raised any errors, the response map must contain an entry with key `errors`. The value of this entry is described in the "Errors" -section. If the operation completed without encountering any errors, this entry +section. If the request completed without raising any errors, this entry must not be present. -If the operation included execution, the response map must contain an entry +If the request included execution, the response map must contain an entry with key `data`. The value of this entry is described in the "Data" section. If -the operation failed before execution, due to a syntax error, missing +the request failed before execution, due to a syntax error, missing information, or validation error, this entry must not be present. The response map may also contain an entry with key `extensions`. This entry, @@ -43,10 +41,10 @@ requested operation. If the operation was a query, this output will be an object of the schema's query root type; if the operation was a mutation, this output will be an object of the schema's mutation root type. -If an error was encountered before execution begins, the `data` entry should +If an error was raised before execution begins, the `data` entry should not be present in the result. -If an error was encountered during the execution that prevented a valid +If an error was raised during the execution that prevented a valid response, the `data` entry in the response should be `null`. @@ -55,17 +53,41 @@ response, the `data` entry in the response should be `null`. The `errors` entry in the response is a non-empty list of errors, where each error is a map. -If no errors were encountered during the requested operation, the `errors` -entry should not be present in the result. +If no errors were raised during the request, the `errors` entry should +not be present in the result. 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 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. +{null}), the `errors` entry in the response may contain any field errors that +were raised during execution. If field errors were raised during execution, it +should contain those errors. + +**Request errors** + +Request errors are raised before execution begins. This may occur due to a parse +grammar or validation error in the requested document, an inability to determine +which operation to execute, or invalid input values for variables. + +Request errors are typically the fault of the requesting client. + +If a request error is raised, execution does not begin and the `data` entry in +the response must not be present. The `errors` entry must include the error. + +**Field errors** + +Field errors are raised during execution from a particular field. This may occur +due to an internal error during value resolution or failure to coerce the +resulting value. + +Field errors are typically the fault of GraphQL service. + +If a field error is raised, execution attempts to continue and a partial result +is produced (see [Handling Field Errors](#sec-Handling-Field-Errors)). +The `data` entry in the response must be present. The `errors` entry should +include all raised field errors. **Error result format** @@ -142,7 +164,7 @@ The response might look like: 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. +was raised, 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