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
data class Data(val id: Int, val data: String, val extensions: JsonElement)

val json = Json { ignoreUnknownKeys = true }
val instance = Data(42, "some data", buildJsonObject { put("key", "value") })

// Plain Json usage: returns '{"id": 42, "some data", "extensions": {"key": "value" } }'
val jsonString: String = json.encodeToString(instance)

// JsonElement serialization, specific for JSON format
val jsonElement: JsonElement = json.encodeToJsonElement(instance)

// Deserialize from string
val deserialized: Data = json.decodeFromString<Data>(jsonString)

// Deserialize from json element, JSON-specific
val deserializedFromElement: Data = json.decodeFromJsonElement<Data>(jsonElement)

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

// Deserialize a stream of a single item from an input stream
val sequence = Json.decodeToSequence<Data>(ByteArrayInputStream(jsonString.encodeToByteArray()))
for (item in sequence) {
println(item) // Prints deserialized Data value
}

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

Json format configuration can be refined using the corresponding constructor:

val defaultJson = Json {
encodeDefaults = true
ignoreUnknownKeys = true
}
// Will inherit the properties of defaultJson
val debugEndpointJson = Json(defaultJson) {
// ignoreUnknownKeys and encodeDefaults are set to true
prettyPrint = true
}

Inheritors

Types

Link copied to clipboard
object Default : Json

The default instance of Json with default configuration.

Properties

Link copied to clipboard
Link copied to clipboard

Functions

Link copied to clipboard
inline fun <T> Json.decodeFromDynamic(dynamic: dynamic): T

A reified version of decodeFromDynamic.

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

Link copied to clipboard

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

Link copied to clipboard

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

Link copied to clipboard

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

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

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

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. Example:

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

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.

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

A reified version of encodeToDynamic.

Converts Kotlin data structures to plain Javascript objects

Link copied to clipboard

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

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

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

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

Link copied to clipboard
inline fun <T> encodeToString(value: T): String

Serializes the value of type T into an equivalent JSON using serializer retrieved from the reified type parameter.

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

Serializes the value into an equivalent JSON using the given serializer. This method is recommended to be used with an explicit serializer (e.g. the custom or third-party one), otherwise the encodeToString(value: T) version might be preferred as the most concise one.

Link copied to clipboard

Deserializes the given JSON string into a corresponding JsonElement representation.