GraphQL SDL conventions

Contract

When you write or edit a GraphQL schema in the Schema Definition Language (SDL), conform to the spec's type system and the community naming conventions: PascalCase type names, camelCase fields/arguments, SCREAMING_SNAKE_CASE enum values, the exactly-five built-in scalars (Int Float String Boolean ID) with everything else declared as a custom scalar, non-null ! discipline, Input/Payload mutation suffixes, and the built-in @deprecated(reason:) directive for retiring fields. Apply this to any object type, interface, union, enum, input, mutation, or scalar you emit.

Rules

1. Type names are PascalCase. Every named type — type, interface, union,

enum, input, and any custom scalar — is UpperCamelCase: PaymentMethod, ShippingAddress. Never snake_case (payment_method) or camelCase (paymentMethod) for a type name. The three root operation types are named exactly Query, Mutation, Subscription.

1. Field and argument names are camelCase. Every field and every argument is

lowerCamelCase: phoneNumber, createdAt, argument orderBy. Convert any snake_case the request hands you (phone_number, created_at) to camelCase — never keep snake_case, SCREAMING_SNAKE_CASE, or PascalCase on a field.

1. Enum values are SCREAMING_SNAKE_CASE. Every enum member is all-uppercase, words

joined by underscores: PENDING, AWAITING_PAYMENT. Never lowercase (pending), camelCase (awaitingPayment), or PascalCase (AwaitingPayment) enum members. The enum type itself is still PascalCase.

1. Use only the five built-in scalars. The complete built-in scalar set is Int

(32-bit signed whole number), Float (double-precision decimal), String, Boolean, and ID. Use Int for counts/quantities — never Integer, Number, or Long. Use Float for decimals — never Double or Decimal. Use Boolean — never Bool. Any other primitive (a date, timestamp, URL, email, JSON blob, decimal money) is not built in: declare it once with the scalar keyword (scalar DateTime) and reference that, or fall back to String. Never write Date, DateTime, Timestamp, JSON, or URL as a field type without a matching scalar declaration.

1. Mark required fields non-null with !. A field that is always present carries a

trailing ! (String!). The primary identifier is id: ID!. Lists: [T] is a nullable list of nullable items; a required list of required items is [T!]!. Choose nullability deliberately — do not make everything nullable and do not make everything non-null.

1. Group mutation arguments into an Input type. When a mutation takes more than a

trivial argument, define an Input Object with the input keyword (not type) and name it with the Input suffix: input CreateBookingInput { ... }. The mutation then takes a single argument of that input type. Input fields follow the same camelCase rule.

1. Return a Payload (or Response) type from mutations. A mutation returns a

dedicated object type whose name ends in Payload or Response (CreateBookingPayload), never the bare entity type and never a naked scalar like Boolean. Mutation field names are camelCase verbs: createBooking, cancelReservation.

1. Retire fields with @deprecated, don't delete them. To phase out a field or enum

value that clients may still use, keep it in the schema and annotate it with the built-in @deprecated(reason: "...") directive; the reason string names the replacement. Never silently delete it, comment it out, or rename it in place.

Worked examples

BEFORE — snake_case fields, wrong scalars, no non-null (the base's reflexive default):

graphql
type blog_post {
  post_id: Integer
  created_at: Date
  view_count: Number
}

AFTER — PascalCase type, camelCase fields, built-in + declared scalars, non-null id:

graphql
scalar DateTime

type BlogPost {
  postId: ID!
  createdAt: DateTime!
  viewCount: Int!
}

BEFORE — enum members in the wrong case:

graphql
enum Direction {
  north
  East
  southWest
}

AFTER — SCREAMING_SNAKE_CASE members, PascalCase enum name:

graphql
enum Direction {
  NORTH
  EAST
  SOUTH_WEST
}

BEFORE — a mutation with loose arguments returning the bare entity:

graphql
type Mutation {
  addProduct(name: String, price: Double, active: Bool): Product
}

AFTER — input argument object, Int/Float/Boolean scalars, Payload result:

graphql
input AddProductInput {
  name: String!
  price: Float!
  active: Boolean!
}

type AddProductPayload {
  product: Product!
}

type Mutation {
  addProduct(input: AddProductInput!): AddProductPayload!
}

BEFORE — a retired field simply removed / commented out:

graphql
type Account {
  # username removed, use handle now
  handle: String!
}

AFTER — kept and marked with the directive so existing clients keep working:

graphql
type Account {
  username: String! @deprecated(reason: "Use `handle` instead.")
  handle: String!
}

Edge cases & exceptions

• Money and precise decimals. Do not invent Money/Decimal as a built-in; either

model as Int in the smallest currency unit (cents) or declare a custom scalar Decimal.

• Multi-word enum values. Join words with an underscore and uppercase every letter:

"awaiting refund" → AWAITING_REFUND, not AWAITINGREFUND or AwaitingRefund.

• Acronyms in type names. Keep PascalCase; prefer HttpEndpoint/ApiKey style and be

consistent — the type name is still Upper-first.

• Trivial single-scalar mutation. A one-argument mutation (e.g. delete-by-id) may take

the scalar directly (id: ID!) but still returns a Payload/Response type.

• Deprecating an enum value. The @deprecated directive works on enum values too:

LEGACY @deprecated(reason: "Use ACTIVE.").

• Interfaces and unions. type Photo implements Node { ... } (interfaces joined by

&); union SearchResult = Photo | Article — both type names PascalCase.

Do / Don't

• DO name types PascalCase and fields/arguments camelCase.
• DON'T carry snake_case field names (user_id, created_at) into the schema.
• DO write enum values in SCREAMING_SNAKE_CASE.
• DON'T use lowercase, camelCase, or PascalCase enum members.
• DO use Int, Float, Boolean, ID, String and declare anything else as scalar.
• DON'T reference Integer, Number, Double, Bool, or an undeclared Date/DateTime.
• DO mark required fields with ! and give the id ID!.
• DO group mutation arguments in an input type named ...Input and return ...Payload.
• DON'T pass loose scalar arguments and return the bare entity from a mutation.
• DO retire fields with @deprecated(reason: "...").
• DON'T delete, comment out, or silently rename a field clients may still use.

Common mistakes

• Echoing snake_case field names straight from a database schema or the prompt.
• Writing enum members as active/Active instead of ACTIVE.
• Typing whole numbers as Integer/Number and decimals as Double/Decimal.
• Treating Date/DateTime/JSON/URL as built-in scalars without a scalar declaration.
• Returning Boolean or the bare entity from a mutation instead of a Payload type.
• Passing many positional scalar arguments to a mutation instead of one Input object.
• Deleting a field during a rename instead of @deprecated-annotating the old one.

Quick checklist

• ] Type/interface/union/enum/input/scalar names are PascalCase; roots are Query/Mutation/Subscription.
• ] Fields and arguments are camelCase (no snake_case).
• ] Enum values are SCREAMING_SNAKE_CASE.
• ] Only Int/Float/String/Boolean/ID used as built-ins; everything else is a declared scalar.
• ] Required fields end in !; primary id is ID!.
• ] Mutation args grouped in an ...Input; result is a ...Payload/...Response type.
• ] Retired fields are kept and marked @deprecated(reason: "...").