DOCPS-41150: Specialized Data Formats + BSON

snooty.toml

@@ -11,6 +11,7 @@ toc_landing_pages = [
     "/connect",
     "/indexes",
     "work-with-indexes",
+    "/data-formats"
 ]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
@@ -21,8 +22,9 @@ driver-short = "Kotlin Sync driver"
 language = "Kotlin"
 version-number = "5.1"
 version = "v{+version-number+}"
-patch-version-number = "{+version-number+}.0"
+patch-version-number = "{+version-number+}.2"
 mdb-server = "MongoDB Server"
 stable-api = "Stable API"
 api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
-core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core/"
+java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}"
+core-api = "{+java-api+}/apidocs/mongodb-driver-core/"

source/data-formats.txt

@@ -0,0 +1,42 @@
+.. _kotlin-sync-data-formats:
+
+========================
+Specialized Data Formats
+========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: bson, data, class, date, time 
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   /data-formats/bson
+
+..     TODO: /data-formats/data-class
+..     TODO: /data-formats/extended-json
+..     TODO: /data-formats/time-series
+
+Overview
+--------
+
+You can use several types of specialized data formats in your {+driver-short+}
+application. To learn how to work with these data formats, see the following
+sections:
+
+- Learn how to work with the BSON data format in the :ref:`BSON <kotlin-sync-bson>` guide.
+
+.. TODO: Uncomment these as pages get built
+.. - Learn how to store and retrieve data using {+language+} data classes in the :ref:`data-classes` guide.
+.. - Learn how to use the Extended JSON format in the :ref:`kotlin-sync-extended-json` guide.
+.. - Learn how to store and interact with time series data in the :ref:`kotlin-sync-time-series` guide.

source/data-formats/bson.txt

@@ -0,0 +1,89 @@
+.. _kotlin-sync-bson:
+
+==========================
+Document Data Format: BSON
+==========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn about the BSON data format, how MongoDB
+uses it, and how to install the BSON library independently of the
+{+driver-short+}.
+
+BSON Data Format
+----------------
+
+**BSON**, or Binary JSON, is the data format that MongoDB uses to organize
+and store data. This data format includes all JSON data structure types and
+adds support for types including dates, differently-sized integers, ObjectIds, and
+binary data. For a complete list of supported types, see the
+:manual:`BSON Types </reference/bson-types>` server manual page.
+
+The binary format is not human-readable, but you can use the
+:ref:`BSON library <install-bson-library>` to convert it to the human-readable JSON
+representation. You can read more about the relationship between these
+formats in the :website:`JSON and BSON </json-and-bson>` guide on the MongoDB website.
+
+MongoDB and BSON
+----------------
+
+You can use BSON data with your {+driver-short+} application by using one of the
+following object types that implements the `BSON interface <{+java-api+}/apidocs/bson/org/bson/conversions/Bson.html>`__:
+
+- `Document <{+java-api+}/apidocs/bson/org/bson/Document.html>`__ (BSON library package)
+- `BsonDocument <{+java-api+}/apidocs/bson/org/bson/BsonDocument.html>`__ (BSON library package)
+- `RawBsonDocument <{+java-api+}/apidocs/bson/org/bson/RawBsonDocument.html>`__ (BSON library package)
+- `JsonObject <{+java-api+}/apidocs/bson/org/bson/json/JsonObject.html>`__ (BSON library package)
+
+.. _install-bson-library:
+
+Install the BSON Library
+------------------------
+
+These instructions detail how to add the BSON library as a dependency to
+your project.
+
+.. note::
+
+   If you have already added the {+driver-short+} as a dependency to your
+   project, then you can skip this step. This is because the BSON library is already
+   included as a required dependency of the driver.
+
+.. TODO: For instructions on how to add the
+.. MongoDB Kotlin driver as a dependency to your project, see the
+.. :ref:`driver installation <kotlin-sync-download-install>` section of our Get Started
+.. guide.
+
+We recommend that you use the `Maven <https://maven.apache.org/>`__ or
+`Gradle <https://gradle.org/>`__ build automation tool to manage your {+language+}
+project's dependencies. Select from the following tabs to see the dependency declaration
+for that tool:
+
+.. tabs::
+
+   .. tab:: Maven
+      :tabid: maven-dependencies
+
+      The following snippet shows the dependency declaration in the
+      ``dependencies`` section of your ``pom.xml`` file.
+
+      .. include:: /includes/data-formats/bson-maven-versioned.rst
+
+   .. tab:: Gradle
+      :tabid: gradle-dependencies
+
+      The following snippet shows the dependency declaration in the
+      ``dependencies`` object in your ``build.gradle`` file.
+
+      .. include:: /includes/data-formats/bson-gradle-versioned.rst
+
+If you are not using either of the preceding tools, then you can include the BSON dependency
+in your project by downloading the JAR file directly from the
+`sonatype repository <https://repo1.maven.org/maven2/org/mongodb/bson/>`__.

source/includes/data-formats/bson-gradle-versioned.rst

@@ -0,0 +1,5 @@
+.. code-block:: kotlin
+
+   dependencies {
+      implementation("org.mongodb:bson:{+patch-version-number+}")
+   }

source/includes/data-formats/bson-maven-versioned.rst

@@ -0,0 +1,9 @@
+.. code-block:: xml
+
+   <dependencies>
+       <dependency>
+           <groupId>org.mongodb</groupId>
+           <artifactId>bson</artifactId>
+           <version>{+patch-version-number+}</version>
+       </dependency>
+   </dependencies>

source/index.txt

@@ -17,6 +17,7 @@
    /write-operations
    /read
    /indexes
+   /data-formats
    /faq
    /connection-troubleshooting
    /issues-and-help
@@ -76,6 +77,18 @@ Read Data from MongoDB
 
 Learn how you can retrieve data from MongoDB in the :ref:`kotlin-sync-read` section.
 
+Optimize Queries with Indexes
+-----------------------------
+
+Learn how to work with common types of indexes in the :ref:`kotlin-sync-indexes`
+section.
+
+Specialized Data Formats
+------------------------
+
+Learn how to work with specialized data formats and custom types in the
+:ref:`kotlin-sync-data-formats` section.
+
 FAQ
 ---