0
# Core Serialization API
1

2
The core serialization API provides fundamental interfaces, annotations, and utility functions that form the foundation of the kotlinx-serialization framework.
3

4
## Serialization Strategy Interfaces
5

6
### KSerializer
7

8
The main serializer interface that combines serialization and deserialization capabilities.
9

10
```kotlin { .api }
11
interface KSerializer<T> : SerializationStrategy<T>, DeserializationStrategy<T> {
12
    override val descriptor: SerialDescriptor
13
}
14
```
15

16
### SerializationStrategy
17

18
Defines the contract for encoding objects to serialized form.
19

20
```kotlin { .api }
21
interface SerializationStrategy<in T> {
22
    val descriptor: SerialDescriptor
23
    fun serialize(encoder: Encoder, value: T)
24
}
25
```
26

27
### DeserializationStrategy
28

29
Defines the contract for decoding objects from serialized form.
30

31
```kotlin { .api }
32
interface DeserializationStrategy<T> {
33
    val descriptor: SerialDescriptor
34
    fun deserialize(decoder: Decoder): T
35
}
36
```
37

38
## Format Interfaces
39

40
### SerialFormat
41

42
Base interface for all serialization formats.
43

44
```kotlin { .api }
45
interface SerialFormat {
46
    val serializersModule: SerializersModule
47
}
48
```
49

50
### StringFormat
51

52
Format that serializes to and from strings.
53

54
```kotlin { .api }
55
interface StringFormat : SerialFormat {
56
    fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String
57
    fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T
58
}
59
```
60

61
**Extension Functions:**
62
```kotlin { .api }
63
inline fun <reified T> StringFormat.encodeToString(value: T): String
64
inline fun <reified T> StringFormat.decodeFromString(string: String): T
65
```
66

67
### BinaryFormat
68

69
Format that serializes to and from byte arrays.
70

71
```kotlin { .api }
72
interface BinaryFormat : SerialFormat {
73
    fun <T> encodeToByteArray(serializer: SerializationStrategy<T>, value: T): ByteArray
74
    fun <T> decodeFromByteArray(deserializer: DeserializationStrategy<T>, bytes: ByteArray): T
75
}
76
```
77

78
**Extension Functions:**
79
```kotlin { .api }
80
inline fun <reified T> BinaryFormat.encodeToByteArray(value: T): ByteArray
81
inline fun <reified T> BinaryFormat.decodeFromByteArray(bytes: ByteArray): T
82

83
// Hex encoding utilities
84
fun <T> BinaryFormat.encodeToHexString(
85
    serializer: SerializationStrategy<T>,
86
    value: T,
87
    lowerCase: Boolean = false
88
): String
89
fun <T> BinaryFormat.decodeFromHexString(
90
    deserializer: DeserializationStrategy<T>,
91
    hex: String
92
): T
93
inline fun <reified T> BinaryFormat.encodeToHexString(
94
    value: T,
95
    lowerCase: Boolean = false
96
): String
97
inline fun <reified T> BinaryFormat.decodeFromHexString(hex: String): T
98
```
99

100
## Core Annotations
101

102
### @Serializable
103

104
Marks classes for automatic serialization code generation.
105

106
```kotlin { .api }
107
@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY)
108
annotation class Serializable(val with: KClass<out KSerializer<*>> = KSerializer::class)
109
```
110

111
**Usage:**
112
```kotlin
113
@Serializable
114
data class User(val name: String, val email: String)
115

116
// Custom serializer
117
@Serializable(with = UserSerializer::class)
118
data class CustomUser(val id: Long, val data: String)
119
```
120

121
### @SerialName
122

123
Overrides the default property or class name in serialized form.
124

125
```kotlin { .api }
126
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.CLASS)
127
annotation class SerialName(val value: String)
128
```
129

130
**Usage:**
131
```kotlin
132
@Serializable
133
@SerialName("person")
134
data class User(
135
    @SerialName("full_name")
136
    val name: String,
137
    val email: String
138
)
139
```
140

141
### @Transient
142

143
Excludes properties from serialization.
144

145
```kotlin { .api }
146
@Target(AnnotationTarget.PROPERTY)
147
annotation class Transient
148
```
149

150
**Usage:**
151
```kotlin
152
@Serializable
153
data class User(
154
    val name: String,
155
    @Transient
156
    val password: String = ""
157
)
158
```
159

160
### @Required
161

162
Marks optional properties as required in input during deserialization.
163

164
```kotlin { .api }
165
@Target(AnnotationTarget.PROPERTY)
166
annotation class Required
167
```
168

169
### @EncodeDefault
170

171
Controls when default values are encoded.
172

173
```kotlin { .api }
174
@ExperimentalSerializationApi
175
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.CLASS)
176
annotation class EncodeDefault(val mode: Mode = Mode.ALWAYS) {
177
    enum class Mode {
178
        ALWAYS,
179
        NEVER
180
    }
181
}
182
```
183

184
### Contextual and Polymorphic Annotations
185

186
```kotlin { .api }
187
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.TYPE)
188
annotation class Contextual
189

190
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.TYPE)
191
annotation class Polymorphic
192

193
@ExperimentalSerializationApi
194
@Target(AnnotationTarget.ANNOTATION_CLASS)
195
annotation class InheritableSerialInfo
196

197
@ExperimentalSerializationApi
198
@Target(AnnotationTarget.ANNOTATION_CLASS)
199
annotation class MetaSerializable
200

201
@ExperimentalSerializationApi
202
@Target(AnnotationTarget.CLASS)
203
annotation class Serializer(val forClass: KClass<*> = KClass::class)
204

205
@Target(AnnotationTarget.FILE)
206
annotation class UseContextualSerialization(vararg val forClasses: KClass<*>)
207

208
@Target(AnnotationTarget.FILE) 
209
annotation class UseSerializers(vararg val serializerClasses: KClass<out KSerializer<*>>)
210

211
@ExperimentalSerializationApi
212
@Target(AnnotationTarget.CLASS)
213
annotation class KeepGeneratedSerializer
214

215
@ExperimentalSerializationApi
216
@Target(AnnotationTarget.ANNOTATION_CLASS)
217
annotation class SerialInfo
218
```
219

220
## Utility Functions
221

222
### Serializer Resolution
223

224
```kotlin { .api }
225
// Get serializer for reified type
226
inline fun <reified T> serializer(): KSerializer<T>
227

228
// Get serializer for KType
229
fun serializer(type: KType): KSerializer<Any>
230
```
231

232
**Usage:**
233
```kotlin
234
val stringSerializer = serializer<String>()
235
val listSerializer = serializer<List<Int>>()
236
val customSerializer = serializer<MyClass>()
237
```
238

239
## Exception Classes
240

241
### SerializationException
242

243
Base exception for all serialization-related errors.
244

245
```kotlin { .api }
246
open class SerializationException(
247
    message: String, 
248
    cause: Throwable? = null
249
) : IllegalArgumentException(message, cause)
250
```
251

252
### MissingFieldException
253

254
Indicates that a required field is missing during deserialization.
255

256
```kotlin { .api }
257
@ExperimentalSerializationApi
258
class MissingFieldException(
259
    val missingFields: List<String>,
260
    message: String,
261
    cause: Throwable? = null
262
) : SerializationException(message, cause)
263
```
264

265
## Serializer Implementations
266

267
### ContextualSerializer
268

269
Delegates serialization to a contextual serializer from the `SerializersModule`.
270

271
```kotlin { .api }
272
@ExperimentalSerializationApi
273
class ContextualSerializer<T : Any>(
274
    val serializableClass: KClass<T>,
275
    val fallbackSerializer: KSerializer<T>? = null,
276
    val typeArgumentsSerializers: Array<KSerializer<*>>
277
) : KSerializer<T>
278
```
279

280
### Polymorphic Serializers
281

282
```kotlin { .api }
283
@ExperimentalSerializationApi
284
sealed class AbstractPolymorphicSerializer<T : Any> : KSerializer<T>
285

286
class PolymorphicSerializer<T : Any>(
287
    val baseClass: KClass<T>
288
) : AbstractPolymorphicSerializer<T>()
289

290
@ExperimentalSerializationApi
291
class SealedClassSerializer<T : Any>(
292
    val serialName: String,
293
    val baseClass: KClass<T>,
294
    val subclasses: Array<KClass<out T>>,
295
    val subSerializers: Array<KSerializer<out T>>
296
) : AbstractPolymorphicSerializer<T>()
297
```
298

299
## Experimental Annotations
300

301
```kotlin { .api }
302
@RequiresOptIn(level = RequiresOptIn.Level.WARNING)
303
annotation class ExperimentalSerializationApi
304

305
@RequiresOptIn(level = RequiresOptIn.Level.ERROR)  
306
annotation class InternalSerializationApi
307
```
308

309
These annotations mark APIs that are either experimental or internal and not intended for public use.