-1
Daily
5,954
stars
691
forks
98
watchers
1,068
prs
2,231
issues
40
releases
README
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 @Serializable and standard collections.
Provides JSON, Protobuf, CBOR, Hocon and Properties formats.
Complete multiplatform support: JVM, JS and Native.
Table of contents
Introduction and references
Setup
Gradle
1) Setting up the serialization plugin
2) Dependency on the JSON library
Android
Multiplatform (Common, JS, Native)
Maven
Bazel
Additional links
Kotlin serialization documentation
Full API reference
Submitting issues and PRs
Building this library
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(string)
println(obj) // Project(name=kotlinx.serialization, language=Kotlin)
}
You can get the full code here.
For detailed guides and examples, see the Kotlin serialization documentation.
You can find auto-generated documentation website on kotlinlang.org.
Setup
New versions of the serialization plugin are released in tandem with each new Kotlin compiler version.
Make sure you have the corresponding Kotlin plugin installed in the IDE, no additional plugins for IDE are required.
Gradle
To set up kotlinx.serialization, you have to do two things:
1) Add the serialization plugin.
2) Add the serialization library dependency.
1) Setting up the serialization plugin
You can set up the serialization plugin with the Kotlin plugin using the
Gradle plugins DSL:
Kotlin DSL:
kotlin
plugins {
kotlin("jvm") version "2.4.10" // or kotlin("multiplatform") or any other kotlin plugin
kotlin("plugin.serialization") version "2.4.10"
}
Groovy DSL:
gradle
plugins {
id 'org.jetbrains.kotlin.multiplatform' version '2.4.10'
id 'org.jetbrains.kotlin.plugin.serialization' version '2.4.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:
kotlin
buildscript {
repositories { mavenCentral() }
dependencies {
val kotlinVersion = "2.4.10"
classpath(kotlin("gradle-plugin", version = kotlinVersion))
classpath(kotlin("serialization", version = kotlinVersion))
}
}
Groovy DSL:
gradle
buildscript {Top issues
#599Can't serialize instances of class hierarchy with constructor parameters35 comments · 2019-11-07#1578Serialize & Deserialize Kotlin Delegates32 comments · 2021-07-02#1247Allow custom policy for adding the polymorphic discriminator30 comments · 2020-12-10#2848CBOR serializer encodes null class instance as empty map instead of null26 comments · 2024-11-05#993"kotlinx.serialization core version is too low" cumbersome message when previous version is present in transitive dependencies24 comments · 2020-08-19#507Global custom serializers24 comments · 2019-07-04#1573Design a general JsonElement-like thing?23 comments · 2021-06-26#1194Inconsistent behaviour with sealed classes serialization19 comments · 2020-11-11
Discussions
Latest release
v1.13.0 v1.13.0 2026-11-11This release is based on Kotlin 2.4.10 and reverts a breaking change introduced in 1.12.0. Besides that, it improves JsonElement.toString performance. Exceptions rework rollback In 1.12.0, Json format started intercepting almost all exceptions thrown by serializers during serialization and deserialization, and wrapping them into a JsonException with additional information about JSON path and input. The impact of the change was underestimated, and it was decided to revert the change. Performance improvements JsonElement.toString was rewritten and its improved twofold on some