Query Shorthand

If a document contains only one operation and that operation is a query which defines no variables and has no directives applied to it then that operation may be represented in a short-hand form which omits the query keyword and operation name.

For example, this unnamed query operation is written via query shorthand.

Example № 6{
  field
}

Arguments Are Unordered

Arguments may be provided in any syntactic order and maintain identical semantic meaning.

These two operations are semantically identical:

Example № 12{
  picture(width: 200, height: 100)
}

Example № 13{
  picture(height: 100, width: 200)
}

Variable Use Within Fragments

Variables can be used within fragments. 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, that operation is invalid (see All Variable Uses Defined).

Semantics

Directive Order Is Significant

Directives may be provided in a specific syntactic order which may have semantic interpretation.

These two type definitions may have different semantic meaning:

Example № 34type Person
  @addExternalFields(source: "profiles")
  @excludeField(name: "photo") {
  name: String
}

Example № 35type Person
  @excludeField(name: "photo")
  @addExternalFields(source: "profiles") {
  name: String
}

Built-in Scalars

GraphQL specifies a basic set of well-defined Scalar types: Int, Float, String, Boolean, and ID. A GraphQL framework should support all of these types, and a GraphQL service which provides a type by these names must adhere to the behavior described for them in this document. As an example, a service must not include a type called Int and use it to represent 64-bit numbers, internationalization information, or anything other than what is defined in this document.

When returning the set of types from the __Schema introspection type, all referenced built-in scalars must be included. If a built-in scalar type is not referenced anywhere in a schema (there is no field, argument, or input field of that type) then it must not be included.

When representing a GraphQL schema using the type system definition language, all built-in scalars must be omitted for brevity.

Custom Scalars

GraphQL services may use custom scalar types in addition to the built-in scalars. For example, a GraphQL service could define a scalar called UUID which, while serialized as a string, conforms to RFC 4122. When querying a field of type UUID, you can then rely on the ability to parse the result with a RFC 4122 compliant parser. Another example of a potentially useful custom scalar is URL, which serializes as a string, but is guaranteed by the service to be a valid URL.

When defining a custom scalar, GraphQL services should provide a scalar specification URL via the @specifiedBy directive or the specifiedByURL introspection field. This URL must link to a human-readable specification of the data format, serialization, and coercion rules for the scalar.

For example, a GraphQL service providing a UUID scalar may link to RFC 4122, or some custom document defining a reasonable subset of that RFC. If a scalar specification URL is present, systems and tools that are aware of it should conform to its described rules.

Example № 43scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122")
scalar URL @specifiedBy(url: "https://tools.ietf.org/html/rfc3986")
scalar DateTime
  @specifiedBy(url: "https://scalars.graphql.org/andimarek/date-time")

Custom scalar specification URLs should provide a single, stable format to avoid ambiguity. If the linked specification is in flux, the service should link to a fixed version rather than to a resource which might change.

Custom scalar specification URLs should not be changed once defined. Doing so would likely disrupt tooling or could introduce breaking changes within the linked specification’s contents.

Built-in scalar types must not provide a scalar specification URL as they are specified by this document.

Result Coercion and Serialization

A GraphQL service, when preparing a field of a given scalar type, must uphold the contract the scalar type describes, either by coercing the value or producing a field error if a value cannot be coerced or if coercion may result in data loss.

A GraphQL service may decide to allow coercing different internal types to the expected return type. For example when coercing a field of type Int a boolean true value may produce 1 or a string value "123" may be parsed as base-10 123. However if internal type coercion cannot be reasonably performed without losing information, then it must raise a field error.

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

GraphQL scalars are serialized according to the serialization format being used. There may be a most appropriate serialized primitive for each given scalar type, and the service should produce each primitive where appropriate.

See Serialization Format for more detailed information on the serialization of scalars in common JSON and other formats.

Input Coercion

If a GraphQL service expects a scalar type as input to an argument, coercion is observable and the rules must be well defined. If an input value does not match a coercion rule, a request error must be raised (input values are validated before execution begins).

GraphQL has different constant literals to represent integer and floating-point input values, and coercion rules may apply differently depending on which type of input value is encountered. GraphQL may be parameterized by 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.

For all types below, with the exception of Non-Null, if the explicit value null is provided, then the result of input coercion is null.

Field Ordering

When querying an Object, the resulting mapping of fields are conceptually ordered in the same order in which they were encountered during 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 serialization formats capable of representing ordered maps should maintain this ordering. Serialization formats which can only represent unordered maps (such as JSON) should retain this order textually. That is, if two fields {foo, bar} were queried in that order, the resulting JSON serialization should contain {"foo": "...", "bar": "..."} in the same order.

Producing a response where fields are represented in the same order in which they appear in the request improves human readability during debugging and enables more efficient parsing of responses if the order of properties can be anticipated.

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

Example № 53{
  foo
  ...Frag
  qux
}

fragment Frag on Query {
  bar
  baz
}

Produces the ordered result:

Example № 54{
  "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 do not affect ordering.

Example № 55{
  foo
  ...Ignored
  ...Matching
  bar
}

fragment Ignored on UnknownType {
  qux
  baz
}

fragment Matching on Query {
  bar
  qux
  foo
}

Produces the ordered result:

Example № 56{
  "foo": 1,
  "bar": 2,
  "qux": 3
}

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

Example № 57{
  foo @skip(if: true)
  bar
  foo
}

Produces the ordered result:

Example № 58{
  "bar": 1,
  "foo": 2
}

Result Coercion

Determining the result of coercing an object is the heart of the GraphQL executor, see Value Completion.

Input Coercion

Objects are never valid inputs.

Type Validation

Object types have the potential to be invalid if incorrectly defined. This set of rules must be adhered to by every Object type in a GraphQL schema.

1. An Object type must define one or more fields.
2. For each field of an Object type:
   1. The field must have a unique name within that Object type; no two fields may share the same name.
   2. The field must not have a name which begins with the characters "__" (two underscores).
   3. The field must return a type where IsOutputType(fieldType) returns true.
   4. For each argument of the field:
      1. The argument must not have a name which begins with the characters "__" (two underscores).
      2. The argument must have a unique name within that field; no two arguments may share the same name.
      3. The argument must accept a type where IsInputType(argumentType) returns true.
      4. If argument type is Non-Null and a default value is not defined:
         1. The @deprecated directive must not be applied to this argument.
3. An object type may declare that it implements one or more unique interfaces.
4. An object type must be a super-set of all interfaces it implements:
   1. Let this object type be objectType.
   2. For each interface declared implemented as interfaceType, IsValidImplementation(objectType, interfaceType) must be true.

Interfaces Implementing Interfaces

When defining an interface that implements another interface, the implementing interface must define each field that is specified by the implemented interface. For example, the interface Resource must define the field id to implement the Node interface:

Example № 70interface Node {
  id: ID!
}

interface Resource implements Node {
  id: ID!
  url: String
}

Transitively implemented interfaces (interfaces implemented by the interface that is being implemented) must also be defined on an implementing type or interface. For example, Image cannot implement Resource without also implementing Node:

Example № 71interface Node {
  id: ID!
}

interface Resource implements Node {
  id: ID!
  url: String
}

interface Image implements Resource & Node {
  id: ID!
  url: String
  thumbnail: String
}

Interface definitions must not contain cyclic references nor implement themselves. This example is invalid because Node and Named implement themselves and each other:

Counter Example № 72interface Node implements Named & Node {
  id: ID!
  name: String
}

interface Named implements Node & Named {
  id: ID!
  name: String
}

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.

Type Validation

Interface types have the potential to be invalid if incorrectly defined.

1. An Interface type must define one or more fields.
2. For each field of an Interface type:
   1. The field must have a unique name within that Interface type; no two fields may share the same name.
   2. The field must not have a name which begins with the characters "__" (two underscores).
   3. The field must return a type where IsOutputType(fieldType) returns true.
   4. For each argument of the field:
      1. The argument must not have a name which begins with the characters "__" (two underscores).
      2. The argument must have a unique name within that field; no two arguments may share the same name.
      3. The argument must accept a type where IsInputType(argumentType) returns true.
3. An interface type may declare that it implements one or more unique interfaces, but may not implement itself.
4. An interface type must be a super-set of all interfaces it implements:
   1. Let this interface type be implementingType.
   2. For each interface declared implemented as implementedType, IsValidImplementation(implementingType, implementedType) must be true.

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.

Type Validation

Union types have the potential to be invalid if incorrectly defined.

1. A Union type must include one or more unique member types.
2. The member types of a Union type must all be Object base types; Scalar, Interface and Union types must not be member types of a Union. Similarly, wrapping types must not be member types of a Union.

Result Coercion

GraphQL services 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 request error.

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.

Type Validation

Enum types have the potential to be invalid if incorrectly defined.

1. An Enum type must define one or more unique enum values.

Circular References

Input Objects are allowed to reference other Input Objects as field types. A circular reference occurs when an Input Object references itself either directly or through referenced Input Objects.

Circular references are generally allowed, however they may not be defined as an unbroken chain of Non-Null singular fields. Such Input Objects are invalid because there is no way to provide a legal value for them.

This example of a circularly-referenced input type is valid as the field self may be omitted or the value null.

Example № 81input Example {
  self: Example
  value: String
}

This example is also valid as the field self may be an empty List.

Example № 82input Example {
  self: [Example!]!
  value: String
}

This example of a circularly-referenced input type is invalid as the field self cannot be provided a finite value.

Counter Example № 83input Example {
  value: String
  self: Example!
}

This example is also invalid, as there is a non-null singular circular reference via the First.second and Second.first fields.

Counter Example № 84input First {
  second: Second!
  value: String
}

input Second {
  first: First!
  value: String
}

Result Coercion

An input object is never a valid result. Input Object types cannot be the return type of an Object or Interface field.

Input Coercion

The value for an input object should be an input object literal or an unordered map supplied by a variable, otherwise a request error must be raised. In either case, the input object literal or unordered map must not contain any entries with names not defined by a field of this input object type, otherwise a request error must be raised.

The result of coercion is an unordered map with an entry for each field both defined by the input object type and for which a value exists. The resulting map is constructed with the following rules:

• If no value is provided for a defined input object field and that field definition provides a default value, the default value should be used. If no default value is provided and the input object field’s type is non-null, an error should be raised. Otherwise, if the field is not required, then no entry is added to the coerced unordered map.
• If the value null was provided for an input object field, and the field’s type is not a non-null type, an entry in the coerced unordered map is given the value null. In other words, there is a semantic difference between the explicitly provided value null versus having not provided a value.
• If a literal value is provided for an input object field, an entry in the coerced unordered map is given the result of coercing that value according to the input coercion rules for the type of that field.
• If a variable is provided for an input object field, the runtime value of that variable must be used. If the runtime value is null and the field type is non-null, a field error must be raised. If no runtime value is provided, the variable definition’s default value should be used. If the variable definition does not provide a default value, the input object field definition’s default value should be used.

Following are examples of input coercion for an input object type with a String field a and a required (non-null) Int! field b:

Example № 85input ExampleInputObject {
  a: String
  b: Int!
}

Type Validation

1. An Input Object type must define one or more input fields.
2. For each input field of an Input Object type:
   1. The input field must have a unique name within that Input Object type; no two input fields may share the same name.
   2. The input field must not have a name which begins with the characters "__" (two underscores).
   3. The input field must accept a type where IsInputType(inputFieldType) returns true.
   4. If input field type is Non-Null and a default value is not defined:
      1. The @deprecated directive must not be applied to this input field.
3. If an Input Object references itself either directly or through referenced Input Objects, at least one of the fields in the chain of references must be either a nullable or a List type.

Result Coercion

GraphQL services 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 it 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.

If a list’s item type is nullable, then errors occurring during preparation or coercion of an individual item in the list must result in a the value null at that position in the list along with a field error added to the response. If a list’s item type is non-null, a field error occurring at an individual item in the list must result in a field error for the entire list.

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 a list and not the null value, then the result of input coercion is a list of size one, where the single item value is the result of input coercion for the list’s item type on the provided value (note this may apply recursively for nested lists).

This allows inputs which accept one or many arguments (sometimes referred to as “var args”) to declare their input type as a list while for the common case of a single value, a client can just pass that value directly rather than constructing the list.

Following are examples of input coercion with various list types and values:

Nullable vs. Optional

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

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

Result Coercion

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

Input Coercion

If an argument or input-object field of a Non-Null type is not provided, is provided with the literal value null, or is provided with a variable that was either not provided a value at runtime, or was provided the value null, then a request error must be raised.

If the value provided to the Non-Null type is provided with a literal value other than null, or a Non-Null variable value, it is coerced using the input coercion for the wrapped type.

A non-null argument cannot be omitted:

Counter Example № 86{
  fieldWithNonNullArg
}

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

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

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

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

Type Validation

1. A Non-Null type must not wrap another Non-Null type.

Built-in Directives

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

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

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

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

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

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

Custom Directives

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

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

Example № 89directive @example on FIELD

fragment SomeFragment on SomeType {
  field @example
}

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

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

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

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

Example № 91directive @example on FIELD_DEFINITION | ARGUMENT_DEFINITION

type SomeType {
  field(arg: Int @example): String @example
}

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

Example № 92directive @delegateField(name: String!) repeatable on OBJECT | INTERFACE

type Book @delegateField(name: "pageCount") @delegateField(name: "author") {
  id: ID!
}

extend type Book @delegateField(name: "index")

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

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

Validation

1. A directive definition must not contain the use of a directive which references itself directly.
2. A directive definition must not contain the use of a directive which references itself indirectly by referencing a Type or Directive which transitively includes a reference to this directive.
3. The directive must not have a name which begins with the characters "__" (two underscores).
4. For each argument of the directive:
   1. The argument must not have a name which begins with the characters "__" (two underscores).
   2. The argument must have a unique name within that directive; no two arguments may share the same name.
   3. The argument must accept a type where IsInputType(argumentType) returns true.

First Class Documentation

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 service may return the description field using Markdown syntax (as specified by CommonMark). Therefore it is recommended that any tool that displays description use a CommonMark-compliant Markdown renderer.

Deprecation

To support the management of backwards compatibility, GraphQL fields, arguments, input fields, and enum values can indicate whether or not they are deprecated (isDeprecated: Boolean!) along with 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.

Schema Introspection Schema

The schema introspection system is itself represented as a GraphQL schema. Below are the full set of type system definitions providing schema introspection, which are fully defined in the sections below.

type __Schema {
  description: String
  types: [__Type!]!
  queryType: __Type!
  mutationType: __Type
  subscriptionType: __Type
  directives: [__Directive!]!
}

type __Type {
  kind: __TypeKind!
  name: String
  description: String
  # must be non-null for OBJECT and INTERFACE, otherwise null.
  fields(includeDeprecated: Boolean = false): [__Field!]
  # must be non-null for OBJECT and INTERFACE, otherwise null.
  interfaces: [__Type!]
  # must be non-null for INTERFACE and UNION, otherwise null.
  possibleTypes: [__Type!]
  # must be non-null for ENUM, otherwise null.
  enumValues(includeDeprecated: Boolean = false): [__EnumValue!]
  # must be non-null for INPUT_OBJECT, otherwise null.
  inputFields(includeDeprecated: Boolean = false): [__InputValue!]
  # must be non-null for NON_NULL and LIST, otherwise null.
  ofType: __Type
  # may be non-null for custom SCALAR, otherwise null.
  specifiedByURL: String
}

enum __TypeKind {
  SCALAR
  OBJECT
  INTERFACE
  UNION
  ENUM
  INPUT_OBJECT
  LIST
  NON_NULL
}

type __Field {
  name: String!
  description: String
  args(includeDeprecated: Boolean = false): [__InputValue!]!
  type: __Type!
  isDeprecated: Boolean!
  deprecationReason: String
}

type __InputValue {
  name: String!
  description: String
  type: __Type!
  defaultValue: String
  isDeprecated: Boolean!
  deprecationReason: String
}

type __EnumValue {
  name: String!
  description: String
  isDeprecated: Boolean!
  deprecationReason: String
}

type __Directive {
  name: String!
  description: String
  locations: [__DirectiveLocation!]!
  args(includeDeprecated: Boolean = false): [__InputValue!]!
  isRepeatable: Boolean!
}

enum __DirectiveLocation {
  QUERY
  MUTATION
  SUBSCRIPTION
  FIELD
  FRAGMENT_DEFINITION
  FRAGMENT_SPREAD
  INLINE_FRAGMENT
  VARIABLE_DEFINITION
  SCHEMA
  SCALAR
  OBJECT
  FIELD_DEFINITION
  ARGUMENT_DEFINITION
  INTERFACE
  UNION
  ENUM
  ENUM_VALUE
  INPUT_OBJECT
  INPUT_FIELD_DEFINITION
}