Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Schema Naming Conventions

Naming conventions and considerations for types, fields, and arguments in your GraphQL schema

schema-design

Want to learn about schema design in-person?

Don't miss the Schema design excellence workshop at this year's GraphQL Summit.

💡 TIP

If you're an enterprise customer looking for more material on this topic, try the Enterprise best practices: Schema design course on .

Not an enterprise customer? Learn about GraphOS for Enterprise.

Enforcing conventions

Use schema linting to catch naming violations. GraphOS schema linting can be done within schema checks which can allow you to enforce this in your CI/CD pipelines, or it can be run using Rover for one-off requests locally.

High-level guidance

  • Regardless of your chosen conventions, be consistent across the entire schema.
  • Be specific with names—don't "land grab" names with broad applicability.
  • Avoid acronyms, initialisms, and abbreviations.

Casing

Use camelCase for names, names, and names:

type Query {
myCamelCaseFieldNames(myArgumentName: String): String
}
directive @myDirective on FIELD

Use PascalCase for type names:

type MyType { ... }
enum MyEnum { ... }
interface MyInterface { ... }
union MyUnion = ...
scalar MyScalar

Use SCREAMING_SNAKE_CASE for enum values:

enum MyEnum {
VALUE_ONE
VALUE_TWO
}

Field names

Avoid verb prefixes like get or list on (read) :

type Query {
# ❌ incorrect
getProducts: [Product]
# ✅ correct
products: [Product]
}

This creates consistency between root fields and nested fields:

# ❌ incorrect
query Products {
getProducts {
id
getReviews {
content
}
}
}
# ✅ correct
query Products {
products {
id
reviews {
content
}
}
}

Start fields with a verb:

type Mutation {
# ❌ incorrect
customerAdd(input: AddCustomerInput): AddCustomerPayload!
# ✅ correct
addCustomer(input: AddCustomerInput): AddCustomerPayload!
}

Type names

Use the suffix Input when naming input types:

input AddCustomerInput {
name: String!
}

Use a consistent suffix like Response or Payload when naming output types returned from :

type Mutation {
addCustomer(input: AddCustomerInput!): AddCustomerResponse!
}
type AddCustomerResponse {
success: Boolean!
}

Additional considerations

Namespacing

When resolving naming conflicts between different domains, we recommend using one of the following:

PascalCase prefix

type StoreCustomer { ... }
type SiteCustomer { ... }

Single_Underscore prefix

type Store_Customer { ... }
type Site_Customer { ... }
Next
Home
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company