commit	3eabe70bae2e9e08a9325f57c4cc558cbb947257	[log] [tgz]
author	Clara Fok <clarafok@google.com>	Tue Apr 23 10:28:10 2024 -0700
committer	Colin Cross <ccross@android.com>	Tue Apr 23 14:03:42 2024 -0700
tree	1e0665b0be3c1eff26b3b737cb3a17a3a3a13388
parent	45d6ad7772c2ea15a55ef6cf30561583da352e99 [diff]
parent	3efe324be422ead21ca44f2f6318e1791c166556 [diff]

tree: 1e0665b0be3c1eff26b3b737cb3a17a3a3a13388

README.md

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.

Introduction and references
Setup

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 kotlinlang.org.

Setup

New versions of the serialization plugin are released in tandem with each new Kotlin compiler version.

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

To set up kotlinx.serialization, you have to do two things:

Add the serialization plugin.
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:

plugins {
    kotlin("jvm") version "1.9.22" // or kotlin("multiplatform") or any other kotlin plugin
    kotlin("plugin.serialization") version "1.9.22"
}

Groovy DSL:

plugins {
    id 'org.jetbrains.kotlin.multiplatform' version '1.9.22'
    id 'org.jetbrains.kotlin.plugin.serialization' version '1.9.22'
}

Kotlin versions before 1.4.0 are not supported by the stable release of Kotlin serialization.

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.9.22"
        classpath(kotlin("gradle-plugin", version = kotlinVersion))
        classpath(kotlin("serialization", version = kotlinVersion))
    }
}

Groovy DSL:

buildscript {
    ext.kotlin_version = '1.9.22'
    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'

2) Dependency on the JSON library

After setting up the plugin, 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.6.3")
}

Groovy DSL:

repositories {
    mavenCentral()
}

dependencies {
    implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3"
}

We also provide kotlinx-serialization-core artifact that contains all serialization API but does not have a bundled serialization format with it

Android

By default, proguard rules are supplied with the library. These rules keep serializers for all serializable classes that are retained after shrinking, so you don't need additional setup.

However, these rules do not affect serializable classes if they have named companion objects.

If you want to serialize classes with named companion objects, you need to add and edit rules below to your proguard-rules.pro configuration.

Note that the rules for R8 differ depending on the compatibility mode used.

# Serializer for classes with named companion objects are retrieved using `getDeclaredClasses`.
# If you have any, 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;
}

# Serializer for classes with named companion objects are retrieved using `getDeclaredClasses`.
# If you have any, 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;
}

# Keep both serializer and serializable classes to save the attribute InnerClasses
-keepclasseswithmembers, allowshrinking, allowobfuscation, allowaccessmodification class
com.example.myapplication.HasNamedCompanion, # <-- List serializable classes with named companions.
com.example.myapplication.HasNamedCompanion2
{
    *;
}

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.

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.9.22</kotlin.version>
    <serialization.version>1.6.3</serialization.version>
</properties>

Add serialization plugin to Kotlin compiler plugin:

<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:

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-serialization-json</artifactId>
    <version>${serialization.version}</version>
</dependency>

Bazel

To setup the Kotlin compiler plugin for Bazel, follow the example from the rules_kotlin repository.

Kotlin multiplatform / multi-format reflectionless serialization

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