Types

# Start with what clients need
type Query {
  # Get a user's profile with recent activity
  userProfile(id: ID!): UserProfile

  # Search for content across the platform
  search(query: String!, type: SearchType): SearchResults!
}

# Good: Focused types
type User {
  id: ID!
  email: String!
  profile: UserProfile!
}

type UserProfile {
  displayName: String!
  bio: String
  avatarUrl: String
}

# Avoid: Overloaded type
type User {
  id: ID!
  email: String!
  displayName: String!
  bio: String
  avatarUrl: String
  # ... mixing identity and profile concerns
}

type Address {
  street: String!
  city: String!
  state: String!
  postalCode: String!
  country: String!
}

type Order {
  id: ID!
  shippingAddress: Address!
  billingAddress: Address!
}

type Product {
  id: ID!
  name: String!
  priceInCents: Int!        # Stored
  formattedPrice: String!   # Computed
  inStock: Boolean!         # Computed from inventory
}

type User {
  id: ID!           # Always exists
  email: String!    # Required field
  name: String      # Optional - user might not set
  deletedAt: DateTime  # Null means not deleted
}

type User {
  # Correct: non-null list, non-null items
  posts: [Post!]!

  # Return empty list, not null
  # Never return [null, post, null]
}

type User {
  id: ID!
  email: String!

  # Might fail if recommendation service is down
  # Better to return null than fail entire query
  recommendedPosts: [Post!]
}

interface Node {
  "Globally unique identifier"
  id: ID!
}

type User implements Node {
  id: ID!  # e.g., "User:123" or base64("User:123")
}

# Format: base64(TypeName:databaseId)
User:123 → VXNlcjoxMjM=
Post:456 → UG9zdDo0NTY=

type User implements Node {
  id: ID!           # Global ID: "VXNlcjoxMjM="
  databaseId: Int!  # Original: 123
}

interface Timestamped {
  createdAt: DateTime!
  updatedAt: DateTime!
}

type User implements Timestamped {
  id: ID!
  email: String!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Post implements Timestamped {
  id: ID!
  title: String!
  createdAt: DateTime!
  updatedAt: DateTime!
}

interface Node {
  id: ID!
}

type Query {
  node(id: ID!): Node
  nodes(ids: [ID!]!): [Node]!
}

interface Node {
  id: ID!
}

interface Timestamped {
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Comment implements Node & Timestamped {
  id: ID!
  body: String!
  createdAt: DateTime!
  updatedAt: DateTime!
}

union SearchResult = User | Post | Comment

type Query {
  search(query: String!): [SearchResult!]!
}

type CreateUserSuccess {
  user: User!
}

type ValidationError {
  field: String!
  message: String!
}

type EmailAlreadyExists {
  existingUserId: ID!
}

union CreateUserResult = CreateUserSuccess | ValidationError | EmailAlreadyExists

type Mutation {
  createUser(input: CreateUserInput!): CreateUserResult!
}

input CreatePostInput {
  title: String!
  body: String!
  tags: [String!]
  publishAt: DateTime
}

input UpdatePostInput {
  title: String
  body: String
  tags: [String!]
}

type Mutation {
  createPost(input: CreatePostInput!): Post!
  updatePost(id: ID!, input: UpdatePostInput!): Post!
}

input UpdateUserInput {
  name: String       # Pass to change, omit to keep
  email: String      # Pass to change, omit to keep
  bio: String        # Pass to change, omit to keep
}

input AddressInput {
  street: String!
  city: String!
  state: String!
  postalCode: String!
  country: String!
}

input CreateOrderInput {
  items: [OrderItemInput!]!
  shippingAddress: AddressInput!
  billingAddress: AddressInput
}

enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

enum SortDirection {
  ASC
  DESC
}

enum Role {
  "Regular user with limited permissions"
  USER

  "Moderator with content management permissions"
  MODERATOR

  "Administrator with full system access"
  ADMIN
}

scalar DateTime    # ISO 8601 date-time
scalar Date        # ISO 8601 date
scalar Time        # ISO 8601 time
scalar URL         # Valid URL string
scalar Email       # Valid email address
scalar JSON        # Arbitrary JSON (use sparingly)
scalar UUID        # UUID string
scalar BigInt      # Large integers beyond Int range

type User {
  email: Email!       # Validated email format
  website: URL        # Validated URL format
  createdAt: DateTime!  # Consistent date format
}

# Avoid: Loses type safety
type Config {
  settings: JSON!
}

# Better: Define the structure
type Config {
  theme: Theme!
  notifications: NotificationSettings!
  privacy: PrivacySettings!
}