diff --git a/draft/index.html b/draft/index.html index 453fd8a49..3564da3ba 100644 --- a/draft/index.html +++ b/draft/index.html @@ -2715,14 +2715,24 @@
[[Int]] [1, 2, 3] -Error: Incorrect item value +[[1], [2], [3]] [[Int]] +[1, null, 3] +[[1], null, [3]] + + +[[Int]] +[[1], ["b"]] +Error: Incorrect item value + + +[[Int]] 1 [[1]] - + [[Int]] null null @@ -2732,139 +2742,139 @@
-

3.12Non-Null

-

By default, all types in GraphQL are nullable; the null value is a valid response for all of the above types. To declare a type that disallows null, the GraphQL Non-Null type can be used. This type wraps an underlying type, and this type acts identically to that wrapped type, with the exception that null is not a valid response for the wrapping type. A trailing exclamation mark is used to denote a field that uses a Non-Null type like this: name: String!.

+

3.12Non-Null

+

By default, all types in GraphQL are nullable; the null value is a valid response for all of the above types. To declare a type that disallows null, the GraphQL Non-Null type can be used. This type wraps an underlying type, and this type acts identically to that wrapped type, with the exception that null is not a valid response for the wrapping type. A trailing exclamation mark is used to denote a field that uses a Non-Null type like this: name: String!.

-
Nullable vs. Optional
-

Fields are always optional within the context of a selection set, a field may be omitted and the selection set is still valid (so long as the selection set does not become empty). However fields that return Non-Null types will never return the value null if queried.

-

Inputs (such as field arguments), are always optional by default. However a non-null input type is required. In addition to not accepting the value null, it also does not accept omission. For the sake of simplicity nullable types are always optional and non-null types are always required.

+
Nullable vs. Optional
+

Fields are always optional within the context of a selection set, a field may be omitted and the selection set is still valid (so long as the selection set does not become empty). However fields that return Non-Null types will never return the value null if queried.

+

Inputs (such as field arguments), are always optional by default. However a non-null input type is required. In addition to not accepting the value null, it also does not accept omission. For the sake of simplicity nullable types are always optional and non-null types are always required.

-
Result Coercion
-

In all of the above result coercions, null was considered a valid value. To coerce the result of a Non-Null type, the coercion of the wrapped type should be performed. If that result was not null, then the result of coercing the Non-Null type is that result. If that result was null, then a field error must be raised.

-
+
Result Coercion
+

In all of the above result coercions, null was considered a valid value. To coerce the result of a Non-Null type, the coercion of the wrapped type should be performed. If that result was not null, then the result of coercing the Non-Null type is that result. If that result was null, then a field error 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 within the Execution section.
-
Input Coercion
-

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 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 coercion for the wrapped type.

-

A non-null argument cannot be omitted:

-
Counter Example № 86{
+
Input Coercion

+
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 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 coercion for the wrapped type.

+
A non-null argument cannot be omitted:

+
Counter Example № 86{
   fieldWithNonNullArg
 }
 

-
The value null cannot be provided to a non-null argument:

-
Counter Example № 87{
+
The value null cannot be provided to a non-null argument:

+
Counter Example № 87{
   fieldWithNonNullArg(nonNullArg: null)
 }
 

-
A variable of a nullable type cannot be provided to a non-null argument:

-
Example № 88query withNullableVariable($var: String) {
+
A variable of a nullable type cannot be provided to a non-null argument:

+
Example № 88query withNullableVariable($var: String) {
   fieldWithNonNullArg(nonNullArg: $var)
 }
 

-

+

 Note
 The Validation section defines providing a nullable variable type to a non-null input type as invalid.
-
Type Validation
+
Type Validation
    -
  1. A Non-Null type must not wrap another Non-Null type.
    2. +
  2. A Non-Null type must not wrap another Non-Null type.
-

3.12.1Combining List and Non-Null

-

The List and Non-Null wrapping types can compose, representing more complex types. The rules for result coercion and input coercion of Lists and Non-Null types apply in a recursive fashion.

-

For example if the inner item type of a List is Non-Null (e.g. [T!]), then that List may not contain any null items. However if the inner type of a Non-Null is a List (e.g. [T]!), then null is not accepted however an empty list is accepted.

-

Following are examples of result coercion with various types and values:

+

3.12.1Combining List and Non-Null

+

The List and Non-Null wrapping types can compose, representing more complex types. The rules for result coercion and input coercion of Lists and Non-Null types apply in a recursive fashion.

+

For example if the inner item type of a List is Non-Null (e.g. [T!]), then that List may not contain any null items. However if the inner type of a Non-Null is a List (e.g. [T]!), then null is not accepted however an empty list is accepted.

+

Following are examples of result coercion with various types and values:

- + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + @@ -2874,19 +2884,19 @@

-

3.13Directives

-

Expected Type Internal Value Coerced Result
[Int] [1, 2, 3] [1, 2, 3]
[Int] null null
[Int] [1, 2, null] [1, 2, null]
[Int] [1, 2, Error] [1, 2, null] (With logged error)
[Int]! [1, 2, 3] [1, 2, 3]
[Int]! null Error: Value cannot be null
[Int]! [1, 2, null] [1, 2, null]
[Int]! [1, 2, Error] [1, 2, null] (With logged error)
[Int!] [1, 2, 3] [1, 2, 3]
[Int!] null null
[Int!] [1, 2, null] null (With logged coercion error)
[Int!] [1, 2, Error] null (With logged error)
[Int!]! [1, 2, 3] [1, 2, 3]
[Int!]! null Error: Value cannot be null
[Int!]! [1, 2, null] Error: Item cannot be null
[Int!]! [1, 2, Error] Error: Error occurred in item
@@ -2906,7 +2916,7 @@

VARIABLE_DEFINITION

QUERY
-
+
TypeSystemDirectiveLocation
@@ -2932,45 +2942,45 @@

INPUT_FIELD_DEFINITION

SCHEMA
-

A GraphQL schema describes directives which are used to annotate various parts of a GraphQL document as an indicator that they should be evaluated differently by a validator, executor, or client tool such as a code generator.

+

A GraphQL schema describes directives which are used to annotate various parts of a GraphQL document as an indicator that they should be evaluated differently by a validator, executor, or client tool such as a code generator.

-
Built-in Directives
-

A built-in directive is any directive defined within this specification.

-

GraphQL implementations should provide the @skip and @include directives.

-

GraphQL implementations that support the type system definition language must provide the @deprecated directive if representing deprecated portions of the schema.

-

GraphQL implementations that support the type system definition language should provide the @specifiedBy directive if representing custom scalar definitions.

-

When representing a GraphQL schema using the type system definition language any built-in directive may be omitted for brevity.

-

When introspecting a GraphQL service all provided directives, including any built-in directive, must be included in the set of returned directives.

+
Built-in Directives
+

A built-in directive is any directive defined within this specification.

+

GraphQL implementations should provide the @skip and @include directives.

+

GraphQL implementations that support the type system definition language must provide the @deprecated directive if representing deprecated portions of the schema.

+

GraphQL implementations that support the type system definition language should provide the @specifiedBy directive if representing custom scalar definitions.

+

When representing a GraphQL schema using the type system definition language any built-in directive may be omitted for brevity.

+

When introspecting a GraphQL service all provided directives, including any built-in directive, must be included in the set of returned directives.

-
Custom Directives
-

GraphQL services and client tooling may provide any additional custom directive beyond those defined in this document. Directives are the preferred way to extend GraphQL with custom or experimental behavior.

-
+
Custom Directives
+

GraphQL services and client tooling may provide any additional custom directive beyond those defined in this document. Directives are the preferred way to extend GraphQL with custom or experimental behavior.

+
Note When defining a custom directive, it is recommended to prefix the directive’s name to make its scope of usage clear and to prevent a collision with built-in directive which may be specified by future versions of this document (which will not include _ in their name). For example, a custom directive used by Facebook’s GraphQL service should be named @fb_auth instead of @auth. This is especially recommended for proposed additions to this specification which can change during the RFC process. For example a work in progress version of @live should be named @rfc_live.
-

Directives must only be used in the locations they are declared to belong in. In this example, a directive is defined which can be used to annotate a field:

-
Example № 89directive @example on FIELD
+
Directives must only be used in the locations they are declared to belong in. In this example, a directive is defined which can be used to annotate a field:

+
Example № 89directive @example on FIELD
 
 fragment SomeFragment on SomeType {
   field @example
 }
 

-
Directive locations may be defined with an optional leading | character to aid formatting when representing a longer list of possible locations:

-
Example № 90directive @example on
+
Directive locations may be defined with an optional leading | character to aid formatting when representing a longer list of possible locations:

+
Example № 90directive @example on
   | FIELD
   | FRAGMENT_SPREAD
   | INLINE_FRAGMENT
 

-
Directives can also be used to annotate the type system definition language as well, which can be a useful tool for supplying additional metadata in order to generate GraphQL execution services, produce client generated runtime code, or many other useful extensions of the GraphQL semantics.

-
In this example, the directive @example annotates field and argument definitions:

-
Example № 91directive @example on FIELD_DEFINITION | ARGUMENT_DEFINITION
+
Directives can also be used to annotate the type system definition language as well, which can be a useful tool for supplying additional metadata in order to generate GraphQL execution services, produce client generated runtime code, or many other useful extensions of the GraphQL semantics.

+
In this example, the directive @example annotates field and argument definitions:

+
Example № 91directive @example on FIELD_DEFINITION | ARGUMENT_DEFINITION
 
 type SomeType {
   field(arg: Int @example): String @example
 }
 

-
A directive may be defined as repeatable by including the “repeatable” keyword. Repeatable directives are often useful when the same directive should be used with different arguments at a single location, especially in cases where additional information needs to be provided to a type or schema extension via a directive:

-
Example № 92directive @delegateField(name: String!) repeatable on OBJECT | INTERFACE
+
A directive may be defined as repeatable by including the “repeatable” keyword. Repeatable directives are often useful when the same directive should be used with different arguments at a single location, especially in cases where additional information needs to be provided to a type or schema extension via a directive:

+
Example № 92directive @delegateField(name: String!) repeatable on OBJECT | INTERFACE
 
 type Book @delegateField(name: "pageCount") @delegateField(name: "author") {
   id: ID!
@@ -2978,62 +2988,62 @@ 
extend type Book @delegateField(name: "index")
 

-
While defining a directive, it must not reference itself directly or indirectly:

-
Counter Example № 93directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION
+
While defining a directive, it must not reference itself directly or indirectly:

+
Counter Example № 93directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION
 

-

+

 Note
 The order in which directives appear may be significant, including repeatable directives.
-
Validation
+
Validation
    -
  1. A directive definition must not contain the use of a directive which references itself directly.
    2. -
  2. A directive definition must not contain the use of a directive which references itself indirectly by referencing a Type or Directive which transitively includes a reference to this directive.
    3. -
  3. The directive must not have a name which begins with the characters "__" (two underscores).
    4. -
  4. For each argument of the directive:
      -
    1. The argument must not have a name which begins with the characters "__" (two underscores).
      2. -
    2. The argument must have a unique name within that directive; no two arguments may share the same name.
      3. -
    3. The argument must accept a type where IsInputType(argumentType) returns true.
      4. +
    4. A directive definition must not contain the use of a directive which references itself directly.
      5. +
    5. A directive definition must not contain the use of a directive which references itself indirectly by referencing a Type or Directive which transitively includes a reference to this directive.
      6. +
    6. The directive must not have a name which begins with the characters "__" (two underscores).
      7. +
    7. For each argument of the directive:
        +
      1. The argument must not have a name which begins with the characters "__" (two underscores).
        2. +
      2. The argument must have a unique name within that directive; no two arguments may share the same name.
        3. +
      3. The argument must accept a type where IsInputType(argumentType) returns true.
-

3.13.1@skip

-
directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
+
3.13.1@skip

+
directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
 

-
The @skip built-in directive may be provided for fields, fragment spreads, and inline fragments, and allows for conditional exclusion during execution as described by the if argument.

-
In this example experimentalField will only be queried if the variable $someTest has the value false.

-
Example № 94query myQuery($someTest: Boolean!) {
+
The @skip built-in directive may be provided for fields, fragment spreads, and inline fragments, and allows for conditional exclusion during execution as described by the if argument.

+
In this example experimentalField will only be queried if the variable $someTest has the value false.

+
Example № 94query myQuery($someTest: Boolean!) {
   experimentalField @skip(if: $someTest)
 }
-

3.13.2@include

-
directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
+
3.13.2@include

+
directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
 

-
The @include built-in directive may be provided for fields, fragment spreads, and inline fragments, and allows for conditional inclusion during execution as described by the if argument.

-
In this example experimentalField will only be queried if the variable $someTest has the value true

-
Example № 95query myQuery($someTest: Boolean!) {
+
The @include built-in directive may be provided for fields, fragment spreads, and inline fragments, and allows for conditional inclusion during execution as described by the if argument.

+
In this example experimentalField will only be queried if the variable $someTest has the value true

+
Example № 95query myQuery($someTest: Boolean!) {
   experimentalField @include(if: $someTest)
 }
 

-

+

 Note
 Neither @skip nor @include has precedence over the other. In the case that both the @skip and @include directives are provided on the same field or fragment, it must be queried only if the @skip condition is false and the @include condition is true. Stated conversely, the field or fragment must not be queried if either the @skip condition is true or the @include condition is false.
-

3.13.3@deprecated

-
directive @deprecated(
+
3.13.3@deprecated

+
directive @deprecated(
   reason: String = "No longer supported"
 ) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE
 

-
The @deprecated built-in directive is used within the type system definition language to indicate deprecated portions of a GraphQL service’s schema, such as deprecated fields on a type, arguments on a field, input fields on an input type, or values of an enum type.

-
Deprecations include a reason for why it is deprecated, which is formatted using Markdown syntax (as specified by CommonMark).

-
In this example type definition, oldField is deprecated in favor of using newField and oldArg is deprecated in favor of using newArg.

-
Example № 96type ExampleType {
+
The @deprecated built-in directive is used within the type system definition language to indicate deprecated portions of a GraphQL service’s schema, such as deprecated fields on a type, arguments on a field, input fields on an input type, or values of an enum type.

+
Deprecations include a reason for why it is deprecated, which is formatted using Markdown syntax (as specified by CommonMark).

+
In this example type definition, oldField is deprecated in favor of using newField and oldArg is deprecated in favor of using newArg.

+
Example № 96type ExampleType {
   newField: String
   oldField: String @deprecated(reason: "Use `newField`.")
 
@@ -3043,26 +3053,26 @@ 
): String
 }
 

-
The @deprecated directive must not appear on required (non-null without a default) arguments or input object field definitions.

-
Counter Example № 97type ExampleType {
+
The @deprecated directive must not appear on required (non-null without a default) arguments or input object field definitions.

+
Counter Example № 97type ExampleType {
   invalidField(
     newArg: String
     oldArg: String! @deprecated(reason: "Use `newArg`.")
   ): String
 }
 

-
To deprecate a required argument or input field, it must first be made optional by either changing the type to nullable or adding a default value.

+
To deprecate a required argument or input field, it must first be made optional by either changing the type to nullable or adding a default value.
-

3.13.4@specifiedBy

-
directive @specifiedBy(url: String!) on SCALAR
+
3.13.4@specifiedBy

+
directive @specifiedBy(url: String!) on SCALAR
 

-
The @specifiedBy built-in directive is used within the type system definition language to provide a scalar specification URL for specifying the behavior of custom scalar types. The URL should point to a human-readable specification of the data format, serialization, and coercion rules. It must not appear on built-in scalar types.

-

+
The @specifiedBy built-in directive is used within the type system definition language to provide a scalar specification URL for specifying the behavior of custom scalar types. The URL should point to a human-readable specification of the data format, serialization, and coercion rules. It must not appear on built-in scalar types.

+

 Note
 Details on implementing a GraphQL scalar specification can be found in the scalars.graphql.org implementation guide.

-
In this example, a custom scalar type for UUID is defined with a URL pointing to the relevant IETF specification.

-
Example № 98scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")
+
In this example, a custom scalar type for UUID is defined with a URL pointing to the relevant IETF specification.

+
Example № 98scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")
diff --git a/index.html b/index.html index 2387c5af0..0ad28eeaa 100644 --- a/index.html +++ b/index.html @@ -1 +1 @@ - GraphQL Specification Versions

GraphQL

Prerelease Working Draft Thu, Oct 17, 2024
Latest Release October 2021 Tue, Oct 26, 2021 Release Notes
June 2018 Sun, Jun 10, 2018 Release Notes
October 2016 Mon, Oct 31, 2016 Release Notes
April 2016 Thu, Apr 7, 2016 Release Notes
October 2015 Thu, Oct 1, 2015 Release Notes
July 2015 Thu, Jul 2, 2015 Release Notes
+ GraphQL Specification Versions

GraphQL

Prerelease Working Draft Thu, Nov 21, 2024
Latest Release October 2021 Tue, Oct 26, 2021 Release Notes
June 2018 Sun, Jun 10, 2018 Release Notes
October 2016 Mon, Oct 31, 2016 Release Notes
April 2016 Thu, Apr 7, 2016 Release Notes
October 2015 Thu, Oct 1, 2015 Release Notes
July 2015 Thu, Jul 2, 2015 Release Notes