kotlinx-serialization-json/kotlinx.serialization.json

Package-level declarations

JSON serialization format implementation, JSON tree data structures with builders for them, and JSON-specific serializers.

Types

ClassDiscriminatorMode

enum ClassDiscriminatorMode : Enum<ClassDiscriminatorMode>

Defines which classes and objects should have their serial name included in the json as so-called class discriminator.

DecodeSequenceMode

@ExperimentalSerializationApi

enum DecodeSequenceMode : Enum<DecodeSequenceMode>

Description of JSON input shape used for decoding to sequence.

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.

JsonArray

@Serializable(with = JsonArraySerializer::class)

class JsonArray(content: List<JsonElement>) : JsonElement, List<JsonElement>

Class representing JSON array, consisting of indexed values, where value is arbitrary JsonElement

JsonArrayBuilder

class JsonArrayBuilder

DSL builder for a JsonArray. To create an instance of builder, use buildJsonArray build function.

JsonBuilder

class JsonBuilder

Builder of the Json instance provided by Json { ... } factory function:

JsonClassDiscriminator

@InheritableSerialInfo

@Target(allowedTargets = [AnnotationTarget.CLASS])

@ExperimentalSerializationApi

annotation class JsonClassDiscriminator(val discriminator: String)

Specifies key for class discriminator value used during polymorphic serialization in Json. Provided key is used only for an annotated class and its subclasses; to configure global class discriminator, use JsonBuilder.classDiscriminator property.

JsonConfiguration

class JsonConfiguration

Configuration of the current Json instance available through Json.configuration and configured with JsonBuilder constructor.

JsonContentPolymorphicSerializer

abstract class JsonContentPolymorphicSerializer<T : Any>(baseClass: KClass<T>) : KSerializer<T>

Base class for custom serializers that allows selecting polymorphic serializer without a dedicated class discriminator, on a content basis.

JsonDecoder

interface JsonDecoder : Decoder, CompositeDecoder

Decoder used by Json during deserialization. This interface can be used to inject desired behaviour into a serialization process of Json.

JsonElement

@Serializable(with = JsonElementSerializer::class)

sealed class JsonElement

Class representing single JSON element. Can be JsonPrimitive, JsonArray or JsonObject.

JsonEncoder

interface JsonEncoder : Encoder, CompositeEncoder

Encoder used by Json during serialization. This interface can be used to inject desired behaviour into a serialization process of Json.

JsonIgnoreUnknownKeys

@SerialInfo

@Target(allowedTargets = [AnnotationTarget.CLASS])

@ExperimentalSerializationApi

annotation class JsonIgnoreUnknownKeys

Specifies whether encounters of unknown properties (i.e., properties not declared in the class) in the input JSON should be ignored instead of throwing SerializationException.

JsonNames

@SerialInfo

@Target(allowedTargets = [AnnotationTarget.PROPERTY])

@ExperimentalSerializationApi

annotation class JsonNames(val names: String)

Indicates that the field can be represented in JSON with multiple possible alternative names. Json format recognizes this annotation and is able to decode the data using any of the alternative names.

JsonNamingStrategy

@ExperimentalSerializationApi

fun interface JsonNamingStrategy

Represents naming strategy — a transformer for serial names in a Json format. Transformed serial names are used for both serialization and deserialization. A naming strategy is always applied globally in the Json configuration builder (see JsonBuilder.namingStrategy).

JsonNull

@Serializable(with = JsonNullSerializer::class)

object JsonNull : JsonPrimitive

Class representing JSON null value

JsonObject

@Serializable(with = JsonObjectSerializer::class)

class JsonObject(content: Map<String, JsonElement>) : JsonElement, Map<String, JsonElement>

Class representing JSON object, consisting of name-value pairs, where value is arbitrary JsonElement

JsonObjectBuilder

class JsonObjectBuilder

DSL builder for a JsonObject. To create an instance of builder, use buildJsonObject build function.

JsonPrimitive

@Serializable(with = JsonPrimitiveSerializer::class)

sealed class JsonPrimitive : JsonElement

Class representing JSON primitive value. JSON primitives include numbers, strings, booleans and special null value JsonNull.

JsonTransformingSerializer

abstract class JsonTransformingSerializer<T : Any>(tSerializer: KSerializer<T>) : KSerializer<T>

Base class for custom serializers that allows manipulating an abstract JSON representation of the class before serialization or deserialization.

Properties

boolean

val JsonPrimitive.boolean: Boolean

Returns content of current element as boolean

booleanOrNull

val JsonPrimitive.booleanOrNull: Boolean?

Returns content of current element as boolean or null if current element is not a valid representation of boolean

contentOrNull

val JsonPrimitive.contentOrNull: String?

Content of the given element without quotes or null if current element is JsonNull

double

val JsonPrimitive.double: Double

Returns content of current element as double

doubleOrNull

val JsonPrimitive.doubleOrNull: Double?

Returns content of current element as double or null if current element is not a valid representation of number

float

val JsonPrimitive.float: Float

Returns content of current element as float

floatOrNull

val JsonPrimitive.floatOrNull: Float?

Returns content of current element as float or null if current element is not a valid representation of number

int

val JsonPrimitive.int: Int

Returns content of the current element as int

intOrNull

val JsonPrimitive.intOrNull: Int?

Returns content of the current element as int or null if current element is not a valid representation of number

jsonArray

val JsonElement.jsonArray: JsonArray

Convenience method to get current element as JsonArray

jsonNull

val JsonElement.jsonNull: JsonNull

Convenience method to get current element as JsonNull

jsonObject

val JsonElement.jsonObject: JsonObject

Convenience method to get current element as JsonObject

jsonPrimitive

val JsonElement.jsonPrimitive: JsonPrimitive

Convenience method to get current element as JsonPrimitive

long

val JsonPrimitive.long: Long

Returns content of current element as long

longOrNull

val JsonPrimitive.longOrNull: Long?

Returns content of current element as long or null if current element is not a valid representation of number

Functions

add

fun JsonArrayBuilder.add(value: Boolean?): Boolean

Adds the given boolean value to a resulting JSON array.

@ExperimentalSerializationApi

fun JsonArrayBuilder.add(value: Nothing?): Boolean

Adds null to a resulting JSON array.

fun JsonArrayBuilder.add(value: Number?): Boolean

Adds the given numeric value to a resulting JSON array.

fun JsonArrayBuilder.add(value: String?): Boolean

Adds the given string value to a resulting JSON array.

addAll

@JvmName(name = "addAllBooleans")

@ExperimentalSerializationApi

fun JsonArrayBuilder.addAll(values: Collection<Boolean?>): Boolean

Adds the given boolean values to a resulting JSON array.

@JvmName(name = "addAllNumbers")

@ExperimentalSerializationApi

fun JsonArrayBuilder.addAll(values: Collection<Number?>): Boolean

Adds the given numeric values to a resulting JSON array.

@JvmName(name = "addAllStrings")

@ExperimentalSerializationApi

fun JsonArrayBuilder.addAll(values: Collection<String?>): Boolean

Adds the given string values to a resulting JSON array.

addJsonArray

fun JsonArrayBuilder.addJsonArray(builderAction: JsonArrayBuilder.() -> Unit): Boolean

Adds the JSON array produced by the builderAction function to a resulting JSON array.

addJsonObject

fun JsonArrayBuilder.addJsonObject(builderAction: JsonObjectBuilder.() -> Unit): Boolean

Adds the JSON object produced by the builderAction function to a resulting JSON array.

buildJsonArray

inline fun buildJsonArray(builderAction: JsonArrayBuilder.() -> Unit): JsonArray

Builds JsonArray with the given builderAction builder. Example of usage:

buildJsonObject

inline fun buildJsonObject(builderAction: JsonObjectBuilder.() -> Unit): JsonObject

Builds JsonObject with the given builderAction builder. Example of usage:

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

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.

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

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.

Json

fun Json(from: Json = Json.Default, builderAction: JsonBuilder.() -> Unit): Json

Creates an instance of Json configured from the optionally given Json instance and adjusted with builderAction.

JsonPrimitive

fun JsonPrimitive(value: Boolean?): JsonPrimitive

Creates a JsonPrimitive from the given boolean.

@ExperimentalSerializationApi

fun JsonPrimitive(value: Nothing?): JsonNull

Creates JsonNull.

fun JsonPrimitive(value: Number?): JsonPrimitive

Creates a JsonPrimitive from the given number.

fun JsonPrimitive(value: String?): JsonPrimitive

Creates a JsonPrimitive from the given string.

@ExperimentalSerializationApi

fun JsonPrimitive(value: UByte): JsonPrimitive

Creates a numeric JsonPrimitive from the given UByte.

@ExperimentalSerializationApi

fun JsonPrimitive(value: UInt): JsonPrimitive

Creates a numeric JsonPrimitive from the given UInt.

@ExperimentalSerializationApi

fun JsonPrimitive(value: ULong): JsonPrimitive

Creates a numeric JsonPrimitive from the given ULong.

@ExperimentalSerializationApi

fun JsonPrimitive(value: UShort): JsonPrimitive

Creates a numeric JsonPrimitive from the given UShort.

JsonUnquotedLiteral

@ExperimentalSerializationApi

fun JsonUnquotedLiteral(value: String?): JsonPrimitive

Creates a JsonPrimitive from the given string, without surrounding it in quotes.

put

fun JsonObjectBuilder.put(key: String, value: Boolean?): JsonElement?

Add the given boolean value to a resulting JSON object using the given key.

@ExperimentalSerializationApi

fun JsonObjectBuilder.put(key: String, value: Nothing?): JsonElement?

Add null to a resulting JSON object using the given key.

fun JsonObjectBuilder.put(key: String, value: Number?): JsonElement?

Add the given numeric value to a resulting JSON object using the given key.

fun JsonObjectBuilder.put(key: String, value: String?): JsonElement?

Add the given string value to a resulting JSON object using the given key.

putJsonArray

fun JsonObjectBuilder.putJsonArray(key: String, builderAction: JsonArrayBuilder.() -> Unit): JsonElement?

Add the JSON array produced by the builderAction function to a resulting JSON object using the given key.

putJsonObject

fun JsonObjectBuilder.putJsonObject(key: String, builderAction: JsonObjectBuilder.() -> Unit): JsonElement?

Add the JSON object produced by the builderAction function to a resulting JSON object using the given key.