Core Principles

1. Design for the Client, Not the Database

Your schema should model the business domain, not your database tables. Clients think in terms of "posts by this author" and "trending products", not JOIN users ON posts.author_id = users.id.

# Bad — exposes database column names
type Post {
  author_id: Int!
  created_at: String!
  is_deleted: Boolean!
}

# Good — models the domain
type Post {
  author: User!
  createdAt: DateTime!
  # is_deleted is an implementation detail — filter it server-side
}

2. Use Enums for Constrained Values

Whenever a field has a known, finite set of values, use an enum. This gives clients compile-time safety and makes the schema self-documenting.

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

type Post {
  status: PostStatus!  # Not String!
}

3. Prefer Non-Null Where Possible

Mark fields as non-null (!) when you can guarantee a value. This reduces null-checking boilerplate in clients.

type User {
  id: ID!            # Always present
  email: String!     # Required at registration
  bio: String        # Optional — might be null
}

Exception: Fields that can fail independently (e.g., a comments field that queries a separate service) should be nullable so a failure in comments doesn't null out the entire post.

Included with GraphQL Starter Kit

Ready for the complete GraphQL Starter Kit?