The main entry point to the serialization process. Applying Serializable to the Kotlin class instructs the serialization plugin to automatically generate implementation of KSerializer for the current class, that can be used to serialize and deserialize the class. The generated serializer can be accessed with T.serializer() extension function on the class companion, both are generated by the plugin as well.

class MyData(val myData: AnotherData, val intProperty: Int, ...)

// Produces JSON string using the generated serializer
val jsonString = Json.encodeToJson(MyData.serializer(), instance)

Additionally, the user-defined serializer can be specified using with parameter:

@Serializable(with = MyAnotherDataCustomSerializer::class)
class MyAnotherData(...)

MyAnotherData.serializer() // <- returns MyAnotherDataCustomSerializer

For annotated properties, specifying with parameter is mandatory and can be used to override serializer on the use-site without affecting the rest of the usages:

@Serializable // By default is serialized as 3 byte components
class RgbPixel(val red: Short, val green: Short, val blue: Short)

class RgbExample(
@Serializable(with = RgbAsHexString::class) p1: RgpPixel, // Serialize as HEX string, e.g. #FFFF00
@Serializable(with = RgbAsSingleInt::class) p2: RgpPixel, // Serialize as single integer, e.g. 16711680
p3: RgpPixel // Serialize as 3 short components, e.g. { "red": 255, "green": 255, "blue": 0 }

In this example, each pixel will be serialized using different data representation.

For classes with generic type parameters, serializer() function requires one additional argument per each generic type parameter:

class Box<T>(value: T)

Box.serializer() // Doesn't compile
Box.serializer(Int.serializer()) // Returns serializer for Box<Int>
Box.serializer(Box.serializer(Int.serializer())) // Returns serializer for Box<Box<Int>>

Implementation details

In order to generate serializer function that is not a method on the particular instance, the class should have a companion object, either named or unnamed. Companion object is generated by the plugin if it is not declared, effectively exposing both companion and serializer() method to class ABI. If companion object already exists, only serializer method will be generated.

@Target(allowedTargets = [AnnotationTarget.PROPERTY, AnnotationTarget.CLASS, AnnotationTarget.TYPE])
annotation class Serializable(with: KClass<out KSerializer<*>>)

See also

Link copied to clipboard

Link copied to clipboard


Link copied to clipboard
fun Serializable(with: KClass<out KSerializer<*>> = KSerializer::class)


Link copied to clipboard
open operator override fun equals(other: Any?): Boolean
Link copied to clipboard
open override fun hashCode(): Int
Link copied to clipboard
open override fun toString(): String


Link copied to clipboard
val with: KClass<out KSerializer<*>>