or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-io-ktor--ktor-serialization-kotlinx-json

Ktor JSON Content Negotiation via kotlinx.serialization support

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

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-serialization-kotlinx-json@3.2.0

index.mddocs/

Ktor JSON Serialization

Ktor JSON Content Negotiation via kotlinx.serialization support. This library provides JSON serialization and deserialization capabilities for Ktor applications using kotlinx.serialization, enabling automatic conversion between Kotlin objects and JSON format through the Content Negotiation plugin.

Package Information

  • Package Name: ktor-serialization-kotlinx-json
  • Package Type: maven
  • Group ID: io.ktor
  • Language: Kotlin
  • Installation: implementation("io.ktor:ktor-serialization-kotlinx-json:3.2.0")

Core Imports

import io.ktor.serialization.kotlinx.json.*

For kotlinx.serialization JSON configuration:

import kotlinx.serialization.json.Json

For Content Negotiation setup:

import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.server.plugins.contentnegotiation.*

For exception handling:

import io.ktor.serialization.JsonConvertException
import io.ktor.serialization.ContentConvertException

For extension provider:

import io.ktor.serialization.kotlinx.KotlinxSerializationExtensionProvider

For experimental converter:

import kotlinx.serialization.ExperimentalSerializationApi

Basic Usage

Server Configuration

import io.ktor.serialization.kotlinx.json.*
import io.ktor.server.application.*
import io.ktor.server.plugins.contentnegotiation.*

fun Application.configureSerialization() {
    install(ContentNegotiation) {
        json() // Uses DefaultJson configuration
    }
}

Client Configuration

import io.ktor.client.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*

val client = HttpClient {
    install(ContentNegotiation) {
        json() // Uses DefaultJson configuration
    }
}

Custom JSON Configuration

import kotlinx.serialization.json.Json

install(ContentNegotiation) {
    json(Json {
        prettyPrint = true
        isLenient = true
        ignoreUnknownKeys = true
        encodeDefaults = false
    })
}

Capabilities

Standard JSON Serialization

Registers JSON content type with Content Negotiation plugin using kotlinx.serialization.

fun Configuration.json(
    json: Json = DefaultJson,
    contentType: ContentType = ContentType.Application.Json
)

Parameters:

  • json: JSON format instance with configuration settings (optional, defaults to DefaultJson)
  • contentType: Content type to register with the converter (optional, defaults to application/json)

Experimental Streaming JSON Serialization

Registers JSON content type using experimental streaming JSON support for improved performance with large data.

@ExperimentalSerializationApi
fun Configuration.jsonIo(
    json: Json = DefaultJson,
    contentType: ContentType = ContentType.Application.Json
)

Parameters:

  • json: JSON format instance (optional, defaults to DefaultJson)
  • contentType: Content type to register (optional, defaults to application/json)

Note: This uses experimental kotlinx-io streaming for better memory efficiency with large JSON data.

Flow and Sequence Support

Special handling for streaming collections using JSON arrays.

class KotlinxSerializationJsonExtensionProvider : KotlinxSerializationExtensionProvider {
    override fun extension(format: SerialFormat): KotlinxSerializationExtension?
}

Features:

  • Automatically serializes Flow<T> as JSON arrays with streaming
  • Deserializes JSON arrays to Sequence<T> (JVM only)
  • UTF-8 charset requirement for streaming operations

Experimental JSON Converter

Direct converter class for advanced use cases requiring custom content negotiation handling.

@ExperimentalSerializationApi
class ExperimentalJsonConverter(private val format: Json) : ContentConverter {
    override suspend fun serialize(
        contentType: ContentType,
        charset: Charset,
        typeInfo: TypeInfo,
        value: Any?
    ): OutgoingContent
    
    override suspend fun deserialize(
        charset: Charset,
        typeInfo: TypeInfo,
        content: ByteReadChannel
    ): Any?
}

Usage Example:

val converter = ExperimentalJsonConverter(Json {
    prettyPrint = true
})
install(ContentNegotiation) {
    register(ContentType.Application.Json, converter)
}

Internal JSON Extensions

Internal implementation class that provides the actual Flow/Sequence serialization functionality.

internal class KotlinxSerializationJsonExtensions(private val format: Json) : KotlinxSerializationExtension {
    override suspend fun serialize(
        contentType: ContentType,
        charset: Charset,
        typeInfo: TypeInfo,
        value: Any?
    ): OutgoingContent?
    
    override suspend fun deserialize(
        charset: Charset,
        typeInfo: TypeInfo,
        content: ByteReadChannel
    ): Any?
}

Note: This is an internal implementation class created by KotlinxSerializationJsonExtensionProvider and should not be used directly.

Configuration and Types

DefaultJson Configuration

Pre-configured JSON instance optimized for Ktor applications.

val DefaultJson: Json

Configuration Settings:

  • encodeDefaults = true - Serializes properties with default values
  • isLenient = true - Allows lenient JSON parsing
  • allowSpecialFloatingPointValues = true - Allows NaN, Infinity, -Infinity
  • allowStructuredMapKeys = true - Allows complex objects as map keys
  • prettyPrint = false - Compact JSON output for efficiency
  • useArrayPolymorphism = false - Uses object-based polymorphism

Content Types

// From io.ktor.http package
ContentType.Application.Json // Standard application/json content type

Required Imports for Types

// Core serialization imports
import io.ktor.serialization.*
import io.ktor.serialization.kotlinx.*
import io.ktor.http.*
import io.ktor.http.content.*
import io.ktor.util.reflect.*
import io.ktor.utils.io.*
import io.ktor.utils.io.charsets.*
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import kotlinx.coroutines.flow.*

Exception Types

// From io.ktor.serialization package
open class ContentConvertException(
    message: String,
    cause: Throwable? = null
) : Exception

class JsonConvertException(
    message: String,
    cause: Throwable? = null
) : ContentConvertException
  • ContentConvertException: Base exception for content conversion errors
  • JsonConvertException: Thrown when JSON conversion fails during serialization or deserialization

Core Interface Types

// From io.ktor.serialization.kotlinx package
interface KotlinxSerializationExtensionProvider {
    fun extension(format: SerialFormat): KotlinxSerializationExtension?
}

interface KotlinxSerializationExtension {
    suspend fun serialize(
        contentType: ContentType,
        charset: Charset,
        typeInfo: TypeInfo,
        value: Any?
    ): OutgoingContent?
    
    suspend fun deserialize(
        charset: Charset,
        typeInfo: TypeInfo,
        content: ByteReadChannel
    ): Any?
}

// From io.ktor.serialization package
interface ContentConverter {
    suspend fun serialize(
        contentType: ContentType,
        charset: Charset,
        typeInfo: TypeInfo,
        value: Any?
    ): OutgoingContent
    
    suspend fun deserialize(
        charset: Charset,
        typeInfo: TypeInfo,
        content: ByteReadChannel
    ): Any?
}

Platform Support

JVM Platform

  • Full functionality including Sequence<T> deserialization
  • Uses Json.decodeToSequence(InputStream, KSerializer) for efficient sequence parsing
  • Sequence elements are parsed lazily during evaluation
  • Requires UTF-8 charset for streaming operations
  • Optimized streaming using InputStream for sequence parsing

JavaScript Platform

  • Standard JSON serialization and deserialization
  • Sequence deserialization is not supported (returns null)
  • Flow serialization supported

Native Platforms (POSIX)

  • Standard JSON serialization and deserialization
  • Sequence deserialization is not supported (returns null)
  • Flow serialization supported

WebAssembly (WASM)

  • Standard JSON serialization and deserialization
  • Sequence deserialization is not supported (returns null)
  • Flow serialization supported

Usage Examples

Serializing Data Classes

@Serializable
data class User(val id: Int, val name: String, val email: String)

// Server endpoint
post("/users") {
    val user = call.receive<User>()
    // Process user...
    call.respond(user)
}

// Client request
val user = User(1, "John Doe", "john@example.com")
val response: User = client.post("http://localhost:8080/users") {
    contentType(ContentType.Application.Json)
    setBody(user)
}.body()

Streaming Large Collections

// Server streaming response
get("/users/stream") {
    val usersFlow: Flow<User> = getUsersAsFlow()
    call.respond(usersFlow) // Automatically serialized as JSON array
}

// Client receiving stream (JVM only)
val users: Sequence<User> = client.get("http://localhost:8080/users/stream").body()
users.forEach { user ->
    println("Received: $user")
}

Custom JSON Configuration

install(ContentNegotiation) {
    json(Json {
        prettyPrint = true
        isLenient = true
        ignoreUnknownKeys = true
        coerceInputValues = true
        useAlternativeNames = false
        namingStrategy = JsonNamingStrategy.SnakeCase
    })
}

Multiple Content Types

install(ContentNegotiation) {
    json(DefaultJson, ContentType.Application.Json)
    json(Json { prettyPrint = true }, ContentType("application", "vnd.api+json"))
}

Error Handling

Common Exceptions

  • JsonConvertException: JSON parsing or serialization errors
  • SerializationException: kotlinx.serialization errors (missing serializers, etc.)
  • ContentConvertException: Base content conversion errors

Error Handling Example

try {
    val data = call.receive<MyDataClass>()
} catch (e: JsonConvertException) {
    call.respond(HttpStatusCode.BadRequest, "Invalid JSON: ${e.message}")
} catch (e: SerializationException) {
    call.respond(HttpStatusCode.BadRequest, "Serialization error: ${e.message}")
} catch (e: ContentConvertException) {
    call.respond(HttpStatusCode.BadRequest, "Content conversion error: ${e.message}")
}