Kotlin Serialization

Overview

You can use the kotlinx.serialization library when serializing and deserializing Kotlin objects in your application.

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

Although you can use 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.

We recommend installing the bson-kotlinx library to support custom codecs that have configurations to encode defaults, nulls, and define class discriminators.

Add the Serialization Dependencies to Your Project

You must install the official Kotlin serialization library, kotlinx.serialization, to serialize and deserialize data in your application. To learn more about this library, see the kotlinx.serialization GitHub repository.

Select from the following tabs to see how to add the serialization dependencies to your project by using either Gradle or Maven:

implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
implementation("org.mongodb:bson-kotlinx:5.2.0")

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

Annotate Data Classes

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

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

This example shows a sample data class with the following annotations:

• @Serializable: Marks the class as serializable.

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

• @Contextual: Marks the BSON id property to use the built-in ObjectIdSerializer. This annotation is required for the driver to serialize BSON types 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 = "Grumbacher" // Use instead of @BsonProperty
)

To learn more about serializable classes and available annotations, see Serializable classes in the kotlinx.serialization library 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.toEpochMilli()))
            else -> throw SerializationException("Instant is not supported by ${encoder::class}")
        }
    }
    override fun deserialize(decoder: Decoder): Instant {
        return when (decoder) {
            is BsonDecoder -> Instant.ofEpochMilli(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 the driver stores in MongoDB.

Use the BsonConfiguration class to define the configuration, which can include whether to encode defaults, encode nulls, or define class discriminators.

To create a custom codec, your project must have the bson-kotlinx dependency. See the Add the Serialization Dependencies to Your Project section of this guide for installation instructions.

You can define your codec by using the KotlinSerializerCodec.create() method, then you can add the codec to the registry.

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

Polymorphic Serialization

The Kotlin Sync driver natively supports serialization and deserialization of polymorphic classes. When you mark a sealed interface and data classes that inherit that interface with the @Serializable annotation, the driver uses a KSerializer implementation to handle conversion of your types to and from BSON.

When you insert an instance of a polymorphic data class into MongoDB, the driver adds the field _t, the discriminator field. The value of this field is the data class name.

@Serializable
sealed interface Person {
    val name: String
}
@Serializable
data class Student(
    @Contextual
    @SerialName("_id")
    val id: ObjectId,
    override val name: String,
    val grade: Int,
) : Person
@Serializable
data class Teacher(
    @Contextual
    @SerialName("_id")
    val id: ObjectId,
    override val name: String,
    val department: String,
) : Person

val collection = database.getCollection<Person>("school")
val teacherDoc = Teacher(ObjectId(), "Vivian Lee", "History")
val studentDoc = Student(ObjectId(), "Kate Parker", 10)
collection.insertOne(teacherDoc)
collection.insertOne(studentDoc)
println("Retrieving by using data classes")
val resultTeacher = collection.withDocumentClass<Teacher>()
    .find(Filters.exists("department"))
    .firstOrNull()
println(resultTeacher)
val resultStudent = collection.withDocumentClass<Student>()
    .find(Filters.exists("grade"))
    .firstOrNull()
println(resultStudent)
println("\nRetrieving by using Person interface")
val resultsPerson = collection.withDocumentClass<Person>().find()
resultsPerson.forEach { result ->
    println(result)
}
println("\nRetrieving as Document type")
val resultsDocument = collection.withDocumentClass<Document>().find()
resultsDocument.forEach { result ->
    println(result)
}

Retrieving by using data classes
Teacher(id=..., name=Vivian Lee, department=History)
Student(id=..., name=Kate Parker, grade=10)
Retrieving by using Person interface
Teacher(id=..., name=Vivian Lee, department=History)
Student(id=..., name=Kate Parker, grade=10)
Retrieving as Document type
Document{{_id=..., _t=Teacher, name=Vivian Lee, department=History}}
Document{{_id=..., _t=Student, name=Kate Parker, grade=10}}

Serialize Dates and Times

In this section, you can learn about using Kotlin serialization to work with date and time types.

implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.6.1")

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-datetime-jvm</artifactId>
    <version>0.6.1</version>
</dependency>

@Serializable
data class Appointment(
    val name: String,
    @Contextual val date: LocalDate,
    val time: LocalTime,
)

val collection = database.getCollection<Appointment>("appointments")
val apptDoc = Appointment(
    "Daria Smith",
    LocalDate(2024, 10, 15),
    LocalTime(hour = 11, minute = 30)
)
collection.insertOne(apptDoc)

{
  "_id": ...,
  "name": "Daria Smith",
  "date": {
    "$date": "2024-10-15T00:00:00.000Z"
  },
  "time": "11:30",
}