Error Code

INVALID_GRAPHQL

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• schema must be a syntactically valid
• schema must be a semantically valid GraphQL schema according to the GraphQL specification.

Explanatory Text

Before composition, every individual source schema must be valid as per the official GraphQL specification. Common reasons a schema may be considered “invalid GraphQL” include:

• Syntax Errors: Missing braces, invalid tokens, or misplaced punctuation.
• Unknown Types: Referencing types that are not defined within the schema or imported from elsewhere.
• Invalid Directive Usage: Omitting required arguments to directives or using directives in disallowed locations.
• Invalid Default Values: Providing default values for arguments or fields that do not conform to the type (e.g., a default of null for a non-null field, an invalid enum value, etc.).
• Conflicting Type Definitions: Defining or overriding a built-in type or directive incorrectly.

When any of these validation checks fail for a particular source schema, that schema does not meet the baseline requirements for composition, and the composition process cannot proceed. An INVALID_GRAPHQL error is raised, prompting the schema owner to correct the GraphQL violations before retrying composition.

Examples

In the following counter-example, the schema is invalid because the type User is referenced in the Query type but never defined:

Counter Example № 54type Query {
  user: User
}

# The type "User" is never defined; this is invalid GraphQL.

In this counter-example, "INVALID_VALUE" is not a valid Role, causing INVALID_GRAPHQL.

Counter Example № 55enum Role {
  ADMIN
  USER
}

type Query {
  users(role: Role = "INVALID_VALUE"): [String]
}

The GraphQL spec requires all non-null directive arguments to be supplied. The omission of the fields argument in the @provides directive triggers INVALID_GRAPHQL.

Counter Example № 56directive @provides(fields: String!) on FIELD_DEFINITION

type Product {
  price: Float @provides
  # "fields" argument is required, but not provided.
}

Error Code

DISALLOWED_INACCESSIBLE

Severity

ERROR

Formal Specification

• Let type be the set of all types the schema.
• For each type in types:
  • If type is a built-in scalar type or introspection type:
    • IsAccessible(type) must be true.
    • For each field in type:
      • IsAccessible(field) must be true.
      • For each argument in field:
        • IsAccessible(argument) must be true.
• For each directive in directives:
  • If directive is a built-in directive:
    • For each argument in directive:
      • IsAccessible(argument) must be true.

Explanatory Text

This rule ensures that certain essential elements of a GraphQL schema, particularly built-in scalars, directive arguments, and introspection types, cannot be marked as @inaccessible. These types are fundamental to GraphQL. Making these elements inaccessible would break core GraphQL functionality.

Here, the String type is not marked as @inaccessible, which adheres to the rule:

Example № 57type Product {
  price: Float
  name: String
}

In this example, the String scalar is marked as @inaccessible. This violates the rule because String is a required built-in type that cannot be inaccessible:

Counter Example № 58scalar String @inaccessible

type Product {
  price: Float
  name: String
}

In this example, the introspection type __Type is marked as @inaccessible. This violates the rule because introspection types must remain accessible for GraphQL introspection queries to work.

Counter Example № 59type __Type @inaccessible {
  kind: __TypeKind!
  name: String
  fields(includeDeprecated: Boolean! = false): [__Field!]
}

Error Code

TYPE_DEFINITION_INVALID

Severity

ERROR

Formal Specification

• Let types be the set of built-in types (for example, FieldSelectionMap) defined by the composition specification from the schema.
• For each type in types:
  • Let kind be the kind of type.
  • kind must be equal to the kind defined by the composition specification.
  • If type is a directive:
    • Let expectedArguments be the set of arguments defined by the composition specification.
    • For each expectedArgument in expectedArguments:
      • Let name be the name of expectedArgument.
      • Let argument be the argument with name in type.
      • argument must be defined.
      • Let expectedType be the type of expectedArgument.
      • Let type be the type of argument.
      • type must be equal to expectedType.

Explanatory Text

Certain types (and directives) are reserved in composite schema specification for specific purposes and must adhere to the specification’s definitions. For example, FieldSelectionMap is a built-in scalar that represents a selection of fields as a string. Redefining these built-in types with a different kind (e.g., an input object, enum, union, or object type) is disallowed and makes the composition invalid.

To ensure schema evolution and interoperability, directives may include additional arguments, provided that all required arguments defined by the specification are present.

This rule ensures that built-in types maintain their expected shapes and semantics so the composed schema can correctly interpret them.

Examples

In the following counter-example, FieldSelectionMap is declared as an input type instead of the required scalar. This leads to a TYPE_DEFINITION_INVALID error because the defined scalar FieldSelectionMap is being overridden by an incompatible definition.

Counter Example № 60directive @require(field: FieldSelectionMap!) on ARGUMENT_DEFINITION

input FieldSelectionMap {
  fields: [String!]!
}

In the following example, the @key directive includes an additional argument, futureArg, which is not part of the specification. This is valid and allows the directive to evolve without breaking existing schemas.

Example № 61directive @key(
  fields: FieldSelectionSet!
  futureArg: String
) repeatable on OBJECT | INTERFACE

However, if the @key directive is defined without the required fields argument, as shown below, it results in a TYPE_DEFINITION_INVALID error.

Counter Example № 62directive @key(futureArg: String) repeatable on OBJECT | INTERFACE

Error Code

QUERY_ROOT_TYPE_INACCESSIBLE

Severity

ERROR

Formal Specification

• Let queryType be the query operation type defined in the schema.
• If queryType is annotated with @inaccessible:
  • Produce a QUERY_ROOT_TYPE_INACCESSIBLE error.

Explanatory Text

Every source schema that contributes to the final composite schema must expose a public (accessible) root query type. Marking the root query type as @inaccessible makes it invisible to the gateway, defeating its purpose as the primary entry point for queries and lookups.

Examples

In this example, no @inaccessible annotation is applied to the query root, so the rule is satisfied.

Example № 63schema {
  query: Query
}

type Query {
  allBooks: [Book]
}

type Book {
  id: ID!
  title: String
}

Since the schema marks the query root type as @inaccessible, the rule is violated. QUERY_ROOT_TYPE_INACCESSIBLE is raised because a schema’s root query type cannot be hidden from consumers.

Counter Example № 64schema {
  query: Query
}

type Query @inaccessible {
  allBooks: [Book]
}

type Book {
  id: ID!
  title: String
}

Error Code

ROOT_MUTATION_USED

Severity

ERROR

Formal Specification

• Let rootMutation be the root mutation type defined in the schema, if it exists.
• Let namedMutationType be the type with the name Mutation in schema, if it exists.
• If rootMutation is defined:
  • rootMutation must be named Mutation.
• Otherwise, namedMutationType must not be defined.

Explanatory Text

This rule enforces that, for any source schema, if a root mutation type is defined, it must be named Mutation. Defining a root mutation type with a name other than Mutation or using a differently named type alongside a type explicitly named Mutation creates inconsistencies in schema design and violates the composite schema specification.

Examples

Valid example:

Example № 65schema {
  mutation: Mutation
}

type Mutation {
  createProduct(name: String): Product
}

type Product {
  id: ID!
  name: String
}

The following counter-example violates the rule because RootMutation is used as the root mutation type, but a type named Mutation is also defined.

Counter Example № 66schema {
  mutation: RootMutation
}

type RootMutation {
  createProduct(name: String): Product
}

type Mutation {
  deprecatedField: String
}

Error Code

ROOT_QUERY_USED

Severity

ERROR

Formal Specification

• Let rootQuery be the root query type defined in the schema, if it exists.
• Let namedQueryType be the type with the name Query in schema, if it exists.
• If rootQuery is defined:
  • rootQuery must be named Query.
• Otherwise, namedQueryType must not be defined.

Explanatory Text

This rule enforces that the root query type in any source schema must be named Query. Defining a root query type with a name other than Query or using a differently named type alongside a type explicitly named Query creates inconsistencies in schema design and violates the composite schema specification.

Examples

Valid example:

Example № 67schema {
  query: Query
}

type Query {
  product(id: ID!): Product
}

type Product {
  id: ID!
  name: String
}

The following counter-example violates the rule because RootQuery is used as the root query type, but a type named Query is also defined.

Counter Example № 68schema {
  query: RootQuery
}

type RootQuery {
  product(id: ID!): Product
}

type Query {
  deprecatedField: String
}

Error Code

ROOT_SUBSCRIPTION_USED

Severity

ERROR

Formal Specification

• Let rootSubscription be the root mutation type defined in the schema, if it exists.
• Let namedSubscriptionType be the type with the name Subscription in schema, if it exists.
• If rootSubscription is defined:
  • rootSubscription must be named Subscription.
• Otherwise, namedSubscriptionType must not be defined.

Explanatory Text

This rule enforces that, for any source schema, if a root subscription type is defined, it must be named Subscription. Defining a root subscription type with a name other than Subscription or using a differently named type alongside a type explicitly named Subscription creates inconsistencies in schema design and violates the composite schema specification.

Examples

Valid example:

Example № 69schema {
  subscription: Subscription
}

type Subscription {
  productCreated: Product
}

type Product {
  id: ID!
  name: String
}

The following counter-example violates the rule because RootSubscription is used as the root subscription type, but a type named Subscription is also defined.

Counter Example № 70schema {
  subscription: RootSubscription
}

type RootSubscription {
  productCreated: Product
}

type Subscription {
  deprecatedField: String
}

Error Code

INTERNAL_OVERRIDE_COLLISION

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let types be the object types in schema.
• For each type in types:
  • If type is annotated with @internal:
    • No field on type may be annotated with @override.
  • For each field on type:
    • If field is annotated with @internal:
      • field must not be annotated with @override.

Explanatory Text

An @internal declaration does not participate in composition, while an @override declaration transfers a composed field from another source schema. The directives are therefore mutually exclusive.

Error Code

EXTERNAL_UNUSED

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let types be the set of all composite types (object, interface) in schema.
• For each type in types:
  • Let fields be the set of fields for type.
  • For each field in fields:
    • If field is marked with @external:
      • Let keyReferences be the set of @key directives on types in schema whose fields selection selects field, including through nested selections.
      • Let providesReferences be the set of @provides directives on fields in schema whose fields selection selects field, including through nested selections.
      • The union of keyReferences and providesReferences must not be empty.

Explanatory Text

A field marked with @external is not resolved by the declaring source schema; it is declared so that the source schema can reference it for composition purposes. There are exactly two such purposes: entity identification, where the field is selected by a @key directive, and field provision, where the field is selected by a @provides directive. An @external field that is referenced by neither @key nor @provides serves no purpose and is likely a leftover from an incomplete refactoring; this rule reports it as an error.

Examples

In this example, the name field is marked with @external and is referenced by the @provides directive, satisfying the rule:

Example № 71# Source Schema A
type Product {
  id: ID
  name: String @external
}

type Query {
  productByName(name: String): Product @provides(fields: "name")
}

In this example, the sku and upc fields are marked with @external and are each referenced by a @key directive on their declaring type, satisfying the rule:

Example № 72# Source schema A
type Product @key(fields: "sku") @key(fields: "upc") {
  sku: String! @external
  upc: String! @external
  name: String
}

type Query {
  productBySku(sku: String!): Product @lookup
  productByUpc(upc: String!): Product @lookup
}

In this example, the name field is marked with @external but is referenced by neither a @key directive nor a @provides directive, violating the rule:

Counter Example № 73# Source Schema A
type Product {
  id: ID
  name: String @external
}

Error Code

EXTERNAL_OVERRIDE_COLLISION

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let types be the set of all INTERFACE and OBJECT types in schema.
• For each type in types:
  • Let fields be the set of fields on type.
  • For each field in fields:
    • If field is annotated with @external:
      • field must not be annotated with @override

Explanatory Text

The @external directive indicates that a field is defined in a different source schema, and the current schema merely references it. Therefore, a field marked with @external must not simultaneously carry directives that assume local ownership or resolution responsibility, such as @override, which transfers ownership of the field’s definition from one schema to another, and is incompatible with an already-external field definition.

Examples

In this scenario, User.fullName is defined in Schema A but overridden in Schema B. Since @override is not combined with @external on the same field, no collision occurs.

Example № 74# Source Schema A
type User {
  id: ID!
  fullName: String
}

# Source Schema B
type User {
  id: ID!
  fullName: String @override(from: "SchemaA")
}

Here, amount is marked with both @override and @external. This violates the rule because the field is simultaneously labeled as “override from another schema” and “external” in the local schema, producing an EXTERNAL_OVERRIDE_COLLISION error.

Counter Example № 75# Source Schema A
type Payment {
  id: ID!
  amount: Int
}

# Source Schema B
type Payment {
  id: ID!
  amount: Int @override(from: "SchemaA") @external
}

Error Code

EXTERNAL_PROVIDES_COLLISION

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let types be the set of all INTERFACE and OBJECT types in schema.
• For each type in types:
  • Let fields be the set of fields on type.
  • For each field in fields:
    • If field is annotated with @external:
      • field must not be annotated with @provides

Explanatory Text

The @external directive indicates that a field is defined in a different source schema, and the current schema merely references it. Therefore, a field marked with @external must not simultaneously carry directives that assume local ownership or resolution responsibility, such as @provides, which declares that the field can supply additional nested fields from the local schema, conflicting with the notion of an external field whose definition resides elsewhere.

Examples

In this example, description is only annotated with @provides in Schema B, without any other directive. This usage is valid.

Example № 76# Source Schema A
type Invoice {
  id: ID!
  description: String
}

# Source Schema B
type Invoice {
  id: ID!
  description: String @provides(fields: "length")
}

In this counter-example, description is annotated with @external and also with @provides. Because @external and @provides cannot co-exist on the same field, an EXTERNAL_PROVIDES_COLLISION error is produced.

Counter Example № 77# Source Schema A
type Invoice {
  id: ID!
  description: String
}

# Source Schema B
type Invoice {
  id: ID!
  description: String @external @provides(fields: "length")
}

Error Code

EXTERNAL_REQUIRE_COLLISION

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let types be the set of all INTERFACE and OBJECT types in schema.
• For each type in types:
  • Let fields be the set of fields on type.
  • For each field in fields:
    • If field is annotated with @external:
      • For each argument in field:
        • argument must not be annotated with @require

Explanatory Text

The @external directive indicates that a field is defined in a different source schema, and the current schema merely references it. Therefore, a field marked with @external must not simultaneously carry directives that assume local ownership or resolution responsibility, such as @require, which specifies dependencies on other fields to resolve this field. Since @external fields are not locally resolved, there is no need for @require.

Examples

In this example, title has arguments annotated with @require in Schema B, but is not marked as @external. This usage is valid.

Example № 78# Source Schema A
type Book {
  id: ID!
  title: String
  subtitle: String
}

# Source Schema B
type Book {
  id: ID!
  title(subtitle: String @require(field: "subtitle")): String
}

The following example is invalid, since title is marked with @external and has an argument that is annotated with @require. This conflict leads to an EXTERNAL_REQUIRE_COLLISION error.

Counter Example № 79# Source Schema A
type Book {
  id: ID!
  title: String
  subtitle: String
}

# Source Schema B
type Book {
  id: ID!
  title(subtitle: String @require(field: "subtitle")): String @external
}

Error Code

EXTERNAL_ON_INTERFACE

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let types be the set of all composite types in schema.
• For each type in types:
  • If type is an interface type:
    • Let fields be the set of fields on type.
    • For each field in fields:
      • field must not be annotated with @external

Explanatory Text

The @external directive indicates that a field is defined and resolved elsewhere, not in the current schema. In the case of an interface type, fields are abstract - they do not have direct resolutions at the interface level. Instead, each implementing object type provides the concrete field implementations. Marking an interface field with @external is therefore nonsensical, as there is no actual field resolution in the interface itself to “borrow” from another schema. Such usage raises an EXTERNAL_ON_INTERFACE error.

Examples

Here, the interface Node merely describes the field id. Object types User and Product implement and resolve id. No @external usage occurs on the interface itself, so no error is triggered.

Example № 80interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String
}

type Product implements Node {
  id: ID!
  price: Int
}

Since id is declared on an interface and marked with @external, the composition fails with EXTERNAL_ON_INTERFACE. An interface does not own the concrete field resolution, so it is invalid to mark any of its fields as external.

Counter Example № 81interface Node {
  id: ID! @external
}

Error Code

IS_INVALID_SYNTAX

Severity

ERROR

Formal Specification

• Let types be the set of all INTERFACE and OBJECT types in the source schema.
• For each type in types:
  • Let fields be the set of all lookup fields on type.
  • Let arguments be the set of all arguments on fields.
  • For each argument in arguments:
    • If argument is annotated with @is:
      • Let fieldArg be the string value of the field argument of the @is directive on argument.
      • fieldArg must be be parsable as a valid FieldSelectionMap.

Explanatory Text

The @is directive’s field argument must be syntactically valid GraphQL. If the FieldSelectionMap string is malformed (e.g., missing closing braces, unbalanced quotes, invalid tokens), then the schema cannot be composed correctly. In such cases, the error IS_INVALID_SYNTAX is raised.

Examples

In the following example, the @is directive’s field argument is a valid FieldSelectionMap and satisfies the rule.

Example № 82type Query {
  product(id: ID! @is(field: "id")): Product @lookup
}

type Product {
  id: ID!
  name: String
}

In the following counter-example, the @is directive’s field argument has invalid syntax because it is missing a closing brace.

Counter Example № 83type Query {
  product(id: ID! @is(field: "{ id ")): Product @lookup
}

type Product {
  id: ID!
  name: String
}

Error Code

IS_INVALID_FIELD_TYPE

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let compositeTypes be the set of all composite types in schema.
• For each composite in compositeTypes:
  • Let fields be the set of fields on composite.
  • Let arguments be the set of all arguments on fields.
  • For each argument in arguments:
    • If argument is not annotated with @is:
      • Continue
    • Let fieldArg be the value of the field argument of the @is directive on argument.
    • If fieldArg is not a string:
      • Produce an IS_INVALID_FIELD_TYPE error.

Explanatory Text

When using the @is directive, the field argument must always be a string that describes how the arguments can be mapped from the entity type that the lookup field resolves. If the field argument is provided as a type other than a string (such as an integer, boolean, or enum), the directive usage is invalid and will cause schema composition to fail.

Examples

In the following example, the @is directive’s field argument is a valid string and satisfies the rule.

Example № 84type Query {
  personById(id: ID! @is(field: "id")): Person @lookup
}

type Person {
  id: ID!
  name: String
}

Since field is set to 123 (an integer) instead of a string, this violates the rule and triggers an IS_INVALID_FIELD_TYPE error.

Counter Example № 85type Query {
  personById(id: ID! @is(field: 123)): Person @lookup
}

type Person {
  id: ID!
  name: String
}

Error Code

IS_INVALID_USAGE

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let compositeTypes be the set of all composite types in schema.
• For each compositeType in compositeTypes:
  • Let fields be the set of fields on compositeType.
  • For each field in fields:
    • Let arguments be the set of all arguments on field.
    • For each argument in arguments:
      • If argument is not annotated with @is:
        • Continue
      • field must be annotated with @lookup

Explanatory Text

When using the @is directive, the field declaring the argument must be a lookup field (i.e. have the @lookup directive applied).

Examples

In the following example, the @is directive is applied to an argument declared on a field with the @lookup directive, satisfying the rule.

Example № 86type Query {
  personById(id: ID! @is(field: "id")): Person @lookup
}

type Person {
  id: ID!
  name: String
}

In the following counter-example, the @is directive is applied to an argument declared on a field without the @lookup directive, violating the rule.

Counter Example № 87type Query {
  personById(id: ID! @is(field: "id")): Person
}

type Person {
  id: ID!
  name: String
}

Error Code

IS_FIELDS_HAS_ARGUMENTS

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let compositeTypes be the set of all composite types in schema.
• For each compositeType in compositeTypes:
  • Let fields be the set of fields on compositeType.
  • For each field in fields:
    • Let arguments be the set of arguments on field.
    • For each argument in arguments:
      • If argument is not annotated with @is:
        • Continue
      • Let selectionMap be the parsed selection map of the field argument of the @is directive on argument.
      • Each selection in selectionMap, including nested selections and path segments, must not supply arguments.

Explanatory Text

The arguments of a lookup field represent the stable key with which the distributed GraphQL executor recalls an entity, and the @is directive maps each argument to a field of the entity. Such a mapping must consist of plain field paths; supplying arguments within an @is selection map is not allowed.

A referenced field may still declare arguments, as long as each argument is nullable, has a default value, or is annotated with @require and therefore supplied by the executor. Such a field can be resolved without any arguments being supplied. A field that requires an argument cannot be referenced by an @is selection map, since the map cannot supply one (see Is Invalid Fields and the argument validation rules in Appendix A).

The same applies to @key (see Key Fields Has Arguments). @provides selections must reference fields that declare no arguments other than @require-annotated ones (see Provides Fields Has Arguments). Only @require selection maps may supply constant arguments, as they derive input values rather than keys.

Examples

In this example, the id argument of the lookup field is mapped to the plain id field of Product, satisfying the rule.

Example № 88type Query {
  productById(id: ID! @is(field: "id")): Product @lookup
}

type Product {
  id: ID!
  name: String
}

In this example, the referenced field id declares the nullable scope argument. Since scope can be omitted, id can be resolved without supplying an argument and may be referenced by the @is selection map.

Example № 89type Query {
  productById(id: ID! @is(field: "id")): Product @lookup
}

type Product {
  id(scope: IdScope): ID!
  name: String
}

In this counter-example, the @is selection map supplies an argument on id, violating the rule.

Counter Example № 90type Query {
  productByLocalId(id: ID! @is(field: "id(scope: LOCAL)")): Product @lookup
}

type Product {
  id(scope: IdScope): ID!
  name: String
}

Error Code

KEY_FIELDS_SELECT_INVALID_TYPE

Severity

ERROR

Formal Specification

• Let types be the set of all object or interface types that are annotated with the @key directive in the schema.
• For each type in types:
  • Let keyDirectives be the set of all @key directives on type.
  • For each keyDirective in keyDirectives
    • Let keyFields be the set of all fields (including nested) referenced by the fields argument of keyDirective.
    • For each field in keyFields:
      • Let fieldType be the type of field.
      • fieldType must not be a List, Interface, or Union type.

Explanatory Text

The @key directive is used to define the set of fields that uniquely identify an entity. These fields must reference scalars or object types to ensure a valid and consistent representation of the entity across schemas. Fields of types List, Interface, or Union cannot be part of a @key because they do not have a well-defined unique value.

Examples

In this valid example, the Product type has a valid @key directive referencing the scalar field sku.

Example № 91type Product @key(fields: "sku") {
  sku: String!
  name: String
}

In the following counter-example, the Product type has an invalid @key directive referencing a field (featuredItem) whose type is an interface, violating the rule.

Counter Example № 92type Product @key(fields: "featuredItem { id }") {
  featuredItem: Node!
  sku: String!
}

interface Node {
  id: ID!
}

In this counter example, the @key directive references a field (tags) of type List, which is also not allowed.

Counter Example № 93type Product @key(fields: "tags") {
  tags: [String!]!
  sku: String!
}

In this counter example, the @key directive references a field (relatedItems) of type Union, which violates the rule.

Counter Example № 94type Product @key(fields: "relatedItems") {
  relatedItems: Related!
  sku: String!
}

union Related = Product | Service

type Service {
  id: ID!
}

Error Code

KEY_DIRECTIVE_IN_FIELDS_ARGUMENT

Severity

ERROR

Formal Specification

• Let types be the set of all object and interface types in the schema.
• For each type in types:
  • Let keyDirectives be the set of all @key directives on type.
  • For each keyDirective in keyDirectives:
    • Let fields be the string value of the fields argument of keyDirective.
    • fields must not contain a directive application.

Explanatory Text

The @key directive specifies the set of fields used to uniquely identify an entity. The fields argument must consist of a valid GraphQL selection set that does not include any directive applications. Directives in the fields argument are not supported.

Examples

In this example, the fields argument of the @key directive does not include any directive applications, satisfying the rule.

Example № 95type User @key(fields: "id name") {
  id: ID!
  name: String
}

In this counter-example, the fields argument of the @key directive includes a directive application @lowercase, which is not allowed.

Counter Example № 96directive @lowercase on FIELD_DEFINITION

type User @key(fields: "id name @lowercase") {
  id: ID!
  name: String
}

In this example, the fields argument includes a directive application @lowercase nested inside the selection set, which is also invalid.

Counter Example № 97directive @lowercase on FIELD_DEFINITION

type User @key(fields: "id name { firstName @lowercase }") {
  id: ID!
  name: FullName
}

type FullName {
  firstName: String
  lastName: String
}

Error Code

KEY_FIELDS_HAS_ARGUMENTS

Severity

ERROR

Formal Specification

• Let types be the set of all object and interface types in the schema that are annotated with the @key directive.
• For each type in types:
  • Let keyDirectives be the set of all @key directives on type.
  • For each keyDirective in keyDirectives:
    • Let selections be the field selections of the fields argument of keyDirective.
    • For each selection in selections:
      • KeyFieldsHasArguments(selection, type) must be false.

Explanatory Text

The @key directive designates the fields that form a stable key of an entity. Selections within the fields argument must not supply arguments: a stable key must consist of plain field values that identify an entity deterministically, and the distributed GraphQL executor resolves key fields without supplying any arguments.

A referenced field may still declare arguments, as long as each argument is nullable, has a default value, or is annotated with @require and therefore supplied by the executor. Such a field can be resolved without any arguments being supplied. A field that requires an argument cannot be part of a stable key because it cannot be resolved without one.

The same applies to @is (see Is Fields Has Arguments). @provides selections must reference fields that declare no arguments other than @require-annotated ones (see Provides Fields Has Arguments). Only @require selection maps may supply constant arguments, as they derive input values rather than keys.

Examples

In this example, the User type has a valid @key directive that references the argument-free fields id and name.

Example № 98type User @key(fields: "id name") {
  id: ID!
  name: String
  tags: [String]
}

In this example, the @key directive references the field tags, which declares the optional limit argument. Since limit can be omitted, tags can be resolved without supplying an argument and may be part of the key.

Example № 99type User @key(fields: "id tags") {
  id: ID!
  tags(limit: Int = 10): [String]
}

In this counter-example, the key selection supplies arguments on id. Selections within the fields argument must not supply arguments.

Counter Example № 100type User @key(fields: "id(scope: LOCAL)") {
  id: ID!
}

In this counter-example, the @key directive references the field tags, which requires the limit argument. Since limit can neither be omitted nor supplied by the key selection, tags cannot be part of a key.

Counter Example № 101type User @key(fields: "id tags") {
  id: ID!
  tags(limit: Int!): [String]
}

Error Code

KEY_INVALID_SYNTAX

Severity

ERROR

Formal Specification

• Let types be the set of all object or interface types in the schema.
• For each type in types:
  • Let keyDirectives be the set of all @key directives on type.
  • For each keyDirective in keyDirectives:
    • Let fieldsArg be the string value of the fields argument of keyDirective.
    • Attempt to parse fieldsArg as a valid GraphQL selection set.
    • Parsing must not fail (e.g., missing braces, invalid tokens, unbalanced curly braces, or other syntax errors).

Explanatory Text

Each @key directive must specify the fields that uniquely identify an entity using a valid GraphQL selection set in its fields argument. If the fields argument string is syntactically incorrect-missing closing braces, containing invalid tokens, or otherwise malformed – it cannot be composed into a valid schema and triggers the KEY_INVALID_SYNTAX error.

Examples

In this valid scenario, the fields argument is a correctly formed selection set: "sku featuredItem { id }" is properly balanced and contains no syntax errors.

Example № 102type Product @key(fields: "sku featuredItem { id }") {
  sku: String!
  featuredItem: Node!
}

interface Node {
  id: ID!
}

Here, the selection set "featuredItem { id" is missing the closing brace }. It is thus invalid syntax, causing a KEY_INVALID_SYNTAX error.

Counter Example № 103type Product @key(fields: "featuredItem { id") {
  featuredItem: Node!
  sku: String!
}

interface Node {
  id: ID!
}

Error Code

KEY_INVALID_FIELDS

Severity

ERROR

Formal Specification

• Let types be the set of all object and interface types in the schema.
• For each type in types:
  • Let keyDirectives be the set of all @key directives on type.
  • For each keyDirective in keyDirectives:
    • Let fieldsArg be the string value of the fields argument of keyDirective.
    • Let selections be the set of fields in the selection set of fieldsArg.
    • For each selection in selections:
      • IsValidKeyField(selection, type) must be true.

Explanatory Text

Even if the selection set for @key(fields: "…") is syntactically valid, field references within that selection set must also refer to actual fields on the annotated type. This includes nested selections, which must appear on the corresponding return type. If any referenced field is missing or incorrectly named, composition fails with a KEY_INVALID_FIELDS error because the stable key cannot be resolved correctly.

Examples

In this valid example, the fields argument of the @key directive is properly defined with valid syntax and references existing fields.

Example № 104type Product @key(fields: "sku featuredItem { id }") {
  sku: String!
  featuredItem: Node!
}

interface Node {
  id: ID!
}

In this counter-example, the fields argument of the @key directive references a field id, which does not exist on the Product type.

Counter Example № 105type Product @key(fields: "id") {
  sku: String!
}

Error Code

KEY_INVALID_FIELDS_TYPE

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let types be the set of all composite types in schema.
• For each type in types:
  • If type is annotated with @key:
    • Let fieldsArg be the value of the fields argument in the @key directive.
    • fieldsArg must be a string.

Explanatory Text

The @key directive designates the fields used to identify a particular object uniquely. The fields argument accepts a string that represents a selection set (for example, "id", or "id otherField"). If the fields argument is provided as any non-string type (e.g., Boolean, Int, Array), the schema fails to compose correctly because it cannot parse a valid field selection.

Examples

In this example, the @key directive’s fields argument is the string "id uuid", identifying two fields that form a composite stable key. This usage is valid.

Example № 106type User @key(fields: "id uuid") {
  id: ID!
  uuid: ID!
  name: String
}

type Query {
  users: [User]
}

Here, the fields argument is provided as a boolean (true) instead of a string. This violates the directive requirement and triggers a KEY_INVALID_FIELDS_TYPE error.

Counter Example № 107type User @key(fields: true) {
  id: ID
}

Error Code

INTERFACE_OBJECT_KEY_MISSING

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let types be the set of all object types in schema annotated with @interfaceObject.
• For each type in types:
  • Let keyDirectives be the set of all @key directives on type.
  • keyDirectives must not be empty.

Explanatory Text

An object type annotated with @interfaceObject stands in for an interface defined in one or more other source schemas. The composite schema resolves this stand-in as an independently queryable entity. The distributed executor must be able to fetch it by its key, or extend it with the fields it contributes. The type must therefore declare at least one @key, exactly as any other entity type would. A stand-in with no key cannot be targeted by the executor and cannot contribute fields to the interface it stands in for.

This rule only requires that a key exists. The fields selected by the key are validated like those of any other @key (see Validate Key Directives). Whether the key matches one of the keys declared on the interface is validated across source schemas by Interface Object Key Mismatch.

Examples

In this example, the Media stand-in declares a @key, so source schema B’s contribution can be joined to the Media interface by id.

Example № 108# Source Schema B
type Media @interfaceObject @key(fields: "id") {
  id: ID!
  reviews: [Review!]!
}

type Review {
  id: ID!
  rating: Int!
}

In the following counter-example, the Media stand-in declares no @key, so the entity it stands in for cannot be resolved. This results in an INTERFACE_OBJECT_KEY_MISSING error.

Counter Example № 109# Source Schema B
type Media @interfaceObject {
  id: ID!
  reviews: [Review!]!
}

type Review {
  id: ID!
  rating: Int!
}

Error Code

LOOKUP_MUST_HAVE_ARGUMENTS

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let fields be the set of all field definitions annotated with @lookup in schema.
• For each field in fields:
  • The number of arguments on field must be greater than zero.

Explanatory Text

Fields annotated with the @lookup directive identify a single entity by the arguments supplied to them. A lookup field that declares no arguments has no stable key with which to resolve an entity and cannot participate in composition. This rule reports such fields as invalid.

Examples

For example, the following usage is valid because productById declares an argument that can be used to resolve a Product entity.

Example № 110type Query {
  productById(id: ID!): Product @lookup
}

type Product {
  id: ID!
  name: String
}

This counter-example demonstrates an invalid usage. The product field is annotated with @lookup but declares no arguments, so it cannot identify which entity to resolve.

Counter Example № 111type Query {
  product: Product @lookup
}

type Product {
  id: ID!
  name: String
}

Error Code

LOOKUP_RETURNS_NON_NULLABLE_TYPE

Severity

WARNING

Formal Specification

• Let schema be the source schema to validate.
• Let fields be the set of all field definitions annotated with @lookup in schema.
• For each field in fields:
  • Let type be the return type of field.
  • type must be a nullable type.

Explanatory Text

Fields annotated with the @lookup directive are intended to retrieve a single entity based on provided arguments. To properly handle cases where the requested entity does not exist, such fields should have a nullable return type. This allows the field to return null when an entity matching the provided criteria is not found, following the standard GraphQL practices for representing missing data.

In a distributed system, it is likely that some entities will not be found on other schemas, even when those schemas contribute fields to the type. Ensuring that @lookup fields have nullable return types also avoids GraphQL errors on schemas and prevents result erasure through non-null propagation. By allowing null to be returned when an entity is not found, the system can gracefully handle missing data without causing exceptions or unexpected behavior.

Ensuring that @lookup fields have nullable return types allows gateways to distinguish between cases where an entity is not found (receiving null) and other error conditions that may have to be propagated to the client.

For example, the following usage is recommended:

Example № 112type Query {
  userById(id: ID!): User @lookup
}

type User {
  id: ID!
  name: String
}

In this example, userById returns a nullable User type, aligning with the recommendation.

Examples

This counter-example demonstrates an invalid usage:

Counter Example № 113type Query {
  userById(id: ID!): User! @lookup
}

type User {
  id: ID!
  name: String
}

Here, userById returns a non-nullable User!, which does not align with the recommendation that a @lookup field should have a nullable return type.

Error Code

LOOKUP_RETURNS_LIST

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let fields be the set of all field definitions annotated with @lookup in schema.
• For each field in fields:
  • Let type be the return type of field.
  • IsListType(type) must be false.

Explanatory Text

Fields annotated with the @lookup directive are intended to retrieve a single entity based on provided arguments. To avoid ambiguity in entity resolution, such fields must return a single object and not a list. This validation rule enforces that any field annotated with @lookup must have a return type that is NOT a list.

Examples

For example, the following usage is valid:

Example № 114type Query {
  userById(id: ID!): User @lookup
}

type User {
  id: ID!
  name: String
}

In this example, userById returns a User object, satisfying the requirement.

This counter-example demonstrates an invalid usage:

Counter Example № 115type Query {
  usersByIds(ids: [ID!]!): [User!] @lookup
}

type User {
  id: ID!
  name: String
}

Here, usersByIds returns a list of User objects, which violates the requirement that a @lookup field must return a single object.

Error Code

LOOKUP_KEY_MISSING_FOR_TYPE

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let lookupFields be the set of all fields in schema annotated with @lookup.
• For each lookupField in lookupFields:
  • Let returnType be the unwrapped return type of lookupField.
  • Let possibleTypes be GetPossibleTypes(returnType).
  • For each argument in the arguments of lookupField:
    • For each possibleType in possibleTypes:
      • IsArgumentMappable(argument, possibleType) must be true.

Explanatory Text

A lookup field must be able to resolve every possible runtime type of its return type. The arguments of a lookup field represent the stable key with which an entity is resolved, and each argument must independently be mappable to a field for every possible object type of the return type.

Without an @is directive, an argument is mapped by its name: every possible object type must define a field with the argument’s name, either directly or through an interface. With an @is directive, the selection map defines the mapping, and its alternatives may map different runtime types to different fields. The alternatives must still cover every possible type: a runtime type that is not covered by any alternative cannot be resolved by the lookup field. A source schema that can only resolve a subset of the possible types must declare a narrower return type instead.

Examples

In this example, the selection map covers all possible types of Media, resolving each by a different key field.

Example № 116type Query {
  mediaByKey(
    key: MediaKeyInput!
      @is(
        field: "{ isbn: <Book>.isbn } | { upc: <Movie>.upc } | { feedUrl: <Podcast>.feedUrl }"
      )
  ): Media @lookup
}

input MediaKeyInput @oneOf {
  isbn: String
  upc: String
  feedUrl: String
}

interface Media {
  id: ID!
}

type Book implements Media {
  id: ID!
  isbn: String!
}

type Movie implements Media {
  id: ID!
  upc: String!
}

type Podcast implements Media {
  id: ID!
  feedUrl: String!
}

In this counter-example, the selection map covers only Book and Movie. Podcast is a possible type of Media but is not covered by any alternative, violating the rule.

Counter Example № 117type Query {
  mediaByKey(
    key: MediaKeyInput!
      @is(field: "{ isbn: <Book>.isbn } | { upc: <Movie>.upc }")
  ): Media @lookup
}

input MediaKeyInput @oneOf {
  isbn: String
  upc: String
}

interface Media {
  id: ID!
}

type Book implements Media {
  id: ID!
  isbn: String!
}

type Movie implements Media {
  id: ID!
  upc: String!
}

type Podcast implements Media {
  id: ID!
  feedUrl: String!
}

In this counter-example, the arguments are mapped by name, but the possible type Clothing does not define a field named categoryId, violating the rule.

Counter Example № 118type Query {
  product(id: ID!, categoryId: Int): Product @lookup
}

union Product = Electronics | Clothing

type Electronics {
  id: ID!
  categoryId: Int
  name: String
}

type Clothing {
  id: ID!
  name: String
}

Error Code

OVERRIDE_FROM_SELF

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let types be the set of all composite types in schema.
• For each type in types:
  • Let fields be the set of fields on type.
  • For each field in fields:
    • If field is annotated with @override:
      • Let from be the value of the from argument of the @override directive on field.
      • from must not be the same as the name of schema:

Explanatory Text

When using @override, the from argument indicates the name of the source schema that originally owns the field. Overriding from the same schema creates a contradiction, as it implies both local and transferred ownership of the field within one schema. If the from value matches the local schema name, it triggers an OVERRIDE_FROM_SELF error.

Examples

In the following example, Schema B overrides the field amount from Schema A. The two schema names are different, so no error is raised.

Example № 119# Source Schema A
type Bill {
  id: ID!
  amount: Int
}

# Source Schema B
type Bill {
  id: ID!
  amount: Int @override(from: "SchemaA")
}

In the following counter-example, the local schema is also "SchemaA", and the from argument is "SchemaA". Overriding a field from the same schema is not allowed, causing an OVERRIDE_FROM_SELF error.

Counter Example № 120# Source Schema A (named "SchemaA")
type Bill {
  id: ID!
  amount: Int @override(from: "SchemaA")
}

Error Code

OVERRIDE_ON_INTERFACE

Severity

ERROR

Formal Specification

• Let schema be the source schema to validate.
• Let types be the set of all interface types in schema.
• For each type in types:
  • Let fields be the set of fields on type.
  • For each field in fields:
    • field must not be annotated with @override

Explanatory Text

The @override directive designates that ownership of a field is transferred from one source schema to another. In the context of interface types, fields are abstract—objects that implement the interface are responsible for providing the actual fields. Consequently, it is invalid to attach @override directly to an interface field. Doing so leads to an OVERRIDE_ON_INTERFACE error because there is no concrete field implementation on the interface itself that can be overridden.

Examples

In this valid example, @override is used on a field of an object type, ensuring that the field definition is concrete and can be reassigned to another schema.

Since @override is not used on any interface fields, no error is produced.

Example № 121# Source Schema A
type Order {
  id: ID!
  amount: Int
}

# Source Schema B
type Order {
  id: ID!
  amount: Int @override(from: "SchemaA")
}

In the following counter-example, Bill.amount is declared on an interface type and annotated with @override. This violates the rule because the interface field itself is not eligible for ownership transfer. The composition fails with an OVERRIDE_ON_INTERFACE error.

Counter Example № 122# Source Schema A
interface Bill {
  id: ID!
  amount: Int @override(from: "SchemaB")
}

Error Code

PROVIDES_DIRECTIVE_IN_FIELDS_ARGUMENT

Severity

ERROR

Formal Specification

• Let fieldsWithProvides be the set of all fields annotated with the @provides directive in the schema.
• For each field in fieldsWithProvides:
  • Let fields be the selected fields of the fields argument of the @provides directive on field.
  • For each selection in fields:
    • HasProvidesDirective(selection) must be false

Explanatory Text

The @provides directive is used to specify the set of fields on an object type that a resolver provides for the parent type. The fields argument must consist of a valid GraphQL selection set without any directive applications, as directives within the fields argument are not supported.

Examples

In this example, the fields argument of the @provides directive does not have any directive applications, satisfying the rule.

Example № 123type User @key(fields: "id name") {
  id: ID!
  name: String
  profile: Profile @provides(fields: "name")
}

type Profile {
  id: ID!
  name: String
}

In this counter-example, the fields argument of the @provides directive has a directive application @lowercase, which is not allowed.

Counter Example № 124directive @lowercase on FIELD_DEFINITION

type User @key(fields: "id name") {
  id: ID!
  name: String
  profile: Profile @provides(fields: "name @lowercase")
}

type Profile {
  id: ID!
  name: String
}

Error Code

PROVIDES_FIELDS_HAS_ARGUMENTS

Severity

ERROR

Formal Specification

• Let fieldsWithProvides be the set of all fields annotated with the @provides directive in the schema.
• For each field in fieldsWithProvides:
  • Let selections be the field selections of the fields argument of the @provides directive on field.
  • Let type be the return type of field.
  • For each selection in selections:
    • ProvidesHasArguments(selection, type) must be false.

Explanatory Text

The @provides directive specifies fields that a resolver provides for the parent type. The fields argument must reference fields that do not declare arguments, as fields with arguments introduce variability that is incompatible with the consistent behavior expected of @provides. Arguments annotated with @require are exempt, since they are supplied by the executor rather than chosen by the consumer. A selection within the fields argument must never supply arguments.

Examples

Example № 125type User @key(fields: "id") {
  id: ID!
  tags: [String]
}

type Article @key(fields: "id") {
  id: ID!
  author: User! @provides(fields: "tags")
}

In this example, the tags field declares only an argument annotated with @require. Since its value is supplied by the executor, tags may still be referenced by the @provides selection.

Example № 126type User @key(fields: "id") {
  id: ID!
  tags(limit: Int @require(field: "tagLimit")): [String]
  tagLimit: Int
}

type Article @key(fields: "id") {
  id: ID!
  author: User! @provides(fields: "tags")
}

This violates the rule because the tags field referenced in the fields argument of the @provides directive is defined with arguments (limit: UserType = ADMIN).

Counter Example № 127type User @key(fields: "id") {
  id: ID!
  tags(limit: UserType = ADMIN): [String]
}

enum UserType {
  REGULAR
  ADMIN
}

type Article @key(fields: "id") {
  id: ID!
  author: User! @provides(fields: "tags")
}

In this counter-example, the @provides selection supplies arguments on tags, even though tags does not declare any. Selections within the fields argument must not supply arguments.

Counter Example № 128type User @key(fields: "id") {
  id: ID!
  tags: [String]
}

type Article @key(fields: "id") {
  id: ID!
  author: User! @provides(fields: "tags(limit: 10)")
}

Error Code

PROVIDES_FIELDS_MISSING_EXTERNAL

Severity

ERROR

Formal Specification