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 query 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 query 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 query 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 query 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 query 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 query documents are full of named things: operations, fields, arguments, 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:

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

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

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

Semantics

2.9.5Enum 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.

An enum value cannot be “null” in order to avoid confusion. GraphQL does not supply a value literal to represent the concept null.

2.9.6List 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.7Input 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:

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

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

Semantics

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.

Built‐in Scalars

GraphQL provides a basic set of well‐defined Scalar types. A GraphQL server should support all of these types, and a GraphQL server which provide a type by these names must adhere to the behavior described below.

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 ordered maps, where the queried field names (or aliases) are the keys and the result of evaluating the field is the value, ordered by the order in which they appear in the query.

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 ordered map containing exactly the subset of the object queried, in the order in which they were 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:

{
  age
  name
}

Must only yield exactly that subset:

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

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"
  }
}

Field Ordering

When querying an Object, the resulting mapping of fields are conceptually ordered in the same order in which they were encountered during query execution, excluding fragments for which the type does not apply and fields or fragments that are skipped via @skip or @include directives. This ordering is correctly produced when using the CollectFields() algorithm.

Response formats which support ordered maps (such as JSON) must maintain this ordering. Response formats which do not support ordered maps may disregard this ordering.

If a fragment is spread before other fields, the fields that fragment specifies occur in the response before the following fields.

{
  foo
  ...Frag
  qux
}

fragment Frag on Query {
  bar
  baz
}

Produces the ordered result:

{
  "foo": 1,
  "bar": 2,
  "baz": 3,
  "qux": 4
}

If a field is queried multiple times in a selection, it is ordered by the first time it is encountered. However fragments for which the type does not apply does not affect ordering.

{
  foo
  ...Ignored
  ...Matching
  bar
}

fragment Ignored on UnknownType {
  qux
  baz
}

fragment Matching on Query {
  bar
  qux
  foo
}

Produces the ordered result:

{
  "foo": 1,
  "bar": 2,
  "qux": 3
}

Also, if directives result in fields being excluded, they are not considered in the ordering of fields.

{
  foo @skip(if: true)
  bar
  foo
}

Produces the ordered result:

{
  "bar": 1,
  "foo": 2
}

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 implements NamedEntity {
  name: String
  age: Int
}

type Business implements 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 list 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 wraps an underlying type, and this type acts identically to that wrapped type, with the exception that null is not a valid response for the wrapping type. A trailing exclamation mark is used to denote a field that uses a Non‐Null type like this: name: String!.

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 coercion of the wrapped type should be performed. If that result was not null, then the result of coercing the Non Null type is that result. If that result was null, then a field error must be raised.

Input Coercion

If the argument of a Non Null type is not provided, a query error must be raised.

If an argument of a Non Null type is provided with a literal value, it is coerced using the input coercion for the wrapped type.

If the argument of a Non Null is provided with a variable, a query error must be raised if the runtime provided value is not provided or is null in the provided representation (usually JSON). Otherwise, the coerced value is the result of using the input coercion for the wrapped type.

{
  field(arg: null)
}

to indicate that the argument is null. Instead, an argument would be null only if it is omitted:

{
  field
}

Or if passed a variable of a nullable type that at runtime was not provided a value:

query withNullableVariable($var: String) {
  field(arg: $var)
}

3.2.1@skip

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 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, fragment spreads, and inline 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)
}

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
}

4.2.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.2.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) 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.2.5The __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.1Named Operation Definitions

query getDogName {
  dog {
    name
  }
}

query getOwnerName {
  dog {
    owner {
      name
    }
  }
}

query getName {
  dog {
    name
  }
}

query getName {
  dog {
    owner {
      name
    }
  }
}

query dogOperation {
  dog {
    name
  }
}

mutation dogOperation {
  mutateDog {
    id
  }
}

5.1.2Anonymous Operation Definitions

{
  dog {
    name
  }
}

{
  dog {
    name
  }
}

query getName {
  dog {
    owner {
      name
    }
  }
}

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

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

But the following is invalid:

fragment directFieldSelectionOnUnion on CatOrDog {
  name
  barkVolume
}

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

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:

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

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:

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

fragment conflictingDifferingResponses on Pet {
  ... on Dog {
    someValue: nickname
  }
  ... on Cat {
    someValue: meowVolume
  }
}

5.2.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 on Dog {
  barkVolume
}

The following is invalid.

fragment scalarSelectionsNotAllowedOnBoolean on 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 additions to the query root type of the schema:

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

The following examples are invalid

query directQueryOnObjectWithoutSubFields {
  human
}

query directQueryOnInterfaceWithoutSubFields {
  pet
}

query directQueryOnUnionWithoutSubFields {
  catOrDog
}

5.3.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!): Int!
  booleanArgField(booleanArg: Boolean): Boolean
  floatArgField(floatArg: Float): Float
  intArgField(intArg: Int): Int
  nonNullBooleanArgField(nonNullBooleanArg: Boolean!): Boolean!
  booleanListArgField(booleanListArg: [Boolean]!): [Boolean]
}

extend type QueryRoot {
  arguments: Arguments
}

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

5.3.3Argument 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 {
  nonNullBooleanArgField
}

5.4.1Fragment Declarations

{
  dog {
    ...fragmentOne
    ...fragmentTwo
  }
}

fragment fragmentOne on Dog {
  name
}

fragment fragmentTwo on Dog {
  owner {
    name
  }
}

{
  dog {
    ...fragmentOne
  }
}

fragment fragmentOne on Dog {
  name
}

fragment fragmentOne on Dog {
  owner {
    name
  }
}

fragment correctType on Dog {
  name
}

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

fragment inlineFragment2 on Dog {
  ... @include(if: true) {
    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.4.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 {
  ...catOrDogNameFragment
}

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.5.1Input 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 fields of the same name, otherwise an amgibuity would exist which includes an ignored portion of syntax.

For example the following query will not pass validation.

{
  field(arg: { field: true, field: false })
}

5.6.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.6.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 effects.
• 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.

query @skip(if: $foo) {
  field
}

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

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

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

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

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

5.7.2Variable Default Values Are Correctly Typed

Formal Specification

• For every operation in a document
• For every variable on each operation
  • Let variableType be the type of variable
  • If variableType is non‐null it cannot have a default value
  • If variable has a default value it must be of the same types or able to be coerced to variableType

Explanatory Text

Variables defined by operations are allowed to define default values if the type of that variable is not non‐null.

For example the following query will pass validation.

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

However if the variable is defined as non‐null, default values are unreachable. Therefore queries such as the following fail validation

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

Default values must be compatible with the types of variables. Types must match or they must be coercible to the type.

Non‐matching types fail, such as in the following example:

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

However if a type is coercible the query will pass validation.

For example:

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

5.7.3Variables Are Input Types

Formal Specification

• For every operation in a document
• For every variable on each operation
  • Let variableType be the type of variable
  • While variableType is LIST or NON_NULL
    • Let variableType be the referenced type of variableType
  • variableType must of kind SCALAR, ENUM or INPUT_OBJECT

Explanatory Text

Variables can only be scalars, enums, input objects, or lists and non‐null variants of those types. These are known as input types. Object, unions, and interfaces cannot be used as inputs.

For these examples, consider the following typesystem additions:

input ComplexInput { name: String, owner: String }

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

The following queries are valid:

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

query takesCat($cat: Cat) {
  # ...
}

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

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

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

5.7.4All Variable Uses Defined

Formal Specification

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

Explanatory Text

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

For example:

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

is valid. $atOtherHomes is defined by the operation.

By contrast the following query is invalid:

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

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

query variableIsNotDefinedUsedInSingleFragment {
  dog {
    ...isHousetrainedFragment
  }
}

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

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

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

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

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

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

However the following does not validate:

query 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.7.5All 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:

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

because $atOtherHomes in not referenced.

These rules apply to transitive fragment spreads as well:

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

query variableNotUsedWithinFragment($atOtherHomes: Boolean) {
  ...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.

query 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.7.6All 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 variableType be the type of variable definition in the operation
  • Let argumentType be the type of the argument the variable is passed to.
  • Let hasDefault be true if the variable definition defines a default.
  • AreTypesCompatible(argumentType, variableType, hasDefault) must be true
• AreTypesCompatible(argumentType, variableType, hasDefault):
  • If hasDefault is true, treat the variableType as non‐null.
  • If inner type of argumentType and variableType be different, return false
  • If argumentType and variableType have different list dimensions, return false
  • If any list level of variableType is not non‐null, and the corresponding level in argument is non‐null, the types are not compatible.

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 not‐null argument type.

Types must match:

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

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

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

A notable exception is when default arguments are provided. They are, in effect, treated as non‐nulls.

query booleanArgQueryWithDefault($booleanArg: Boolean = true) {
  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:

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

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

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

6.6.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 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.6.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.6.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.6.4Nullability

If the result of resolving a field is null (either because the function to resolve the field returned null or because an error occurred), and that field is of a Non-Null type, then a field error is thrown.

If the field was null because of an error which has already been added to the "errors" list in the response, the "errors" list must not be further affected.

If the field resolve function returned null, the resulting field error must be added to the "errors" list in the response.

6.6.5Error 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.

However, if the type of that field is of a Non-Null type, since the field cannot be null the error is propogated to be dealt with by the parent field.

If all fields from the root of the request to the source of the error return Non-Null types, then the "data" entry in the response should be null.

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.