Json
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
Functions
A reified version of decodeFromDynamic.
Converts native JavaScript objects into Kotlin ones, verifying their types.
Deserializes the given element into a value of type T using the given deserializer.
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.
Decodes and deserializes the given JSON string to the value of type T using deserializer retrieved from the reified type parameter. Example:
Deserializes the given JSON string into a value of type T using the given deserializer. Example:
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.
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.
A reified version of encodeToDynamic.
Converts Kotlin data structures to plain Javascript objects
Serializes the given value into an equivalent JsonElement using the given serializer
Serializes the given value into an equivalent JsonElement using a serializer retrieved from reified type parameter.
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.
Serializes the value of type T into an equivalent JSON using serializer retrieved from the reified type parameter.
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.
Deserializes the given JSON string into a corresponding JsonElement representation.