0
# Kotlinx Serialization JSON
1

2
Kotlinx Serialization JSON is a multiplatform JSON serialization library for Kotlin providing a type-safe, reflectionless approach to JSON handling. It supports all Kotlin platforms (JVM, JS, Native, WebAssembly) with zero runtime reflection and compile-time code generation.
3

4
## Package Information
5

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

16
## Core Imports
17

18
```kotlin
19
import kotlinx.serialization.json.*
20
import kotlinx.serialization.*
21
```
22

23
## Basic Usage
24

25
```kotlin
26
import kotlinx.serialization.*
27
import kotlinx.serialization.json.*
28

29
@Serializable
30
data class User(val name: String, val age: Int)
31

32
// Create JSON instance with configuration
33
val json = Json { 
34
    prettyPrint = true
35
    ignoreUnknownKeys = true 
36
}
37

38
// Serialize to JSON string
39
val user = User("Alice", 25)
40
val jsonString = json.encodeToString(user)
41
// {"name":"Alice","age":25}
42

43
// Deserialize from JSON string
44
val userFromJson = json.decodeFromString<User>(jsonString)
45

46
// Work with JsonElement hierarchy
47
val element = json.encodeToJsonElement(user)
48
val userBack = json.decodeFromJsonElement<User>(element)
49

50
// Parse string to JsonElement
51
val jsonElement = json.parseToJsonElement("""{"name":"Bob","age":30}""")
52
```
53

54
## Architecture
55

56
Kotlinx Serialization JSON is built around several key components:
57

58
- **Json Class**: Main entry point providing serialization/deserialization methods with configurable behavior
59
- **JsonElement Hierarchy**: Abstract JSON representation with JsonObject, JsonArray, JsonPrimitive, and JsonNull
60
- **Configuration System**: Comprehensive configuration options via JsonBuilder for encoding/decoding behavior  
61
- **DSL Builders**: Fluent builders for constructing JSON objects and arrays programmatically
62
- **Custom Serializer Support**: Interfaces and base classes for implementing custom JSON serialization logic
63
- **Platform Extensions**: JVM stream support and JavaScript dynamic object integration
64

65
## Capabilities
66

67
### Core JSON Operations
68

69
Main serialization and deserialization functionality for converting between Kotlin objects and JSON strings or JsonElement representations.
70

71
```kotlin { .api }
72
sealed class Json(
73
    val configuration: JsonConfiguration,
74
    override val serializersModule: SerializersModule
75
) : StringFormat {
76
    companion object Default : Json
77
    
78
    fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String
79
    inline fun <reified T> encodeToString(value: T): String
80
    fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T
81
    inline fun <reified T> decodeFromString(string: String): T
82
    
83
    fun <T> encodeToJsonElement(serializer: SerializationStrategy<T>, value: T): JsonElement  
84
    inline fun <reified T> encodeToJsonElement(value: T): JsonElement
85
    fun <T> decodeFromJsonElement(deserializer: DeserializationStrategy<T>, element: JsonElement): T
86
    inline fun <reified T> decodeFromJsonElement(json: JsonElement): T
87
    
88
    fun parseToJsonElement(string: String): JsonElement
89
}
90

91
fun Json(from: Json = Json.Default, builderAction: JsonBuilder.() -> Unit): Json
92
```
93

94
[Core JSON Operations](./core-operations.md)
95

96
### JsonElement Hierarchy
97

98
Abstract representation of JSON data structures providing a DOM-like API for working with JSON without specific types.
99

100
```kotlin { .api }
101
sealed class JsonElement
102

103
sealed class JsonPrimitive : JsonElement() {
104
    abstract val isString: Boolean
105
    abstract val content: String
106
}
107

108
class JsonObject(private val content: Map<String, JsonElement>) : JsonElement(), Map<String, JsonElement>
109
class JsonArray(private val content: List<JsonElement>) : JsonElement(), List<JsonElement>
110
object JsonNull : JsonPrimitive()
111

112
// Factory functions
113
fun JsonPrimitive(value: Boolean?): JsonPrimitive
114
fun JsonPrimitive(value: Number?): JsonPrimitive  
115
fun JsonPrimitive(value: String?): JsonPrimitive
116
fun JsonUnquotedLiteral(value: String?): JsonPrimitive
117
```
118

119
[JsonElement Hierarchy](./json-elements.md)
120

121
### Configuration and Builder
122

123
Comprehensive configuration system for customizing JSON encoding and decoding behavior through builder pattern.
124

125
```kotlin { .api }
126
class JsonBuilder {
127
    var encodeDefaults: Boolean
128
    var ignoreUnknownKeys: Boolean
129
    var isLenient: Boolean
130
    var prettyPrint: Boolean
131
    var explicitNulls: Boolean
132
    var coerceInputValues: Boolean
133
    var allowSpecialFloatingPointValues: Boolean
134
    var allowStructuredMapKeys: Boolean
135
    var useArrayPolymorphism: Boolean
136
    var classDiscriminator: String
137
    var namingStrategy: JsonNamingStrategy?
138
    var serializersModule: SerializersModule
139
}
140

141
class JsonConfiguration(/* all configuration properties */)
142
```
143

144
[Configuration and Builder](./configuration.md)
145

146
### DSL Builders
147

148
Fluent DSL for constructing JsonObject and JsonArray instances programmatically with type-safe operations.
149

150
```kotlin { .api }
151
inline fun buildJsonObject(builderAction: JsonObjectBuilder.() -> Unit): JsonObject
152
inline fun buildJsonArray(builderAction: JsonArrayBuilder.() -> Unit): JsonArray
153

154
class JsonObjectBuilder {
155
    fun put(key: String, element: JsonElement): JsonElement?
156
    fun put(key: String, value: Boolean?): JsonElement?
157
    fun put(key: String, value: Number?): JsonElement?
158
    fun put(key: String, value: String?): JsonElement?
159
    fun putJsonObject(key: String, builderAction: JsonObjectBuilder.() -> Unit): JsonElement?
160
    fun putJsonArray(key: String, builderAction: JsonArrayBuilder.() -> Unit): JsonElement?
161
}
162

163
class JsonArrayBuilder {
164
    fun add(element: JsonElement): Boolean
165
    fun add(value: Boolean?): Boolean
166
    fun add(value: Number?): Boolean  
167
    fun add(value: String?): Boolean
168
    fun addJsonObject(builderAction: JsonObjectBuilder.() -> Unit): Boolean
169
    fun addJsonArray(builderAction: JsonArrayBuilder.() -> Unit): Boolean
170
}
171
```
172

173
[DSL Builders](./dsl-builders.md)
174

175
### Custom Serializers
176

177
Interfaces and base classes for implementing custom JSON serialization logic with access to JsonElement representations.
178

179
```kotlin { .api }
180
interface JsonEncoder : Encoder, CompositeEncoder {
181
    val json: Json
182
    fun encodeJsonElement(element: JsonElement)
183
}
184

185
interface JsonDecoder : Decoder, CompositeDecoder {
186
    val json: Json  
187
    fun decodeJsonElement(): JsonElement
188
}
189

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

197
abstract class JsonContentPolymorphicSerializer<T>(
198
    private val baseClass: KClass<T>
199
) : KSerializer<T> {
200
    protected abstract fun selectDeserializer(element: JsonElement): DeserializationStrategy<T>
201
}
202
```
203

204
[Custom Serializers](./custom-serializers.md)
205

206
### Annotations
207

208
Annotations for controlling JSON serialization behavior including alternative property names and polymorphic serialization.
209

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

214
@Target(AnnotationTarget.CLASS)  
215
annotation class JsonClassDiscriminator(val discriminator: String)
216

217
@Target(AnnotationTarget.CLASS)
218
annotation class JsonIgnoreUnknownKeys
219
```
220

221
[Annotations](./annotations.md)
222

223
### Naming Strategies
224

225
Built-in naming strategies for transforming property names during serialization/deserialization.
226

227
```kotlin { .api }
228
fun interface JsonNamingStrategy {
229
    fun serialNameForJson(descriptor: SerialDescriptor, elementIndex: Int, serialName: String): String
230
    
231
    companion object Builtins {
232
        val SnakeCase: JsonNamingStrategy
233
        val KebabCase: JsonNamingStrategy  
234
    }
235
}
236
```
237

238
[Naming Strategies](./naming-strategies.md)
239

240
### Platform Extensions
241

242
Platform-specific extensions providing additional functionality for JVM streams and JavaScript dynamic objects.
243

244
```kotlin { .api }
245
// JVM only
246
fun <T> Json.encodeToStream(serializer: SerializationStrategy<T>, value: T, stream: OutputStream)
247
fun <T> Json.decodeFromStream(deserializer: DeserializationStrategy<T>, stream: InputStream): T
248
fun <T> Json.decodeToSequence(stream: InputStream, deserializer: DeserializationStrategy<T>, format: DecodeSequenceMode): Sequence<T>
249

250
// JavaScript only  
251
fun <T> Json.decodeFromDynamic(deserializer: DeserializationStrategy<T>, dynamic: dynamic): T
252
fun <T> Json.encodeToDynamic(serializer: SerializationStrategy<T>, value: T): dynamic
253
```
254

255
[Platform Extensions](./platform-extensions.md)
256

257
## Types
258

259
```kotlin { .api }
260
enum class DecodeSequenceMode {
261
    /** Parse JSON objects/arrays separated by whitespace (newlines, spaces, tabs) */
262
    WHITESPACE_SEPARATED,
263
    /** Parse a JSON array containing objects/values as elements */
264
    ARRAY_WRAPPED,
265
    /** Automatically detect format based on first non-whitespace character */
266
    AUTO_DETECT
267
}
268

269
enum class ClassDiscriminatorMode {
270
    NONE,
271
    ALL_JSON_OBJECTS,
272
    POLYMORPHIC
273
}
274
```