Json

sealed class Json : StringFormat

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.

Types

Link copied to clipboard
object Default : Json

The default instance of Json with default configuration.

Functions

Link copied to clipboard
fun <T> decodeFromJsonElement(deserializer: DeserializationStrategy<T>, element: JsonElement): T

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

Link copied to clipboard
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.

Link copied to clipboard
fun <T> encodeToJsonElement(serializer: SerializationStrategy<T>, value: T): JsonElement

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

Link copied to clipboard
override fun <T> encodeToString(serializer: SerializationStrategy<T>, value: T): String

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

Link copied to clipboard
fun parseToJsonElement(string: String): JsonElement

Deserializes the given JSON string into a corresponding JsonElement representation.

Properties

Link copied to clipboard
val configuration: JsonConfiguration
Link copied to clipboard
open override val serializersModule: SerializersModule

Inheritors

Link copied to clipboard

Extensions

Link copied to clipboard
fun <T> Json.decodeFromDynamic(deserializer: DeserializationStrategy<T>, dynamic: dynamic): T

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

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

A reified version of decodeFromDynamic.

Link copied to clipboard
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.

Link copied to clipboard
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.

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.

Link copied to clipboard
fun <T> Json.decodeStringToJsonTree(deserializer: DeserializationStrategy<T>, source: String): JsonElement
Link copied to clipboard
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.

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.

Link copied to clipboard
fun <T> Json.encodeToDynamic(serializer: SerializationStrategy<T>, value: T): dynamic

Converts Kotlin data structures to plain Javascript objects

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

A reified version of encodeToDynamic.

Link copied to clipboard
inline fun <T> Json.encodeToJsonElement(value: T): JsonElement

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

Link copied to clipboard
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.

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.

Link copied to clipboard
fun <T> Json.readJson(element: JsonElement, deserializer: DeserializationStrategy<T>): T
Link copied to clipboard
fun <T> Json.writeJson(value: T, serializer: SerializationStrategy<T>): JsonElement