diff --git a/source/fundamentals/data-formats/serialization.txt b/source/fundamentals/data-formats/serialization.txt index d28013af..16f40fad 100644 --- a/source/fundamentals/data-formats/serialization.txt +++ b/source/fundamentals/data-formats/serialization.txt @@ -4,6 +4,13 @@ Kotlin Serialization ==================== +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, data model, conversion + .. contents:: On this page :local: :backlinks: none @@ -13,23 +20,26 @@ Kotlin Serialization Overview -------- -The Kotlin driver supports the ``kotlinx.serialization`` library for serializing -and deserializing Kotlin objects. +The Kotlin driver supports the ``kotlinx.serialization`` library for +serializing and deserializing Kotlin objects. -The driver provides an efficient ``Bson`` serializer that can can be used with +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. -The ``bson-kotlinx`` library also supports :ref:`custom codecs ` -with configurations to encode defaults, encode nulls, and define class -discriminators. +to BSON data. + +You can also install the ``bson-kotlinx`` library to support +:ref:`custom codecs ` with configurations to encode +defaults, encode nulls, and define class discriminators. .. note:: - To use the ``Codec`` interface instead of the Kotlin serialization library - to specify custom encoding and decoding of Kotlin objects to BSON data, - see the :ref:`Codecs ` documentation. You might choose - Kotlin serialization if you are already familiar with the framework or - you prefer to use an idiomatic Kotlin approach. + To learn how to use the ``Codec`` interface instead of the + Kotlin serialization library to specify custom encoding and decoding + of Kotlin objects to BSON data, see the :ref:`Codecs + ` guide. + + You might choose Kotlin serialization if you are already familiar + with the framework or if you prefer to use an idiomatic Kotlin approach. Although you can use the Kotlin driver with the Kotlin serialization ``Json`` library, the ``Json`` serializer does *not* directly support BSON value types such @@ -162,8 +172,22 @@ To create a custom codec, install the ``bson-kotlinx`` dependency to your projec {+full-version+} -Then, you can define your codec using the `KotlinSerializerCodec.create() `__ -method and add it to the registry. +.. note:: bson-kotlin Dependency + + You can also optionally install the ``bson-kotlin`` dependency + through the default codec registry. This dependency uses reflection + and the codec registry to support Kotlin data classes, but it does + not support certain POJO annotations such as ``BsonDiscriminator``, + ``BsonExtraElements``, and ``BsonConstructor``. To learn more, see + the `bson-kotlin API documentation <{+api+}/apidocs/bson-kotlin/index.html>`__. + + Generally, we recommend that you install and use the faster + ``bson-kotlinx`` library for codec configuration. + +Then, you can define your codec using the +`KotlinSerializerCodec.create() +<{+api+}/apidocs/bson-kotlinx/bson-kotlinx/org.bson.codecs.kotlinx/-kotlin-serializer-codec/-companion/index.html>`__ +method and add it to the registry. The following example shows how to create a codec using the ``KotlinSerializerCodec.create()`` method and configure it to not encode defaults: