GraphOS 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.
Rules are categorized by the part(s) of your schema that they correspond to.
Schema
DOES_NOT_PARSE
The schema linter raises this violation if it attempts to read a malformed GraphQL schema. Check your schema for any syntax errors.
QUERY_DOCUMENT_DECLARATION
A GraphQL schema should never include definitions of GraphQL operations (such as queries and mutations).
❌
type Query {users: [User!]!}query GetUsers { # Don't define operations in a schema documentusers {id}}
All fields
FIELD_NAMES_SHOULD_BE_CAMEL_CASE
Field names should always use camelCase
.
❌
type User {FirstName: String! # PascalCase}
✅
type User {firstName: String # camelCase}
RESTY_FIELD_NAMES
A field's name should never start with any of the following verbs:
get
list
post
put
patch
Most fields should not start with any verb, with the exception of Mutation
fields. For Mutation
fields, use a verb that more specifically describes the action being performed (such as create
, delete
, or edit
).
❌
type Query {getUsers: [User!]!}
✅
type Query {users: [User!]!}
All types
These rules apply to all types that appear in a GraphQL schema, including:
- Objects
- Interfaces
- Inputs
- Enums
- Unions
TYPE_NAMES_SHOULD_BE_PASCAL_CASE
All type names should use PascalCase
.
❌
type streamingService { # camelCaseid: ID!}
✅
type StreamingService { # PascalCaseid: ID!}
TYPE_PREFIX
Type names should never use the prefix Type
.
❌
type TypeBook {title: String!}
✅
type Book {title: String!}
TYPE_SUFFIX
Type names should never use the suffix Type
.
❌
type BookType {title: String!}
✅
type Book {title: String!}
Objects
OBJECT_PREFIX
An object type's name should never use the prefix Object
.
❌
type ObjectBook {title: String!}
✅
type Book {title: String!}
OBJECT_SUFFIX
An object type's name should never use the suffix Object
.
❌
type BookObject {title: String!}
✅
type Book {title: String!}
Interfaces
INTERFACE_PREFIX
An interface type's name should never use the prefix Interface
.
❌
interface InterfaceBook {title: Stringauthor: String}
✅
interface Book {title: Stringauthor: String}
INTERFACE_SUFFIX
An interface type's name should never use the suffix Interface
.
❌
interface BookInterface {title: Stringauthor: String}
✅
interface Book {title: Stringauthor: String}
Inputs & arguments
INPUT_ARGUMENT_NAMES_SHOULD_BE_CAMEL_CASE
A GraphQL argument's name should always use camelCase
.
❌
type Mutation {createBlogPost(BlogPostContent: BlogPostContent!): Post # PascalCase}
✅
type Mutation {createBlogPost(blogPostContent: BlogPostContent!): Post # camelCase}
INPUT_TYPE_SUFFIX
An input type's name should always use the suffix Input
.
❌
input BlogPostDetails {title: String!content: String!}
✅
input BlogPostDetailsInput {title: String!content: String!}
Enums
ENUM_VALUES_SHOULD_BE_SCREAMING_SNAKE_CASE
Enum values should always use SCREAMING_SNAKE_CASE
.
❌
enum Amenity {public_park # snake_case}
✅
enum Amenity {PUBLIC_PARK # SCREAMING_SNAKE_CASE 😱}
ENUM_PREFIX
An enum type's name should never use the prefix Enum
.
❌
enum EnumResidence {HOUSEAPARTMENTCONDO}
✅
enum Residence {HOUSEAPARTMENTCONDO}
ENUM_SUFFIX
An enum type's name should never use the suffix Enum
.
❌
enum ResidenceEnum {HOUSEAPARTMENTCONDO}
✅
enum Residence {HOUSEAPARTMENTCONDO}
ENUM_USED_AS_INPUT_WITHOUT_SUFFIX
If an enum type is used as an input argument, its name should use the suffix Input
.
❌
enum Role {EDITORVIEWER}type Query {users(role: Role): [User!]!}
✅
enum RoleInput {EDITORVIEWER}type Query {users(role: RoleInput): [User!]!}
ENUM_USED_AS_OUTPUT_DESPITE_SUFFIX
If an enum is used as the return type of a non-input field, its name should not use the suffix Input
.
❌
enum RoleInput {EDITORVIEWER}type Query {userRole(userId: ID!): RoleInput}
✅
enum Role {EDITORVIEWER}type Query {userRole(userId: ID!): Role}
Directives
DIRECTIVE_NAMES_SHOULD_BE_CAMEL_CASE
Directive names should always use camelCase
.
❌
directive @SpecialField on FIELD_DEFINITION # PascalCase
✅
directive @specialField on FIELD_DEFINITION # camelCase
CONTACT_DIRECTIVE_MISSING
A subgraph schema should always provide owner contact details via the @contact
directive. Learn more.
✅
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).")
DEPRECATED_DIRECTIVE_MISSING_REASON
The @deprecated
directive should always include a reason
argument.
❌
type Product {title: String @deprecatedname: String!}
✅
type Product {title: String @deprecated(reason: "Use Product.name instead")name: String!}
TAG_DIRECTIVE_USES_UNKNOWN_NAME
The @tag
directive should always use an approved value for its name
argument. You specify approved values in GraphOS Studio.