or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

annotations.mdbuilt-ins.mdcore-serialization.mddescriptors.mdencoding.mdindex.mdmodules.md
tile.json

tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-core-jvm

Kotlin multiplatform serialization runtime library core module with JVM target support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.jetbrains.kotlinx/kotlinx-serialization-core-jvm@1.9.x

To install, run

npx @tessl/cli install tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-core-jvm@1.9.0

index.mddocs/

Kotlinx Serialization Core

Kotlinx Serialization Core is the foundation library for Kotlin multiplatform serialization. It provides the core runtime APIs, serialization strategies, descriptors, encoders, decoders, and built-in serializers necessary for converting Kotlin objects to and from various formats. This library enables reflectionless serialization through compiler plugin-generated code, offering type-safe serialization across JVM, JS, and Native platforms.

Package Information

  • Package Name: org.jetbrains.kotlinx:kotlinx-serialization-core-jvm
  • Package Type: maven
  • Language: Kotlin
  • Installation: implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.9.0")

Core Imports

import kotlinx.serialization.*
import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*
import kotlinx.serialization.modules.*
import kotlinx.serialization.builtins.*

Basic Usage

import kotlinx.serialization.*
import kotlinx.serialization.json.*

// Mark classes as serializable
@Serializable
data class User(
    val name: String,
    val email: String,
    val age: Int = 0
)

// Serialize to JSON
val user = User("Alice", "alice@example.com", 25)
val json = Json.encodeToString(user)
// {"name":"Alice","email":"alice@example.com","age":25}

// Deserialize from JSON
val deserializedUser = Json.decodeFromString<User>(json)

Architecture

Kotlinx Serialization Core is built around several key components:

  • Annotations: @Serializable, @SerialName, @Transient and others for controlling serialization behavior
  • Core Interfaces: KSerializer<T>, SerializationStrategy<T>, DeserializationStrategy<T> for defining serialization logic
  • Descriptors: SerialDescriptor system for describing the structure of serializable types
  • Encoding/Decoding: Encoder, Decoder and their specialized variants for format-specific implementations
  • Modules: SerializersModule for configuring custom serializers and polymorphic behavior
  • Built-in Serializers: Pre-defined serializers for primitive types, collections, and common Kotlin types

Capabilities

Annotations

Essential annotations for controlling serialization behavior, including marking classes as serializable, customizing names, and handling optional properties.

@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY)
annotation class Serializable(val with: KClass<out KSerializer<*>> = KSerializer::class)

@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY)
annotation class SerialName(val value: String)

@Target(AnnotationTarget.PROPERTY)
annotation class Transient

Annotations

Core Serialization

Main serialization interfaces and lookup functions for obtaining serializers and performing basic serialization operations.

interface KSerializer<T> : SerializationStrategy<T>, DeserializationStrategy<T> {
    override val descriptor: SerialDescriptor
}

interface SerializationStrategy<in T> {
    val descriptor: SerialDescriptor
    fun serialize(encoder: Encoder, value: T)
}

interface DeserializationStrategy<out T> {
    val descriptor: SerialDescriptor
    fun deserialize(decoder: Decoder): T
}

inline fun <reified T> serializer(): KSerializer<T>

Core Serialization

Descriptors

Type descriptor system for describing the structure and metadata of serializable types, enabling format implementations to understand data layout.

interface SerialDescriptor {
    val serialName: String
    val kind: SerialKind
    val elementsCount: Int
    fun getElementName(index: Int): String
    fun getElementIndex(name: String): Int
}

sealed class SerialKind {
    object ENUM : PrimitiveKind()
    object CONTEXTUAL : SerialKind()
    
    sealed class PrimitiveKind : SerialKind()
    sealed class StructureKind : SerialKind()
}

Descriptors

Encoding and Decoding

Core encoding and decoding interfaces that format implementations use to read and write serialized data in a structured way.

interface Encoder {
    val serializersModule: SerializersModule
    fun beginStructure(descriptor: SerialDescriptor): CompositeEncoder
    fun encodeBoolean(value: Boolean)
    fun encodeString(value: String)
    fun encodeInt(value: Int)
}

interface Decoder {
    val serializersModule: SerializersModule
    fun beginStructure(descriptor: SerialDescriptor): CompositeDecoder
    fun decodeBoolean(): Boolean  
    fun decodeString(): String
    fun decodeInt(): Int
}

Encoding and Decoding

Serialization Modules

Configuration system for custom serializers, contextual serialization, and polymorphic type handling.

class SerializersModule {
    fun <T : Any> getContextual(kClass: KClass<T>): KSerializer<T>?
    fun getPolymorphic(baseClass: KClass<Any>, value: Any): SerializationStrategy<Any>?
}

class SerializersModuleBuilder {
    fun <T : Any> contextual(kClass: KClass<T>, serializer: KSerializer<T>)
    fun <Base : Any> polymorphic(baseClass: KClass<Base>)
}

fun SerializersModule(builderAction: SerializersModuleBuilder.() -> Unit): SerializersModule

Serialization Modules

Built-in Serializers

Pre-built serializers for primitive types, collections, arrays, and other common Kotlin types.

val String.Companion.serializer: KSerializer<String>
val Int.Companion.serializer: KSerializer<Int>
val Boolean.Companion.serializer: KSerializer<Boolean>

fun <T> ListSerializer(elementSerializer: KSerializer<T>): KSerializer<List<T>>
fun <T> SetSerializer(elementSerializer: KSerializer<T>): KSerializer<Set<T>>
fun <K, V> MapSerializer(
    keySerializer: KSerializer<K>, 
    valueSerializer: KSerializer<V>
): KSerializer<Map<K, V>>

Built-in Serializers

Types

interface SerialFormat {
    val serializersModule: SerializersModule
}

interface StringFormat : SerialFormat {
    fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String
    fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T
}

interface BinaryFormat : SerialFormat {
    fun <T> encodeToByteArray(serializer: SerializationStrategy<T>, value: T): ByteArray
    fun <T> decodeFromByteArray(deserializer: DeserializationStrategy<T>, bytes: ByteArray): T
}

open class SerializationException(message: String? = null, cause: Throwable? = null) : IllegalArgumentException(message, cause)

class MissingFieldException(fieldName: String, serialName: String = fieldName) : SerializationException(
    "Field '$fieldName' is required for type with serial name '$serialName', but it was missing"
)