Kotlin Serialization

Overview

The Kotlin driver supports the kotlinx.serialization library for serializing and deserializing Kotlin objects.

The driver provides an efficient Bson serializer that you can use with classes marked as @Serializable to handle the serialization of Kotlin objects to BSON data.

You can also install the bson-kotlinx library to support custom codecs with configurations to encode defaults, encode nulls, and define class discriminators.

Although you can use the Kotlin driver with the Kotlin serialization Json library, the Json serializer does not directly support BSON value types such as ObjectId. You must provide a custom serializer that can handle the conversion between BSON and JSON.

Add Kotlin Serialization to Your Project

Support for serialization in the Kotlin driver depends on the official Kotlin serialization library.

Select from the following tabs to see how to add the serialization dependencies to your project by using the Gradle and Maven package managers:

implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.6.0")
implementation("org.mongodb:bson-kotlinx:5.0.0")

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-serialization-core</artifactId>
    <version>1.6.0</version>
</dependency>
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.0.0</version>
</dependency>

Annotate Data Classes

To declare a class as serializable, annotate your Kotlin data classes with the @Serializable annotation from the Kotlin serialization framework.

You can use your data classes in your code as normal after you mark them as serializable. The Kotlin driver and the Kotlin serialization framework handle the BSON serialization and deserialization.

This example shows a simple data class annotated with the following:

• @Serializable to mark the class as serializable.

• @SerialName to specify the name of the id and manufacturer properties in the BSON document. This can be used in place of the @BsonId and @BsonProperty annotations, which are unsupported in serializable classes.

• @Contextual to mark the BSON id property to use the built-in ObjectIdSerializer. This annotation is required for BSON types to be serialized correctly.

@Serializable
data class PaintOrder(
    @SerialName("_id") // Use instead of @BsonId
    @Contextual val id: ObjectId?,
    val color: String,
    val qty: Int,
    @SerialName("brand")
    val manufacturer: String = "Acme" // Use instead of @BsonProperty
)

For more information on serializable classes and available annotation classes, see the official Kotlin Serialization documentation.

object InstantAsBsonDateTime : KSerializer<Instant> {
    override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("InstantAsBsonDateTime", PrimitiveKind.LONG)
    override fun serialize(encoder: Encoder, value: Instant) {
        when (encoder) {
            is BsonEncoder -> encoder.encodeBsonValue(BsonDateTime(value.toEpochMilliseconds()))
            else -> throw SerializationException("Instant is not supported by ${encoder::class}")
        }
    }
    override fun deserialize(decoder: Decoder): Instant {
        return when (decoder) {
            is BsonDecoder -> Instant.fromEpochMilliseconds(decoder.decodeBsonValue().asDateTime().value)
            else -> throw SerializationException("Instant is not supported by ${decoder::class}")
        }
    }
}

@Serializable
data class PaintOrder(
    val color: String,
    val qty: Int,
    @Serializable(with = InstantAsBsonDateTime::class)
    val orderDate: Instant,
)

Customize the Serializer Configuration

You can use the KotlinSerializerCodec class from the org.bson.codecs.kotlinx package to create a codec for your @Serializable data classes and customize what is stored.

Use the BsonConfiguration class to define the configuration, including whether to encode defaults, encode nulls, or define class discriminators.

To create a custom codec, install the bson-kotlinx dependency to your project. Select from the following tabs to see how to add the dependency to your project by using the Gradle and Maven package managers:

implementation("org.mongodb:bson-kotlinx:5.0.0")

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.0.0</version>
</dependency>

Then, you can define your codec using the KotlinSerializerCodec.create() method and add it to the registry.

import org.bson.codecs.configuration.CodecRegistries
import org.bson.codecs.kotlinx.BsonConfiguration
import org.bson.codecs.kotlinx.KotlinSerializerCodec

val myCustomCodec = KotlinSerializerCodec.create<PaintOrder>(
    bsonConfiguration = BsonConfiguration(encodeDefaults = false)
)
val registry = CodecRegistries.fromRegistries(
    CodecRegistries.fromCodecs(myCustomCodec), collection.codecRegistry
)