CtrlK
BlogDocsLog inGet started
Tessl Logo

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

A Kotlin multiplatform library for JSON serialization providing type-safe JSON parsing and object serialization

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

kotlinx-serialization-json

kotlinx-serialization-json is a Kotlin multiplatform library for JSON serialization that provides type-safe JSON parsing, object serialization, and DOM-style manipulation of JSON data. It offers both high-level serialization APIs and low-level JsonElement manipulation, with extensive configuration options and platform-specific optimizations.

Package Information

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

Core Imports

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

For specific components:

import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonArray
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.buildJsonArray

Basic Usage

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

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

// Serialization
val user = User("Alice", 30, "alice@example.com")
val jsonString = Json.encodeToString(user)
// Result: {"name":"Alice","age":30,"email":"alice@example.com"}

// Deserialization
val deserializedUser = Json.decodeFromString<User>(jsonString)

// JSON DOM manipulation
val jsonElement = Json.parseToJsonElement("""{"users": [{"name": "Bob"}]}""")
val userName = jsonElement.jsonObject["users"]?.jsonArray?.get(0)?.jsonObject?.get("name")?.jsonPrimitive?.content

Architecture

kotlinx-serialization-json is built around several key components:

  • Json Class: Main entry point providing serialization/deserialization APIs with configurable behavior
  • JsonElement Hierarchy: DOM-style JSON representation (JsonObject, JsonArray, JsonPrimitive, JsonNull)
  • Configuration System: Comprehensive options via JsonBuilder for customizing JSON processing behavior
  • DSL Builders: Kotlin DSL for programmatically constructing JSON structures
  • Advanced Serialization: Custom serializers, encoders/decoders, and transformation utilities
  • Platform Integration: Platform-specific APIs for JVM streams and JavaScript dynamic objects

Capabilities

Core Serialization

High-level JSON serialization and deserialization with the Json class, supporting configuration, custom serializers, and type-safe operations.

object Json {
    fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String
    fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T
    inline fun <reified T> encodeToString(value: T): String
    inline fun <reified T> decodeFromString(string: String): T
    
    fun <T> encodeToJsonElement(serializer: SerializationStrategy<T>, value: T): JsonElement
    fun <T> decodeFromJsonElement(deserializer: DeserializationStrategy<T>, element: JsonElement): T
    inline fun <reified T> encodeToJsonElement(value: T): JsonElement
    inline fun <reified T> decodeFromJsonElement(json: JsonElement): T
    
    fun parseToJsonElement(string: String): JsonElement
    
    val Default: Json
}

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

Core Serialization

JsonElement DOM

JSON Document Object Model for programmatic JSON manipulation, providing type-safe access to JSON structures without predefined data classes.

sealed class JsonElement

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

object JsonNull : JsonPrimitive

class JsonObject(content: Map<String, JsonElement>) : JsonElement, Map<String, JsonElement>

class JsonArray(content: List<JsonElement>) : JsonElement, List<JsonElement>

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

// Extension properties
val JsonElement.jsonPrimitive: JsonPrimitive
val JsonElement.jsonObject: JsonObject
val JsonElement.jsonArray: JsonArray
val JsonPrimitive.int: Int
val JsonPrimitive.boolean: Boolean
val JsonPrimitive.double: Double

JsonElement DOM

DSL Builders

Kotlin DSL for building JSON structures programmatically with type-safe, fluent APIs.

fun buildJsonObject(builderAction: JsonObjectBuilder.() -> Unit): JsonObject
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

Configuration

Comprehensive configuration options for customizing JSON serialization behavior, formatting, and parsing rules.

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

class JsonConfiguration {
    // Immutable configuration properties
}

Configuration

Advanced Serialization

Custom serializers, transforming serializers, and advanced encoder/decoder interfaces for specialized JSON processing needs.

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

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

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

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

Advanced Serialization

Annotations and Naming

Annotations for customizing JSON serialization behavior and naming strategies for property name transformation.

@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

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

Annotations and Naming

Platform-Specific APIs

Platform-specific extensions for JVM stream operations and JavaScript dynamic object interoperability.

// JVM-specific stream operations
fun <T> Json.encodeToStream(serializer: SerializationStrategy<T>, value: T, stream: OutputStream)
fun <T> Json.decodeFromStream(deserializer: DeserializationStrategy<T>, stream: InputStream): T

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

Platform-Specific APIs

Types

Core Configuration Types

enum class ClassDiscriminatorMode {
    NONE, ALL_JSON_OBJECTS, POLYMORPHIC
}

enum class DecodeSequenceMode {
    WHITESPACE_SEPARATED, ARRAY_WRAPPED, AUTO_DETECT
}

Serialization Exception Types

The library throws standard kotlinx.serialization exceptions for error conditions including SerializationException, IllegalArgumentException, and JsonDecodingException for malformed JSON.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.jetbrains.kotlinx/kotlinx-serialization-json-jvm@1.9.x
Publish Source
CLI
Badge
tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-json-jvm badge