0
# kotlinx-serialization-json
1

2
kotlinx-serialization-json is a Kotlin multiplatform library for JSON serialization that provides type-safe JSON parsing, object serialization, and DOM-style manipulation of JSON data. It offers both high-level serialization APIs and low-level JsonElement manipulation, with extensive configuration options and platform-specific optimizations.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```kotlin
14
import kotlinx.serialization.json.*
15
import kotlinx.serialization.Serializable
16
```
17

18
For specific components:
19

20
```kotlin
21
import kotlinx.serialization.json.Json
22
import kotlinx.serialization.json.JsonElement
23
import kotlinx.serialization.json.JsonObject
24
import kotlinx.serialization.json.JsonArray
25
import kotlinx.serialization.json.JsonPrimitive
26
import kotlinx.serialization.json.buildJsonObject
27
import kotlinx.serialization.json.buildJsonArray
28
```
29

30
## Basic Usage
31

32
```kotlin
33
import kotlinx.serialization.Serializable
34
import kotlinx.serialization.json.*
35

36
@Serializable
37
data class User(val name: String, val age: Int, val email: String?)
38

39
// Serialization
40
val user = User("Alice", 30, "alice@example.com")
41
val jsonString = Json.encodeToString(user)
42
// Result: {"name":"Alice","age":30,"email":"alice@example.com"}
43

44
// Deserialization
45
val deserializedUser = Json.decodeFromString<User>(jsonString)
46

47
// JSON DOM manipulation
48
val jsonElement = Json.parseToJsonElement("""{"users": [{"name": "Bob"}]}""")
49
val userName = jsonElement.jsonObject["users"]?.jsonArray?.get(0)?.jsonObject?.get("name")?.jsonPrimitive?.content
50
```
51

52
## Architecture
53

54
kotlinx-serialization-json is built around several key components:
55

56
- **Json Class**: Main entry point providing serialization/deserialization APIs with configurable behavior
57
- **JsonElement Hierarchy**: DOM-style JSON representation (JsonObject, JsonArray, JsonPrimitive, JsonNull)
58
- **Configuration System**: Comprehensive options via JsonBuilder for customizing JSON processing behavior
59
- **DSL Builders**: Kotlin DSL for programmatically constructing JSON structures
60
- **Advanced Serialization**: Custom serializers, encoders/decoders, and transformation utilities
61
- **Platform Integration**: Platform-specific APIs for JVM streams and JavaScript dynamic objects
62

63
## Capabilities
64

65
### Core Serialization
66

67
High-level JSON serialization and deserialization with the Json class, supporting configuration, custom serializers, and type-safe operations.
68

69
```kotlin { .api }
70
object Json {
71
    fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String
72
    fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T
73
    inline fun <reified T> encodeToString(value: T): String
74
    inline fun <reified T> decodeFromString(string: String): T
75
    
76
    fun <T> encodeToJsonElement(serializer: SerializationStrategy<T>, value: T): JsonElement
77
    fun <T> decodeFromJsonElement(deserializer: DeserializationStrategy<T>, element: JsonElement): T
78
    inline fun <reified T> encodeToJsonElement(value: T): JsonElement
79
    inline fun <reified T> decodeFromJsonElement(json: JsonElement): T
80
    
81
    fun parseToJsonElement(string: String): JsonElement
82
    
83
    val Default: Json
84
}
85

86
fun Json(from: Json = Json.Default, builderAction: JsonBuilder.() -> Unit): Json
87
```
88

89
[Core Serialization](./serialization.md)
90

91
### JsonElement DOM
92

93
JSON Document Object Model for programmatic JSON manipulation, providing type-safe access to JSON structures without predefined data classes.
94

95
```kotlin { .api }
96
sealed class JsonElement
97

98
sealed class JsonPrimitive : JsonElement {
99
    val isString: Boolean
100
    val content: String
101
}
102

103
object JsonNull : JsonPrimitive
104

105
class JsonObject(content: Map<String, JsonElement>) : JsonElement, Map<String, JsonElement>
106

107
class JsonArray(content: List<JsonElement>) : JsonElement, List<JsonElement>
108

109
// Factory functions
110
fun JsonPrimitive(value: Boolean?): JsonPrimitive
111
fun JsonPrimitive(value: Number?): JsonPrimitive  
112
fun JsonPrimitive(value: String?): JsonPrimitive
113

114
// Extension properties
115
val JsonElement.jsonPrimitive: JsonPrimitive
116
val JsonElement.jsonObject: JsonObject
117
val JsonElement.jsonArray: JsonArray
118
val JsonPrimitive.int: Int
119
val JsonPrimitive.boolean: Boolean
120
val JsonPrimitive.double: Double
121
```
122

123
[JsonElement DOM](./json-element.md)
124

125
### DSL Builders
126

127
Kotlin DSL for building JSON structures programmatically with type-safe, fluent APIs.
128

129
```kotlin { .api }
130
fun buildJsonObject(builderAction: JsonObjectBuilder.() -> Unit): JsonObject
131
fun buildJsonArray(builderAction: JsonArrayBuilder.() -> Unit): JsonArray
132

133
class JsonObjectBuilder {
134
    fun put(key: String, element: JsonElement): JsonElement?
135
    fun put(key: String, value: Boolean?): JsonElement?
136
    fun put(key: String, value: Number?): JsonElement?
137
    fun put(key: String, value: String?): JsonElement?
138
    fun putJsonObject(key: String, builderAction: JsonObjectBuilder.() -> Unit): JsonElement?
139
    fun putJsonArray(key: String, builderAction: JsonArrayBuilder.() -> Unit): JsonElement?
140
}
141

142
class JsonArrayBuilder {
143
    fun add(element: JsonElement): Boolean
144
    fun add(value: Boolean?): Boolean
145
    fun add(value: Number?): Boolean
146
    fun add(value: String?): Boolean
147
    fun addJsonObject(builderAction: JsonObjectBuilder.() -> Unit): Boolean
148
    fun addJsonArray(builderAction: JsonArrayBuilder.() -> Unit): Boolean
149
}
150
```
151

152
[DSL Builders](./builders.md)
153

154
### Configuration
155

156
Comprehensive configuration options for customizing JSON serialization behavior, formatting, and parsing rules.
157

158
```kotlin { .api }
159
class JsonBuilder {
160
    var encodeDefaults: Boolean
161
    var explicitNulls: Boolean
162
    var ignoreUnknownKeys: Boolean
163
    var isLenient: Boolean
164
    var prettyPrint: Boolean
165
    var coerceInputValues: Boolean
166
    var classDiscriminator: String
167
    var allowSpecialFloatingPointValues: Boolean
168
    var allowStructuredMapKeys: Boolean
169
    var useArrayPolymorphism: Boolean
170
    var useAlternativeNames: Boolean
171
    var serializersModule: SerializersModule
172
}
173

174
class JsonConfiguration {
175
    // Immutable configuration properties
176
}
177
```
178

179
[Configuration](./configuration.md)
180

181
### Advanced Serialization
182

183
Custom serializers, transforming serializers, and advanced encoder/decoder interfaces for specialized JSON processing needs.
184

185
```kotlin { .api }
186
abstract class JsonContentPolymorphicSerializer<T>(baseClass: KClass<T>) : KSerializer<T> {
187
    abstract fun selectDeserializer(element: JsonElement): DeserializationStrategy<T>
188
}
189

190
abstract class JsonTransformingSerializer<T>(tSerializer: KSerializer<T>) : KSerializer<T> {
191
    open fun transformDeserialize(element: JsonElement): JsonElement
192
    open fun transformSerialize(element: JsonElement): JsonElement
193
}
194

195
interface JsonEncoder : Encoder, CompositeEncoder {
196
    val json: Json
197
    fun encodeJsonElement(element: JsonElement)
198
}
199

200
interface JsonDecoder : Decoder, CompositeDecoder {
201
    val json: Json
202
    fun decodeJsonElement(): JsonElement
203
}
204
```
205

206
[Advanced Serialization](./advanced.md)
207

208
### Annotations and Naming
209

210
Annotations for customizing JSON serialization behavior and naming strategies for property name transformation.
211

212
```kotlin { .api }
213
@Target(AnnotationTarget.PROPERTY)
214
annotation class JsonNames(vararg val names: String)
215

216
@Target(AnnotationTarget.CLASS)
217
annotation class JsonClassDiscriminator(val discriminator: String)
218

219
@Target(AnnotationTarget.CLASS)
220
annotation class JsonIgnoreUnknownKeys
221

222
fun interface JsonNamingStrategy {
223
    fun serialNameForJson(descriptor: SerialDescriptor, elementIndex: Int, serialName: String): String
224
    
225
    companion object {
226
        val SnakeCase: JsonNamingStrategy
227
        val KebabCase: JsonNamingStrategy
228
    }
229
}
230
```
231

232
[Annotations and Naming](./annotations.md)
233

234
### Platform-Specific APIs
235

236
Platform-specific extensions for JVM stream operations and JavaScript dynamic object interoperability.
237

238
```kotlin { .api }
239
// JVM-specific stream operations
240
fun <T> Json.encodeToStream(serializer: SerializationStrategy<T>, value: T, stream: OutputStream)
241
fun <T> Json.decodeFromStream(deserializer: DeserializationStrategy<T>, stream: InputStream): T
242

243
// JavaScript-specific dynamic object interop
244
fun <T> Json.decodeFromDynamic(deserializer: DeserializationStrategy<T>, dynamic: dynamic): T
245
fun <T> Json.encodeToDynamic(serializer: SerializationStrategy<T>, value: T): dynamic
246
```
247

248
[Platform-Specific APIs](./platform.md)
249

250
## Types
251

252
### Core Configuration Types
253

254
```kotlin { .api }
255
enum class ClassDiscriminatorMode {
256
    NONE, ALL_JSON_OBJECTS, POLYMORPHIC
257
}
258

259
enum class DecodeSequenceMode {
260
    WHITESPACE_SEPARATED, ARRAY_WRAPPED, AUTO_DETECT
261
}
262
```
263

264
### Serialization Exception Types
265

266
The library throws standard kotlinx.serialization exceptions for error conditions including SerializationException, IllegalArgumentException, and JsonDecodingException for malformed JSON.