Merge pull request #36 from ccho-mongodb/DOCSP-12156-data-format-bson

DOCSP-12156: BSON Data Format

Author: Chris Cho

source/fundamentals/data-formats/document-data-format-bson.txt

@@ -13,11 +13,75 @@ Document Data Format: BSON
 Overview
 --------
 
-- Definition of BSON format, where it's used, why it's used.
-- Link to more info on BSON
-- What information you can find in the following sections
+This guide explains the BSON data format, how MongoDB uses it, and how to
+install the BSON library independently of the MongoDB driver.
 
-Installation
-------------
+BSON Data Format
+----------------
 
-- Instructions on how to add the dependency with Maven or Gradle
+**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, different size 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:`Java BSON library <install-bson-library>` to convert it to a JSON
+representation. You can read more about the relationship between these
+formats in our article on :website:`JSON and BSON </json-and-bson>`.
+
+MongoDB and BSON
+----------------
+
+The MongoDB Java Driver, which uses the BSON library, allows you to work
+with BSON data by using one of the object types that implement the
+:java-docs:`Bson <apidocs/bson/org/bson/conversions/Bson.html>` interface,
+including:
+
+- :java-docs:`Document <apidocs/bson/org/bson/Document.html>` (BSON library package)
+- :java-docs:`BsonDocument <apidocs/bson/org/bson/BsonDocument.html>` (BSON library package)
+- :java-docs:`RawBsonDocument <apidocs/bson/org/bson/RawBsonDocument.html>` (BSON library package)
+- :java-docs:`BasicDBObject <apidocs/mongodb-driver-core/com/mongodb/BasicDBObject.html>` (Java Driver package)
+
+For more information on using these object types, see our
+:doc:`Documents guide <fundamentals/data-formats/documents>`.
+
+.. _install-bson-library:
+
+Install the BSON Library
+------------------------
+
+These instructions show you how to add the BSON library as a dependency to
+your project. If you added the MongoDB Java driver as a dependency to your
+project, you can skip this step since the BSON library is already included
+as a required dependency of the driver. For instructions on how to add the
+MongoDB driver as a dependency to your project, see the
+:ref:`driver installation <add-mongodb-dependency>` section of our Quick Start
+guide.
+
+We recommend that you use the `Maven <https://maven.apache.org/>`__ or
+`Gradle <https://gradle.org/>`__ build automation tool to manage your project
+dependencies. Select from the tabs below 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/fundamentals/code-snippets/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/fundamentals/code-snippets/bson-gradle-versioned.rst
+
+If you are not using one of the tools listed above, you can include it in
+your project by downloading the JAR file directly from the
+`sonatype repository <https://repo1.maven.org/maven2/org/mongodb/bson/>`__.

source/includes/fundamentals/code-snippets/bson-gradle-versioned.rst

@@ -0,0 +1,6 @@
+.. code-block:: groovy
+
+   dependencies {
+      compile 'org.mongodb:bson:4.1.0'
+   }
+

source/includes/fundamentals/code-snippets/bson-maven-versioned.rst

@@ -0,0 +1,10 @@
+.. code-block:: xml
+
+   <dependencies>
+       <dependency>
+           <groupId>org.mongodb</groupId>
+           <artifactId>bson</artifactId>
+           <version>4.1.0</version>
+       </dependency>
+   </dependencies>
+

source/quick-start.txt

@@ -25,11 +25,13 @@ Create the Project
 
 .. include:: /includes/quick-start/create-project.rst
 
+.. _add-mongodb-dependency:
+
 Add MongoDB as a Dependency
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you are using Maven, add the following to your ``pom.xml`` dependencies
-list:
+If you are using `Maven <https://maven.apache.org/>`__, add the following to 
+your ``pom.xml`` dependencies list:
 
 .. code-block:: xml
 
@@ -41,8 +43,8 @@ list:
        </dependency>
    </dependencies>
 
-If you are using Gradle, add the following to your ``build.gradle``
-dependencies list:
+If you are using `Gradle <https://gradle.org/>`__, add the following to your
+``build.gradle`` dependencies list:
 
 .. code-block:: groovy