0
# kotlinx-serialization-core
1

2
Kotlin multiplatform reflectionless serialization library providing format-agnostic serialization for classes marked with `@Serializable`. The core module contains fundamental serialization infrastructure supporting multiple target platforms including JVM, JavaScript, and Native targets.
3

4
**Note**: Some APIs are marked with `@ExperimentalSerializationApi` and may change in future versions. Stable APIs form the foundation for production use, while experimental APIs provide access to advanced features.
5

6
## Package Information
7

8
- **Package Name**: kotlinx-serialization-core
9
- **Package Type**: maven
10
- **Language**: Kotlin
11
- **Installation**: 
12
  ```kotlin
13
  dependencies {
14
      implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.9.0")
15
  }
16
  ```
17

18
## Core Imports
19

20
```kotlin
21
import kotlinx.serialization.*
22
import kotlinx.serialization.descriptors.*
23
import kotlinx.serialization.encoding.*
24
import kotlinx.serialization.modules.*
25
import kotlinx.serialization.builtins.*
26
```
27

28
## Basic Usage
29

30
```kotlin
31
import kotlinx.serialization.*
32
import kotlinx.serialization.json.*
33

34
@Serializable
35
data class User(val name: String, val email: String)
36

37
fun main() {
38
    val user = User("John Doe", "john@example.com")
39
    
40
    // Serialization to JSON (requires kotlinx-serialization-json)
41
    val json = Json.encodeToString(user)
42
    println(json) // {"name":"John Doe","email":"john@example.com"}
43
    
44
    // Deserialization from JSON
45
    val deserializedUser = Json.decodeFromString<User>(json)
46
    println(deserializedUser) // User(name=John Doe, email=john@example.com)
47
}
48
```
49

50
## Architecture
51

52
The library uses a plugin-based architecture:
53
- **Compiler Plugin**: Generates serialization code for `@Serializable` classes at compile time
54
- **Runtime Library**: Provides serialization infrastructure, format interfaces, and built-in serializers
55
- **Format Abstraction**: Supports any serialization format through `Encoder`/`Decoder` interfaces
56
- **Modular Design**: Core API is format-agnostic, with separate format-specific libraries (JSON, ProtoBuf, etc.)
57
- **Multiplatform Support**: Works across JVM, JavaScript, and Native platforms
58

59
## Capabilities
60

61
### Core Serialization API
62

63
Fundamental serialization interfaces and annotations for marking classes and controlling serialization behavior.
64

65
```kotlin { .api }
66
// Main serializer interface
67
interface KSerializer<T> : SerializationStrategy<T>, DeserializationStrategy<T> {
68
    override val descriptor: SerialDescriptor
69
}
70

71
// Core annotations
72
@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY)
73
annotation class Serializable(val with: KClass<out KSerializer<*>> = KSerializer::class)
74

75
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.CLASS)
76
annotation class SerialName(val value: String)
77
```
78

79
[Core Serialization API](./core-api.md)
80

81
### Descriptors System
82

83
Type descriptor system providing structural metadata and introspection capabilities for serializable types.
84

85
```kotlin { .api }
86
interface SerialDescriptor {
87
    val serialName: String
88
    val kind: SerialKind
89
    val elementsCount: Int
90
    fun getElementName(index: Int): String
91
    fun getElementDescriptor(index: Int): SerialDescriptor
92
}
93

94
fun buildClassSerialDescriptor(
95
    serialName: String,
96
    vararg typeParameters: SerialDescriptor,
97
    builderAction: ClassSerialDescriptorBuilder.() -> Unit = {}
98
): SerialDescriptor
99
```
100

101
[Descriptors System](./descriptors.md)
102

103
### Encoding System
104

105
Format-agnostic encoding and decoding interfaces that form the foundation for all serialization formats.
106

107
```kotlin { .api }
108
interface Encoder {
109
    val serializersModule: SerializersModule
110
    fun encodeBoolean(value: Boolean)
111
    fun encodeString(value: String)
112
    fun beginStructure(descriptor: SerialDescriptor): CompositeEncoder
113
}
114

115
interface Decoder {
116
    val serializersModule: SerializersModule
117
    fun decodeBoolean(): Boolean
118
    fun decodeString(): String
119
    fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder
120
}
121
```
122

123
[Encoding System](./encoding.md)
124

125
### Serializers Module
126

127
Runtime system for contextual and polymorphic serializer resolution, enabling flexible serialization strategies.
128

129
```kotlin { .api }
130
class SerializersModule {
131
    fun getContextual(kClass: KClass<*>): KSerializer<*>?
132
    fun getPolymorphic(baseClass: KClass<out Any>, value: Any): SerializationStrategy<Any>?
133
}
134

135
fun SerializersModule(builderAction: SerializersModuleBuilder.() -> Unit): SerializersModule
136
```
137

138
[Serializers Module](./modules.md)
139

140
### Built-in Serializers
141

142
Comprehensive collection of serializers for Kotlin standard library types including primitives, collections, and special types.
143

144
```kotlin { .api }
145
// Primitive serializers
146
fun Boolean.Companion.serializer(): KSerializer<Boolean>
147
fun String.Companion.serializer(): KSerializer<String>
148

149
// Collection serializers
150
fun <T> ListSerializer(elementSerializer: KSerializer<T>): KSerializer<List<T>>
151
fun <K, V> MapSerializer(
152
    keySerializer: KSerializer<K>, 
153
    valueSerializer: KSerializer<V>
154
): KSerializer<Map<K, V>>
155
```
156

157
[Built-in Serializers](./builtins.md)
158

159
## Common Types
160

161
```kotlin { .api }
162
// Core serialization exception
163
open class SerializationException(message: String, cause: Throwable? = null) : IllegalArgumentException(message, cause)
164

165
// Missing field exception for required properties
166
class MissingFieldException(
167
    val missingFields: List<String>,
168
    message: String,
169
    cause: Throwable? = null
170
) : SerializationException(message, cause)
171

172
// Serial kinds for descriptor system
173
sealed class SerialKind {
174
    object ENUM : SerialKind()
175
    object CONTEXTUAL : SerialKind()
176
}
177

178
sealed class PrimitiveKind : SerialKind() {
179
    object BOOLEAN : PrimitiveKind()
180
    object STRING : PrimitiveKind()
181
    object INT : PrimitiveKind()
182
    // ... other primitive kinds
183
}
184

185
sealed class StructureKind : SerialKind() {
186
    object CLASS : StructureKind()
187
    object LIST : StructureKind()
188
    object MAP : StructureKind()
189
    object OBJECT : StructureKind()
190
}
191
```