Schema Change Management

# ✅ Adding new fields
extend type User {
  phoneNumber: String
  preferences: UserPreferences
}

# ✅ Adding new types
type UserPreferences {
  theme: String
  language: String
}

# ✅ Adding new optional arguments
type Query {
  users(limit: Int, offset: Int, filter: String): [User]  # Added 'filter'
}

# ✅ Making a non-null argument nullable
type Query {
  user(id: ID): User  # Changed from ID! to ID
}

# ✅ Adding new enum values (with caution)
enum UserStatus {
  ACTIVE
  SUSPENDED
  DELETED
  PENDING  # New value
}

# ✅ Making a field nullable
type User {
  bio: String  # Changed from String! to String
}

# ✅ Adding interfaces to existing types
type User implements Node {
  id: ID!
  name: String
}

# ⚠️ Adding new enum values (compilation breaking)
# Clients with exhaustive switch statements will fail to compile
enum Status {
  ACTIVE
  INACTIVE
  NEW_STATUS  # Breaks exhaustive switches
}

# ⚠️ Adding required arguments with defaults
type Query {
  users(limit: Int = 10, required: String!): [User]  # Added required arg
}

# ❌ Removing fields
type User {
  id: ID!
  # name: String  <- REMOVED
}

# ❌ Renaming fields
type User {
  id: ID!
  fullName: String  # Was 'name'
}

# ❌ Changing field types
type User {
  id: ID!
  age: String  # Was Int
}

# ❌ Making a nullable field non-null
type User {
  email: String!  # Was String
}

# ❌ Removing enum values
enum Status {
  ACTIVE
  # INACTIVE <- REMOVED
}

# ❌ Removing types
# type OldType { ... }  <- REMOVED

# ❌ Changing argument types
type Query {
  user(id: String!): User  # Was ID!
}

# Step 1: Add new field
extend type User {
  friends: [User] @resolver
}

# Step 2: Implement resolver
@Resolver
class UserFriendsResolver : UserResolvers.Friends() {
    override suspend fun resolve(ctx: Context): List<User> {
        // Implementation
    }
}

# Step 3: Deploy
# Clients can immediately start using the new field

type User @scope(to: ["viaduct:public"]) {
  id: ID!
  
  # Step 1: Mark old field as deprecated
  name: String @deprecated(reason: "Use firstName and lastName instead")
  
  # Step 2: Add replacement fields
  firstName: String
  lastName: String
}

type Listing @scope(to: ["viaduct:public"]) {
  # Old field (deprecated)
  price: String @deprecated(reason: "Use priceV2 for proper decimal support")
  
  # New field with correct type
  priceV2: BigDecimal
}

# Legacy type
type User @scope(to: ["viaduct:public"]) {
  id: ID!
  name: String
}

# New type with breaking changes
type UserV2 @scope(to: ["viaduct:public"]) {
  id: ID!
  firstName: String!
  lastName: String!
  email: String!
}

type Query {
  user(id: ID!): User @deprecated(reason: "Use userV2")
  userV2(id: ID!): UserV2
}

# Legacy API (v1 scope)
type User @scope(to: ["api:v1"]) {
  id: ID!
  name: String
}

# New API (v2 scope)
type User @scope(to: ["api:v2"]) {
  id: ID!
  firstName: String!
  lastName: String!
}

# ✅ Adding optional fields
input CreateUserInput {
  name: String!
  email: String!
  phone: String  # New optional field
}

# ✅ Making required fields optional
input UpdateUserInput {
  name: String   # Was String!
  email: String
}

# ❌ Adding required fields
input CreateUserInput {
  name: String!
  email: String!
  requiredField: String!  # BREAKING
}

# ❌ Removing fields
input CreateUserInput {
  name: String!
  # email: String!  <- REMOVED (BREAKING)
}

# ❌ Changing field types
input CreateUserInput {
  name: String!
  age: String  # Was Int (BREAKING)
}

// In your build.gradle.kts
tasks.register("validateSchema") {
    doLast {
        // Viaduct validates schema at build time
        // - Invalid scope names
        // - Inaccessible fields
        // - Invalid type references
        // - Circular dependencies
    }
}

name: Schema Validation

on: [pull_request]

jobs:
  validate-schema:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Build and Validate Schema
        run: ./gradlew build validateSchema
      
      - name: Check for Breaking Changes
        run: |
          # Compare with main branch schema
          # Fail if breaking changes detected
          ./scripts/check-schema-compatibility.sh
      
      - name: Generate Schema Diff
        run: |
          # Generate human-readable diff
          ./scripts/generate-schema-diff.sh

@Resolver
class UserNameResolver : UserResolvers.Name() {
    override suspend fun resolve(ctx: Context): String? {
        // Log deprecated field usage
        logger.warn("Deprecated field 'name' accessed by client: ${ctx.requestContext.clientId}")
        
        // Continue serving the field
        return "${ctx.objectValue.getFirstName()} ${ctx.objectValue.getLastName()}"
    }
}

modules/
  entity/           # Base types (User, Listing)
    schema/
      User.graphqls
      Listing.graphqls
  
  data/             # Data operations (depends on entity)
    schema/
      Query.graphqls
    build.gradle.kts  # dependencies: entity
  
  mutations/        # Mutations (depends on entity, data)
    schema/
      Mutation.graphqls
    build.gradle.kts  # dependencies: entity, data

# modules/entity/schema/User.graphqls
type User @scope(to: ["viaduct"]) {
  id: ID!
  name: String
}

# modules/data/schema/Query.graphqls (depends on entity)
extend type Query @scope(to: ["viaduct"]) {
  user(id: ID!): User @resolver
}

# ❌ Module A references type from Module B
# ❌ Module B references type from Module A
# This creates a circular dependency and will fail validation

type User @scope(to: ["viaduct:public"]) {
  id: ID!
  name: String!
  email: String!
}

type User @scope(to: ["viaduct:public"]) {
  id: ID!
  name: String!
  email: String!
  
  # New fields
  avatar: String
  bio: String
}

type User @scope(to: ["viaduct:public"]) {
  id: ID!
  
  # Deprecated
  name: String! @deprecated(reason: "Use firstName and lastName")
  
  # Replacements
  firstName: String!
  lastName: String!
  
  email: String!
  avatar: String
  bio: String
}

type User @scope(to: ["viaduct:public"]) {
  id: ID!
  firstName: String!
  lastName: String!
  email: String!
  avatar: String
  bio: String
}