2.1.1Unicode

Non‐ASCII Unicode characters may freely appear within StringValue and Comment portions of GraphQL.

The “Byte Order Mark” is a special Unicode character which may appear at the beginning of a file containing Unicode which programs may use to determine the fact that the text stream is Unicode, what endianness the text stream is in, and which of several Unicode encodings to interpret.

2.1.2White Space

White space is used to improve legibility of source text and act as separation between tokens, and any amount of white space may appear before or after any token. White space between tokens is not significant to the semantic meaning of a GraphQL Document, however white space characters may appear within a String or Comment token.

2.1.3Line Terminators

Like white space, line terminators are used to improve the legibility of source text, any amount may appear before or after any other token and have no significance to the semantic meaning of a GraphQL Document. Line terminators are not found within any other token.

2.1.4Comments

GraphQL source documents may contain single‐line comments, starting with the # marker.

A comment can contain any Unicode code point except LineTerminator so a comment always consists of all code points starting with the # character up to but not including the line terminator.

Comments behave like white space and may appear after any token, or before a line terminator, and have no significance to the semantic meaning of a GraphQL Document.

2.1.5Insignificant Commas

Similar to white space and line terminators, commas (,) are used to improve the legibility of source text and separate lexical tokens but are otherwise syntactically and semantically insignificant within GraphQL Documents.

Non‐significant comma characters ensure that the absence or presence of a comma does not meaningfully alter the interpreted syntax of the document, as this can be a common user‐error in other languages. It also allows for the stylistic use of either trailing commas or line‐terminators as list delimiters which are both often desired for legibility and maintainability of source code.

2.1.6Lexical Tokens

A GraphQL document is comprised of several kinds of indivisible lexical tokens defined here in a lexical grammar by patterns of source Unicode characters.

Tokens are later used as terminal symbols in a GraphQL Document syntactic grammars.

2.1.7Ignored Tokens

Before and after every lexical token may be any amount of ignored tokens including WhiteSpace and Comment. No ignored regions of a source document are significant, however ignored source characters may appear within a lexical token in a significant way, for example a String may contain white space characters.

No characters are ignored while parsing a given token, as an example no white space characters are permitted between the characters defining a FloatValue.

2.1.8Punctuators

GraphQL documents include punctuation in order to describe structure. GraphQL is a data description language and not a programming language, therefore GraphQL lacks the punctuation often used to describe mathematical expressions.

2.1.9Names

GraphQL Documents are full of named things: operations, fields, arguments, types, directives, fragments, and variables. All names must follow the same grammatical form.

Names in GraphQL are case‐sensitive. That is to say name, Name, and NAME all refer to different names. Underscores are significant, which means other_name and othername are two different names.

Names in GraphQL are limited to this ASCII subset of possible characters to support interoperation with as many other systems as possible.

2.8.1Type Conditions

Fragments must specify the type they apply to. In this example, friendFields can be used in the context of querying a User.

Fragments cannot be specified on any input value (scalar, enumeration, or input object).

Fragments can be specified on object types, interfaces, and unions.

Selections within fragments only return values when concrete type of the object it is operating on matches the type of the fragment.

For example in this query on the Facebook data model:

Example № 21query FragmentTyping {
  profiles(handles: ["zuck", "cocacola"]) {
    handle
    ...userFragment
    ...pageFragment
  }
}

fragment userFragment on User {
  friends {
    count
  }
}

fragment pageFragment on Page {
  likers {
    count
  }
}

The profiles root field returns a list where each element could be a Page or a User. When the object in the profiles result is a User, friends will be present and likers will not. Conversely when the result is a Page, likers will be present and friends will not.

Example № 22{
  "profiles": [
    {
      "handle": "zuck",
      "friends": { "count" : 1234 }
    },
    {
      "handle": "cocacola",
      "likers": { "count" : 90234512 }
    }
  ]
}

2.8.2Inline Fragments

Fragments can be defined inline within a selection set. This is done to conditionally include fields based on their runtime type. This feature of standard fragment inclusion was demonstrated in the query FragmentTyping example. We could accomplish the same thing using inline fragments.

Example № 23query inlineFragmentTyping {
  profiles(handles: ["zuck", "cocacola"]) {
    handle
    ... on User {
      friends {
        count
      }
    }
    ... on Page {
      likers {
        count
      }
    }
  }
}

Inline fragments may also be used to apply a directive to a group of fields. If the TypeCondition is omitted, an inline fragment is considered to be of the same type as the enclosing context.

Example № 24query inlineFragmentNoType($expandedInfo: Boolean) {
  user(handle: "zuck") {
    id
    name
    ... @include(if: $expandedInfo) {
      firstName
      lastName
      birthday
    }
  }
}

2.9.1Int Value

An Int number is specified without a decimal point or exponent (ex. 1).

2.9.2Float Value

A Float number includes either a decimal point (ex. 1.0) or an exponent (ex. 1e50) or both (ex. 6.0221413e23).

2.9.3Boolean Value

The two keywords true and false represent the two boolean values.

2.9.4String Value

Strings are sequences of characters wrapped in double‐quotes ("). (ex. "Hello World"). White space and other otherwise‐ignored characters are significant within a string value.

Block Strings

Block strings are sequences of characters wrapped in triple‐quotes ("""). White space, line terminators, quote, and backslash characters may all be used unescaped to enable verbatim text. Characters must all be valid SourceCharacter.

Since block strings represent freeform text often used in indented positions, the string value semantics of a block string excludes uniform indentation and blank initial and trailing lines via BlockStringValue().

For example, the following operation containing a block string:

Example № 25mutation {
  sendEmail(message: """
    Hello,
      World!

    Yours,
      GraphQL.
  """)
}

Is identical to the standard quoted string:

Example № 26mutation {
  sendEmail(message: "Hello,\n  World!\n\nYours,\n  GraphQL.")
}

Since block string values strip leading and trailing empty lines, there is no single canonical printed block string for a given value. Because block strings typically represent freeform text, it is considered easier to read if they begin and end with an empty line.

Example № 27"""
This starts with and ends with an empty line,
which makes it easier to read.
"""

Counter Example № 28"""This does not start with or end with any empty lines,
which makes it a little harder to read."""

Semantics

2.9.5Null Value

Null values are represented as the keyword null.

GraphQL has two semantically different ways to represent the lack of a value:

• Explicitly providing the literal value: null.
• Implicitly not providing a value at all.

For example, these two field calls are similar, but are not identical:

Example № 29{
  field(arg: null)
  field
}

The first has explictly provided null to the argument “arg”, while the second has implicitly not provided a value to the argument “arg”. These two forms may be interpreted differently. For example, a mutation representing deleting a field vs not altering a field, respectively. Neither form may be used for an input expecting a Non‐Null type.

2.9.6Enum Value

Enum values are represented as unquoted names (ex. MOBILE_WEB). It is recommended that Enum values be “all caps”. Enum values are only used in contexts where the precise enumeration type is known. Therefore it’s not necessary to supply an enumeration type name in the literal.

2.9.7List Value

Lists are ordered sequences of values wrapped in square‐brackets [ ]. The values of a List literal may be any value literal or variable (ex. [1, 2, 3]).

Commas are optional throughout GraphQL so trailing commas are allowed and repeated commas do not represent missing values.

Semantics

2.9.8Input Object Values

Input object literal values are unordered lists of keyed input values wrapped in curly‐braces { }. The values of an object literal may be any input value literal or variable (ex. { name: "Hello world", score: 1.0 }). We refer to literal representation of input objects as “object literals.”

Input object fields are unordered

Input object fields may be provided in any syntactic order and maintain identical semantic meaning.

These two queries are semantically identical:

Example № 30{
  nearestThing(location: { lon: 12.43, lat: -53.211 })
}

Example № 31{
  nearestThing(location: { lat: -53.211, lon: 12.43 })
}

Semantics

3.2.1Root Operation Types

A schema defines the initial root operation type for each kind of operation it supports: query, mutation, and subscription; this determines the place in the type system where those operations begin.

The query root operation type must be provided and must be an Object type.

The mutation root operation type is optional; if it is not provided, the service does not support mutations. If it is provided, it must be an Object type.

Similarly, the subscription root operation type is also optional; if it is not provided, the service does not support subscriptions. If it is provided, it must be an Object type.

The fields on the query root operation type indicate what fields are available at the top level of a GraphQL query. For example, a basic GraphQL query like:

Example № 34query {
  myName
}

Is valid when the query root operation type has a field named “myName”.

Example № 35type Query {
  myName: String
}

Similarly, the following mutation is valid if a mutation root operation type has a field named “setName”. Note that the query and mutation root types must be different types.

Example № 36mutation {
  setName(name: "Zuck") {
    newName
  }
}

When using the type system definition language, a document must include at most one schema definition.

In this example, a GraphQL schema is defined with both query and mutation root types:

Example № 37schema {
  query: MyQueryRootType
  mutation: MyMutationRootType
}

type MyQueryRootType {
  someField: String
}

type MyMutationRootType {
  setSomeField(to: String): String
}

Default Root Operation Type Names

While any type can be the root operation type for a GraphQL operation, the type system definition language can omit the schema definition when the query, mutation, and subscription root types are named Query, Mutation, and Subscription respectively.

Likewise, when representing a GraphQL schema using the type system definition language, a schema definition should be omitted if it only uses the default root operation type names.

This example describes a valid complete GraphQL schema, despite not explicitly including a schema definition. The Query type is presumed to be the query root operation type of the schema.

Example № 38type Query {
  someField: String
}

3.2.2Schema Extension

Schema extensions are used to represent a schema which has been extended from an original schema. For example, this might be used by a GraphQL service which adds additional operation types, or additional directives to an existing schema.

Schema Validation

Schema extensions have the potential to be invalid if incorrectly defined.

1. The Schema must already be defined.
2. Any directives provided must not already apply to the original Schema.

3.4.1Wrapping Types

All of the types so far are assumed to be both nullable and singular: e.g. a scalar string returns either null or a singular string.

A GraphQL schema may describe that a field represents list of another types; 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 null value).

These two types are referred to as “wrapping types”; non‐wrapping types are referred to as “named types”. A wrapping type has an underlying named type, found by continually unwrapping the type until a named type is found.

3.4.2Input and Output Types

Types are used throughout GraphQL to describe both the values accepted as input to arguments and variables as well as the values output by fields. These two uses categorize types as input types and output types. Some kinds of types, like Scalar and Enum types, can be used as both input types and output types; other kinds types can only be used in one or the other. Input Object types can only be used as input types. Object, Interface, and Union types can only be used as output types. Lists and Non‐Null types may be used as input types or output types depending on how the wrapped type may be used.

3.4.3Type Extensions

Type extensions are used to represent a GraphQL type which has been extended from some original type. For example, this might be used by a local service to represent additional fields a GraphQL client only accesses locally.

3.5.1Int

The Int scalar type represents a signed 32‐bit numeric non‐fractional value. Response formats that support a 32‐bit integer or a number type should use that type to represent this scalar.

Result Coercion

Fields returning the type Int expect to encounter 32‐bit integer internal values.

GraphQL servers may coerce non‐integer internal values to integers when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning 1 for the floating‐point number 1.0, or returning 123 for the string "123". In scenarios where coercion may lose data, raising a field error is more appropriate. For example, a floating‐point number 1.2 should raise a field error instead of being truncated to 1.

If the integer internal value represents a value less than -2³¹ or greater than or equal to 2³¹, 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 error indicating an incorrect type. If the integer input value represents a value less than -2³¹ or greater than or equal to 2³¹, a query error should be raised.

3.5.2Float

The Float scalar type represents signed double‐precision fractional values as specified by IEEE 754. Response formats that support an appropriate double‐precision number type should use that type to represent this scalar.

Result Coercion

Fields returning the type Float expect to encounter double‐precision floating‐point internal values.

GraphQL servers may coerce non‐floating‐point internal values to Float when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning 1.0 for the integer number 1, or 123.0 for the string "123".

Input Coercion

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 error indicating an incorrect type. If the integer input value represents a value not representable by IEEE 754, a query error should be raised.

3.5.3String

The String scalar type represents textual data, represented as UTF‐8 character sequences. The String type is most often used by GraphQL to represent free‐form human‐readable text. All response formats must support string representations, and that representation must be used here.

Result Coercion

Fields returning the type String expect to encounter UTF‐8 string internal values.

GraphQL servers may coerce non‐string raw values to String when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning the string "true" for a boolean true value, or the 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 incorrect type.

3.5.4Boolean

The Boolean scalar type represents true or false. Response formats should use a built‐in boolean type if supported; otherwise, they should use their representation of the integers 1 and 0.

Result Coercion

Fields returning the type Boolean expect to encounter boolean internal values.

GraphQL servers may coerce non‐boolean raw values to Boolean when reasonable without losing information, otherwise they must raise a field error. Examples of 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.

3.5.5ID

The ID scalar type represents a unique identifier, often used to refetch an object or as the key for a cache. The ID type is serialized in the same way as a String; however, it is not intended to be human‐readable. While it is often numeric, it should always serialize as a String.

Result Coercion

GraphQL is agnostic to ID format, and serializes to string to ensure consistency across many formats ID could represent, from small auto‐increment numbers, to large 128‐bit random numbers, to base64 encoded values, or string values of a format like GUID.

GraphQL servers should coerce as appropriate given the ID formats they expect. When coercion is not possible they must raise a field error.

Input Coercion

When expected as an input type, any string (such as "4") or integer (such as 4) input value should be coerced to ID as appropriate for the ID formats a given GraphQL server expects. Any other input value, including float input values (such as 4.0), must raise a query error indicating an incorrect type.

3.5.6Scalar Extensions

Scalar type extensions are used to represent a scalar type which has been extended from some original scalar type. For example, this might be used by a GraphQL tool or service which adds directives to an existing scalar.

Type Validation

Scalar type extensions have the potential to be invalid if incorrectly defined.

1. The named type must already be defined and must be a Scalar type.
2. Any directives provided must not already apply to the original Scalar type.

3.6.1Field Arguments

Object fields are conceptually functions which yield values. Occasionally object fields can accept arguments to further specify the return value. Object field arguments are defined as a list of all possible argument names and their expected input types.

All arguments defined within a field must not have a name which begins with "__" (two underscores), as this is used exclusively by GraphQL’s introspection system.

For example, a Person type with a picture field could accept an argument to determine what size of an image to return.

Example № 56type Person {
  name: String
  picture(size: Int): Url
}

GraphQL queries can optionally specify arguments to their fields to provide these arguments.

This example query:

Example № 57{
  name
  picture(size: 600)
}

May yield the result:

Example № 58{
  "name": "Mark Zuckerberg",
  "picture": "http://some.cdn/picture_600.jpg"
}

The type of an object field argument must be an input type (any type except an Object, Interface, or Union type).

3.6.2Field Deprecation

Fields in an object may be marked as deprecated as deemed necessary by the application. It is still legal to query for these fields (to ensure existing clients are not broken by the change), but the fields should be appropriately treated in documentation and tooling.

When using the type system definition language, @deprecated directives are used to indicate that a field is deprecated:

Example № 59type ExampleType {
  oldField: String @deprecated
}

3.6.3Object Extensions

Object type extensions are used to represent a type which has been extended from some original type. For example, this might be used to represent local data, or by a GraphQL service which is itself an extension of another GraphQL service.

In this example, a local data field is added to a Story type:

Example № 60extend type Story {
  isHiddenLocally: Boolean
}

Object type extensions may choose not to add additional fields, instead only adding interfaces or directives.

In this example, a directive is added to a User type without adding fields:

Example № 61extend type User @addedDirective

Type Validation

Object type extensions have the potential to be invalid if incorrectly defined.

1. The named type must already be defined and must be an Object type.
2. The fields of an Object type extension must have unique names; no two fields may share the same name.
3. Any fields of an Object type extension must not be already defined on the original Object type.
4. Any directives provided must not already apply to the original Object type.
5. Any interfaces provided must not be already implemented by the original Object type.
6. The resulting extended object type must be a super‐set of all interfaces it implements.

3.7.1Interface Extensions

Interface type extensions are used to represent an interface which has been extended from some original interface. For example, this might be used to represent common local data on many types, or by a GraphQL service which is itself an extension of another GraphQL service.

In this example, an extended data field is added to a NamedEntity type along with the types which implement it:

Example № 67extend interface NamedEntity {
  nickname: String
}

extend type Person {
  nickname: String
}

extend type Business {
  nickname: String
}

Interface type extensions may choose not to add additional fields, instead only adding directives.

In this example, a directive is added to a NamedEntity type without adding fields:

Example № 68extend interface NamedEntity @addedDirective

Type Validation

Interface type extensions have the potential to be invalid if incorrectly defined.

1. The named type must already be defined and must be an Interface type.
2. The fields of an Interface type extension must have unique names; no two fields may share the same name.
3. Any fields of an Interface type extension must not be already defined on the original Interface type.
4. Any Object type which implemented the original Interface type must also be a super‐set of the fields of the Interface type extension (which may be due to Object type extension).
5. Any directives provided must not already apply to the original Interface type.

3.8.1Union Extensions

Union type extensions are used to represent a union type which has been extended from some original union type. For example, this might be used to represent additional local data, or by a GraphQL service which is itself an extension of another GraphQL service.

Type Validation

Union type extensions have the potential to be invalid if incorrectly defined.

1. The named type must already be defined and must be a Union type.
2. The member types of a Union type extension must all be Object base types; Scalar, Interface and Union types must not be member types of a Union. Similarly, wrapping types must not be member types of a Union.
3. All member types of a Union type extension must be unique.
4. All member types of a Union type extension must not already be a member of the original Union type.
5. Any directives provided must not already apply to the original Union type.

3.9.1Enum Extensions

Enum type extensions are used to represent an enum type which has been extended from some original enum type. For example, this might be used to represent additional local data, or by a GraphQL service which is itself an extension of another GraphQL service.

Type Validation

Enum type extensions have the potential to be invalid if incorrectly defined.

1. The named type must already be defined and must be an Enum type.
2. All values of an Enum type extension must be unique.
3. All values of an Enum type extension must not already be a value of the original Enum.
4. Any directives provided must not already apply to the original Enum type.

3.10.1Input Object Extensions

Input object type extensions are used to represent an input object type which has been extended from some original input object type. For example, this might be used by a GraphQL service which is itself an extension of another GraphQL service.

Type Validation

Input object type extensions have the potential to be invalid if incorrectly defined.

1. The named type must already be defined and must be a Input Object type.
2. All fields of an Input Object type extension must have unique names.
3. All fields of an Input Object type extension must not already be a field of the original Input Object.
4. Any directives provided must not already apply to the original Input Object 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.13.1@skip

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

The @skip 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 № 83query myQuery($someTest: Boolean) {
  experimentalField @skip(if: $someTest)
}

3.13.2@include

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

The @include 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 № 84query myQuery($someTest: Boolean) {
  experimentalField @include(if: $someTest)
}

3.13.3@deprecated

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

The @deprecated 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 or deprecated enum values.

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.

Example № 85type ExampleType {
  newField: String
  oldField: String @deprecated(reason: "Use `newField`.")
}

4.5.1The __Type Type

__Type is at the core of the type introspection system. It represents scalars, interfaces, object types, unions, enums in the system.

__Type also represents type modifiers, which are used to modify a type that it refers to (ofType: __Type). This is how we represent lists, non‐nullable types, and the combinations thereof.

4.5.2Type Kinds

There are several different kinds of type. In each kind, different fields are actually valid. These kinds are listed in the __TypeKind enumeration.

Example № 89input Point {
  x: Int
  y: Int
}

4.5.3The __Field Type

The __Field type represents each field in an Object or Interface type.

Fields

• name must return a String
• description may return a String or null
• args returns a List of __InputValue representing the arguments this field accepts.
• type must return a __Type that represents the type of value returned by this field.
• isDeprecated returns true if this field should no longer be used, otherwise false.
• deprecationReason optionally provides a reason why this field is deprecated.

4.5.4The __InputValue Type

The __InputValue type represents field and directive arguments as well as the inputFields of an input object.

Fields

• name must return a String
• description may return a String or null
• type must return a __Type that represents the type this input value expects.
• defaultValue may return a String encoding (using the GraphQL language) of the default value used by this input value in the condition a value is not provided at runtime. If this input value has no default value, returns null.

4.5.5The __EnumValue Type

The __EnumValue type represents one of possible values of an enum.

Fields

• name must return a String
• description may return a String or null
• isDeprecated returns true if this field should no longer be used, otherwise false.
• deprecationReason optionally provides a reason why this field is deprecated.

4.5.6The __Directive Type

The __Directive type represents a Directive that a server supports.

Fields

• name must return a String
• description may return a String or null
• locations returns a List of __DirectiveLocation representing the valid locations this directive may be placed.
• args returns a List of __InputValue representing the arguments this directive accepts.

5.1.1Executable Definitions

Formal Specification

• For each definition definition in the document.
• definition must be OperationDefinition or FragmentDefinition (it must not be TypeSystemDefinition).

Explanatory Text

GraphQL execution will only consider the executable definitions Operation and Fragment. Type system definitions and extensions are not executable, and are not considered during execution.

To avoid ambiguity, a document containing TypeSystemDefinition is invalid for execution.

GraphQL documents not intended to be directly executed may include TypeSystemDefinition.

For example, the following document is invalid for execution since the original executing schema may not know about the provided type extension:

Counter Example № 91query getDogName {
  dog {
    name
    color
  }
}

extend type Dog {
  color: String
}

5.2.1Named Operation Definitions

Example № 92query getDogName {
  dog {
    name
  }
}

query getOwnerName {
  dog {
    owner {
      name
    }
  }
}

Counter Example № 93query getName {
  dog {
    name
  }
}

query getName {
  dog {
    owner {
      name
    }
  }
}

Counter Example № 94query dogOperation {
  dog {
    name
  }
}

mutation dogOperation {
  mutateDog {
    id
  }
}

5.2.2Anonymous Operation Definitions

Example № 95{
  dog {
    name
  }
}

Counter Example № 96{
  dog {
    name
  }
}

query getName {
  dog {
    owner {
      name
    }
  }
}

5.2.3Subscription Operation Definitions

Example № 97subscription sub {
  newMessage {
    body
    sender
  }
}

Example № 98subscription sub {
  ...newMessageFields
}

fragment newMessageFields on Subscription {
  newMessage {
    body
    sender
  }
}

Counter Example № 99subscription sub {
  newMessage {
    body
    sender
  }
  disallowedSecondRootField
}

Counter Example № 100subscription sub {
  ...multipleSubscriptions
}

fragment multipleSubscriptions on Subscription {
  newMessage {
    body
    sender
  }
  disallowedSecondRootField
}

Counter Example № 101subscription sub {
  newMessage {
    body
    sender
  }
  __typename
}

5.3.1Field Selections on Objects, Interfaces, and Unions Types

Formal Specification

• For each selection in the document.
• Let fieldName be the target field of selection
• fieldName must be defined on type in scope

Explanatory Text

The target field of a field selection must be defined on the scoped type of the selection set. There are no limitations on alias names.

For example the following fragment would not pass validation:

Counter Example № 102fragment fieldNotDefined on Dog {
  meowVolume
}

fragment aliasedLyingFieldTargetNotDefined on Dog {
  barkVolume: kawVolume
}

For interfaces, direct field selection can only be done on fields. Fields of concrete implementors are not relevant to the validity of the given interface‐typed selection set.

For example, the following is valid:

Example № 103fragment interfaceFieldSelection on Pet {
  name
}

and the following is invalid:

Counter Example № 104fragment definedOnImplementorsButNotInterface on Pet {
  nickname
}

Because unions do not define fields, fields may not be directly selected from a union‐typed selection set, with the exception of the meta‐field __typename. Fields from a union‐typed selection set must only be queried indirectly via a fragment.

For example the following is valid:

Example № 105fragment inDirectFieldSelectionOnUnion on CatOrDog {
  __typename
  ... on Pet {
    name
  }
  ... on Dog {
    barkVolume
  }
}

But the following is invalid:

Counter Example № 106fragment directFieldSelectionOnUnion on CatOrDog {
  name
  barkVolume
}

5.3.2Field Selection Merging

Formal Specification

• Let set be any selection set defined in the GraphQL document.
• FieldsInSetCanMerge(set) must be true.

Explanatory Text

If multiple field selections with the same response names are encountered during execution, the field and arguments to execute and the resulting value should be unambiguous. Therefore any two field selections which might both be encountered for the same object are only valid if they are equivalent.

During execution, the simultaneous execution of fields with the same response name is accomplished by MergeSelectionSets() and CollectFields().

For simple hand‐written GraphQL, this rule is obviously a clear developer error, however nested fragments can make this difficult to detect manually.

The following selections correctly merge:

Example № 107fragment mergeIdenticalFields on Dog {
  name
  name
}

fragment mergeIdenticalAliasesAndFields on Dog {
  otherName: name
  otherName: name
}

The following is not able to merge:

Counter Example № 108fragment conflictingBecauseAlias on Dog {
  name: nickname
  name
}

Identical arguments are also merged if they have identical arguments. Both values and variables can be correctly merged.

For example the following correctly merge:

Example № 109fragment mergeIdenticalFieldsWithIdenticalArgs on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand(dogCommand: SIT)
}

fragment mergeIdenticalFieldsWithIdenticalValues on Dog {
  doesKnowCommand(dogCommand: $dogCommand)
  doesKnowCommand(dogCommand: $dogCommand)
}

The following do not correctly merge:

Counter Example № 110fragment conflictingArgsOnValues on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand(dogCommand: HEEL)
}

fragment conflictingArgsValueAndVar on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand(dogCommand: $dogCommand)
}

fragment conflictingArgsWithVars on Dog {
  doesKnowCommand(dogCommand: $varOne)
  doesKnowCommand(dogCommand: $varTwo)
}

fragment differingArgs on Dog {
  doesKnowCommand(dogCommand: SIT)
  doesKnowCommand
}

The following fields would not merge together, however both cannot be encountered against the same object, so they are safe:

Example № 111fragment safeDifferingFields on Pet {
  ... on Dog {
    volume: barkVolume
  }
  ... on Cat {
    volume: meowVolume
  }
}

fragment safeDifferingArgs on Pet {
  ... on Dog {
    doesKnowCommand(dogCommand: SIT)
  }
  ... on Cat {
    doesKnowCommand(catCommand: JUMP)
  }
}

However, the field responses must be shapes which can be merged. For example, scalar values must not differ. In this example, someValue might be a String or an Int:

Counter Example № 112fragment conflictingDifferingResponses on Pet {
  ... on Dog {
    someValue: nickname
  }
  ... on Cat {
    someValue: meowVolume
  }
}

5.3.3Leaf Field Selections

Formal Specification

• For each selection in the document
• Let selectionType be the result type of selection
• If selectionType is a scalar or enum:
  • The subselection set of that selection must be empty
• If selectionType is an interface, union, or object
  • The subselection set of that selection must NOT BE empty

Explanatory Text

Field selections on scalars or enums are never allowed, because they are the leaf nodes of any GraphQL query.

The following is valid.

Example № 113fragment scalarSelection on Dog {
  barkVolume
}

The following is invalid.

Counter Example № 114fragment scalarSelectionsNotAllowedOnInt on Dog {
  barkVolume {
    sinceWhen
  }
}

Conversely the leaf field selections of GraphQL queries must be of type scalar or enum. Leaf selections on objects, interfaces, and unions without subfields are disallowed.

Let’s assume the following additions to the query root type of the schema:

Example № 115extend type Query {
  human: Human
  pet: Pet
  catOrDog: CatOrDog
}

The following examples are invalid

Counter Example № 116query directQueryOnObjectWithoutSubFields {
  human
}

query directQueryOnInterfaceWithoutSubFields {
  pet
}

query directQueryOnUnionWithoutSubFields {
  catOrDog
}

5.4.1Argument Names

Formal Specification

• For each argument in the document
• Let argumentName be the Name of argument.
• Let argumentDefinition be the argument definition provided by the parent field or definition named argumentName.
• argumentDefinition must exist.

Explanatory Text

Every argument provided to a field or directive must be defined in the set of possible arguments of that field or directive.

For example the following are valid:

Example № 117fragment argOnRequiredArg on Dog {
  doesKnowCommand(dogCommand: SIT)
}

fragment argOnOptional on Dog {
  isHousetrained(atOtherHomes: true) @include(if: true)
}

the following is invalid since command is not defined on DogCommand.

Counter Example № 118fragment invalidArgName on Dog {
  doesKnowCommand(command: CLEAN_UP_HOUSE)
}

and this is also invalid as unless is not defined on @include.

Counter Example № 119fragment invalidArgName on Dog {
  isHousetrained(atOtherHomes: true) @include(unless: false)
}

In order to explore more complicated argument examples, let’s add the following to our type system:

Example № 120type Arguments {
  multipleReqs(x: Int!, y: Int!): Int!
  booleanArgField(booleanArg: Boolean): Boolean
  floatArgField(floatArg: Float): Float
  intArgField(intArg: Int): Int
  nonNullBooleanArgField(nonNullBooleanArg: Boolean!): Boolean!
  booleanListArgField(booleanListArg: [Boolean]!): [Boolean]
  optionalNonNullBooleanArgField(optionalBooleanArg: Boolean! = false): Boolean!
}

extend type Query {
  arguments: Arguments
}

Order does not matter in arguments. Therefore both the following example are valid.

Example № 121fragment multipleArgs on Arguments {
  multipleReqs(x: 1, y: 2)
}

fragment multipleArgsReverseOrder on Arguments {
  multipleReqs(y: 1, x: 2)
}

5.4.2Argument Uniqueness

Fields and directives treat arguments as a mapping of argument name to value. More than one argument with the same name in an argument set is ambiguous and invalid.

Formal Specification

• For each argument in the Document.
• Let argumentName be the Name of argument.
• Let arguments be all Arguments named argumentName in the Argument Set which contains argument.
• arguments must be the set containing only argument.

Example № 122fragment goodBooleanArg on Arguments {
  booleanArgField(booleanArg: true)
}

fragment goodNonNullArg on Arguments {
  nonNullBooleanArgField(nonNullBooleanArg: true)
}

Example № 123fragment goodBooleanArgDefault on Arguments {
  booleanArgField
}

Counter Example № 124fragment missingRequiredArg on Arguments {
  nonNullBooleanArgField
}

Counter Example № 125fragment missingRequiredArg on Arguments {
  nonNullBooleanArgField(nonNullBooleanArg: null)
}

5.5.1Fragment Declarations

Example № 126{
  dog {
    ...fragmentOne
    ...fragmentTwo
  }
}

fragment fragmentOne on Dog {
  name
}

fragment fragmentTwo on Dog {
  owner {
    name
  }
}

Counter Example № 127{
  dog {
    ...fragmentOne
  }
}

fragment fragmentOne on Dog {
  name
}

fragment fragmentOne on Dog {
  owner {
    name
  }
}

Example № 128fragment correctType on Dog {
  name
}

fragment inlineFragment on Dog {
  ... on Dog {
    name
  }
}

fragment inlineFragment2 on Dog {
  ... @include(if: true) {
    name
  }
}

Counter Example № 129fragment notOnExistingType on NotInSchema {
  name
}

fragment inlineNotExistingType on Dog {
  ... on NotInSchema {
    name
  }
}

Example № 130fragment fragOnObject on Dog {
  name
}

fragment fragOnInterface on Pet {
  name
}

fragment fragOnUnion on CatOrDog {
  ... on Dog {
    name
  }
}

Counter Example № 131fragment fragOnScalar on Int {
  something
}

fragment inlineFragOnScalar on Dog {
  ... on Boolean {
    somethingElse
  }
}

Counter Example № 132fragment nameFragment on Dog { # unused
  name
}

{
  dog {
    name
  }
}

5.5.2Fragment Spreads

Field selection is also determined by spreading fragments into one another. The selection set of the target fragment is unioned with the selection set at the level at which the target fragment is referenced.

Counter Example № 133{
  dog {
    ...undefinedFragment
  }
}

Counter Example № 134{
  dog {
    ...nameFragment
  }
}

fragment nameFragment on Dog {
  name
  ...barkVolumeFragment
}

fragment barkVolumeFragment on Dog {
  barkVolume
  ...nameFragment
}

Example № 135{
  dog {
    name
    barkVolume
    name
    barkVolume
    name
    barkVolume
    name
    # forever...
  }
}

Counter Example № 136{
  dog {
    ...dogFragment
  }
}

fragment dogFragment on Dog {
  name
  owner {
    ...ownerFragment
  }
}

fragment ownerFragment on Dog {
  name
  pets {
    ...dogFragment
  }
}

Example № 137fragment dogFragment on Dog {
  ... on Dog {
    barkVolume
  }
}

Counter Example № 138fragment catInDogFragmentInvalid on Dog {
  ... on Cat {
    meowVolume
  }
}

Example № 139fragment petNameFragment on Pet {
  name
}

fragment interfaceWithinObjectFragment on Dog {
  ...petNameFragment
}

Example № 140fragment catOrDogNameFragment on CatOrDog {
  ... on Cat {
    meowVolume
  }
}

fragment unionWithObjectFragment on Dog {
  ...catOrDogNameFragment
}

Example № 141fragment petFragment on Pet {
  name
  ... on Dog {
    barkVolume
  }
}

fragment catOrDogFragment on CatOrDog {
  ... on Cat {
    meowVolume
  }
}

Counter Example № 142fragment sentientFragment on Sentient {
  ... on Dog {
    barkVolume
  }
}

fragment humanOrAlienFragment on HumanOrAlien {
  ... on Cat {
    meowVolume
  }
}

Example № 143fragment unionWithInterface on Pet {
  ...dogOrHumanFragment
}

fragment dogOrHumanFragment on DogOrHuman {
  ... on Dog {
    barkVolume
  }
}

Counter Example № 144fragment nonIntersectingInterfaces on Pet {
  ...sentientFragment
}

fragment sentientFragment on Sentient {
  name
}

5.6.1Values of Correct Type

Format Specification

• For each input Value value in the document.
  • Let type be the type expected in the position value is found.
  • value must be coercible to type.

Explanatory Text

Literal values must be compatible with the type expected in the position they are found as per the coercion rules defined in the Type System chapter.

The type expected in a position include the type defined by the argument a value is provided for, the type defined by an input object field a value is provided for, and the type of a variable definition a default value is provided for.

The following examples are valid use of value literals:

Example № 145fragment goodBooleanArg on Arguments {
  booleanArgField(booleanArg: true)
}

fragment coercedIntIntoFloatArg on Arguments {
  # Note: The input coercion rules for Float allow Int literals.
  floatArgField(floatArg: 123)
}

query goodComplexDefaultValue($search: ComplexInput = { name: "Fido" }) {
  findDog(complex: $search)
}

Non‐coercible values (such as a String into an Int) are invalid. The following examples are invalid:

Counter Example № 146fragment stringIntoInt on Arguments {
  intArgField(intArg: "123")
}

query badComplexValue {
  findDog(complex: { name: 123 })
}

5.6.2Input Object Field Names

Formal Specification

• For each Input Object Field inputField in the document
• Let inputFieldName be the Name of inputField.
• Let inputFieldDefinition be the input field definition provided by the parent input object type named inputFieldName.
• inputFieldDefinition must exist.

Explanatory Text

Every input field provided in an input object value must be defined in the set of possible fields of that input object’s expected type.

For example the following example input object is valid:

Example № 147{
  findDog(complex: { name: "Fido" })
}

While the following example input‐object uses a field “favoriteCookieFlavor” which is not defined on the expected type:

Counter Example № 148{
  findDog(complex: { favoriteCookieFlavor: "Bacon" })
}

5.6.3Input Object Field Uniqueness

Formal Specification

• For each input object value inputObject in the document.
• For every inputField in inputObject
  • Let name be the Name of inputField.
  • Let fields be all Input Object Fields named name in inputObject.
  • fields must be the set containing only inputField.

Explanatory Text

Input objects must not contain more than one field of the same name, otherwise an ambiguity would exist which includes an ignored portion of syntax.

For example the following query will not pass validation.

Counter Example № 149{
  field(arg: { field: true, field: false })
}

5.6.4Input Object Required Fields

Formal Specification

• For each Input Object in the document.
  • Let fields be the fields provided by that Input Object.
  • Let fieldDefinitions be the set of input field definitions of that Input Object.
• For each fieldDefinition in fieldDefinitions:
  • Let type be the expected type of fieldDefinition.
  • Let defaultValue be the default value of fieldDefinition.
  • If type is Non‐Null and defaultValue does not exist:
    • Let fieldName be the name of fieldDefinition.
    • Let field be the input field in fields named fieldName
    • field must exist.
    • Let value be the value of field.
    • value must not be the null literal.

Explanatory Text

Input object fields may be required. Much like a field may have required arguments, an input object may have required fields. An input field is required if it has a non‐null type and does not have a default value. Otherwise, the input object field is optional.

5.7.1Directives Are Defined

Formal Specification

• For every directive in a document.
• Let directiveName be the name of directive.
• Let directiveDefinition be the directive named directiveName.
• directiveDefinition must exist.

Explanatory Text

GraphQL servers define what directives they support. For each usage of a directive, the directive must be available on that server.

5.7.2Directives Are In Valid Locations

Formal Specification

• For every directive in a document.
• Let directiveName be the name of directive.
• Let directiveDefinition be the directive named directiveName.
• Let locations be the valid locations for directiveDefinition.
• Let adjacent be the AST node the directive affects.
• adjacent must be represented by an item within locations.

Explanatory Text

GraphQL servers define what directives they support and where they support them. For each usage of a directive, the directive must be used in a location that the server has declared support for.

For example the following query will not pass validation because @skip does not provide QUERY as a valid location.

Counter Example № 150query @skip(if: $foo) {
  field
}

5.7.3Directives Are Unique Per Location

Formal Specification

• For every location in the document for which Directives can apply:
  • Let directives be the set of Directives which apply to location.
  • For each directive in directives:
    • Let directiveName be the name of directive.
    • Let namedDirectives be the set of all Directives named directiveName in directives.
    • namedDirectives must be a set of one.

Explanatory Text

Directives are used to describe some metadata or behavioral change on the definition they apply to. When more than one directive of the same name is used, the expected metadata or behavior becomes ambiguous, therefore only one of each directive is allowed per location.

For example, the following query will not pass validation because @skip has been used twice for the same field:

Counter Example № 151query ($foo: Boolean = true, $bar: Boolean = false) {
  field @skip(if: $foo) @skip(if: $bar)
}

However the following example is valid because @skip has been used only once per location, despite being used twice in the query and on the same named field:

Example № 152query ($foo: Boolean = true, $bar: Boolean = false) {
  field @skip(if: $foo) {
    subfieldA
  }
  field @skip(if: $bar) {
    subfieldB
  }
}

5.8.1Variable Uniqueness

Formal Specification

• For every operation in the document
  • For every variable defined on operation
    • Let variableName be the name of variable
    • Let variables be the set of all variables named variableName on operation
    • variables must be a set of one

Explanatory Text

If any operation defines more than one variable with the same name, it is ambiguous and invalid. It is invalid even if the type of the duplicate variable is the same.

Counter Example № 153query houseTrainedQuery($atOtherHomes: Boolean, $atOtherHomes: Boolean) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

It is valid for multiple operations to define a variable with the same name. If two operations reference the same fragment, it might actually be necessary:

Example № 154query A($atOtherHomes: Boolean) {
  ...HouseTrainedFragment
}

query B($atOtherHomes: Boolean) {
  ...HouseTrainedFragment
}

fragment HouseTrainedFragment {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

5.8.2Variables Are Input Types

Formal Specification

• For every operation in a document
• For every variable on each operation
  • Let variableType be the type of variable
  • IsInputType(variableType) must be true

Explanatory Text

Variables can only be input types. Objects, unions, and interfaces cannot be used as inputs.

For these examples, consider the following typesystem additions:

Example № 155input ComplexInput { name: String, owner: String }

extend type Query {
  findDog(complex: ComplexInput): Dog
  booleanList(booleanListArg: [Boolean!]): Boolean
}

The following queries are valid:

Example № 156query takesBoolean($atOtherHomes: Boolean) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

query takesComplexInput($complexInput: ComplexInput) {
  findDog(complex: $complexInput) {
    name
  }
}

query TakesListOfBooleanBang($booleans: [Boolean!]) {
  booleanList(booleanListArg: $booleans)
}

The following queries are invalid:

Counter Example № 157query takesCat($cat: Cat) {
  # ...
}

query takesDogBang($dog: Dog!) {
  # ...
}

query takesListOfPet($pets: [Pet]) {
  # ...
}

query takesCatOrDog($catOrDog: CatOrDog) {
  # ...
}

5.8.3All Variable Uses Defined

Formal Specification

• For each operation in a document
  • For each variableUsage in scope, variable must be in operation‘s variable list.
  • Let fragments be every fragment referenced by that operation transitively
  • For each fragment in fragments
    • For each variableUsage in scope of fragment, variable must be in operation‘s variable list.

Explanatory Text

Variables are scoped on a per‐operation basis. That means that any variable used within the context of an operation must be defined at the top level of that operation

For example:

Example № 158query variableIsDefined($atOtherHomes: Boolean) {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

is valid. $atOtherHomes is defined by the operation.

By contrast the following query is invalid:

Counter Example № 159query variableIsNotDefined {
  dog {
    isHousetrained(atOtherHomes: $atOtherHomes)
  }
}

$atOtherHomes is not defined by the operation.

Fragments complicate this rule. Any fragment transitively included by an operation has access to the variables defined by that operation. Fragments can appear within multiple operations and therefore variable usages must correspond to variable definitions in all of those operations.

For example the following is valid:

Example № 160query variableIsDefinedUsedInSingleFragment($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

since isHousetrainedFragment is used within the context of the operation variableIsDefinedUsedInSingleFragment and the variable is defined by that operation.

On the other hand, if a fragment is included within an operation that does not define a referenced variable, the query is invalid.

Counter Example № 161query variableIsNotDefinedUsedInSingleFragment {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

This applies transitively as well, so the following also fails:

Counter Example № 162query variableIsNotDefinedUsedInNestedFragment {
  dog {
    ...outerHousetrainedFragment
  }
}

fragment outerHousetrainedFragment on Dog {
  ...isHousetrainedFragment
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

Variables must be defined in all operations in which a fragment is used.

Example № 163query housetrainedQueryOne($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

query housetrainedQueryTwo($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

However the following does not validate:

Counter Example № 164query housetrainedQueryOne($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

query housetrainedQueryTwoNotDefined {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

This is because housetrainedQueryTwoNotDefined does not define a variable $atOtherHomes but that variable is used by isHousetrainedFragment which is included in that operation.

5.8.4All Variables Used

Formal Specification

• For every operation in the document.
• Let variables be the variables defined by that operation
• Each variable in variables must be used at least once in either the operation scope itself or any fragment transitively referenced by that operation.

Explanatory Text

All variables defined by an operation must be used in that operation or a fragment transitively included by that operation. Unused variables cause a validation error.

For example the following is invalid:

Counter Example № 165query variableUnused($atOtherHomes: Boolean) {
  dog {
    isHousetrained
  }
}

because $atOtherHomes is not referenced.

These rules apply to transitive fragment spreads as well:

Example № 166query variableUsedInFragment($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

The above is valid since $atOtherHomes is used in isHousetrainedFragment which is included by variableUsedInFragment.

If that fragment did not have a reference to $atOtherHomes it would be not valid:

Counter Example № 167query variableNotUsedWithinFragment($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedWithoutVariableFragment
  }
}

fragment isHousetrainedWithoutVariableFragment on Dog {
  isHousetrained
}

All operations in a document must use all of their variables.

As a result, the following document does not validate.

Counter Example № 168query queryWithUsedVar($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

query queryWithExtraVar($atOtherHomes: Boolean, $extra: Int) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

This document is not valid because queryWithExtraVar defines an extraneous variable.

5.8.5All Variable Usages are Allowed

Formal Specification

• For each operation in document:
• Let variableUsages be all usages transitively included in the operation.
• For each variableUsage in variableUsages:
  • Let variableName be the name of variableUsage.
  • Let variableDefinition be the VariableDefinition named variableName defined within operation.
  • IsVariableUsageAllowed(variableDefinition, variableUsage) must be true.

Explanatory Text

Variable usages must be compatible with the arguments they are passed to.

Validation failures occur when variables are used in the context of types that are complete mismatches, or if a nullable type in a variable is passed to a non‐null argument type.

Types must match:

Counter Example № 169query intCannotGoIntoBoolean($intArg: Int) {
  arguments {
    booleanArgField(booleanArg: $intArg)
  }
}

$intArg typed as Int cannot be used as a argument to booleanArg, typed as Boolean.

List cardinality must also be the same. For example, lists cannot be passed into singular values.

Counter Example № 170query booleanListCannotGoIntoBoolean($booleanListArg: [Boolean]) {
  arguments {
    booleanArgField(booleanArg: $booleanListArg)
  }
}

Nullability must also be respected. In general a nullable variable cannot be passed to a non‐null argument.

Counter Example № 171query booleanArgQuery($booleanArg: Boolean) {
  arguments {
    nonNullBooleanArgField(nonNullBooleanArg: $booleanArg)
  }
}

For list types, the same rules around nullability apply to both outer types and inner types. A nullable list cannot be passed to a non‐null list, and a list of nullable values cannot be passed to a list of non‐null values. The following is valid:

Example № 172query nonNullListToList($nonNullBooleanList: [Boolean]!) {
  arguments {
    booleanListArgField(booleanListArg: $nonNullBooleanList)
  }
}

However, a nullable list cannot be passed to a non‐null list:

Counter Example № 173query listToNonNullList($booleanList: [Boolean]) {
  arguments {
    nonNullBooleanListField(nonNullBooleanListArg: $booleanList)
  }
}

This would fail validation because a [T] cannot be passed to a [T]!. Similarly a [T] cannot be passed to a [T!].

Allowing optional variables when default values exist

A notable exception to typical variable type compatibility is allowing a variable definition with a nullable type to be provided to a non‐null location as long as either that variable or that location provides a default value.

Example № 174query booleanArgQueryWithDefault($booleanArg: Boolean) {
  arguments {
    optionalNonNullBooleanArgField(optionalBooleanArg: $booleanArg)
  }
}

In the example above, an optional variable is allowed to be used in an non‐null argument which provides a default value.

Example № 175query booleanArgQueryWithDefault($booleanArg: Boolean = true) {
  arguments {
    nonNullBooleanArgField(nonNullBooleanArg: $booleanArg)
  }
}

In the example above, a variable provides a default value and can be used in a non‐null argument. This behavior is explicitly supported for compatibility with earlier editions of this specification. GraphQL authoring tools may wish to report this is a warning with the suggestion to replace Boolean with Boolean!.