A GraphQL schema is an API contract, so schema design should begin with the needs of API consumers and the domain rather than the shape of database tables.

A database model might contain:

users
user_profiles
user_addresses
user_login_metadata

That does not mean the GraphQL schema should expose those tables directly.

Instead, the API should model meaningful domain concepts:

type User {
  id: ID!
  name: String!
  profile: Profile
  addresses: [Address!]!
}

The GraphQL layer is an abstraction boundary.

Design around capabilities

Prefer operations that represent meaningful business actions:

cancelOrder(id: ID!): CancelOrderPayload!

rather than exposing implementation-oriented operations:

setOrderStatus(id: ID!, status: String!): Order!

The first expresses a business capability. The second exposes an internal state mutation that may allow invalid transitions.

Make invalid states difficult to represent

Use enums instead of arbitrary strings where values are constrained.

Use non-null types where a value is genuinely guaranteed.

Use input types for structured client data.

Use dedicated payload types when an operation has meaningful result metadata.

A well-designed schema communicates domain rules before a client ever reads the resolver implementation.

Consistent naming makes a GraphQL API much easier to learn.

Use clear names for object types:

type User
type Product
type Order

Fields generally use descriptive names:

createdAt
updatedAt
firstName

Arguments should also communicate their purpose:

user(id: ID!)
products(category: ProductCategory)

Mutation names should describe actions:

createUser
updateUser
cancelOrder
publishArticle

Avoid vague mutation names such as:

save
process
execute
handle

unless the domain itself genuinely defines such an operation.

Boolean fields should read naturally:

isActive: Boolean!
hasAccess: Boolean!
canPublish: Boolean!

Consistent naming is especially important in GraphQL because schema exploration tools expose the names directly to developers.

Nullability is one of the most consequential GraphQL schema design decisions.

Consider:

type User {
  id: ID!
  name: String!
  nickname: String
}

This says that id and name are required in a successful User value, while nickname may be null.

Do not make everything non-null simply because non-null feels safer. If a value can legitimately be absent, forcing it to be non-null can create execution failures or make future evolution harder.

At the same time, making everything nullable weakens the contract and forces clients to handle unnecessary null cases.

Ask these questions when choosing nullability:

1. Is the value guaranteed by the domain?
2. Can the value legitimately be absent?
3. Can the resolver fail to produce the value?
4. What should happen if the underlying data source is unavailable?
5. How will null propagation affect parent fields?

For lists, separately consider list nullability and element nullability.

products: [Product!]!

This is a strong contract: the list exists and contains only valid products.

Schema evolution also matters. Changing a nullable field to non-null can break clients if the server previously returned null. Therefore, nullability changes should be treated as API contract changes.

GraphQL's built-in scalars are useful but do not cover every domain value.

A custom scalar can represent a domain-specific leaf value such as:

scalar DateTime
scalar JSON
scalar URL
scalar EmailAddress

For example:

scalar DateTime

type User {
  id: ID!
  createdAt: DateTime!
}

The server implementation defines how the custom scalar serializes output and parses input.

Conceptually, a DateTime scalar may accept ISO-formatted timestamps and serialize internal date objects into a consistent wire representation.

Custom scalars are useful when the semantic type matters. However, creating a scalar for every primitive value can make a schema unnecessarily complicated.

A scalar should have clearly defined semantics. For example, if DateTime accepts multiple unrelated formats, different clients may interpret the same API inconsistently.

Custom scalar validation should be strict enough to prevent ambiguous values and should produce predictable serialization.

GraphQL APIs are expected to evolve without unnecessarily breaking existing clients.

GraphQL provides the @deprecated directive:

type User {
  username: String @deprecated(reason: "Use displayName instead")
  displayName: String!
}

Deprecation communicates that clients should migrate away from an existing field.

A typical migration strategy is:

Existing field
      ↓
Introduce replacement
      ↓
Mark old field deprecated
      ↓
Notify / monitor consumers
      ↓
Migrate clients
      ↓
Remove old field when safe

Do not remove fields simply because a new version of the application no longer uses them internally. GraphQL APIs may have external consumers that are not visible to the server team.

Schema registries, usage analytics, persisted operation tracking, and client communication can help determine whether a deprecated field is still in use.

Backward-compatible evolution is one of GraphQL's strengths, but only if teams actively manage schema lifecycle.

Large collections should not normally be returned without bounds.

A naive schema might expose:

users: [User!]!

This becomes dangerous if the database contains millions of users.

A basic pagination design could use:

users(limit: Int!, offset: Int!): [User!]!

But large-scale APIs often use cursor-based pagination because cursors can provide more stable traversal semantics when data changes during pagination.

A connection-style design can expose metadata:

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int
}

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

The client can request:

users(first: 20, after: $cursor) {
  edges {
    node {
      id
      name
    }
    cursor
  }
  pageInfo {
    hasNextPage
    endCursor
  }
}

This structure is more verbose than returning a raw list, but it provides room for pagination metadata and future evolution.

Pagination strategy should match the underlying data store and access patterns. Cursor pagination is not a magical performance solution by itself; the cursor design and database query still matter.