CtrlK
BlogDocsLog inGet started
Tessl Logo

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

Kotlin multiplatform serialization runtime library core module with JVM target support

—

Pending
Overview
Eval results
Files

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"
)

Install with Tessl CLI

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