Kotlin multiplatform / multi-format reflectionless serialization
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
@Serializableand standard collections. - Provides JSON, Protobuf, CBOR, Hocon and Properties formats.
- Complete multiplatform support: JVM, JS and Native.
Table of contents
- Additional links
Introduction and references
Here is a small example.
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.
Read the Kotlin Serialization Guide for all details.
You can find auto-generated documentation website on GitHub Pages.
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:
Kotlin DSL:
plugins {
kotlin("jvm") version "1.6.10" // or kotlin("multiplatform") or any other kotlin plugin
kotlin("plugin.serialization") version "1.6.10"
}
Groovy DSL:
plugins {
id 'org.jetbrains.kotlin.multiplatform' version '1.6.10'
id 'org.jetbrains.kotlin.plugin.serialization' version '1.6.10'
}
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:
Kotlin DSL:
buildscript {
repositories { mavenCentral() }
dependencies {
val kotlinVersion = "1.6.10"
classpath(kotlin("gradle-plugin", version = kotlinVersion))
classpath(kotlin("serialization", version = kotlinVersion))
}
}
Groovy DSL:
buildscript {
ext.kotlin_version = '1.6.10'
repositories { mavenCentral() }
dependencies {
classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"
}
}
Then you can apply plugin (example in Groovy):
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:
repositories {
mavenCentral()
}
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.2")
}
Groovy DSL:
repositories {
mavenCentral()
}
dependencies {
implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.2"
}
We also provide
kotlinx-serialization-coreartifact that contains all serialization API but does not have bundled serialization format with it
Android
The library works on Android, but, if you're using ProGuard, you need to add rules to your proguard-rules.pro configuration to cover all classes that are serialized at runtime.
The following configuration keeps serializers for all serializable classes that are retained after shrinking. Uncomment and modify the last section in case you're serializing classes with named companion objects.
# Keep `Companion` object fields of serializable classes.
# This avoids serializer lookup through `getDeclaredClasses` as done for named companion objects.
-if @kotlinx.serialization.Serializable class **
-keepclassmembers class <1> {
static <1>$Companion Companion;
}
# Keep `serializer()` on companion objects (both default and named) of serializable classes.
-if @kotlinx.serialization.Serializable class ** {
static **$* *;
}
-keepclassmembers class <1>$<3> {
kotlinx.serialization.KSerializer serializer(...);
}
# Keep `INSTANCE.serializer()` of serializable objects.
-if @kotlinx.serialization.Serializable class ** {
public static ** INSTANCE;
}
-keepclassmembers class <1> {
public static <1> INSTANCE;
kotlinx.serialization.KSerializer serializer(...);
}
# @Serializable and @Polymorphic are used at runtime for polymorphic serialization.
-keepattributes RuntimeVisibleAnnotations,AnnotationDefault
# Serializer for classes with named companion objects are retrieved using `getDeclaredClasses`.
# If you have any, uncomment and replace classes with those containing named companion objects.
#-keepattributes InnerClasses # Needed for `getDeclaredClasses`.
#-if @kotlinx.serialization.Serializable class
#com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions.
#com.example.myapplication.HasNamedCompanion2
#{
# static **$* *;
#}
#-keepnames class <1>$$serializer { # -keepnames suffices; class is kept when serializer() is kept.
# static <1>$$serializer INSTANCE;
#}
In case you want to exclude serializable classes that are used, but never serialized at runtime, you will need to write custom rules with narrower class specifications.
Example of custom rules
-keepattributes RuntimeVisibleAnnotations,AnnotationDefault
# 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(...);
}
# Application rules
# Change here com.yourcompany.yourpackage
-keepclassmembers @kotlinx.serialization.Serializable class com.yourcompany.yourpackage.** {
# lookup for plugin generated serializable classes
*** Companion;
# lookup for serializable objects
*** INSTANCE;
kotlinx.serialization.KSerializer serializer(...);
}
# lookup for plugin generated serializable classes
-if @kotlinx.serialization.Serializable class com.yourcompany.yourpackage.**
-keepclassmembers class com.yourcompany.yourpackage.<1>$Companion {
kotlinx.serialization.KSerializer serializer(...);
}
# Serialization supports named companions but for such classes it is necessary to add an additional rule.
# This rule keeps serializer and serializable class from obfuscation. Therefore, it is recommended not to use wildcards in it, but to write rules for each such class.
-keepattributes InnerClasses # Needed for `getDeclaredClasses`.
-keep class com.yourcompany.yourpackage.SerializableClassWithNamedCompanion$$serializer {
*** INSTANCE;
}
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:
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:
<properties>
<kotlin.version>1.6.10kotlin.version>
<serialization.version>1.3.2serialization.version>
properties>
Add serialization plugin to Kotlin compiler plugin:
<build>
<plugins>
<plugin>
<groupId>org.jetbrains.kotlingroupId>
<artifactId>kotlin-maven-pluginartifactId>
<version>${kotlin.version}version>
<executions>
<execution>
<id>compileid>
<phase>compilephase>
<goals>
<goal>compilegoal>
goals>
execution>
executions>
<configuration>
<compilerPlugins>
<plugin>kotlinx-serializationplugin>
compilerPlugins>
configuration>
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlingroupId>
<artifactId>kotlin-maven-serializationartifactId>
<version>${kotlin.version}version>
dependency>
dependencies>
plugin>
plugins>
build>
Add dependency on serialization runtime library:
<dependency>
<groupId>org.jetbrains.kotlinxgroupId>
<artifactId>kotlinx-serialization-jsonartifactId>
<version>${serialization.version}version>
dependency>
2 May 29, 2022
41 Dec 21, 2022
50 Nov 20, 2022
12 Dec 16, 2022
32 Jan 4, 2023
3 Nov 5, 2022
23 Dec 27, 2022
11 Nov 15, 2022
132 Dec 9, 2022
34 Dec 30, 2022
30 Dec 27, 2022
3 Sep 10, 2022
14 Nov 5, 2022
19 Sep 8, 2022
55 Sep 15, 2022
0 Oct 3, 2022
20 Nov 19, 2022
9 Jul 13, 2022