2.10.1Types on fragments

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:

query 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.

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

2.10.2Query variables in fragments

Query variables can be used within fragments. Query variables have global scope with a given operation, so a variable used within a fragment must be declared in any top‐level operation that transitively consumes that fragment. If a variable is referenced in a fragment and is included by an operation that does not define that variable, the operation cannot be executed.

2.10.3Inline fragments

Fragments can be defined inline to query. This is done to conditionally execute 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.

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

2.11.1Fragment Directives

Fragments may include directives to alter their behavior. At runtime, the directives provided on a fragment spread override those described on the definition.

For example, the following query:

query hasConditionalFragment($condition: Boolean) {
...maybeFragment @include(if: $condition)
}

fragment maybeFragment on Query {
me {
name
}
}

Will have identical runtime behavior as

query hasConditionalFragment($condition: Boolean) {
...maybeFragment
}

fragment maybeFragment on Query @include(if: $condition) {
me {
name
}
}

3.1.1Scalars

As expected by the name, a scalar represents a primitive value in GraphQL. GraphQL responses take the form of a hierarchical tree; the leaves on these trees are GraphQL scalars.

All GraphQL scalars are representable as strings, though depending on the response format being used, there may be a more appropriate primitive for the given scalar type, and server should use those types when appropriate.

GraphQL provides a number of built‐in scalars, but type systems can add additional scalars with semantic meaning. For example, a GraphQL system could define a scalar called Time which, while serialized as a string, promises to conform to ISO‐8601. When querying a field of type Time, you can then rely on the ability to parse the result with an ISO‐8601 parser and use a client‐specific primitive for time. Another example of a potentially useful custom scalar is Url, which serializes as a string, but is guaranteed by the server to be a valid URL.

Result Coercion

A GraphQL server, when preparing a field of a given scalar type, must uphold the contract the scalar type describes, either by coercing the value or producing an error.

For example, a GraphQL server could be preparing a field with the scalar type Int and encounter a floating‐point number. Since the server must not break the contract by yielding a non‐integer, the server should truncate the fractional value and only yield the integer value. If the server encountered a boolean true value, it should return 1. If the server encountered a string, it may attempt to parse the string for a base‐10 integer value. If the server encounters some value that cannot be reasonably coerced to an Int, then it must raise a field error.

Since this coercion behavior is not observable to clients of the GraphQL server, the precise rules of coercion are left to the implementation. The only requirement is that the server must yield values which adhere to the expected Scalar type.

Input Coercion

If a GraphQL server 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.

GraphQL has different constant literals to represent integer and floating‐point input values, and coercion rules may apply differently depending on which type of input value is encountered. GraphQL may be parameterized by query variables, the values of which are often serialized when sent over a transport like HTTP. Since some common serializations (ex. JSON) do not discriminate between integer and floating‐point values, they are interpreted as an integer input value if they have an empty fractional part (ex. 1.0) and otherwise as floating‐point input value.

3.1.2Objects

GraphQL queries are hierarchical and composed, describing a tree of information. While Scalar types describe the leaf values of these hierarchical queries, Objects describe the intermediate levels.

GraphQL Objects represent a list of named fields, each of which yield a value of a specific type. Object values are serialized as unordered maps, where the queried field names (or aliases) are the keys and the result of evaluating the field is the value.

For example, a type Person could be described as:

type Person {
name: String
age: Int
picture: Url
}

Where name is a field that will yield a String value, and age is a field that will yield an Int value, and picture a field that will yield a Url value.

A query of an object value must select at least one field. This selection of fields will yield an unordered map containing exactly the subset of the object queried. Only fields that are declared on the object type may validly be queried on that object.

For example, selecting all the fields of Person:

{
name
age
picture
}

Would yield the object:

{
"name": "Mark Zuckerberg",
"age": 30,
"picture": "http://some.cdn/picture.jpg"
}

While selecting a subset of fields:

{
name
age
}

Must only yield exactly that subset:

{
"name": "Mark Zuckerberg",
"age": 30
}

A field of an Object type may be a Scalar, Enum, another Object type, an Interface, or a Union. Additionally, it may be any wrapping type whose underlying base type is one of those five.

For example, the Person type might include a relationship:

type Person {
name: String
age: Int
picture: Url
relationship: Person
}

Valid queries must supply a nested field set for a field that returns an object, so this query is not valid:

{
name
relationship
}

However, this example is valid:

{
name
relationship {
name
}
}

And will yield the subset of each object type queried:

{
"name": "Mark Zuckerberg",
"relationship": {
"name": "Priscilla Chan"
}
}

Result Coercion

Determining the result of coercing an object is the heart of the GraphQL executor, so this is covered in that section of the spec.

Input Coercion

Objects are never valid inputs.

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

{
name
picture(size: 600)
}

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

3.1.3Interfaces

GraphQL Interfaces represent a list of named fields and their arguments. GraphQL object can then implement an interface, which guarantees that they will contain the specified fields.

Fields on a GraphQL interface have the same rules as fields on a GraphQL object; their type can be Scalar, Object, Enum, Interface, or Union, or any wrapping type whose base type is one of those five.

For example, an interface may describe a required field and types such as Person or Business may then implement this interface.

interface NamedEntity {
name: String
}

type Person : NamedEntity {
name: String
age: Int
}
type Business : NamedEntity {
name: String
employeeCount: Int
}

Fields which yield an interface are useful when one of many Object types are expected, but some fields should be guaranteed.

To continue the example, a Contact might refer to NamedEntity.

type Contact {
entity: NamedEntity
phoneNumber: String
address: String
}

This allows us to write a query for a Contact that can select the common fields.

{
entity {
name
}
phoneNumber
}

When querying for fields on an interface type, only those fields declared on the interface may be queried. In the above example, entity returns a NamedEntity, and name is defined on NamedEntity, so it is valid. However, the following would not be a valid query:

{
entity {
name
age
}
phoneNumber
}

because entity refers to a NamedEntity, and age is not defined on that interface. Querying for age is only valid when the result of entity is a Person; the query can express this using a fragment or an inline fragment:

{
entity {
name
... on Person {
  age
}
},
phoneNumber
}

Result Coercion

The interface type should have some way of determining which object a given result corresponds to. Once it has done so, the result coercion of the interface is the same as the result coercion of the object.

Input Coercion

Interfaces are never valid inputs.

3.1.4Unions

GraphQL Unions represent an object that could be one of a list of GraphQL Object types, but provides for no guaranteed fields between those types. They also differ from interfaces in that Object types declare what interfaces they implement, but are not aware of what unions contain them.

With interfaces and objects, only those fields defined on the type can be queried directly; to query other fields on an interface, typed fragments must be used. This is the same as for unions, but unions do not define any fields, so no fields may be queried on this type without the use of typed fragments.

For example, we might have the following type system:

Union SearchResult = Photo | Person

type Person {
name: String
age: Int
}
type Photo {
height: Int
width: Int
}
type SearchQuery {
firstSearchResult: SearchResult
}

When querying the firstSearchResult field of type SearchQuery, the query would ask for all fields inside of a fragment indicating the appropriate type. If the query wanted the name if the result was a Person, and the height if it was a photo, the following query is invalid, because the union itself defines no fields:

{
firstSearchResult {
name
height
}
}

Instead, the query would be:

{
firstSearchResult {
... on Person {
  name
}
... on Photo {
  height
}
}
}

Result Coercion

The union type should have some way of determining which object a given result corresponds to. Once it has done so, the result coercion of the union is the same as the result coercion of the object.

Input Coercion

Unions are never valid inputs.

3.1.5Enums

GraphQL Enums are a variant on the Scalar type, which represents one of a finite set of possible values.

GraphQL Enums are not references for a numeric value, but are unique values in their own right. They serialize as a string: the name of the represented value.

Result Coercion

GraphQL servers must return one of the defined set of possible values, if a 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.

Query variable transport serializations which have a different representation for non‐string symbolic values (for example, EDN) should only allow such values as enum input values. Otherwise, for most transport serializations that do not, strings may be interpreted as the enum input value with the same name.

3.1.6Input Objects

Fields can define arguments that the client passes up with the query, to configure their behavior. These inputs can be Strings or Enums, but they sometimes need to be more complex than this.

The Object type defined above is inappropriate for re‐use here, because Objects can contain fields that express circular references or references to interfaces and unions, neither of which is appropriate for use as an input argument. For this reason, input objects have a separate type in the system.

An Input Object defines a set of input fields; the input fields are either scalars, enums, or other input objects. This allows arguments to accept arbitrarily complex structs.

Result Coercion

An input object is never a valid result.

Input Coercion

The input to an input object should be an unordered map, otherwise an error should be thrown. The result of the coercion is an unordered map, with an entry for each input field, whose key is the name of the input field. The value of an entry in the coerced map is the result of input coercing the value of the entry in the input with the same key; if the input does not have a corresponding entry, the value is the result of coercing null. The input coercion above should be performed according to the input coercion rules of the type declared by the input field.

3.1.7Lists

A GraphQL list is a special collection type which declares the type of each item in the List (referred to as the item type of the list). List values are serialized as ordered lists, where each item in the array is serialized as per the item type. To denote that a field uses a List type the item type is wrapped in square brackets like this: pets: [Pet].

Result Coercion

GraphQL servers must return an ordered list as the result of a list type. Each item in the list must be the result of a result coercion of the item type. If a reasonable coercion is not possible they must raise a field error. In particular, if a non‐list is returned, the coercion should fail, as this indicates a mismatch in expectations between the type system and the implementation.

Input Coercion

When expected as an input, list values are accepted only when each item in the list can be accepted by the list’s item type.

If the value passed as an input to a list type is not as list, it should be coerced as though the input was a list of size one, where the value passed is the only item in the list. This is to allow inputs that accept a “var args” to declare their input type as a list; if only one argument is passed (a common case), the client can just pass that value rather than constructing the list.

3.1.8Non-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 declares an underlying type, and this type acts identically to that underlying 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!.

Result Coercion

In all of the above result coercion, null was considered a valid value. To coerce the result of a Non Null type, the result coercion of the underlying 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 an error should be raised.

Input Coercion

{
field(arg: null)
}

to indicate that the argument is null. Instead, an argument would be null only if it is passed a variable that is then not set:

{
field(arg: $var)
}

Hence, if the value for a non‐null is hard‐coded in the query, it is always coerced using the input coercion for the wrapped type.

When a non‐null input has its value set using a variable, the coerced value should be null if the provided value is null-like in the provided representation, or if the provided value is omitted. Otherwise, the coerced value is the result of running the wrapped type’s input coercion on the provided value.

3.2.1@skip

The @skip directive may be provided for fields or fragments, and allows for conditional exclusion during execution as described by the if argument.

In this example experimentalField will be queried only if the $someTest is provided a false value.

query myQuery($someTest: Boolean) {
experimentalField @skip(if: $someTest)
}

3.2.2@include

The @include directive may be provided for fields or fragments, and allows for conditional inclusion during execution as described by the if argument.

In this example experimentalField will be queried only if the $someTest is provided a true value.

query myQuery($someTest: Boolean) {
experimentalField @include(if: $someTest)
}

The @skip directive has precedence over the @include directive should both be provided in the same context.

4.1.1Naming conventions

Types and fields required by the GraphQL introspection system that are used in the same context as user‐defined type and fields are prefixed with two underscores. This in order to avoid naming collisions with user‐defined GraphQL types. Conversely, GraphQL type system authors must not define any types, fields, arguments, or any other type system artifact with two leading underscores.

4.1.2Documentation

All types in the introspection system provide a description field of type String to allow type designers to publish documentation in addition to capabilities. A GraphQL server may return the description field using Markdown syntax. Therefore it is recommended that any tool that displays description use a Markdown renderer.

4.1.3Deprecation

To support the management of backwards compatibility, GraphQL fields and enum values can indicate whether or not they are deprecated (isDeprecated: Boolean) and a description of why it is deprecated (deprecationReason: String).

Tools built using GraphQL introspection should respect deprecation by discouraging deprecated use through information hiding or developer‐facing warnings.

4.1.4Type Name Introspection

GraphQL supports type name introspection at any point within a query by the meta field __typename: String! when querying against any Object, Interface, or Union. It returns the name of the object type currently being queried.

This is most often used when querying against Interface or Union types to identify which actual type of the possible types has been returned.

This field is implicit and does not appear in the fields list in any defined type.

4.2.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.2.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.

type Point {
x: Int
y: Int
}

5.1.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 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:

fragment 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 is not relevant to the validity of the given interface‐typed selection set.

For example, the following is valid:

fragment interfaceFieldSelection on Pet {
name
}

and the following is invalid:

fragment definedOnImplementorsButNotInterface on Pet {
nickname
}

Because fields are not declared on unions, direct field selection on union‐typed selection set. This is true even if concrete implementors of the union define the fieldName.

For example the following is invalid

fragment directFieldSelectionOnUnion on CatOrDog {
directField
}

fragment definedOnImplementorsQueriedOnUnion on CatOrDog {
name
}

5.1.2Field Selection Merging

Formal Specification

• Let set be any selection set defined in the GraphQL document
• Let setForKey be the set of selections with a given response key in set
• All members of setForKey must:
  • Have identical target fields
  • Have identical sets of arguments.
  • Have identical sets of directives.

Explanatory Text

Selection names are de‐duplicated and merged for validation, but the target field, arguments, and directives must all be identical.

For human‐curated GraphQL, this rules seem a bit counterintuitive since it appears to be clear developer error. However in the presence of nested fragments or machine‐generated GraphQL, requiring unique selections is a burdensome limitation on tool authors.

The following selections correctly merge:

fragment mergeIdenticalFields on Dog {
name
name
}

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

The following is not able to merge:

fragment 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:

fragment 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:

fragment 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)
}

The same logic applies to directives. The set of directives on each selection with the same response key in a given scope must be identical.

The following is valid:

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

and the following is invalid:

fragment conflictingDirectiveArgs on Dog {
name @include(if: true)
name @include(if: false)
}

5.1.3Leaf Field Selections

Formal Specification

• For each selection in the document
• Let selectionType be the result type of selection
• If selectionType is a scalar:
  • 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 are never allowed: scalars are the leaf nodes of any GraphQL query.

The following is valid.

fragment scalarSelection: Dog {
barkVolume
}

The following is invalid.

fragment scalarSelectionsNotAllowedOnBoolean : Dog {
barkVolume {
sinceWhen
}
}

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

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

type QueryRoot {
human: Human
pet: Pet
catOrDog: CatOrDog
}

The following examples are invalid

query directQueryOnObjectWithoutSubFields {
human
}

query directQueryOnInterfaceWithoutSubFields {
pet
}
query directQueryOnUnionWithoutSubFields {
catOrDog
}

5.2.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:

fragment 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.

fragment invalidArgName on Dog {
doesKnowCommand(command: CLEAN_UP_HOUSE)
}

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

fragment 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:

type Arguments {
multipleReqs(x: Int!, y: Int!)
booleanArgField(booleanArg: Boolean)
floatArgField(floatArg: Float)
intArgField(intArg: Int)
nonNullBooleanArgField(nonNullBooleanArg: Boolean!)
}

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

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

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

5.2.2Argument Values Type Correctness

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

fragment coercedIntIntoFloatArg on Arguments {
floatArgField(floatArg: 1)
}

fragment stringIntoInt on Arguments {
intArgField(intArg: "3")
}

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

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

fragment goodBooleanArgDefault on Arguments {
booleanArgField
}

fragment missingRequiredArg on Arguments {
notNullBooleanArgField
}

5.3.1Fragment Declarations

fragment correctType on Dog {
name
}

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

fragment notOnExistingType on NotInSchema {
name
}

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

fragment fragOnObject on Dog {
name
}

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

fragment fragOnScalar on Int {
something
}

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

fragment nameFragment on Dog { # unused
name
}

{
dog {
name
}
}

5.3.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.

{
dog {
...undefinedFragment
}
}

{
dog {
...nameFragment
}
}

fragment nameFragment on Dog {
name
...barkVolumeFragment
}
fragment barkVolumeFragment on Dog {
barkVolume
...nameFragment
}

{
dog {
name
barkVolume
name
barkVolume
name
barkVolume
name

forever...
}
}

{
dog {
...dogFragment
}
}

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

fragment dogFragment on Dog {
... on Dog {
barkVolume
}
}

fragment catInDogFragmentInvalid on Dog {
... on Cat {
meowVolume
}
}

fragment petNameFragment on Pet {
name
}

fragment interfaceWithinObjectFragment on Dog {
...petNameFragment
}

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

fragment unionWithObjectFragment on Dog {
...CatOrDogFragment
}

fragment petFragment on Pet {
name
... on Dog {
barkVolume
}
}

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

fragment sentientFragment on Sentient {
... on Dog {
barkVolume
}
}

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

fragment unionWithInterface on Pet {
...dogOrHumanFragment
}

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

fragment nonIntersectingInterfaces on Pet {
...sentientFragment
}

fragment sentientFragment on Sentient {
name
}

5.4.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.5.1Variables

query houseTrainedQuery($atOtherHomes: Boolean = true) {
dog {
isHousetrained(atOtherHomes: $atOtherHomes)
}
}

query houseTrainedQuery($atOtherHomes: Boolean! = true) {
dog {
isHousetrained(atOtherHomes: $atOtherHomes)
}
}

query houseTrainedQuery($atOtherHomes: Boolean = "true") {
dog {
isHousetrained(atOtherHomes: $atOtherHomes)
}
}

query intToFloatQuery($floatVar: Float = 1) {
arguments {
floatArgField(floatArg: $floatVar)
}
}

query takesBoolean($atOtherHomes: Boolean) {

...
}
query takesComplexInput($complexInput: ComplexInput) {
...
}
query TakesListOfBooleanBang($booleans: [Boolean!]) {
...
}

query takesCat($cat: Cat) {

...
}
query takesDogBang($dog: Dog!) {
...
}
query takesListOfPet($pets: [Pet]) {
...
}
query takesCatOrDog($catOrDog: CatOrDog) {
...
}

query variableIsDefined($atOtherHomes: Boolean) {
dog {
isHousetrained(atOtherHomes: $booleanArg)
}
}

query variableIsNotDefined {
dog {
isHousetrained(atOtherHomes: $atOtherHomes)
}
}

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

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

query variableIsNotDefinedUsedInSingleFragment {
dog {
...isHousetrainedFragment
}
}

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

query variableIsNotDefinedUsedInNestedFragment {
dog {
...outerHousetrainedFragment
}
}

fragment outerHousetrainedFragment on Dog {
...isHousetrainedFragment
}
fragment isHousetrainedFragment on Dog {
isHousetrained(atOtherHomes: $atOtherHomes}
}

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

query housetrainedQueryTwo($atOtherHomes: Boolean) {
dog {
...isHousetrainedFragment
}
}
fragment isHousetrainedFragment on Dog {
isHousetrained(atOtherHomes: $atOtherHomes}
}

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

query housetrainedQueryTwoNotDefined {
dog {
...isHousetrainedFragment
}
}
fragment isHousetrainedFragment on Dog {
isHousetrained(atOtherHomes: $atOtherHomes)
}

query variableUnused($atOtherHomes: Boolean) {
dog {
isHousetrained
}
}

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

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

query variableNotUsedWithinFragment($atOtherHomes: Boolean) {
...isHousetrainedWithoutVariableFragment
}

fragment isHousetrainedWithoutVariableFragment on Dog {
isHousetrained
}

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

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

query intCannotGoIntoBoolean($intArg: Int) {
arguments {
booleanArgField(booleanArg: $intArg)
}
}

query booleanListCannotGoIntoBoolean($booleanListArg: [Boolean]) {
arguments {
booleanArgField(booleanArg: $booleanListArg)
}
}

query booleanArgQuery($booleanArg: Boolean) {
arguments {
nonNullBooleanArgField(nonNullBooleanArg: $booleanArg)
}
}

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

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

query listToNonNullList($booleanList: [Boolean]) {
arguments {
nonNullBooleanListField(nonNullBooleanListArg: $booleanList)
}
}

6.4.1Field entries

Each item in the grouped field set can potentially create an entry in the result map. That entry in the result map is the result is the result of calling GetFieldEntry on the corresponding item in the grouped field set. GetFieldEntry can return null, which indicates that there should be no entry in the result map for this item. Note that this is distinct from returning an entry with a string key and a null value, which indicates that an entry in the result should be added for that key, and its value should be null.

GetFieldEntry assumes the existence of two functions that are not defined in this section of the spec. It is expected that the type system provides these methods:

• ResolveFieldOnObject, which takes an object type, a field, and an object, and returns the result of resolving that field on the object.
• GetFieldTypeFromObjectType, which takes an object type and a field, and returns that field’s type on the object type, or null if the field is not valid on the object type.

6.4.2Normal evaluation

When evaluating a grouped field set without a serial execution order requirement, the executor can determine the entries in the result map in whatever order it chooses. Because the resolution of fields other than top‐level mutation fields is always side effect–free and idempotent, the execution order must not affect the result, and hence the server has the freedom to evaluate the field entries in whatever order it deems optimal.

For example, given the following grouped field set to be evaluated normally:

{
birthday {
month
}
address {
street
}
}

A valid GraphQL executor can resolve the four fields in whatever order it chose.

6.4.3Serial execution

Observe that based on the above sections, the only time an executor will run in serial execution order is on the top level selection set of a mutation operation and on its corresponding grouped field set.

When evaluating a grouped field set serially, the executor must consider each entry from the grouped field set in the order provided in the grouped field set. It must determine the corresponding entry in the result map for each item to completion before it continues on to the next item in the grouped field set:

For example, given the following selection set to be evaluated serially:

{
changeBirthday(birthday: $newBirthday) {
month
}
changeAddress(address: $newAddress) {
street
}
}

The executor must, in serial:

• Run getFieldEntry for changeBirthday, which during CompleteValue will evaluate the { month } sub‐selection set normally.
• Run getFieldEntry for changeAddress, which during CompleteValue will evaluate the { street } sub‐selection set normally.

As an illustrative example, let’s assume we have a mutation field changeTheNumber that returns an object containing one field, theNumber. If we execute the following selection set serially:

{
first: changeTheNumber(newNumber: 1) {
theNumber
}
second: changeTheNumber(newNumber: 3) {
theNumber
}
third: changeTheNumber(newNumber: 2) {
theNumber
}
}

The executor will evaluate the following serially:

• Resolve the changeTheNumber(newNumber: 1) field
• Evaluate the { theNumber } sub‐selection set of first normally
• Resolve the changeTheNumber(newNumber: 3) field
• Evaluate the { theNumber } sub‐selection set of second normally
• Resolve the changeTheNumber(newNumber: 2) field
• Evaluate the { theNumber } sub‐selection set of third normally

A correct executor must generate the following result for that selection set:

{
"first": {
"theNumber": 1
},
"second": {
"theNumber": 3
},
"third": {
"theNumber": 2
}
}

6.4.4Error handling

If an error occurs when 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.

6.4.5Nullability

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 marked as being non‐null in the type system, then the result of evaluating the entire field set that contains this field is now null.

If the field was null because of an error, then the error has already been logged, and the “errors” list in the response must not be affected.

If the field resolution function returned null, and the field was non‐null, then no error has been logged, so an appropriate error must be added to the “errors” list.

7.1.1JSON Serialization

JSON is the preferred serialization format for GraphQL, though as noted above, GraphQL does not require a specific serialization format. For consistency and ease of notation, examples of the response are given in JSON throughout the spec. In particular, in our JSON examples, we will represent primitives using the following JSON concepts:

7.2.1Data

The data entry in the response will be the result of the execution of the 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 not be present in the result.

If an error was encountered during the execution that prevented a valid response, the data entry in the response should be null.

7.2.2Errors

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.

Every error must contain an entry with the key message with a string description of the error intended for the developer as a guide to understand and correct the error.

If an error can be associated to a particular point in the requested GraphQL document, it should contain an entry with the key locations with a list of locations, where each location is a map with the keys line and column, both positive numbers starting from 1 which describe the beginning of an associated syntax element.

GraphQL servers may provide additional entries to error as they choose to produce more helpful or machine‐readable errors, however future versions of the spec may describe additional entries to errors.

If the data entry in the response is null or 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 not 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.

8.3.1Document

A GraphQL document describes a complete file or request string. A document contains multiple definitions including an Operation.

8.3.2Operations

An operation describes some type of request to GraphQL. The most common operation is a query, a read‐only request for data from GraphQL. A short‐hand syntax exists for a query operation.

8.3.3Fragments

Fragments allow for the reuse of common selections of fields, reducing duplicated text in the document. Inline fragments can be used directly inline a selection to apply a type condition when querying against an interface or union.

8.3.4Values

Fields may take values for arguments. A value may be any JSON‐style value, a variable or an Enum value.

8.3.5Directives

Directives provide a way to describe runtime execution and type validation behavior in a GraphQL document.

8.3.6Types

GraphQL describes the schema of the data it provides using a type system. These types are referred to in the document when defining query variables.

Semantics