or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-io-ktor--ktor-client-serialization-jvm

Deprecated kotlinx.serialization support for Ktor HTTP client JSON plugin.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-client-serialization-jvm@3.2.x

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-client-serialization-jvm@3.2.0

index.mddocs/

Ktor Client Serialization

Ktor Client Serialization provides deprecated kotlinx.serialization support for Ktor HTTP client JSON plugin. This package offers the KotlinxSerializer class that enables automatic serialization and deserialization of Kotlin classes marked with @Serializable annotation when making HTTP requests and processing responses.

⚠️ Deprecation Notice: This package has been deprecated with ERROR level and replaced by the ContentNegotiation plugin which offers better performance and broader format support. New applications should use ContentNegotiation instead.

Package Information

  • Package Name: ktor-client-serialization-jvm
  • Package Type: maven
  • Language: Kotlin
  • Platform: JVM (with multiplatform support)
  • Installation: 
    implementation("io.ktor:ktor-client-serialization-jvm:3.2.0")

Core Imports

import io.ktor.client.plugins.kotlinx.serializer.KotlinxSerializer
import io.ktor.client.plugins.json.*
import kotlinx.serialization.json.Json

Basic Usage

import io.ktor.client.plugins.kotlinx.serializer.KotlinxSerializer
import io.ktor.client.plugins.json.*
import kotlinx.serialization.json.Json

// Create serializer with default configuration
val serializer = KotlinxSerializer()

// Create serializer with custom JSON configuration
val customJson = Json {
    isLenient = true
    ignoreUnknownKeys = true
}
val customSerializer = KotlinxSerializer(customJson)

// Use with Ktor HTTP client (deprecated pattern)
@Suppress("DEPRECATION_ERROR")
val client = HttpClient {
    install(JsonFeature) {
        serializer = KotlinxSerializer()
    }
}

Capabilities

KotlinxSerializer Class

Main serializer class implementing JsonSerializer interface for kotlinx.serialization integration.

@Deprecated(
    "Please use ContentNegotiation plugin and its converters",
    level = DeprecationLevel.ERROR
)
class KotlinxSerializer(
    private val json: Json = DefaultJson
) : JsonSerializer {
    
    /**
     * Serialize data to JSON content with specified content type
     */
    override fun write(data: Any, contentType: ContentType): OutgoingContent
    
    /**
     * Serialize data to JSON content with default JSON content type
     */
    fun write(data: Any): OutgoingContent
    
    /**
     * Deserialize JSON content to specified type using TypeInfo
     */
    override fun read(type: TypeInfo, body: Input): Any
    
    companion object {
        /**
         * Default Json configuration for KotlinxSerializer
         */
        val DefaultJson: Json
    }
}

Write Methods

Serializes Kotlin objects to JSON content for HTTP requests.

/**
 * Serialize data to JSON content with specified content type
 * @param data - Any object to serialize (must be @Serializable)
 * @param contentType - HTTP content type for the output
 * @return OutgoingContent containing serialized JSON
 */
override fun write(data: Any, contentType: ContentType): OutgoingContent

/**
 * Serialize data to JSON content with default JSON content type (Application/Json)
 * @param data - Any object to serialize (must be @Serializable)
 * @return OutgoingContent containing serialized JSON
 */
fun write(data: Any): OutgoingContent

Read Method

Deserializes JSON content from HTTP responses to Kotlin objects.

/**
 * Deserialize JSON content to specified type using TypeInfo
 * @param type - TypeInfo specifying the target type
 * @param body - Input stream containing JSON data
 * @return Deserialized object of the specified type
 */
override fun read(type: TypeInfo, body: Input): Any

Default JSON Configuration

Default Json configuration used when no custom configuration is provided.

companion object {
    /**
     * Default Json configuration for KotlinxSerializer with conservative settings:
     * - isLenient = false
     * - ignoreUnknownKeys = false  
     * - allowSpecialFloatingPointValues = true
     * - useArrayPolymorphism = false
     */
    val DefaultJson: Json
}

Types

Required Types from Dependencies

// From kotlinx.serialization
interface Json {
    val serializersModule: SerializersModule
    fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String
    fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T
}

// From Ktor
interface JsonSerializer {
    fun write(data: Any, contentType: ContentType): OutgoingContent
    fun write(data: Any): OutgoingContent  // Default implementation delegates to write(data, ContentType.Application.Json)
    fun read(type: TypeInfo, body: Input): Any
}

interface ContentType
interface OutgoingContent
interface TypeInfo
interface Input

Supported Data Types

The serializer automatically handles the following types through kotlinx.serialization:

  • Primitive types: String, Int, Long, Float, Double, Boolean
  • Collections: List, Set, Array, Map
  • @Serializable classes: Custom Kotlin classes marked with @Serializable
  • JsonElement: Direct JSON manipulation
  • Nullable types: Optional values with null support

Platform Support

This package supports multiple Kotlin platforms:

  • JVM: Primary target platform
  • JS: JavaScript/Node.js environments
  • Native: Native platforms (posix)
  • WebAssembly: wasmJs target

Platform-specific initializers automatically register the serializer with the appropriate plugin system on each platform.

Migration Path

Instead of this deprecated package, use:

// New approach with ContentNegotiation
import io.ktor.client.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*

val client = HttpClient {
    install(ContentNegotiation) {
        json()
    }
}

The ContentNegotiation plugin provides:

  • Better performance
  • More serialization formats (JSON, XML, CBOR, ProtoBuf)
  • Improved type safety
  • Better error handling
  • More flexible configuration options