1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
|
# Kotlin multiplatform / multi-format reflectionless serialization
[](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
[](http://www.apache.org/licenses/LICENSE-2.0)
[](https://teamcity.jetbrains.com/viewType.html?buildTypeId=KotlinTools_KotlinxSerialization_Ko&guest=1)
[](https://search.maven.org/artifact/org.jetbrains.kotlinx/kotlinx-serialization-core/1.1.0/pom)
Kotlin serialization consists of a compiler plugin, that generates visitor code for serializable classes,
runtime library with core serialization API and support libraries with various serialization formats.
* Supports Kotlin classes marked as `@Serializable` and standard collections.
* Provides [JSON](formats/README.md#JSON), [Protobuf](formats/README.md#ProtoBuf), [CBOR](formats/README.md#CBOR), [Hocon](formats/README.md#HOCON) and [Properties](formats/README.md#properties) formats.
* Complete multiplatform support: JVM, JS and Native.
## Table of contents
<!--- TOC -->
* [Introduction and references](#introduction-and-references)
* [Setup](#setup)
* [Gradle](#gradle)
* [Using the `plugins` block](#using-the-plugins-block)
* [Using `apply plugin` (the old way)](#using-apply-plugin-the-old-way)
* [Dependency on the JSON library](#dependency-on-the-json-library)
* [Android](#android)
* [Multiplatform (Common, JS, Native)](#multiplatform-common-js-native)
* [Maven](#maven)
<!--- END -->
## Introduction and references
Here is a small example.
```kotlin
import kotlinx.serialization.*
import kotlinx.serialization.json.*
@Serializable
data class Project(val name: String, val language: String)
fun main() {
// Serializing objects
val data = Project("kotlinx.serialization", "Kotlin")
val string = Json.encodeToString(data)
println(string) // {"name":"kotlinx.serialization","language":"Kotlin"}
// Deserializing back into objects
val obj = Json.decodeFromString<Project>(string)
println(obj) // Project(name=kotlinx.serialization, language=Kotlin)
}
```
> You can get the full code [here](guide/example/example-readme-01.kt).
<!--- TEST_NAME ReadmeTest -->
<!--- TEST
{"name":"kotlinx.serialization","language":"Kotlin"}
Project(name=kotlinx.serialization, language=Kotlin)
-->
**Read the [Kotlin Serialization Guide](docs/serialization-guide.md) for all details.**
You can find auto-generated documentation website on [GitHub Pages](https://kotlin.github.io/kotlinx.serialization/).
## Setup
Kotlin serialization plugin is shipped with the Kotlin compiler distribution, and the IDEA plugin is bundled into the Kotlin plugin.
Using Kotlin Serialization requires Kotlin compiler `1.4.0` or higher.
Make sure you have the corresponding Kotlin plugin installed in the IDE, no additional plugins for IDE are required.
### Gradle
#### Using the `plugins` block
You can set up the serialization plugin with the Kotlin plugin using
[Gradle plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block):
Kotlin DSL:
```kotlin
plugins {
kotlin("jvm") version "1.4.30" // or kotlin("multiplatform") or any other kotlin plugin
kotlin("plugin.serialization") version "1.4.30"
}
```
Groovy DSL:
```gradle
plugins {
id 'org.jetbrains.kotlin.multiplatform' version '1.4.30'
id 'org.jetbrains.kotlin.plugin.serialization' version '1.4.30'
}
```
> Kotlin versions before 1.4.0 are not supported by the stable release of Kotlin serialization
#### Using `apply plugin` (the old way)
First, you have to add the serialization plugin to your classpath as the other [compiler plugins](https://kotlinlang.org/docs/reference/compiler-plugins.html):
Kotlin DSL:
```kotlin
buildscript {
repositories { mavenCentral() }
dependencies {
val kotlinVersion = "1.4.30"
classpath(kotlin("gradle-plugin", version = kotlinVersion))
classpath(kotlin("serialization", version = kotlinVersion))
}
}
```
Groovy DSL:
```gradle
buildscript {
ext.kotlin_version = '1.4.30'
repositories { mavenCentral() }
dependencies {
classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"
}
}
```
Then you can `apply plugin` (example in Groovy):
```gradle
apply plugin: 'kotlin' // or 'kotlin-multiplatform' for multiplatform projects
apply plugin: 'kotlinx-serialization'
```
#### Dependency on the JSON library
After setting up the plugin one way or another, you have to add a dependency on the serialization library.
Note that while the plugin has version the same as the compiler one, runtime library has different coordinates, repository and versioning.
Kotlin DSL:
```kotlin
repositories {
mavenCentral()
}
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.1.0")
}
```
Groovy DSL:
```gradle
repositories {
mavenCentral()
}
dependencies {
implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.1.0"
}
```
>We also provide `kotlinx-serialization-core` artifact that contains all serialization API but does not have bundled serialization format with it
### Android
Library should work on Android "as is". If you're using proguard, you need
to add this to your `proguard-rules.pro`:
```proguard
-keepattributes *Annotation*, InnerClasses
-dontnote kotlinx.serialization.AnnotationsKt # core serialization annotations
# kotlinx-serialization-json specific. Add this if you have java.lang.NoClassDefFoundError kotlinx.serialization.json.JsonObjectSerializer
-keepclassmembers class kotlinx.serialization.json.** {
*** Companion;
}
-keepclasseswithmembers class kotlinx.serialization.json.** {
kotlinx.serialization.KSerializer serializer(...);
}
# Change here com.yourcompany.yourpackage
-keep,includedescriptorclasses class com.yourcompany.yourpackage.**$$serializer { *; } # <-- change package name to your app's
-keepclassmembers class com.yourcompany.yourpackage.** { # <-- change package name to your app's
*** Companion;
}
-keepclasseswithmembers class com.yourcompany.yourpackage.** { # <-- change package name to your app's
kotlinx.serialization.KSerializer serializer(...);
}
```
You may also want to keep all custom serializers you've defined.
### Multiplatform (Common, JS, Native)
Most of the modules are also available for Kotlin/JS and Kotlin/Native.
You can add dependency to the required module right to the common source set:
```gradle
commonMain {
dependencies {
// Works as common dependency as well as the platform one
implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:$serialization_version"
}
}
```
The same artifact coordinates can be used to depend on platform-specific artifact in platform-specific source-set.
### Maven
Ensure the proper version of Kotlin and serialization version:
```xml
<properties>
<kotlin.version>1.4.30</kotlin.version>
<serialization.version>1.1.0</serialization.version>
</properties>
```
Add serialization plugin to Kotlin compiler plugin:
```xml
<build>
<plugins>
<plugin>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-plugin</artifactId>
<version>${kotlin.version}</version>
<executions>
<execution>
<id>compile</id>
<phase>compile</phase>
<goals>
<goal>compile</goal>
</goals>
</execution>
</executions>
<configuration>
<compilerPlugins>
<plugin>kotlinx-serialization</plugin>
</compilerPlugins>
</configuration>
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-serialization</artifactId>
<version>${kotlin.version}</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
```
Add dependency on serialization runtime library:
```xml
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>kotlinx-serialization-json</artifactId>
<version>${serialization.version}</version>
</dependency>
```
|
