Composition hints

When you successfully compose the schemas provided by your subgraphs into a supergraph schema, the composition process can flag potential improvements or hints. Hints are violations of the GraphOS schema linter's composition rules. You can review them on the Checks page in GraphOS Studio or via the Rover CLI.

Composition hints only appear in GraphOS Studio and via the rover subgraph check command for graphs on federation version 2.4 or later. You can update a graph's version from its Settings page in GraphOS Studio.

The rover subgraph check command outputs rule violations with the severity levels you've configured for your graph variant. The rover supergraph compose command outputs rule violations for all local subgraph schemas.

See below for a list of composition rules categorized by rule type. The heading for each rule is the code that GraphOS returns for the rule violation. Refer to the rules reference page for a comprehensive list of linter rules.

Inconsistent elements

`INCONSISTENT_ARGUMENT_PRESENCE`

Indicates that an optional argument (of a field or directive definition) isn't present in all subgraphs and therefore won't be part of the supergraph.

❌

Subgraph A

1
type Product {
2
  id: ID!
3
  name: String
4
  price(currency: Currency): Float 
5
}

Subgraph B

1
type Product {
2
  id: ID!
3
  name: String
4
  price(currency: Currency, taxIncluded: Boolean): Float 
5
}

✅

Subgraph A

1
type Product {
2
  id: ID!
3
  name: String
4
  price(currency: Currency, taxIncluded: Boolean): Float 
5
}

Subgraph B

1
type Product {
2
  id: ID!
3
  name: String
4
  price(currency: Currency, taxIncluded: Boolean): Float 
5
}

`INCONSISTENT_BUT_COMPATIBLE_ARGUMENT_TYPE`

Indicates that an argument type (of a field, input field, or directive definition) doesn't have the exact same type in all subgraphs, but that the types are compatible.

Two types are compatible if one is:

a non-nullable version
a list version
a subtype
or a combination of any of these

of the other.

❌

Subgraph A

type Product {
  id: ID!
  name: String
  price(currency: Currency!): Float 
}

enum Currency {
  USD
  EUR
  GBP
  JPY
  AUD
  CAD
}

Subgraph B

type Product {
  id: ID!
  name: String
  price(currency: Currency): Float 
}

enum Currency {
  USD
  EUR
  GBP
  JPY
  AUD
  CAD
}

✅

Subgraph A

type Product {
  id: ID!
  name: String
  price(currency: Currency!): Float 
}

enum Currency {
  USD
  EUR
  GBP
  JPY
  AUD
  CAD
}

Subgraph B

type Product {
  id: ID!
  name: String
  price(currency: Currency!): Float 
}

enum Currency {
  USD
  EUR
  GBP
  JPY
  AUD
  CAD
}

`INCONSISTENT_BUT_COMPATIBLE_FIELD_TYPE`

Indicates that a field doesn't have the exact same types in all subgraphs, but that the types are compatible.

Two types are compatible if one is:

a non-nullable version
a list version
a subtype
or a combination of any of these

of the other.

❌

Subgraph A

type Product {
  id: ID!
  name: String
  price: Money 
}

type Money {
  amount: Float!
  currency: Currency!
}

enum Currency {
  USD
  EUR
  GBP
  JPY
  AUD
  CAD
}

Subgraph B

type Product {
  id: ID!
  name: String
  price: Money! 
}

type Money {
  amount: Float!
  currency: Currency!
}

enum Currency {
  USD
  EUR
  GBP
  JPY
  AUD
  CAD
}

✅

Subgraph A

type Product {
  id: ID!
  name: String
  price: Money! 
}

type Money {
  amount: Float!
  currency: Currency!
}

enum Currency {
  USD
  EUR
  GBP
  JPY
  AUD
  CAD
}

Subgraph B

type Product {
  id: ID!
  name: String
  price: Money! 
}

type Money {
  amount: Float!
  currency: Currency!
}

enum Currency {
  USD
  EUR
  GBP
  JPY
  AUD
  CAD
}

`INCONSISTENT_DEFAULT_VALUE_PRESENCE`

Indicates that an argument definition (of a field, input field, or directive definition) has a default value in only some of the subgraphs that define the argument.

❌

Subgraph A

type Product {
  id: ID!
  name: String
  weight(kg: Float = 1.0): Float 
}

Subgraph B

type Product {
  id: ID!
  name: String
  weight(kg: Float): Float 
}

✅

Subgraph A

type Product {
  id: ID!
  name: String
  weight(kg: Float = 1.0): Float 
}

Subgraph B

type Product {
  id: ID!
  name: String
  weight(kg: Float = 1.0): Float 
}

`INCONSISTENT_DESCRIPTION`

Indicates that an element has a description in more than one subgraph, and the descriptions aren't equal.

❌

Subgraph A

"""
A type representing a product.
"""
type Product {
  id: ID!
  name: String
}

Subgraph B

"""
An object representing a product.
"""
type Product {
  id: ID!
  name: String
}

✅

Subgraph A

"""
A type representing a product.
"""
type Product {
  id: ID!
  name: String
}

Subgraph B

"""
A type representing a product.
"""
type Product {
  id: ID!
  name: String
}

`INCONSISTENT_ENTITY`

Indicates that an object is declared as an entity (has a @key) in only some of the subgraphs in which the object is defined.

❌

Subgraph A

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

Subgraph B

type Product { 
  id: ID!
  stock: Int
}

✅

Subgraph A

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

Subgraph B

type Product @key(fields: "id") { 
  id: ID!
  stock: Int
}

`INCONSISTENT_ENUM_VALUE_FOR_INPUT_ENUM`

Indicates that a value of an enum type definition, that is only used as an input type, hasn't been merged into the supergraph because it's defined in only some of the subgraphs that declare the enum.

❌

Subgraph A

enum ProductStatus {
  AVAILABLE
  SOLD_OUT
  BACK_ORDER 
}

input ProductInput {
  name: String!
  status: ProductStatus!
}

Subgraph B

enum ProductStatus {
  AVAILABLE
  SOLD_OUT
}

input ProductInput {
  name: String!
  status: ProductStatus!
}

✅

Subgraph A

enum ProductStatus {
  AVAILABLE
  SOLD_OUT
  BACK_ORDER
}

input ProductInput {
  name: String!
  status: ProductStatus!
}

Subgraph B

enum ProductStatus {
  AVAILABLE
  SOLD_OUT
  BACK_ORDER
}

input ProductInput {
  name: String!
  status: ProductStatus!
}

`INCONSISTENT_ENUM_VALUE_FOR_OUTPUT_ENUM`

Indicates that a value of an enum type definition, that is only used as an output type or is unused, has been merged in the supergraph but is defined in only some of the subgraphs that declare the enum.

❌

Subgraph A

enum OrderStatus {
  CREATED
  PROCESSING 
  COMPLETED
}

type Order {
  name: String!
  status: OrderStatus!
}

Subgraph B

enum OrderStatus {
  CREATED
  COMPLETED
}

type Order {
  name: String!
  status: OrderStatus!
}

✅

Subgraph A

enum OrderStatus {
  CREATED
  PROCESSING
  COMPLETED
}

type Order {
  name: String!
  status: OrderStatus!
}

Subgraph B

enum OrderStatus {
  CREATED
  PROCESSING
  COMPLETED
}

type Order {
  name: String!
  status: OrderStatus!
}

`INCONSISTENT_EXECUTABLE_DIRECTIVE_LOCATIONS`

Indicates that an executable directive definition is declared with inconsistent locations across subgraphs. (The supergraph schema then uses the intersection of all locations in the supergraph.)

❌

Subgraph A

directive @log(
  message: String!
) on QUERY | FIELD

Subgraph B

directive @log(
  message: String!
) on FIELD

✅

Subgraph A

directive @log(
  message: String!
) on QUERY | FIELD

Subgraph B

directive @log(
  message: String!
) on QUERY | FIELD

`INCONSISTENT_EXECUTABLE_DIRECTIVE_PRESENCE`

Indicates that an executable directive definition is declared in only some of the subgraphs.

❌

Subgraph A

directive @modify(
  field: String!
) on FIELD

Subgraph B

# 🦗🦗🦗

✅

Subgraph A

directive @modify(
  field: String!
) on FIELD

Subgraph B

directive @modify(
  field: String!
) on FIELD

`INCONSISTENT_EXECUTABLE_DIRECTIVE_REPEATABLE`

Indicates that an executable directive definition is marked repeatable in only some of the subgraphs and won't be repeatable in the supergraph.

❌

Subgraph A

directive @validateLength(
  max: Int!
) repeatable on FIELD

Subgraph B

directive @validateLength(
  max: Int!
) on FIELD

✅

Subgraph A

directive @validateLength(
  max: Int!
) repeatable on FIELD

Subgraph B

directive @validateLength(
  max: Int!
) repeatable on FIELD

`INCONSISTENT_INPUT_OBJECT_FIELD`

Indicates that a field of an input object type definition is only defined in some of the subgraphs that declare the input object.

❌

Subgraph A

input ProductInput {
  name: String
  price: Float 
}

input OrderInput {
  product: ProductInput
}

Subgraph B

input ProductInput {
  name: String
}

input OrderInput {
  product: ProductInput
}

✅

Subgraph A

input ProductInput {
  name: String
  price: Float
}

input OrderInput {
  product: ProductInput
}

Subgraph B

input ProductInput {
  name: String
  price: Float
}

input OrderInput {
  product: ProductInput
}

`INCONSISTENT_INTERFACE_VALUE_TYPE_FIELD`

Indicates that a field of an interface "value type" (has no @key in any subgraph) isn't defined in all the subgraphs that declare the type.

❌

Subgraph A

1
interface Product {
2
  id: ID!
3
  name: String
4
  cost: Float 
5
}
6

7
type DigitalProduct implements Product {
8
  id: ID!
9
  name: String
10
  cost: Float
11
  size: Int 
12
}

Subgraph B

1
interface Product {
2
  id: ID!
3
  name: String
4
  # cost is not defined in the interface
5
}
6

7
type PhysicalProduct implements Product {
8
  id: ID!
9
  name: String
10
  cost: Float
11
  weight: Float 
12
}

✅

Subgraph A

1
interface Product {
2
  id: ID!
3
  name: String
4
  cost: Float 
5
}
6

7
type DigitalProduct implements Product {
8
  id: ID!
9
  name: String
10
  cost: Float
11
  size: Int 
12
}

Subgraph B

1
interface Product {
2
  id: ID!
3
  name: String
4
  cost: Float 
5
}
6

7
type PhysicalProduct implements Product {
8
  id: ID!
9
  name: String
10
  cost: Float
11
  weight: Float 
12
}

`INCONSISTENT_NON_REPEATABLE_DIRECTIVE_ARGUMENTS`

A non-repeatable directive is applied to a schema element in different subgraphs but with arguments that are different.

❌

Subgraph A

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
type Query {
7
  allProducts: [Product] @customDirective(orderBy: "name") 
8
}

Subgraph B

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
type Query {
7
  allProducts: [Product] @customDirective(orderBy: "price") 
8
}

✅

Subgraph A

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
type Query {
7
  allProducts: [Product] @customDirective(orderBy: "name") 
8
}

Subgraph B

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
type Query {
7
  allProducts: [Product] @customDirective(orderBy: "name") 
8
}

`INCONSISTENT_OBJECT_VALUE_TYPE_FIELD`

Indicates that a field of an object "value type" (has no @key in any subgraph) isn't defined in all the subgraphs that declare the type.

❌

Subgraph A

type Product {
  id: ID!
  name: String
  price: Float 
}

Subgraph B

type Product {
  id: ID!
  name: String
}

✅

Subgraph A

type Product {
  id: ID!
  name: String
  price: Float 
}

Subgraph B

type Product {
  id: ID!
  name: String
  price: Float 
}

`INCONSISTENT_RUNTIME_TYPES_FOR_SHAREABLE_RETURN`

Indicates that a @shareable field returns different sets of runtime types in the different subgraphs in which it's defined.

❌

Subgraph A

type Product {
  id: ID!
  name: String
  details: Details @shareable 
}

type Details {
  size: String 
}

Subgraph B

type Product {
  id: ID!
  name: String
  details: Details @shareable 
}

type Details {
  weight: Float 
}

✅

Subgraph A

type Product {
  id: ID!
  name: String
  details: Details @shareable 
}

type Details {
  size: String 
}

Subgraph B

type Product {
  id: ID!
  name: String
  details: Details @shareable 
}

type Details {
  size: String 
}

`INCONSISTENT_TYPE_SYSTEM_DIRECTIVE_LOCATIONS`

Indicates that an executable directive definition is declared with inconsistent locations across subgraphs. (The supergraph schema then uses the intersection of all locations in the supergraph.)

❌

Subgraph A

directive @customDirective(
  message: String!
) on OBJECT | FIELD_DEFINITION

Subgraph B

directive @customDirective(
  message: String!
) on FIELD_DEFINITION

✅

Subgraph A

directive @customDirective(
  message: String!
) on OBJECT | FIELD_DEFINITION

Subgraph B

directive @customDirective(
  message: String!
) on OBJECT | FIELD_DEFINITION

`INCONSISTENT_TYPE_SYSTEM_DIRECTIVE_REPEATABLE`

Indicates that a type system directive definition is marked repeatable in only some of the subgraphs that declare the directive and will be repeatable in the supergraph.

❌

Subgraph A

1
directive @customDirective on OBJECT

Subgraph B

1
directive @customDirective repeatable on OBJECT

✅

Subgraph A

1
directive @customDirective repeatable on OBJECT

Subgraph B

1
directive @customDirective repeatable on OBJECT

`INCONSISTENT_UNION_MEMBER`

Indicates that a member of a union type definition is only defined in some of the subgraphs that declare the union.

❌

Subgraph A

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
type Service {
7
  id: ID!
8
  description: String
9
}
10

11
union SearchResult = Product | Service

Subgraph B

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
union SearchResult = Product

✅

Subgraph A

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
type Service {
7
  id: ID!
8
  description: String
9
}
10

11
union SearchResult = Product | Service

Subgraph B

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
type Service {
7
  id: ID!
8
  description: String
9
}
10

11
union SearchResult = Product | Service

Overridden and unused elements

`OVERRIDE_DIRECTIVE_CAN_BE_REMOVED`

Indicates a field with the @override directive no longer exists in a source subgraph, so the directive can be safely removed.

❌

Subgraph A

1
type Product @key(fields: "id") {
2
  id: ID!
3
  inStock: Boolean! @override(from: "Subgraph B")
4
}

Subgraph B

1
type Product @key(fields: "id") {
2
  id: ID!
3
  name: String!
4
}

✅

Subgraph A

1
type Product @key(fields: "id") {
2
  id: ID!
3
  inStock: Boolean!
4
}

Subgraph B

1
type Product @key(fields: "id") {
2
  id: ID!
3
  name: String!
4
}

`OVERRIDDEN_FIELD_CAN_BE_REMOVED`

Indicates that a field has been overridden by another subgraph. You should consider removing the overriden field to avoid confusion.

❌

Subgraph A

1
type Product @key(fields: "id") {
2
  id: ID!
3
  name: String!
4
  inStock: Boolean! @override(from: "Subgraph B")
5
}

Subgraph B

1
type Product @key(fields: "id") {
2
  id: ID!
3
  inStock: Boolean!
4
}

✅

Subgraph A

1
type Product @key(fields: "id") {
2
  id: ID!
3
  name: String!
4
}

Subgraph B

1
type Product @key(fields: "id") {
2
  id: ID!
3
  inStock: Boolean!
4
}

`UNUSED_ENUM_TYPE`

Indicates that an enum type is defined in some subgraphs but is unused (no field/argument references it). All values from subgraphs defining that enum will be included in the supergraph.

❌

Subgraph A

enum ProductStatus {
  AVAILABLE
  SOLD_OUT
}

type Product {
  id: ID!
  name: String
}

Subgraph B

type Order {
  id: ID!
  product: Product
  status: String
}

✅

Subgraph A

type Product {
  id: ID!
  name: String
  status: ProductStatus
}

Subgraph B

type Order {
  id: ID!
  product: Product
  status: ProductStatus
}

Subgraph A

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
type Query {
7
  products: [Product] @customDirective(orderBy: ["name"]) 
8
}

Subgraph B

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
type Query {
7
  products: [Product] @customDirective(orderBy: ["price"]) 
8
}

✅

Subgraph A

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
type Query {
7
  products: [Product] @customDirective(orderBy: ["name", "price"]) 
8
}

Subgraph B

1
type Product {
2
  id: ID!
3
  name: String
4
}
5

6
type Query {
7
  products: [Product] @customDirective(orderBy: ["name", "price"]) 
8
}

`NO_EXECUTABLE_DIRECTIVE_INTERSECTION`

Indicates that an executable directive definition is declared with no shared locations across subgraphs.

❌

Subgraph A

directive @log(
  message: String!
) on QUERY

Subgraph B

directive @log(
  message: String!
) on FIELD

✅

Subgraph A

directive @log(
  message: String!
) on QUERY | FIELD

Subgraph B

directive @log(
  message: String!
) on QUERY | FIELD

`FROM_SUBGRAPH_DOES_NOT_EXIST`

Indicates the source subgraph specified by @override directive doesn't exist.

❌

Subgraph A

1
type Product @key(fields: "id") {
2
  id: ID!
3
  inStock: Boolean! @override(from: "Subgraph B")
4
}

Subgraph B

1
# Subgraph B doesn't exist

✅

Subgraph A

1
type Product @key(fields: "id") {
2
  id: ID!
3
  inStock: Boolean! @override(from: "Subgraph B")
4
}

Subgraph B

1
type Product @key(fields: "id") {
2
  id: ID!
3
  inStock: Boolean!
4
}

Error codes

Federated trace data

Composition hints

Inconsistent elements

`INCONSISTENT_ARGUMENT_PRESENCE`

`INCONSISTENT_BUT_COMPATIBLE_ARGUMENT_TYPE`

`INCONSISTENT_BUT_COMPATIBLE_FIELD_TYPE`

`INCONSISTENT_DEFAULT_VALUE_PRESENCE`

`INCONSISTENT_DESCRIPTION`

`INCONSISTENT_ENTITY`

`INCONSISTENT_ENUM_VALUE_FOR_INPUT_ENUM`

`INCONSISTENT_ENUM_VALUE_FOR_OUTPUT_ENUM`

`INCONSISTENT_EXECUTABLE_DIRECTIVE_LOCATIONS`

`INCONSISTENT_EXECUTABLE_DIRECTIVE_PRESENCE`

`INCONSISTENT_EXECUTABLE_DIRECTIVE_REPEATABLE`

`INCONSISTENT_INPUT_OBJECT_FIELD`

`INCONSISTENT_INTERFACE_VALUE_TYPE_FIELD`

`INCONSISTENT_NON_REPEATABLE_DIRECTIVE_ARGUMENTS`

`INCONSISTENT_OBJECT_VALUE_TYPE_FIELD`

`INCONSISTENT_RUNTIME_TYPES_FOR_SHAREABLE_RETURN`

`INCONSISTENT_TYPE_SYSTEM_DIRECTIVE_LOCATIONS`

`INCONSISTENT_TYPE_SYSTEM_DIRECTIVE_REPEATABLE`

`INCONSISTENT_UNION_MEMBER`

Overridden and unused elements

`OVERRIDE_DIRECTIVE_CAN_BE_REMOVED`

`OVERRIDDEN_FIELD_CAN_BE_REMOVED`

`UNUSED_ENUM_TYPE`

Directives

`DIRECTIVE_COMPOSITION`

`MERGED_NON_REPEATABLE_DIRECTIVE_ARGUMENTS`

`NO_EXECUTABLE_DIRECTIVE_INTERSECTION`

`FROM_SUBGRAPH_DOES_NOT_EXIST`