kotlinx-serialization-json/kotlinx.serialization.json/Json

Json

sealed class Json : StringFormat(source)

The main entry point to work with JSON serialization. It is typically used by constructing an application-specific instance, with configured JSON-specific behaviour and, if necessary, registered in SerializersModule custom serializers. Json instance can be configured in its Json {} factory function using JsonBuilder. For demonstration purposes or trivial usages, Json companion can be used instead.

Then constructed instance can be used either as regular SerialFormat or StringFormat or for converting objects to JsonElement back and forth.

This is the only serial format which has the first-class JsonElement support. Any serializable class can be serialized to or from JsonElement with Json.decodeFromJsonElement and Json.encodeToJsonElement respectively or serialize properties of JsonElement type.

Example of usage:

@Serializable
class DataHolder(val id: Int, val data: String, val extensions: JsonElement)

val json = Json
val instance = DataHolder(42, "some data", buildJsonObject { put("additional key", "value") }

// Plain StringFormat usage
val stringOutput: String = json.encodeToString(instance)

// JsonElement serialization specific for JSON only
val jsonTree: JsonElement = json.encodeToJsonElement(instance)

// Deserialize from string
val deserialized: DataHolder = json.decodeFromString<DataHolder>(stringOutput)

// Deserialize from json tree, JSON-specific
val deserializedFromTree: DataHolder = json.decodeFromJsonElement<DataHolder>(jsonTree)

 // Deserialize from string to JSON tree, JSON-specific
 val deserializedToTree: JsonElement = json.parseToJsonElement(stringOutput)

Json instance also exposes its configuration that can be used in custom serializers that rely on JsonDecoder and JsonEncoder for customizable behaviour.

Inheritors

Default

Types

Default

object Default : Json

The default instance of Json with default configuration.

Properties

configuration

val configuration: JsonConfiguration

serializersModule

open override val serializersModule: SerializersModule

Functions

decodeFromDynamic

@ExperimentalSerializationApi

inline fun <T> Json.decodeFromDynamic(dynamic: dynamic): T

A reified version of decodeFromDynamic.

@ExperimentalSerializationApi

fun <T> Json.decodeFromDynamic(deserializer: DeserializationStrategy<T>, dynamic: dynamic): T

Converts native JavaScript objects into Kotlin ones, verifying their types.

decodeFromJsonElement

fun <T> decodeFromJsonElement(deserializer: DeserializationStrategy<T>, element: JsonElement): T

Deserializes the given element into a value of type T using the given deserializer.

decodeFromJsonElement

inline fun <T> Json.decodeFromJsonElement(json: JsonElement): T

Deserializes the given json element into a value of type T using a deserializer retrieved from reified type parameter.

decodeFromStream

@ExperimentalSerializationApi

inline fun <T> Json.decodeFromStream(stream: InputStream): T

Deserializes the contents of given stream to the value of type T using UTF-8 encoding and deserializer retrieved from the reified type parameter.

@ExperimentalSerializationApi

fun <T> Json.decodeFromStream(deserializer: DeserializationStrategy<T>, stream: InputStream): T

Deserializes JSON from stream using UTF-8 encoding to a value of type T using deserializer.

decodeFromString

inline fun <T> decodeFromString(string: String): T

Decodes and deserializes the given JSON string to the value of type T using deserializer retrieved from the reified type parameter.

override fun <T> decodeFromString(deserializer: DeserializationStrategy<T>, string: String): T

Deserializes the given JSON string into a value of type T using the given deserializer.

decodeToSequence

@ExperimentalSerializationApi

inline fun <T> Json.decodeToSequence(stream: InputStream, format: DecodeSequenceMode = DecodeSequenceMode.AUTO_DETECT): Sequence<T>

Transforms the given stream into lazily deserialized sequence of elements of type T using UTF-8 encoding and deserializer retrieved from the reified type parameter. Unlike decodeFromStream, stream is allowed to have more than one element, separated as format declares.

@ExperimentalSerializationApi

fun <T> Json.decodeToSequence(stream: InputStream, deserializer: DeserializationStrategy<T>, format: DecodeSequenceMode = DecodeSequenceMode.AUTO_DETECT): Sequence<T>

Transforms the given stream into lazily deserialized sequence of elements of type T using UTF-8 encoding and deserializer. Unlike decodeFromStream, stream is allowed to have more than one element, separated as format declares.

encodeToDynamic

@ExperimentalSerializationApi

inline fun <T> Json.encodeToDynamic(value: T): dynamic

A reified version of encodeToDynamic.

@ExperimentalSerializationApi

fun <T> Json.encodeToDynamic(serializer: SerializationStrategy<T>, value: T): dynamic

Converts Kotlin data structures to plain Javascript objects

encodeToJsonElement

fun <T> encodeToJsonElement(serializer: SerializationStrategy<T>, value: T): JsonElement

Serializes the given value into an equivalent JsonElement using the given serializer

encodeToJsonElement

inline fun <T> Json.encodeToJsonElement(value: T): JsonElement

Serializes the given value into an equivalent JsonElement using a serializer retrieved from reified type parameter.

encodeToStream

@ExperimentalSerializationApi

inline fun <T> Json.encodeToStream(value: T, stream: OutputStream)

Serializes given value to stream using UTF-8 encoding and serializer retrieved from the reified type parameter.

@ExperimentalSerializationApi

fun <T> Json.encodeToStream(serializer: SerializationStrategy<T>, value: T, stream: OutputStream)

Serializes the value with serializer into a stream using JSON format and UTF-8 encoding.

encodeToString

override fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String

Serializes the value into an equivalent JSON using the given serializer.

parseToJsonElement

fun parseToJsonElement(string: String): JsonElement

Deserializes the given JSON string into a corresponding JsonElement representation.