• December 21, 2025
• 2 min read

0.25.0 • BsonContext/BsonFactory split, serialization annotation support, experimental BsonPath and eager multiplatform BSON

BsonContext and BsonFactory

Breaking change

Impacted modules: :bson, :dsl

See: #95, !157

Since the start of the project, the configuration of BSON documents is stored by the BsonContext interface. However, it was starting to become too big. Initially, BsonContext was used for BSON object creation. In 0.19.0, it obtained the capability of creating ObjectId instances. In this version, it would also have obtained the configuration for serializing paths.

In this release, it is changed as follows:

• The BsonContext is removed from :bson.
• The new BsonFactory interface becomes responsible from creating BSON documents.
• The capability of creating new ObjectId instances remains in ObjectIdGenerator.
• A new BsonContext interface is created in :dsl, which aggregates the capabilities required by the DSL.

If you created custom operators, you will need to switch the imports from the old BsonContext to the new one.

Otherwise, end-users should not be impacted.

PropertyNameStrategy

Impacted modules: :dsl, :driver-sync-kmongo, :driver-coroutines-kmongo

See: #89, !151, !157

The new interface PropertyNameStrategy was added to configure how the Foo::user / User::name syntax is converted into MongoDB paths. Users can override the default implementation when initializing the KtMongo library. For example, this can be used to look up annotations on the fields to change their name.

When using one of the KMongo compatibility modules, the strategy used understands @BsonId and KotlinX.Serialization's @SerialName, as recommended by the KMongo documentation for the KotlinX.Serialization library.

If you use Jackson or want to use KotlinX.Serialization annotations with the regular driver modules (without using the KMongo compatibility modules) you can override the PropertyNameStrategy used by the driver.

We do not plan to add support for serialization annotations in the default implementation.

As a consequence, some methods have been moved from Field to FieldDsl.

BsonPath

Experimental

Impacted modules: :bson

See: #2, #93, #146

Added the experimental BsonPath interface to represent JSONPath-like accessors to BSON documents.

BsonPath is a great alternative to deserialization when we are only interested in a few fields, as it avoids the need for creating complex DTOs, especially when they are deeply nested.

val path = BsonPath.parse("$.users.1.name")

val name: String = myDocument at path

BSON

• Removed @ExperimentalStdlibApi on the ObjectId constructor as it has been stabilized in the standard library (b9ccf073)
• ObjectId.Serializer has been changed from a class to an object (88f6947e)
• Timestamp.Serializer has been changed from a class to an object (88f6947e)

BSON (multiplatform)

• Instances of .reader() are now reused. This will make access to fields faster (60397c9d)
• Added Bson.eager() and BsonArray.eager() to eagerly initialize the readers, which makes them thread-safe. Improved the documentation on thread-safety (!167)
• Improved the documentation of Bson and BsonArray (!167)

Dependencies

• Kotlin 2.2.21