or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

annotations.mdconfiguration.mdcore-operations.mdcustom-serializers.mddsl-builders.mdindex.mdjson-elements.mdnaming-strategies.mdplatform-extensions.md
tile.json

tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-json

Kotlin multiplatform JSON serialization library with type-safe, reflectionless approach supporting all platforms

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

To install, run

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

index.mddocs/

Kotlinx Serialization JSON

Kotlinx Serialization JSON is a multiplatform JSON serialization library for Kotlin providing a type-safe, reflectionless approach to JSON handling. It supports all Kotlin platforms (JVM, JS, Native, WebAssembly) with zero runtime reflection and compile-time code generation.

Package Information

  • Package Name: kotlinx-serialization-json
  • Package Type: maven
  • Language: Kotlin
  • Installation: 
    dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0")
}

Core Imports

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

Basic Usage

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

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

// Create JSON instance with configuration
val json = Json { 
    prettyPrint = true
    ignoreUnknownKeys = true 
}

// Serialize to JSON string
val user = User("Alice", 25)
val jsonString = json.encodeToString(user)
// {"name":"Alice","age":25}

// Deserialize from JSON string
val userFromJson = json.decodeFromString<User>(jsonString)

// Work with JsonElement hierarchy
val element = json.encodeToJsonElement(user)
val userBack = json.decodeFromJsonElement<User>(element)

// Parse string to JsonElement
val jsonElement = json.parseToJsonElement("""{"name":"Bob","age":30}""")

Architecture

Kotlinx Serialization JSON is built around several key components:

  • Json Class: Main entry point providing serialization/deserialization methods with configurable behavior
  • JsonElement Hierarchy: Abstract JSON representation with JsonObject, JsonArray, JsonPrimitive, and JsonNull
  • Configuration System: Comprehensive configuration options via JsonBuilder for encoding/decoding behavior
  • DSL Builders: Fluent builders for constructing JSON objects and arrays programmatically
  • Custom Serializer Support: Interfaces and base classes for implementing custom JSON serialization logic
  • Platform Extensions: JVM stream support and JavaScript dynamic object integration

Capabilities

Core JSON Operations

Main serialization and deserialization functionality for converting between Kotlin objects and JSON strings or JsonElement representations.

sealed class Json(
    val configuration: JsonConfiguration,
    override val serializersModule: SerializersModule
) : StringFormat {
    companion object Default : Json
    
    fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String
    inline fun <reified T> encodeToString(value: T): String
    fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T
    inline fun <reified T> decodeFromString(string: String): T
    
    fun <T> encodeToJsonElement(serializer: SerializationStrategy<T>, value: T): JsonElement  
    inline fun <reified T> encodeToJsonElement(value: T): JsonElement
    fun <T> decodeFromJsonElement(deserializer: DeserializationStrategy<T>, element: JsonElement): T
    inline fun <reified T> decodeFromJsonElement(json: JsonElement): T
    
    fun parseToJsonElement(string: String): JsonElement
}

fun Json(from: Json = Json.Default, builderAction: JsonBuilder.() -> Unit): Json

Core JSON Operations

JsonElement Hierarchy

Abstract representation of JSON data structures providing a DOM-like API for working with JSON without specific types.

sealed class JsonElement

sealed class JsonPrimitive : JsonElement() {
    abstract val isString: Boolean
    abstract val content: String
}

class JsonObject(private val content: Map<String, JsonElement>) : JsonElement(), Map<String, JsonElement>
class JsonArray(private val content: List<JsonElement>) : JsonElement(), List<JsonElement>
object JsonNull : JsonPrimitive()

// Factory functions
fun JsonPrimitive(value: Boolean?): JsonPrimitive
fun JsonPrimitive(value: Number?): JsonPrimitive  
fun JsonPrimitive(value: String?): JsonPrimitive
fun JsonUnquotedLiteral(value: String?): JsonPrimitive

JsonElement Hierarchy

Configuration and Builder

Comprehensive configuration system for customizing JSON encoding and decoding behavior through builder pattern.

class JsonBuilder {
    var encodeDefaults: Boolean
    var ignoreUnknownKeys: Boolean
    var isLenient: Boolean
    var prettyPrint: Boolean
    var explicitNulls: Boolean
    var coerceInputValues: Boolean
    var allowSpecialFloatingPointValues: Boolean
    var allowStructuredMapKeys: Boolean
    var useArrayPolymorphism: Boolean
    var classDiscriminator: String
    var namingStrategy: JsonNamingStrategy?
    var serializersModule: SerializersModule
}

class JsonConfiguration(/* all configuration properties */)

Configuration and Builder

DSL Builders

Fluent DSL for constructing JsonObject and JsonArray instances programmatically with type-safe operations.

inline fun buildJsonObject(builderAction: JsonObjectBuilder.() -> Unit): JsonObject
inline fun buildJsonArray(builderAction: JsonArrayBuilder.() -> Unit): JsonArray

class JsonObjectBuilder {
    fun put(key: String, element: JsonElement): JsonElement?
    fun put(key: String, value: Boolean?): JsonElement?
    fun put(key: String, value: Number?): JsonElement?
    fun put(key: String, value: String?): JsonElement?
    fun putJsonObject(key: String, builderAction: JsonObjectBuilder.() -> Unit): JsonElement?
    fun putJsonArray(key: String, builderAction: JsonArrayBuilder.() -> Unit): JsonElement?
}

class JsonArrayBuilder {
    fun add(element: JsonElement): Boolean
    fun add(value: Boolean?): Boolean
    fun add(value: Number?): Boolean  
    fun add(value: String?): Boolean
    fun addJsonObject(builderAction: JsonObjectBuilder.() -> Unit): Boolean
    fun addJsonArray(builderAction: JsonArrayBuilder.() -> Unit): Boolean
}

DSL Builders

Custom Serializers

Interfaces and base classes for implementing custom JSON serialization logic with access to JsonElement representations.

interface JsonEncoder : Encoder, CompositeEncoder {
    val json: Json
    fun encodeJsonElement(element: JsonElement)
}

interface JsonDecoder : Decoder, CompositeDecoder {
    val json: Json  
    fun decodeJsonElement(): JsonElement
}

abstract class JsonTransformingSerializer<T>(
    private val tSerializer: KSerializer<T>
) : KSerializer<T> {
    protected open fun transformDeserialize(element: JsonElement): JsonElement
    protected open fun transformSerialize(element: JsonElement): JsonElement
}

abstract class JsonContentPolymorphicSerializer<T>(
    private val baseClass: KClass<T>
) : KSerializer<T> {
    protected abstract fun selectDeserializer(element: JsonElement): DeserializationStrategy<T>
}

Custom Serializers

Annotations

Annotations for controlling JSON serialization behavior including alternative property names and polymorphic serialization.

@Target(AnnotationTarget.PROPERTY)
annotation class JsonNames(vararg val names: String)

@Target(AnnotationTarget.CLASS)  
annotation class JsonClassDiscriminator(val discriminator: String)

@Target(AnnotationTarget.CLASS)
annotation class JsonIgnoreUnknownKeys

Annotations

Naming Strategies

Built-in naming strategies for transforming property names during serialization/deserialization.

fun interface JsonNamingStrategy {
    fun serialNameForJson(descriptor: SerialDescriptor, elementIndex: Int, serialName: String): String
    
    companion object Builtins {
        val SnakeCase: JsonNamingStrategy
        val KebabCase: JsonNamingStrategy  
    }
}

Naming Strategies

Platform Extensions

Platform-specific extensions providing additional functionality for JVM streams and JavaScript dynamic objects.

// JVM only
fun <T> Json.encodeToStream(serializer: SerializationStrategy<T>, value: T, stream: OutputStream)
fun <T> Json.decodeFromStream(deserializer: DeserializationStrategy<T>, stream: InputStream): T
fun <T> Json.decodeToSequence(stream: InputStream, deserializer: DeserializationStrategy<T>, format: DecodeSequenceMode): Sequence<T>

// JavaScript only  
fun <T> Json.decodeFromDynamic(deserializer: DeserializationStrategy<T>, dynamic: dynamic): T
fun <T> Json.encodeToDynamic(serializer: SerializationStrategy<T>, value: T): dynamic

Platform Extensions

Types

enum class DecodeSequenceMode {
    /** Parse JSON objects/arrays separated by whitespace (newlines, spaces, tabs) */
    WHITESPACE_SEPARATED,
    /** Parse a JSON array containing objects/values as elements */
    ARRAY_WRAPPED,
    /** Automatically detect format based on first non-whitespace character */
    AUTO_DETECT
}

enum class ClassDiscriminatorMode {
    NONE,
    ALL_JSON_OBJECTS,
    POLYMORPHIC
}