0
# Kotlinx Serialization Core
1

2
Kotlinx Serialization Core is the foundation library for Kotlin multiplatform serialization. It provides the core runtime APIs, serialization strategies, descriptors, encoders, decoders, and built-in serializers necessary for converting Kotlin objects to and from various formats. This library enables reflectionless serialization through compiler plugin-generated code, offering type-safe serialization across JVM, JS, and Native platforms.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.kotlinx:kotlinx-serialization-core-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: `implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.9.0")`
10

11
## Core Imports
12

13
```kotlin
14
import kotlinx.serialization.*
15
import kotlinx.serialization.descriptors.*
16
import kotlinx.serialization.encoding.*
17
import kotlinx.serialization.modules.*
18
import kotlinx.serialization.builtins.*
19
```
20

21
## Basic Usage
22

23
```kotlin
24
import kotlinx.serialization.*
25
import kotlinx.serialization.json.*
26

27
// Mark classes as serializable
28
@Serializable
29
data class User(
30
    val name: String,
31
    val email: String,
32
    val age: Int = 0
33
)
34

35
// Serialize to JSON
36
val user = User("Alice", "alice@example.com", 25)
37
val json = Json.encodeToString(user)
38
// {"name":"Alice","email":"alice@example.com","age":25}
39

40
// Deserialize from JSON
41
val deserializedUser = Json.decodeFromString<User>(json)
42
```
43

44
## Architecture
45

46
Kotlinx Serialization Core is built around several key components:
47

48
- **Annotations**: `@Serializable`, `@SerialName`, `@Transient` and others for controlling serialization behavior
49
- **Core Interfaces**: `KSerializer<T>`, `SerializationStrategy<T>`, `DeserializationStrategy<T>` for defining serialization logic
50
- **Descriptors**: `SerialDescriptor` system for describing the structure of serializable types
51
- **Encoding/Decoding**: `Encoder`, `Decoder` and their specialized variants for format-specific implementations
52
- **Modules**: `SerializersModule` for configuring custom serializers and polymorphic behavior
53
- **Built-in Serializers**: Pre-defined serializers for primitive types, collections, and common Kotlin types
54

55
## Capabilities
56

57
### Annotations
58

59
Essential annotations for controlling serialization behavior, including marking classes as serializable, customizing names, and handling optional properties.
60

61
```kotlin { .api }
62
@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY)
63
annotation class Serializable(val with: KClass<out KSerializer<*>> = KSerializer::class)
64

65
@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY)
66
annotation class SerialName(val value: String)
67

68
@Target(AnnotationTarget.PROPERTY)
69
annotation class Transient
70
```
71

72
[Annotations](./annotations.md)
73

74
### Core Serialization
75

76
Main serialization interfaces and lookup functions for obtaining serializers and performing basic serialization operations.
77

78
```kotlin { .api }
79
interface KSerializer<T> : SerializationStrategy<T>, DeserializationStrategy<T> {
80
    override val descriptor: SerialDescriptor
81
}
82

83
interface SerializationStrategy<in T> {
84
    val descriptor: SerialDescriptor
85
    fun serialize(encoder: Encoder, value: T)
86
}
87

88
interface DeserializationStrategy<out T> {
89
    val descriptor: SerialDescriptor
90
    fun deserialize(decoder: Decoder): T
91
}
92

93
inline fun <reified T> serializer(): KSerializer<T>
94
```
95

96
[Core Serialization](./core-serialization.md)
97

98
### Descriptors
99

100
Type descriptor system for describing the structure and metadata of serializable types, enabling format implementations to understand data layout.
101

102
```kotlin { .api }
103
interface SerialDescriptor {
104
    val serialName: String
105
    val kind: SerialKind
106
    val elementsCount: Int
107
    fun getElementName(index: Int): String
108
    fun getElementIndex(name: String): Int
109
}
110

111
sealed class SerialKind {
112
    object ENUM : PrimitiveKind()
113
    object CONTEXTUAL : SerialKind()
114
    
115
    sealed class PrimitiveKind : SerialKind()
116
    sealed class StructureKind : SerialKind()
117
}
118
```
119

120
[Descriptors](./descriptors.md)
121

122
### Encoding and Decoding
123

124
Core encoding and decoding interfaces that format implementations use to read and write serialized data in a structured way.
125

126
```kotlin { .api }
127
interface Encoder {
128
    val serializersModule: SerializersModule
129
    fun beginStructure(descriptor: SerialDescriptor): CompositeEncoder
130
    fun encodeBoolean(value: Boolean)
131
    fun encodeString(value: String)
132
    fun encodeInt(value: Int)
133
}
134

135
interface Decoder {
136
    val serializersModule: SerializersModule
137
    fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder
138
    fun decodeBoolean(): Boolean  
139
    fun decodeString(): String
140
    fun decodeInt(): Int
141
}
142
```
143

144
[Encoding and Decoding](./encoding.md)
145

146
### Serialization Modules
147

148
Configuration system for custom serializers, contextual serialization, and polymorphic type handling.
149

150
```kotlin { .api }
151
class SerializersModule {
152
    fun <T : Any> getContextual(kClass: KClass<T>): KSerializer<T>?
153
    fun getPolymorphic(baseClass: KClass<Any>, value: Any): SerializationStrategy<Any>?
154
}
155

156
class SerializersModuleBuilder {
157
    fun <T : Any> contextual(kClass: KClass<T>, serializer: KSerializer<T>)
158
    fun <Base : Any> polymorphic(baseClass: KClass<Base>)
159
}
160

161
fun SerializersModule(builderAction: SerializersModuleBuilder.() -> Unit): SerializersModule
162
```
163

164
[Serialization Modules](./modules.md)
165

166
### Built-in Serializers
167

168
Pre-built serializers for primitive types, collections, arrays, and other common Kotlin types.
169

170
```kotlin { .api }
171
val String.Companion.serializer: KSerializer<String>
172
val Int.Companion.serializer: KSerializer<Int>
173
val Boolean.Companion.serializer: KSerializer<Boolean>
174

175
fun <T> ListSerializer(elementSerializer: KSerializer<T>): KSerializer<List<T>>
176
fun <T> SetSerializer(elementSerializer: KSerializer<T>): KSerializer<Set<T>>
177
fun <K, V> MapSerializer(
178
    keySerializer: KSerializer<K>, 
179
    valueSerializer: KSerializer<V>
180
): KSerializer<Map<K, V>>
181
```
182

183
[Built-in Serializers](./built-ins.md)
184

185
## Types
186

187
```kotlin { .api }
188
interface SerialFormat {
189
    val serializersModule: SerializersModule
190
}
191

192
interface StringFormat : SerialFormat {
193
    fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String
194
    fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T
195
}
196

197
interface BinaryFormat : SerialFormat {
198
    fun <T> encodeToByteArray(serializer: SerializationStrategy<T>, value: T): ByteArray
199
    fun <T> decodeFromByteArray(deserializer: DeserializationStrategy<T>, bytes: ByteArray): T
200
}
201

202
open class SerializationException(message: String? = null, cause: Throwable? = null) : IllegalArgumentException(message, cause)
203

204
class MissingFieldException(fieldName: String, serialName: String = fieldName) : SerializationException(
205
    "Field '$fieldName' is required for type with serial name '$serialName', but it was missing"
206
)
207
```