kotlinx-serialization / kotlinx.serialization.json / Json

Json

(common, js, jvm, native) 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 (configuration constructor parameter) and, if necessary, registered custom serializers (in SerialModule provided by context constructor parameter). 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 first-class JsonElement support. Any serializable class can be serialized to or from JsonElement with Json.fromJson and Json.toJson 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(JsonConfiguration.Default)
val instance = DataHolder(42, "some data", json { "additional key" to "value" })

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

// JsonElement serialization specific for Json only
val jsonTree: JsonElement = json.toJson(instance)

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

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

 // Deserialize from string to json tree, Json-specific
 val deserializedToTree: JsonElement = json.fromJson<JsonElement>(stringOutput)

Note that @ImplicitReflectionSerializer are used in order to omit DataHolder.serializer, but this is a temporary limitation.

Types

(common, js, jvm, native)

Default

The default instance of Json in the form of companion object. Configured with JsonConfiguration.Default.

companion object Default : StringFormat

Constructors

(common, js, jvm, native)

<init>

DSL-like constructor for Json. This constructor is marked with unstable default: its default parameters values and behaviour may change in the next releases.

<init>(block: JsonBuilder.() -> Unit)

The main entry point to work with JSON serialization. It is typically used by constructing an application-specific instance, with configured json-specific behaviour (configuration constructor parameter) and, if necessary, registered custom serializers (in SerialModule provided by context constructor parameter). Then constructed instance can be used either as regular SerialFormat or StringFormat or for converting objects to JsonElement back and forth.

<init>(configuration: JsonConfiguration = JsonConfiguration.Stable, context: SerialModule = EmptyModule)

Properties

(common, js, jvm, native)

context

Contains all serializers registered by format user for ContextualSerialization and Polymorphic serialization.

val context: SerialModule

Functions

(common, js, jvm, native)

fromJson

Deserializes json element into a corresponding object of type T using provided deserializer.

fun <T> fromJson(deserializer: DeserializationStrategy<T>, json: JsonElement): T

Deserializes json element into a corresponding object of type T using serializer registered in the module.

fun <T : Any> fromJson(tree: JsonElement): T
(common, js, jvm, native)

parse

Deserializes given json string into a corresponding object of type T using provided deserializer.

fun <T> parse(deserializer: DeserializationStrategy<T>, string: String): T
(common, js, jvm, native)

parseJson

Deserializes given json string into a corresponding JsonElement representation.

fun parseJson(string: String): JsonElement
(common, js, jvm, native)

stringify

Serializes value into an equivalent JSON using provided serializer.

fun <T> stringify(serializer: SerializationStrategy<T>, value: T): String
(common, js, jvm, native)

toJson

Serializes value into an equivalent JsonElement using provided serializer.

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

Serializes value into an equivalent JsonElement using serializer registered in the module.

fun <T : Any> toJson(value: T): JsonElement

Companion Object Properties

(common, js, jvm, native)

context

Contains all serializers registered by format user for ContextualSerialization and Polymorphic serialization.

val context: SerialModule
fun <T> stringify(serializer: SerializationStrategy<T>, value: T): String
fun <T> parse(deserializer: DeserializationStrategy<T>, string: String): T
fun <T> toJson(serializer: SerializationStrategy<T>, value: T): JsonElement
fun <T : Any> toJson(value: T): JsonElement
fun parseJson(string: String): JsonElement
fun <T> fromJson(deserializer: DeserializationStrategy<T>, json: JsonElement): T
fun <T : Any> fromJson(tree: JsonElement): T