shared-model-designer

Shared Model Designer

Design and implement cross-platform data models for Kotlin Multiplatform.

Core Principles

1. Serialization - Use kotlinx.serialization for all shared models
2. Immutability - Use val and data classes
3. Platform Compatibility - Ensure Swift interop works
4. Validation - Domain validation in models
5. Type Safety - Avoid platform-specific types

Model Design Checklist

✅ DO

// ✅ Immutable data class
@Serializable
data class User(
    val id: String,
    val name: String,
    val email: String,
    val avatarUrl: String?,
    val createdAt: Instant,
    val metadata: Map<String, String> = emptyMap()
)

// ✅ Sealed hierarchy for state
@Serializable
sealed class Result<out T> {
    @Serializable
    data class Success<T>(val data: T) : Result<T>()

    @Serializable
    data class Error(val message: String, val code: String? = null) : Result<Nothing>()
}

// ✅ Platform-agnostic types
@Serializable
data class Timestamp(val value: Long) {
    fun toInstant(): Instant = Instant.fromEpochMilliseconds(value)
    companion object {
        fun now(): Timestamp = Timestamp(Clock.System.now().toEpochMilliseconds())
    }
}

❌ DON'T

// ❌ Platform-specific types (won't serialize)
@Serializable
data class Event(
    val date: Date,           // ❌ Use Instant/Long
    val file: File,           // ❌ Use String path
    val uuid: UUID            // ❌ Use String, or custom serializer
)

// ❌ Mutable collections
@Serializable
data class UsersResponse(
    val users: MutableList<User>  // ❌ Use List
)

// ❌ Complex nested nulls
@Serializable
data class Complex(
    val field: Map<String, List<String?>?>  // ❌ Simplify
)

// ❌ var in data classes
@Serializable
data class User(
    var name: String  // ❌ Use val
)

iOS Interop Annotations

@ObjCName for Swift

// ✅ Add @ObjCName for clean Swift API
@ObjCName("UserModel")
@Serializable
data class User(
    @ObjCName("userId")
    val id: String,

    @ObjCName("fullName")
    val name: String,

    @ObjCName("emailAddress")
    val email: String
)

// Swift usage:
// let user = UserModel(userId: "123", fullName: "John", emailAddress: "[email protected]")