0
# Kotlinx Serialization JSON for JavaScript
1

2
Kotlinx Serialization JSON for JavaScript is the JavaScript platform implementation of Kotlin's multiplatform JSON serialization library. It provides comprehensive JSON serialization and deserialization capabilities with JavaScript-specific features for seamless interoperability with native JavaScript objects.
3

4
## Package Information
5

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

11
## Core Imports
12

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

18
For JavaScript-specific dynamic conversion:
19

20
```kotlin
21
import kotlinx.serialization.json.Json
22
// Dynamic functions are extension functions on Json
23
```
24

25
For JSON annotations and builders:
26

27
```kotlin
28
import kotlinx.serialization.json.JsonNames
29
import kotlinx.serialization.json.JsonClassDiscriminator  
30
import kotlinx.serialization.json.JsonIgnoreUnknownKeys
31
import kotlinx.serialization.json.buildJsonObject
32
import kotlinx.serialization.json.buildJsonArray
33
```
34

35
For JsonElement tree manipulation:
36

37
```kotlin
38
import kotlinx.serialization.json.JsonElement
39
import kotlinx.serialization.json.JsonObject
40
import kotlinx.serialization.json.JsonArray
41
import kotlinx.serialization.json.JsonPrimitive
42
import kotlinx.serialization.json.JsonNull
43
// Extension properties for type conversion
44
import kotlinx.serialization.json.jsonObject
45
import kotlinx.serialization.json.jsonArray
46
import kotlinx.serialization.json.jsonPrimitive
47
```
48

49
## Basic Usage
50

51
```kotlin
52
@Serializable
53
data class User(val name: String, val age: Int, val isActive: Boolean)
54

55
// Create Json instance
56
val json = Json { 
57
    ignoreUnknownKeys = true
58
    prettyPrint = true
59
}
60

61
// Serialize to JSON string
62
val user = User("Alice", 25, true)
63
val jsonString = json.encodeToString(user)
64
// {"name":"Alice","age":25,"isActive":true}
65

66
// Deserialize from JSON string  
67
val parsedUser = json.decodeFromString<User>(jsonString)
68

69
// JavaScript-specific: Convert to/from dynamic objects
70
val dynamicObject = json.encodeToDynamic(user)
71
val userFromDynamic = json.decodeFromDynamic<User>(dynamicObject)
72
```
73

74
## Architecture
75

76
Kotlinx Serialization JSON is built around several key components:
77

78
- **Json Class**: Primary entry point providing serialization/deserialization methods and configuration
79
- **JsonElement API**: Tree-based JSON representation for programmatic manipulation 
80
- **Configuration System**: Extensive customization options for encoding/decoding behavior
81
- **JavaScript Integration**: Dynamic object conversion for seamless JS interop
82
- **Custom Serializers**: Base classes for implementing custom serialization logic
83
- **Type Safety**: Full Kotlin type safety with generic type preservation
84

85
## Capabilities
86

87
### Core JSON Operations
88

89
Primary JSON serialization and deserialization functionality with comprehensive configuration options.
90

91
```kotlin { .api }
92
object Json {
93
    companion object {
94
        val Default: Json
95
    }
96
}
97

98
fun Json(builderAction: JsonBuilder.() -> Unit = {}): Json
99
fun Json(from: Json, builderAction: JsonBuilder.() -> Unit): Json
100

101
// String serialization
102
fun <T> Json.encodeToString(serializer: SerializationStrategy<T>, value: T): String
103
inline fun <reified T> Json.encodeToString(value: T): String
104
fun <T> Json.decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T  
105
inline fun <reified T> Json.decodeFromString(string: String): T
106

107
// JsonElement serialization
108
fun <T> Json.encodeToJsonElement(serializer: SerializationStrategy<T>, value: T): JsonElement
109
inline fun <reified T> Json.encodeToJsonElement(value: T): JsonElement
110
fun <T> Json.decodeFromJsonElement(deserializer: DeserializationStrategy<T>, element: JsonElement): T
111
inline fun <reified T> Json.decodeFromJsonElement(element: JsonElement): T
112
fun Json.parseToJsonElement(string: String): JsonElement
113
```
114

115
[Core JSON Operations](./core-operations.md)
116

117
### JavaScript Dynamic Conversion
118

119
JavaScript-specific functionality for converting between Kotlin objects and native JavaScript objects with full type safety.
120

121
```kotlin { .api }
122
@ExperimentalSerializationApi
123
fun <T> Json.encodeToDynamic(serializer: SerializationStrategy<T>, value: T): dynamic
124
@ExperimentalSerializationApi  
125
inline fun <reified T> Json.encodeToDynamic(value: T): dynamic
126
@ExperimentalSerializationApi
127
fun <T> Json.decodeFromDynamic(deserializer: DeserializationStrategy<T>, dynamic: dynamic): T
128
@ExperimentalSerializationApi
129
inline fun <reified T> Json.decodeFromDynamic(dynamic: dynamic): T
130
```
131

132
[JavaScript Dynamic Conversion](./dynamic-conversion.md)
133

134
### JsonElement Tree API
135

136
Programmatic JSON tree manipulation with a rich hierarchy of JsonElement types for building and accessing JSON structures.
137

138
```kotlin { .api }
139
sealed class JsonElement
140
abstract class JsonPrimitive : JsonElement {
141
    abstract val content: String
142
    val isString: Boolean
143
    val contentOrNull: String?
144
}
145
class JsonObject(val content: Map<String, JsonElement>) : JsonElement, Map<String, JsonElement>
146
class JsonArray(val content: List<JsonElement>) : JsonElement, List<JsonElement>  
147
object JsonNull : JsonPrimitive()
148

149
fun JsonPrimitive(value: Boolean?): JsonPrimitive
150
fun JsonPrimitive(value: Number?): JsonPrimitive
151
fun JsonPrimitive(value: String?): JsonPrimitive
152
```
153

154
[JsonElement Tree API](./json-element.md)
155

156
### JSON Builder DSL
157

158
Fluent DSL for constructing JSON objects and arrays with type-safe builder functions.
159

160
```kotlin { .api }
161
fun buildJsonObject(builderAction: JsonObjectBuilder.() -> Unit): JsonObject
162
fun buildJsonArray(builderAction: JsonArrayBuilder.() -> Unit): JsonArray
163

164
interface JsonObjectBuilder {
165
    fun put(key: String, value: JsonElement)
166
    fun put(key: String, value: String?)
167
    fun put(key: String, value: Number?)
168
    fun put(key: String, value: Boolean?)
169
    fun putJsonObject(key: String, builderAction: JsonObjectBuilder.() -> Unit)
170
    fun putJsonArray(key: String, builderAction: JsonArrayBuilder.() -> Unit)
171
}
172
```
173

174
[JSON Builder DSL](./builder-dsl.md)
175

176
### Configuration and Customization
177

178
Comprehensive configuration system for customizing JSON encoding/decoding behavior, naming strategies, and polymorphism handling.
179

180
```kotlin { .api }
181
class JsonBuilder {
182
    var encodeDefaults: Boolean
183
    var explicitNulls: Boolean
184
    var ignoreUnknownKeys: Boolean
185
    var coerceInputValues: Boolean
186
    var prettyPrint: Boolean
187
    var prettyPrintIndent: String
188
    var isLenient: Boolean
189
    var allowSpecialFloatingPointValues: Boolean
190
    var allowStructuredMapKeys: Boolean
191
    var allowTrailingComma: Boolean
192
    var allowComments: Boolean
193
    var useAlternativeNames: Boolean
194
    var namingStrategy: JsonNamingStrategy?
195
    var decodeEnumsCaseInsensitive: Boolean
196
    var classDiscriminator: String
197
    var classDiscriminatorMode: ClassDiscriminatorMode
198
    var useArrayPolymorphism: Boolean
199
}
200

201
interface JsonNamingStrategy {
202
    fun serialNameForJson(descriptor: SerialDescriptor, elementIndex: Int, serialName: String): String
203
    
204
    companion object {
205
        val SnakeCase: JsonNamingStrategy
206
        val KebabCase: JsonNamingStrategy
207
    }
208
}
209
```
210

211
[Configuration and Customization](./configuration.md)
212

213
### Custom Serializers
214

215
Base classes and interfaces for implementing custom JSON serialization logic with transformation and polymorphic capabilities.
216

217
```kotlin { .api }
218
abstract class JsonTransformingSerializer<T>(private val tSerializer: KSerializer<T>) : KSerializer<T> {
219
    protected open fun transformSerialize(element: JsonElement): JsonElement = element
220
    protected open fun transformDeserialize(element: JsonElement): JsonElement = element
221
}
222

223
abstract class JsonContentPolymorphicSerializer<T : Any>(private val baseClass: KClass<T>) : AbstractPolymorphicSerializer<T>() {
224
    protected abstract fun selectDeserializer(element: JsonElement): DeserializationStrategy<T>
225
}
226

227
interface JsonEncoder : Encoder, CompositeEncoder {
228
    val json: Json
229
    fun encodeJsonElement(element: JsonElement)
230
}
231

232
interface JsonDecoder : Decoder, CompositeDecoder {
233
    val json: Json  
234
    fun decodeJsonElement(): JsonElement
235
}
236
```
237

238
[Custom Serializers](./custom-serializers.md)
239

240
### JSON Annotations
241

242
JSON-specific annotations for controlling serialization behavior, providing alternative names, class discriminators, and selective ignoring of unknown properties.
243

244
```kotlin { .api }
245
/**
246
 * Allows multiple alternative names for a single property during JSON deserialization
247
 */
248
@ExperimentalSerializationApi
249
annotation class JsonNames(vararg val names: String)
250

251
/**
252
 * Specifies a custom key for class discriminator values in polymorphic serialization
253
 */
254
@ExperimentalSerializationApi  
255
annotation class JsonClassDiscriminator(val discriminator: String)
256

257
/**
258
 * Allows specific classes to ignore unknown properties during deserialization
259
 */
260
@ExperimentalSerializationApi
261
annotation class JsonIgnoreUnknownKeys
262
```
263

264
[JSON Annotations](./json-annotations.md)
265

266
## Types
267

268
```kotlin { .api }
269
enum class ClassDiscriminatorMode {
270
    NONE, POLYMORPHIC, ALL_JSON_OBJECTS
271
}
272

273
class JsonEncodingException(message: String) : SerializationException(message)
274
class JsonDecodingException(message: String) : SerializationException(message)
275
```