Schema linter rules
Reference
This reference lists the rules that you can enforce with GraphOS schema linting, along with the code that GraphOS returns for each rule violation.
Naming rules
These rules enforce naming conventions. Rules are categorized by the part(s) of your schema that they correspond to.
Fields
What it does
Checks that all field names usecamelCase.Rationale
camelCase is a convention for field names in GraphQL.Examples
The following example violates the rule:
❌ schema.graphql
type User {FirstName: String! # PascalCase}
Use instead:
✅ schema.graphql
type User {firstName: String # camelCase}
What it does
Checks that a field's name doesn't start with any of the following verbs:get, list, post, put, patch.Rationale
Fields should not start with a verb, except for mutations. For mutation fields, it's best to use a verb that describes the specific action being performed, for example,create, delete, or edit.Examples
The following example violates the rule:
❌ schema.graphql
type Query {getUsers: [User!]!}
Use instead:
✅ schema.graphql
type Query {users: [User!]!}
Types
These rules apply to all types that appear in a GraphQL schema, including:
- Objects
- Interfaces
- Inputs
- Enums
- Unions
What it does
Checks that all type names usePascalCase.Rationale
PascalCase is a convention for type names in GraphQL.Examples
The following example violates the rule:
❌ schema.graphql
type streamingService { # camelCaseid: ID!}
Use instead:
✅ schema.graphql
type StreamingService { # PascalCaseid: ID!}
What it does
Checks that type names don't start with the prefixType.Rationale
Avoid using the redundantType prefix to shorten your schema definitions and improve readability.Examples
The following example violates the rule:
❌ schema.graphql
type TypeBook {title: String!}
Use instead:
✅ schema.graphql
type Book {title: String!}
What it does
Checks that type names don't use the suffixType.Rationale
Avoid using the redundantType suffix to shorten your schema definitions and improve readability.Examples
The following example violates the rule:
❌ schema.graphql
type BookType {title: String!}
Use instead:
✅ schema.graphql
type Book {title: String!}
Objects
What it does
Checks that object type names don't start with the prefixObject.Rationale
Avoid using the redundantObject prefix to shorten your schema definitions and improve readability.Examples
The following example violates the rule:
❌ schema.graphql
type ObjectBook {title: String!}
Use instead:
✅ schema.graphql
type Book {title: String!}
What it does
Checks that object type names don't use the suffixObject.Rationale
Avoid using the redundantObject suffix to shorten your schema definitions and improve readability.Examples
The following example violates the rule:
❌ schema.graphql
type BookObject {title: String!}
Use instead:
✅ schema.graphql
type Book {title: String!}
Interfaces
What it does
Checks that interface type names don't start with the prefixInterface.Rationale
Avoid using the redundantInterface prefix to shorten your schema definitions and improve readability.Examples
The following example violates the rule:
❌ schema.graphql
interface InterfaceBook {title: Stringauthor: String}
Use instead:
✅ schema.graphql
interface Book {title: Stringauthor: String}
What it does
Checks that interface type names don't use the suffixInterface.Rationale
Avoid using the redundantInterface suffix to shorten your schema definitions and improve readability.Examples
The following example violates the rule:
❌ schema.graphql
interface BookInterface {title: Stringauthor: String}
Use instead:
✅ schema.graphql
interface Book {title: Stringauthor: String}
Inputs and arguments
What it does
Checks that argument names usecamelCase.Rationale
camelCase is a convention for argument names in GraphQL.Examples
The following example violates the rule:
❌ schema.graphql
type Mutation {createBlogPost(BlogPostContent: BlogPostContent!): Post # PascalCase}
Use instead:
✅ schema.graphql
type Mutation {createBlogPost(blogPostContent: BlogPostContent!): Post # camelCase}
What it does
Checks that input type names use the suffixInput.Rationale
Ending input type names withInput distinguishes input types from "output" types like objects.Examples
The following example violates the rule:
❌ schema.graphql
input BlogPostDetails {title: String!content: String!}
Use instead:
✅ schema.graphql
input BlogPostDetailsInput {title: String!content: String!}
Enums
What it does
Checks that enum values useSCREAMING_SNAKE_CASE.Rationale
SCREAMING_SNAKE_CASE is a convention for enum values in GraphQL.Examples
The following example violates the rule:
❌ schema.graphql
enum Amenity {public_park # snake_case}
Use instead:
✅ schema.graphql
enum Amenity {PUBLIC_PARK # SCREAMING_SNAKE_CASE 😱}
What it does
Checks that enum type names don't start with the prefixEnum.Rationale
Avoid using the redundantEnum prefix to shorten your schema definitions and improve readability.Examples
The following example violates the rule:
❌ schema.graphql
enum EnumResidence {HOUSEAPARTMENTCONDO}
Use instead:
✅ schema.graphql
enum Residence {HOUSEAPARTMENTCONDO}
What it does
Checks that enum type names don't use the suffixEnum.Rationale
Avoid using the redundantEnum suffix to shorten your schema definitions and improve readability.Examples
The following example violates the rule:
❌ schema.graphql
enum ResidenceEnum {HOUSEAPARTMENTCONDO}
Use instead:
✅ schema.graphql
enum Residence {HOUSEAPARTMENTCONDO}
What it does
If an enum type is used as an input argument, checks that its name uses the suffixInput.Rationale
Ending input arguments withInput distinguishes inputs from "output" types like objects.Examples
The following example violates the rule:
❌ schema.graphql
enum Role {EDITORVIEWER}type Query {users(role: Role): [User!]!}
Use instead:
✅ schema.graphql
enum RoleInput {EDITORVIEWER}type Query {users(role: RoleInput): [User!]!}
What it does
If an enum is used as the return type of a non-input field, checks that its name doesn't use the suffixInput.Rationale
Including the suffixInput on an output type is misleading.Examples
The following example violates the rule:
❌ schema.graphql
enum RoleInput {EDITORVIEWER}type Query {userRole(userId: ID!): RoleInput}
Use instead:
✅ schema.graphql
enum Role {EDITORVIEWER}type Query {userRole(userId: ID!): Role}
Directives
What it does
Checks that directive names usecamelCase.Rationale
camelCase is a convention for directive names in GraphQL.Examples
The following example violates the rule:
❌ schema.graphql
directive @SpecialField on FIELD_DEFINITION # PascalCase
Use instead:
✅ schema.graphql
directive @specialField on FIELD_DEFINITION # camelCase
Composition rulesSince 2.4
ⓘ NOTE
Composition rules are only available for graphs on federation version 2.4 or later. You can update a graph's version from its Settings page in GraphOS Studio.
Composition rules flag potential improvements to subgraph schemas used to compose a supergraph schema.
Inconsistent elements
These rules identity inconsistencies in fields, types, arguments, etc across subgraphs. Such inconsistencies can disrupt or even break composition.
Compatibility
In some cases, inconsistency rules also indicate the compatibility of checked types. 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.
For example, the price fields in the example subgraphs below are inconsistent and incompatible because they use completely different types (Float vs String):
Subgraph A
type Product {id: ID!name: Stringprice: Float}
Subgraph B
type Product {id: ID!name: Stringprice: String}
These price fields in the example subgraphs below are inconsistent but compatible since both use Floats, but one is nullable and the other is the non-nullable list of Floats.
Subgraph A
type Product {id: ID!name: Stringprice: Float}
Subgraph B
type Product {id: ID!name: Stringprice: [Float]!}
What it does
Checks that an argument of a field or directive definition is present in all subgraphs.Rationale
The supergraph schema only includes arguments that are exactly the same for all subgraphs that define its field or directive. Learn more.Examples
The following example violates the rule:
❌ Subgraph A
type Product {id: ID!name: Stringprice(currency: Currency): Float}
❌ Subgraph B
type Product {id: ID!name: Stringprice(currency: Currency, taxIncluded: Boolean): Float}
Use instead:
✅ Subgraph A
type Product {id: ID!name: Stringprice(currency: Currency, taxIncluded: Boolean): Float}
✅ Subgraph B
type Product {id: ID!name: Stringprice(currency: Currency, taxIncluded: Boolean): Float}
What it does
Checks that arguments (of a field, input field, or directive definition) have the exact same types in all subgraphs. This warning/error indicates the argument types are compatible but inconsistent.Rationale
The supergraph schema only includes arguments that are exactly the same for all subgraphs that define its field or directive. Learn more.Examples
Because subgraph A's price field expects a non-nullable Currency argument type and subgraph B allows a nullable Currency argument type, the following example violates the rule:
❌ Subgraph A
type Product {id: ID!name: Stringprice(currency: Currency!): Float}enum Currency {USDEURGBPJPYAUDCAD}
❌ Subgraph B
type Product {id: ID!name: Stringprice(currency: Currency): Float}enum Currency {USDEURGBPJPYAUDCAD}
Use instead:
✅ Subgraph A
type Product {id: ID!name: Stringprice(currency: Currency!): Float}enum Currency {USDEURGBPJPYAUDCAD}
✅ Subgraph B
type Product {id: ID!name: Stringprice(currency: Currency!): Float}enum Currency {USDEURGBPJPYAUDCAD}
What it does
Checks that fields have the exact same types in all subgraphs. This warning/error indicates the field types are compatible but inconsistent.Rationale
Inconsistent types can lead to discrepancies in the way data is retrieved and processed, resulting in unexpected client behavior.Examples
The following example violates the rule:
❌ Subgraph A
type Product {id: ID!name: Stringprice: Money}type Money {amount: Float!currency: Currency!}enum Currency {USDEURGBPJPYAUDCAD}
❌ Subgraph B
type Product {id: ID!name: Stringprice: Money!}type Money {amount: Float!currency: Currency!}enum Currency {USDEURGBPJPYAUDCAD}
Use instead:
✅ Subgraph A
type Product {id: ID!name: Stringprice: Money!}type Money {amount: Float!currency: Currency!}enum Currency {USDEURGBPJPYAUDCAD}
✅ Subgraph B
type Product {id: ID!name: Stringprice: Money!}type Money {amount: Float!currency: Currency!}enum Currency {USDEURGBPJPYAUDCAD}
What it does
Checks that argument definitions (of a field, input field, or directive definition) consistently include—or consistently don't include—a default value in all subgraphs that define the argument.Rationale
Inconsistent defaults can lead to discrepancies in the way data is retrieved and processed, resulting in unexpected client behavior.Examples
The following example violates the rule:
❌ Subgraph A
type Product {id: ID!name: Stringweight(kg: Float = 1.0): Float}
❌ Subgraph B
type Product {id: ID!name: Stringweight(kg: Float): Float}
Use instead:
✅ Subgraph A
type Product {id: ID!name: Stringweight(kg: Float = 1.0): Float}
✅ Subgraph B
type Product {id: ID!name: Stringweight(kg: Float = 1.0): Float}
What it does
Checks that a type's description is consistent across subgraphs.Rationale
Inconsistent type descriptions can lead to inconsistent expectations around type values resulting in unexpected client behavior.Examples
The following example violates the rule:
❌ 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}
Use instead:
✅ 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}
What it does
Checks that an object is consistently declared as an entity (has a@key) in all subgraphs in which the object is defined.Rationale
If an object is only declared as an entity in some subgraphs, the federated schema won't have complete information about that entity.Examples
The following example violates the rule:
❌ Subgraph A
type Product @key(fields: "id") {id: ID!name: String}
❌ Subgraph B
type Product {id: ID!stock: Int}
Use instead:
✅ Subgraph A
type Product @key(fields: "id") {id: ID!name: String}
✅ Subgraph B
type Product @key(fields: "id") {id: ID!stock: Int}
What it does
Checks that values of an input enum type are consistently defined in all subgraphs that declare the enum.Rationale
When a value of an enum that is only used as an input type is defined in only some of the subgraphs that declare the enum, inconsistent values won't be merged into the supergraph. Learn more.Examples
The following example violates the rule:
❌ Subgraph A
enum ProductStatus {AVAILABLESOLD_OUTBACK_ORDER}input ProductInput {name: String!status: ProductStatus!}
❌ Subgraph B
enum ProductStatus {AVAILABLESOLD_OUT}input ProductInput {name: String!status: ProductStatus!}
Use instead:
✅ Subgraph A
enum ProductStatus {AVAILABLESOLD_OUTBACK_ORDER}input ProductInput {name: String!status: ProductStatus!}
✅ Subgraph B
enum ProductStatus {AVAILABLESOLD_OUTBACK_ORDER}input ProductInput {name: String!status: ProductStatus!}
What it does
Checks that values of an output enum type are consistently defined in all subgraphs that declare the enum.Rationale
When values of an output or unused enum type definition are inconsistent, all values are merged into the supergraph. Regardless, it can be helpful to set expectations by including all possible values in all subgraphs defining the enum. Learn more.Examples
The following example violates the rule:
❌ Subgraph A
enum OrderStatus {CREATEDPROCESSINGCOMPLETED}type Order {name: String!status: OrderStatus!}
❌ Subgraph B
enum OrderStatus {CREATEDCOMPLETED}type Order {name: String!status: OrderStatus!}
Use instead:
✅ Subgraph A
enum OrderStatus {CREATEDPROCESSINGCOMPLETED}type Order {name: String!status: OrderStatus!}
✅ Subgraph B
enum OrderStatus {CREATEDPROCESSINGCOMPLETED}type Order {name: String!status: OrderStatus!}
What it does
Checks that an executable directive definition is declared with consistent locations across all subgraphs.Rationale
An executable directive is composed into the supergraph schema only when it is defined identically in all subgraphs. Learn more.Examples
The following example violates the rule:
❌ Subgraph A
directive @log(message: String!) on QUERY
❌ Subgraph B
directive @log(message: String!) on FIELD
Use instead:
✅ Subgraph A
directive @log(message: String!) on QUERY | FIELD
✅ Subgraph B
directive @log(message: String!) on QUERY | FIELD
What it does
Checks that an executable directive definition is declared in all subgraphs.Rationale
An executable directive is composed into the supergraph schema only if it's defined in all subgraphs. Learn more.Examples
The following example violates the rule:
❌ Subgraph A
directive @modify(field: String!) on FIELD
❌ Subgraph B
# 🦗🦗🦗
Use instead:
✅ Subgraph A
directive @modify(field: String!) on FIELD
✅ Subgraph B
directive @modify(field: String!) on FIELD
What it does
Checks that an executable directive definition is markedrepeatable in all subgraphs that define it.Rationale
Unless an executable directive is defined asrepeatable in all subgraphs, it won't be repeatable in the supergraph.Examples
The following example violates the rule:
❌ Subgraph A
directive @validateLength(max: Int!) repeatable on FIELD
❌ Subgraph B
directive @validateLength(max: Int!) on FIELD
Use instead:
✅ Subgraph A
directive @validateLength(max: Int!) repeatable on FIELD
✅ Subgraph B
directive @validateLength(max: Int!) repeatable on FIELD
What it does
Checks that a field of an input object definition is defined in all the subgraphs that declare the input object.Rationale
The supergraph schema includes only the input object fields that all subgraphs define for the object. Learn more.Examples
The following example violates the rule:
❌ Subgraph A
input ProductInput {name: Stringprice: Float}input OrderInput {product: ProductInput}
❌ Subgraph B
input ProductInput {name: String}input OrderInput {product: ProductInput}
Use instead:
✅ Subgraph A
input ProductInput {name: Stringprice: Float}input OrderInput {product: ProductInput}
✅ Subgraph B
input ProductInput {name: Stringprice: Float}input OrderInput {product: ProductInput}
What it does
Checks that a field of an interface value type (has no@key in any subgraph) is defined in all the subgraphs that declare the type.Rationale
If different subgraphs contribute different fields to an interface type, any object types that implement that interface must define all contributed fields from all subgraphs. Otherwise, composition fails. Learn more.Examples
The following example violates the rule:
❌ Subgraph A
interface Product {id: ID!name: Stringcost: Float}type DigitalProduct implements Product {id: ID!name: Stringcost: Floatsize: Int}
❌ Subgraph B
interface Product {id: ID!name: String# cost is not defined in the interface}type PhysicalProduct implements Product {id: ID!name: Stringcost: Floatweight: Float}
Use instead:
✅ Subgraph A
interface Product {id: ID!name: Stringcost: Float}type DigitalProduct implements Product {id: ID!name: Stringcost: Floatsize: Int}
✅ Subgraph B
interface Product {id: ID!name: Stringcost: Float}type PhysicalProduct implements Product {id: ID!name: Stringcost: Floatweight: Float}
What it does
Checks if a non-repeatable directive is applied to a schema element across different subgraphs with differing arguments.Rationale
Inconsistent directive argument usage can lead to misunderstandings and potential issues in client applications.Examples
The following example violates the rule:
❌ Subgraph A
type Product {id: ID!name: String}type Query {allProducts: [Product] @customDirective(orderBy: "name")}
❌ Subgraph B
type Product {id: ID!name: String}type Query {allProducts: [Product] @customDirective(orderBy: "price")}
Use instead:
✅ Subgraph A
type Product {id: ID!name: String}type Query {allProducts: [Product] @customDirective(orderBy: "name")}
✅ Subgraph B
type Product {id: ID!name: String}type Query {allProducts: [Product] @customDirective(orderBy: "name")}
What it does
Checks that object value types (has no@key in any subgraph) declare the same fields in all subgraphs that declare the type.Rationale
When an object value type includes differing fields across subgraphs, the supergraph schema includes the union of all fields. Depending on which subgraph executes the query, omitted fields may be unresolvable. You can include the same types as shown below or check out Solutions for unresolvable fields.Examples
The following example violates the rule:
❌ Subgraph A
type Product {id: ID! @shareablename: String @shareableprice: Float}
❌ Subgraph B
type Product {id: ID! @shareablename: String @shareable}
Use instead:
✅ Subgraph A
type Product @shareable {id: ID!name: Stringprice: Float}
✅ Subgraph B
type Product @shareable {id: ID!name: Stringprice: Float}
What it does
Checks that a@shareable field returns consistent sets of runtime types in all subgraphs in which it's defined.Rationale
Each subgraph's resolver for a@shareable field should behave identically. Otherwise, requests might return inconsistent results depending on which subgraph resolves the field. Learn more.Examples
The following example violates the rule:
❌ Subgraph A
type Product {id: ID!name: Stringdetails: Details @shareable}type Details {size: String}
❌ Subgraph B
type Product {id: ID!name: Stringdetails: Details @shareable}type Details {weight: Float}
Use instead:
✅ Subgraph A
type Product {id: ID!name: Stringdetails: Details @shareable}type Details {size: String}
✅ Subgraph B
type Product {id: ID!name: Stringdetails: Details @shareable}type Details {size: String}
What it does
Checks that a type system directive definition is declared with consistent locations across subgraphs.Rationale
To ensure consistent expectations, it's best that all definitions declare the same locations. Learn more.Examples
The following example violates the rule:
❌ Subgraph A
directive @customDirective(message: String!) on OBJECT | FIELD_DEFINITION
❌ Subgraph B
directive @customDirective(message: String!) on FIELD_DEFINITION
Use instead:
✅ Subgraph A
directive @customDirective(message: String!) on OBJECT | FIELD_DEFINITION
✅ Subgraph B
directive @customDirective(message: String!) on OBJECT | FIELD_DEFINITION
What it does
Checks that a type system directive definition is markedrepeatable in all subgraphs that declare the directive and will be repeatable in the supergraph.Rationale
To ensure consistent expectations, directives should have consistent definitions across subgraphs, including whether they arerepeatable. Learn more.Examples
The following example violates the rule:
❌ Subgraph A
directive @customDirective on OBJECT
❌ Subgraph B
directive @customDirective repeatable on OBJECT
Use instead:
✅ Subgraph A
directive @customDirective repeatable on OBJECT
✅ Subgraph B
directive @customDirective repeatable on OBJECT
What it does
Checks that a member of a union definition is defined in all subgraphs that declare the union.Rationale
When a union definition has inconsistent members, the supergraph schema includes all members in the union definition. Nevertheless, to ensure consistent expectations, it's best that all union definitions declare the same members across subgraphs. Learn more.Examples
The following example violates the rule:
❌ Subgraph A
type Product {id: ID!name: String}type Service {id: ID!description: String}union SearchResult = Product | Service
❌ Subgraph B
type Product {id: ID!name: String}union SearchResult = Product
Use instead:
✅ Subgraph A
type Product {id: ID!name: String}type Service {id: ID!description: String}union SearchResult = Product | Service
✅ Subgraph B
type Product {id: ID!name: String}type Service {id: ID!description: String}union SearchResult = Product | Service
Overridden and unused elements
Rationale
If a field with the@override directive no longer exists in a source subgraph, the directive can be safely removed.Examples
The following example violates the rule:
❌ Subgraph A
type Product @key(fields: "id") {id: ID!inStock: Boolean! @override(from: "Subgraph B")}
❌ Subgraph B
type Product @key(fields: "id") {id: ID!name: String!}
Use instead:
✅ Subgraph A
type Product @key(fields: "id") {id: ID!inStock: Boolean!}
✅ Subgraph B
type Product @key(fields: "id") {id: ID!name: String!}
What it does
Checks if a field has been overridden by another subgraph.Rationale
You should consider removing overridden fields to avoid confusion.Examples
The following example violates the rule:
❌ Subgraph A
type Product @key(fields: "id") {id: ID!inStock: Boolean! @override(from: "Subgraph B")}
❌ Subgraph B
type Product @key(fields: "id") {id: ID!name: String!inStock: Boolean!}
Use instead:
✅ Subgraph A
type Product @key(fields: "id") {id: ID!name: String!inStock: Boolean!}
✅ Subgraph B
type Product @key(fields: "id") {id: ID!name: String!}
What it does
Checks if a field migration is in progress.Rationale
You should complete a field migration.Examples
The following example violates the rule:
❌ Subgraph A
type Product @key(fields: "id") {id: ID!inStock: Boolean! @override(from: "Subgraph B", label: "percent(50)")}
❌ Subgraph B
type Product @key(fields: "id") {id: ID!name: String!inStock: Boolean!}
After completing the migration, use instead:
✅ Subgraph A
type Product @key(fields: "id") {id: ID!name: String!inStock: Boolean!}
✅ Subgraph B
type Product @key(fields: "id") {id: ID!name: String!}
What it does
Checks if an enum type is defined but no field or argument in any subgraph references it.Rationale
If the enum is defined, it should be used or removed.Examples
The following example violates the rule:
❌ Subgraph A
enum ProductStatus {AVAILABLESOLD_OUT}type Product {id: ID!name: String}
❌ Subgraph B
type Order {id: ID!product: Productstatus: String}
Use instead:
✅ Subgraph A
enum ProductStatus {AVAILABLESOLD_OUT}type Product {id: ID!name: Stringstatus: ProductStatus}
✅ Subgraph B
type Order {id: ID!product: Productstatus: ProductStatus}
Directives
What it does
Checks for issues when composing custom directives.What it does
Checks if a non-repeatable directive has been applied to the same schema element in different subgraphs with different arguments. Learn more.Rationale
Arguments should be consistent across a non-repeatable directive's usage. If arguments differ, it may be a sign that subgraph owners need to communicate about the directive's usage. If the arguments need to differ, consider using a repeatable directive.Examples
The following example violates the rule:
❌ Subgraph A
type Product {id: ID!name: String}type Query {products: [Product] @customDirective(orderBy: ["name"])}
❌ Subgraph B
type Product {id: ID!name: String}type Query {products: [Product] @customDirective(orderBy: ["price"])}
Use instead:
✅ Subgraph A
type Product {id: ID!name: String}type Query {products: [Product] @customDirective(orderBy: ["name", "price"])}
✅ Subgraph B
type Product {id: ID!name: String}type Query {products: [Product] @customDirective(orderBy: ["name", "price"])}
Rationale
Directives must only be used in the locations they are declared to belong in. If the same executable directive is defined with different locations in different subgraphs, it may be a sign that subgraph owners need to communicate about the directive's usage.Examples
The following example violates the rule:
❌ Subgraph A
directive @log(message: String!) on QUERY
❌ Subgraph B
directive @log(message: String!) on FIELD
Use instead:
✅ Subgraph A
directive @log(message: String!) on QUERY | FIELD
✅ Subgraph B
directive @log(message: String!) on QUERY | FIELD
Rationale
The@override directive indicates that an object field is now resolved by a different subgraph. The directive can't work unless you specify an existing subgraph to resolve the field from.Examples
The following example violates the rule:
❌ Subgraph A
type Product @key(fields: "id") {id: ID!inStock: Boolean! @override(from: "Subgraph B")}
❌ Subgraph B
# Subgraph B doesn't exist
Use instead:
✅ Subgraph A
type Product @key(fields: "id") {id: ID!inStock: Boolean! @override(from: "Subgraph B")}
✅ Subgraph B
type Product @key(fields: "id") {id: ID!inStock: Boolean!}
Other rules
These rules define conventions for the entire schema and directive usage outside of composition.
Schema
These rules apply to the entire schema.
What it does
Checks for malformed GraphQL schemas. To resolve, check your schema for syntax errors.Rationale
Descriptions document your GraphQL schema so consumers of your graph can easily discover fields and learn how to use them. See examples.Examples
The following example violates the rule:
❌ schema.graphql
type User {username: String!}
Use instead:
✅ schema.graphql
"Represents a user"type User {"A username must be [8-64] characters."username: String!}
What it does
Checks that every type defined in a schema is be used at least once.Rationale
Unused types waste resources and should be immediately removed once they've been refactored out of a schema.Examples
The following example violates the rule:
❌ schema.graphql
type SomeUnusedType { # Also fails the TYPE_SUFFIX rule!name: String!}type AnActuallyUsedType {name: String!}type Query {hello: String!title: AnActuallyUsedType}
Use instead:
✅ schema.graphql
type Book {title: String!}type Query {books: [Book!]!}
What it does
Checks that schemas don't define operations, such as queries and mutations.Rationale
Operations should be defined on the client side, not within schemas. Schemas define types, fields, and their relationships. Operations specify what data to fetch or change. Since what to fetch or change is a client concern, this separation allows for a clean and modular architecture, making it easier to manage and evolve the API over time.Examples
The following example violates the rule:
❌ schema.graphql
type Query {users: [User!]!}query GetUsers {# Don't define operations in a schema documentusers {id}}
Directives
What it does
Checks that subgraph schemas always provide owner contact details via the@contact directive.Rationale
You can use the@contact directive to add your team's contact info to a subgraph schema. This info is displayed in GraphOS Studio, which helps other teams know who to contact for assistance with the subgraph. Learn more.Examples
This example shows correct @contact directive usage:
✅ schema.graphql
directive @contact("Contact title of the subgraph owner"name: String!"URL where the subgraph's owner can be reached"url: String"Other relevant notes can be included here; supports markdown links"description: String) on SCHEMAextend schema@contact(name: "Products Team"url: "https://myteam.slack.com/archives/teams-chat-room-url"description: "Send urgent issues to [#oncall](https://yourteam.slack.com/archives/oncall).")
What it does
Checks that the@deprecated directive always includes a reason argument.Rationale
Thereason argument can help graph consumers understand which field to use instead of the @deprecated one.Examples
The following example violates the rule:
❌ schema.graphql
type Product {title: String @deprecatedname: String!}
Use instead:
✅ schema.graphql
type Product {title: String @deprecated(reason: "Use Product.name instead")name: String!}
What it does
Checks that the@tag directive uses an approved value for its name argument. You specify approved values in GraphOS Studio.Rationale
This directive is used most commonly with GraphOS contracts. Validating@tag names ensures contracts work as intended.Custom rules
The schema linter is configurable with the predefined rules documented above. Custom rule creation isn't currently supported but is under consideration.