Create and use serializers

Obtain serializers for collection types

Unlike classes annotated with @Serializable, collection types like List<T> don't have a generated .serializer() function.

To obtain a serializer for a collection type, create one with ListSerializer(), SetSerializer(), or MapSerializer() and specify serializers for the collection's type parameters.

Here's an example that uses the ListSerializer() function to create a serializer for List<String>:

Create a custom primitive serializer

Use a primitive serializer to represent a class as a single primitive value, such as a string or integer.

To create a custom primitive serializer:

1. Create a custom serializer as an object that implements KSerializer for the serialized class:

   object YourSerializer : KSerializer<Type>

2. Override the descriptor property to define the schema for the serialized data.

   Use the PrimitiveSerialDescriptor(serialName, kind) to define the structure of the serialized form as a single primitive value. Specify a unique serialName, such as a fully qualified name, and use a PrimitiveKind that matches the encoder and decoder functions used in the serializer:

   override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("com.example.Type", PrimitiveKind.STRING)

3. Implement the serialize() function to define how values are converted to their serialized form. Choose an Encoder function that matches the PrimitiveKind in the descriptor:

   override fun serialize(encoder: Encoder, value: Type) { val encodedValue: String = // convert value to a primitive representation encoder.encodeString(encodedValue) }

4. Implement the deserialize() function to define how to convert the serialized data back into an instance of your class. The Decoder provides functions to read the data, such as decodeString().

   override fun deserialize(decoder: Decoder): Type { val decodedValue: String = decoder.decodeString() // Converts decodedValue back to Type return ... }

5. Use the @Serializable annotation to specify a custom serializer for the class:

   @Serializable(YourSerializer::class) data class Type(val stringValue: String)

Here's an example for a custom primitive serializer that serializes Color as a hexadecimal string:

Serialize binary data as Base64 strings

You can use a custom primitive serializer to solve common serialization tasks beyond simple value conversion. One such task is representing binary data as a Base64 string.

Different APIs use different Base64 variants by default. Choose a Kotlin Base64 encoder that matches the expected variant, such as Base64.Default or Base64.Mime.

Here's an example that serializes a ByteArray as a Base64 string with Base64.Default in JSON format:

Delegate serialization to another serializer

You can serialize a class as another type by delegating the serialization logic to the serializer for that type. For example, you can use this approach to serialize a class as a non-primitive type, such as an IntArray.

To delegate serialization, create a custom serializer that defines a property for the serializer of the delegated type:

1. Override the descriptor property to wrap the delegated serializer's descriptor.

2. Override the serialize() function to convert an instance of your class to the delegated type and use encoder.encodeSerializableValue() function to encode it with the delegated serializer.

3. Override the deserialize() function to use the decoder.decodeSerializableValue() function with the delegated serializer to decode the value and convert it back into an instance of your class.

Here's an example that serializes a Color class as an IntArray by delegating the serialization logic to IntArraySerializer:

While using the array representation isn't conventional in JSON, it can reduce the size of serialized data when used with a ByteArray and a binary format.

Serialize classes with a surrogate class

You can use a surrogate class, a class that matches the serialized form of another class, when you want to:

• Change how a class is serialized without modifying the class itself.

• Avoid creating a composite serializer.

• Validate the serialized form before creating the original class.

• Handle cases where direct serialization doesn't fit the class's rules.

You can make surrogate classes private, and use an init block to enforce constraints on the serial representation of the class. You can also define a custom serial name to keep the serialized type name unchanged.

Let's look at an example that serializes Color as a JSON object with specific ranges for the r, g, and b properties:

Similarly to delegating serialization to another serializer, the custom serializer converts the original class to another representation and wraps that representation's automatically generated SerialDescriptor.

To retrieve the generated serializer for the surrogate class, use ColorSurrogate.serializer():

Finally, specify the custom serializer for the class:

Create a custom composite serializer

You can use composite serializers to represent complex data structures, such as classes with multiple properties.

Compared to using a surrogate class, a custom composite serializer lets you define the serialized structure of the original class directly without an additional conversion step. This can also improve performance in some cases, but requires writing more of the serialization logic manually.

To create a custom composite serializer:

1. Create a serializer as an object that implements KSerializer for the target class:

   object YourSerializer : KSerializer<Type>

2. Override the descriptor property and define the serialization schema with the buildClassSerialDescriptor() function:

   override val descriptor: SerialDescriptor = buildClassSerialDescriptor("com.example.Type") { // ... }

3. Specify each property in the buildClassSerialDescriptor() function with the element() function. The order of elements determines their indices, starting from 0.

   The SerialKind of the serializer's descriptor determines what each element() represents. In a class descriptor, an element() represents a property, while in an enum descriptor, an element() represents constants such as RED or GREEN:

   override val descriptor: SerialDescriptor = buildClassSerialDescriptor("com.example.Type") { element<Int>("first") element<Int>("second") }

4. Implement the serialize() function using the encodeStructure() DSL. Inside its block, the lambda receiver is a CompositeEncoder, which you use to call functions such as encodeIntElement() for each field, following the order defined in the descriptor:

   override fun serialize(encoder: Encoder, value: Type) = encoder.encodeStructure(descriptor) { encodeIntElement(descriptor, 0, value.first) encodeIntElement(descriptor, 1, value.second) }

5. Implement the deserialize() function using the decodeStructure() DSL. Inside its block, the lambda receiver is a CompositeDecoder, which you use to call functions like decodeIntElement() to decode each property.

   Most formats allow data to be encoded in an arbitrary order, which can differ from the order of elements in the serializer's descriptor. Use the decodeElementIndex() function to identify which element() to decode. It returns CompositeDecoder.DECODE_DONE when no more elements are left, which you use to stop decoding the current structure:

   override fun deserialize(decoder: Decoder): Type = decoder.decodeStructure(descriptor) { var first = 0 var second = "" // Uses decodeElementIndex to ensure correct decoding regardless of order while (true) { when (val index = decodeElementIndex(descriptor)) { 0 -> first = decodeStringElement(descriptor, 0) 1 -> second = decodeIntElement(descriptor, 1) CompositeDecoder.DECODE_DONE -> break else -> error("Unexpected index: $index") } } Type(first, second) }

6. Use the @Serializable(YourSerializer::class) annotation to specify the custom serializer for the class.

Let's look at an example of how to serialize a Color class with multiple properties:

Encode default values in custom serializers

Plugin-generated serializers check whether the encoder needs to encode values that are equal to their defaults. For example, in JSON, this is controlled by the encodeDefaults property.

To achieve the same behavior in a custom serializer, use the shouldEncodeElementDefault() function with the serializer's descriptor and the index of the element you're encoding.

Here's an example where a custom serializer encodes default Color values when encodeDefaults is enabled:

Optimize deserialization with sequential decoding

Some formats use a strictly ordered schema and can support sequential decoding. For these formats, you can optimize deserialization with the decodeSequentially() function. This function returns true if the current structure can be decoded in order. Handle that case separately to skip the more complex logic of decoding individual elements out of order.

Here's an example that uses decodeSequentially() to optimize deserialization when possible:

Create a custom serializer for generic types

To create a custom serializer for a generic class, declare the serializer as a class instead of an object, with one KSerializer constructor parameter for each generic type parameter.

You can delegate the serialization logic for each type parameter to the corresponding KSerializer, so it's encoded according to its own serialization rules.

Let's look at an example using a generic Box<T> class:

Use a plugin-generated serializer together with a custom serializer

By default, the Kotlin serialization plugin doesn't generate a serializer if you specify a custom serializer with @Serializable(YourSerializer::class).

You might still want to use the plugin-generated serializer, for example:

• Using the plugin-generated serializer as a fallback strategy.

• Inspecting the plugin-generated descriptor to access the default structure.

• Reusing default serialization behavior in subclasses that don't use a custom serializer.

You can keep the automatically generated serializer alongside your custom one by annotating the serializable class with @KeepGeneratedSerializer. To access the plugin-generated serializer, use the .generatedSerializer() function on the companion object of the serializable class.

This can also be useful when using a JsonTransformingSerializer to adjust the JSON structure and reuse the plugin-generated serializer for the default serialization logic.

Here's an example that uses both a custom serializer and the plugin-generated serializer:

Pass a serializer manually

To serialize a type with a custom serializer, create the serializer and pass it explicitly to overloads of functions such as Json.encodeToString() and Json.decodeFromString().

Here's an example that serializes Date values as the number of milliseconds since the Unix epoch:

Specify a serializer on a property

When a type is used as a property in a serializable class, specify its custom serializer on that property with the @Serializable annotation:

Specify a serializer on a type

You can also apply the @Serializable annotation directly to a type. You can use this to specify a custom serializer for a type when it's used as a generic type argument, for example in List<Date>:

Specify a serializer for a file

To apply a serializer to all properties of a given type in a source file, add the @UseSerializers annotation at the beginning of the file:

This applies the DateAsLongSerializer to all instances of that type within the file, so you don't need to annotate each property separately.

Here's an example:

Specify serializers with type aliases

In Kotlin serialization, you usually specify serialization strategies explicitly with the @Serializable annotation. It doesn't provide a global serializer configuration, except for contextual serialization.

If you use the same serializer repeatedly in many places, you can define a typealias with an attached serializer annotation.

This lets you reuse the annotated type without adding the @Serializable annotation at each usage site.

Here's an example of using typealias to apply DateAsLongSerializer and DateAsSimpleTextSerializer to Date:

Implement contextual serialization

By default, serialization strategies are defined at compile time. Contextual serialization allows you to adjust the serialization strategy for specific types at runtime, even when they're nested deep within an object tree.

For example, you can use contextual serialization to serialize java.util.Date in JSON format either as an ISO 8601 String or as a Long, depending on the protocol version being used. This approach is supported by the built-in ContextualSerializer class.

Contextual serialization selects a custom serializer for a type at runtime from a SerializersModule.

To implement contextual serialization:

1. Mark the property in your serializable class with the @Contextual annotation.

2. Create a SerializersModule with the SerializersModule() builder function. Use the contextual() function to register the custom serializer for contextual serialization.

   Without the SerializersModule, a SerializationException is thrown during the serialization or deserialization of contextually annotated types that don't have a default serializer.

3. Create a Json instance and pass the SerializersModule to the serializersModule property.

Here's an example: