From 691b493234ec0fa7100c259b2c0b5d2095d74175 Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Thu, 3 Apr 2025 23:28:33 -0400
Subject: [PATCH 01/14] DOCSP-48390 Document Data Formats: EJSON

---
 source/data-formats/bson.txt          |   1 -
 source/data-formats/extended-json.txt | 206 ++++++++++++++++++++++++++
 2 files changed, 206 insertions(+), 1 deletion(-)
 create mode 100644 source/data-formats/extended-json.txt

diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt
index 25fd0f948..28e2c294a 100644
--- a/source/data-formats/bson.txt
+++ b/source/data-formats/bson.txt
@@ -138,4 +138,3 @@ API Documentation
 
 To learn more about any of the methods or types discussed in this
 guide, see the `BSON <{+api+}/modules/BSON.html>`__ API documentation.
-
diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
new file mode 100644
index 000000000..71a0816e7
--- /dev/null
+++ b/source/data-formats/extended-json.txt
@@ -0,0 +1,206 @@
+. _node-extended-json:
+
+=============
+Extended JSON
+=============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+ 
+.. meta::
+   :keywords: code examples, bson, relaxed, canonical, legacy
+
+Overview
+--------
+
+JSON is a data format that represents the values of objects, arrays, numbers,
+strings, booleans, and nulls. The **Extended JSON** format defines a reserved
+set of keys prefixed with "``$``" to represent field type information that
+directly corresponds to each type in BSON, the format that MongoDB uses to
+store data.
+
+Extended JSON Formats
+---------------------
+
+MongoDB Extended JSON features different string formats to represent BSON data.
+Each of the different formats conform to the JSON RFC
+and meet specific use cases. The **extended** format, also known as the
+**canonical** format, features specific representations for every BSON type
+for bidirectional conversion without loss of information. The **Relaxed mode**
+format is more concise and closer to ordinary JSON, but does not represent
+all the type information such as the specific byte size of number fields.
+
+See the following table to see a description of each format:
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 10 40
+
+   * - Name
+     - Description
+
+   * - **Extended**
+     - | Also known as the *canonical* format, this JSON representation avoids loss of
+         BSON type information.
+       | This format prioritizes type preservation at the loss of human-readability and
+         interoperability with older formats.
+
+   * - **Relaxed Mode**
+     - | JSON representation that describes BSON documents with some type information loss.
+       | This format prioritizes human-readability and interoperability at the loss of
+         certain type information.
+
+.. note::
+
+   The driver parses the ``$uuid`` Extended JSON type from a string to a
+   ``BsonBinary`` object of binary subtype 4. For more information about ``$uuid`` field
+   parsing, see the
+   :spec:`special rules for parsing $uuid fields </extended-json.rst#special-rules-for-parsing-uuid-fields>`
+   section in the extended JSON specification.
+
+To learn more about JSON, BSON, and Extended JSON, see
+`our article about JSON and BSON <https://www.mongodb.com/resources/basics/json-and-bson>`__
+and :manual:`Extended JSON </reference/mongodb-extended-json/>` in the {+mdb-server+} manual.
+
+.. _extended_json_example_section:
+
+Extended JSON Examples
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following examples show a document containing an ObjectId, date, and long
+number field represented in each Extended JSON format. Click the tab that
+corresponds to the format of the example you want to see:
+
+.. tabs::
+
+   .. tab:: Extended
+      :tabid: extended-format
+
+      .. code-block:: json
+
+         {
+           "_id": { "$oid": "573a1391f29313caabcd9637" },
+           "createdAt": { "$date": { "$numberLong": "1601499609" }},
+           "numViews": { "$numberLong": "36520312" }
+         }
+
+   .. tab:: Relaxed Mode
+      :tabid: relaxed-mode-format
+
+      .. code-block:: json
+
+         {
+           "_id": { "$oid": "573a1391f29313caabcd9637" },
+           "createdAt": { "$date": "2020-09-30T18:22:51.648Z" },
+           "numViews": 36520312
+         }
+
+Read Extended JSON
+------------------
+
+You can read an Extended JSON string into the JavaScript value or object described 
+by the string by using the ``EJSON.parse()`` method. 
+
+The following example shows how you can read an Extended JSON string into a
+JavaScript value or object by using the ``parse()`` method:
+
+.. io-code-block::
+
+   .. input::
+      :language: javascript
+
+      import { BSON } from 'mongodb';
+      const EJSON = BSON.EJSON;
+
+      const ejson_str = '[{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}}]'
+
+      const doc = EJSON.parse(ejson_str);
+      console.log(doc)
+
+   .. output::
+      :language: none
+      :visible: false
+
+      [
+         {'foo': [1, 2]},
+         {'bar': {'hello': 'world'}},
+         {'code': Code('function x() { return 1; }', {})}
+      ]
+
+Write Extended JSON
+-------------------
+
+You can write an Extended JSON string from a BSON document object by using the
+``EJSON.stringify()`` method.
+
+The following example outputs an Extended JSON string in the Relaxed format:
+
+.. io-code-block::
+
+   .. input::
+      :language: js
+
+      const { EJSON } = require('bson');
+
+      doc = [
+         {'foo': [1, 2]},
+         {'bar': {'hello': 'world'}},
+         {'code': Code('function x() { return 1; }', {})}
+      ]
+
+      const ejson_str = EJSON.stringify(doc);
+      console.log(ejson_str);
+
+   .. output::
+      :language: none
+      :visible: false
+
+      [{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}}]
+
+By default, the ``stringify()`` method returns the Extended JSON string in the 
+Relaxed format. To specify the Canonical format, set the ``relaxed`` 
+option to ``false``.
+
+The following example shows how to output Extended JSON in the Canonical format:
+
+.. io-code-block::
+
+   .. input::
+      :language: js
+
+      const { EJSON } = require('bson');
+
+      doc = [
+         {'foo': [1, 2]},
+         {'bar': {'hello': 'world'}},
+         {'code': Code('function x() { return 1; }', {})}
+      ]
+
+      const ejson_str = EJSON.stringify(doc, { relaxed: false });
+      print(ejson_str)
+
+   .. output::
+      :language: none
+      :visible: false
+
+      [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}}]
+
+Additional Information
+----------------------
+
+The resources in the following sections provide more information about working
+with Extended JSON.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the methods or types discussed in this
+guide, see the `EJSON <https://github.com/mongodb/js-bson#ejson>`__ API documentation.

From 38c0fce8d59241bb76c7d73b4cdbfbf40efbcb05 Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Thu, 3 Apr 2025 23:51:17 -0400
Subject: [PATCH 02/14] add to toc and bson import note

---
 source/data-formats.txt               |  1 +
 source/data-formats/bson.txt          | 20 +++++++++++++++-----
 source/data-formats/extended-json.txt |  6 +++---
 3 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/source/data-formats.txt b/source/data-formats.txt
index 4a0c516fd..a0b28f2a8 100644
--- a/source/data-formats.txt
+++ b/source/data-formats.txt
@@ -22,6 +22,7 @@ Specialized Data Formats
    :maxdepth: 1
 
    BSON </data-formats/bson>
+   Extended JSON <data-formats/extended-json>
    Time Series Data </data-formats/time-series>
 
 Overview
diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt
index 28e2c294a..331db738b 100644
--- a/source/data-formats/bson.txt
+++ b/source/data-formats/bson.txt
@@ -1,9 +1,9 @@
 .. _node-bson-control:
 .. _node-bson:
 
-==============
-Work with BSON
-==============
+===================
+Work with BSON Data
+===================
 
 .. default-domain:: mongodb
 
@@ -40,6 +40,16 @@ The code samples in this guide use the following BSON document as an example:
        "name" : "Mongo's Pizza"
    }
 
+.. note:: Use the {+driver-short+}'s BSON package
+
+   We recommend that you use the BSON package that is bundled with the driver to avoid
+   compatibility issues with other BSON packages. You can import the {+driver-short+}'s 
+   BSON package with the following import statement:
+
+   .. code-block::
+
+       import { BSON } from 'mongodb';  
+
 Create a BSON Document
 ----------------------
 
@@ -91,7 +101,7 @@ The following example writes the sample BSON document to ``file.bson``:
 .. code-block:: javascript
 
    import fs from 'fs/promises';  // Import the file system module
-   import { BSON } from 'bson';  // Import the BSON package
+   import { BSON } from 'mongodb';  // Import the BSON package
 
    // Create a BSON object
    const bsonData = BSON.serialize(result);
@@ -115,7 +125,7 @@ The following example reads the sample BSON document from ``file.bson``:
       :language: javascript
 
       import fs from 'fs/promises';  // Import the file system module
-      import { BSON } from 'bson';  // Import the BSON package
+      import { BSON } from 'mongodb';  // Import the BSON package
 
       // Read the BSON data from a file
       const data = await fs.readFile('file.bson');
diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index 71a0816e7..ae16bb84c 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -1,8 +1,8 @@
 . _node-extended-json:
 
-=============
-Extended JSON
-=============
+============================
+Work with Extended JSON Data
+============================
 
 .. contents:: On this page
    :local:

From bd76c8391a4db27f4d8e681943b39bb80327faf7 Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Thu, 3 Apr 2025 23:59:42 -0400
Subject: [PATCH 03/14] edit

---
 source/data-formats/extended-json.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index ae16bb84c..ab72a67ad 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -1,4 +1,4 @@
-. _node-extended-json:
+.. _node-extended-json:
 
 ============================
 Work with Extended JSON Data

From cb976a4d6eb4bbcd99e513a0eaa4f287fc4ac312 Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Fri, 4 Apr 2025 15:29:43 -0400
Subject: [PATCH 04/14] add binary type

---
 source/data-formats/extended-json.txt | 71 ++++++++++++++-------------
 1 file changed, 36 insertions(+), 35 deletions(-)

diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index ab72a67ad..f05efbd08 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -103,38 +103,6 @@ corresponds to the format of the example you want to see:
            "numViews": 36520312
          }
 
-Read Extended JSON
-------------------
-
-You can read an Extended JSON string into the JavaScript value or object described 
-by the string by using the ``EJSON.parse()`` method. 
-
-The following example shows how you can read an Extended JSON string into a
-JavaScript value or object by using the ``parse()`` method:
-
-.. io-code-block::
-
-   .. input::
-      :language: javascript
-
-      import { BSON } from 'mongodb';
-      const EJSON = BSON.EJSON;
-
-      const ejson_str = '[{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}}]'
-
-      const doc = EJSON.parse(ejson_str);
-      console.log(doc)
-
-   .. output::
-      :language: none
-      :visible: false
-
-      [
-         {'foo': [1, 2]},
-         {'bar': {'hello': 'world'}},
-         {'code': Code('function x() { return 1; }', {})}
-      ]
-
 Write Extended JSON
 -------------------
 
@@ -153,7 +121,8 @@ The following example outputs an Extended JSON string in the Relaxed format:
       doc = [
          {'foo': [1, 2]},
          {'bar': {'hello': 'world'}},
-         {'code': Code('function x() { return 1; }', {})}
+         {'code': Code('function x() { return 1; }', {})},
+         {"$binary": {"base64":"AQIDBA==","subType":"00"}}
       ]
 
       const ejson_str = EJSON.stringify(doc);
@@ -163,7 +132,7 @@ The following example outputs an Extended JSON string in the Relaxed format:
       :language: none
       :visible: false
 
-      [{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}}]
+      [{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}},{"$binary":{"base64":"AQIDBA==","subType":"00"}}]
 
 By default, the ``stringify()`` method returns the Extended JSON string in the 
 Relaxed format. To specify the Canonical format, set the ``relaxed`` 
@@ -191,7 +160,39 @@ The following example shows how to output Extended JSON in the Canonical format:
       :language: none
       :visible: false
 
-      [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}}]
+      [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}}, {"$binary":{"base64":"AQIDBA==","subType":"00"}}]
+
+Read Extended JSON
+------------------
+
+You can read an Extended JSON string into the JavaScript value or object described 
+by the string by using the ``EJSON.parse()`` method. 
+
+The following example shows how you can read an Extended JSON string into a
+JavaScript value or object by using the ``parse()`` method:
+
+.. io-code-block::
+
+   .. input::
+      :language: javascript
+
+      import { BSON } from 'mongodb';
+      const EJSON = BSON.EJSON;
+
+      const ejson_str = '[{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}}]'
+
+      const doc = EJSON.parse(ejson_str);
+      console.log(doc)
+
+   .. output::
+      :language: none
+      :visible: false
+
+      [
+         {'foo': [1, 2]},
+         {'bar': {'hello': 'world'}},
+         {'code': Code('function x() { return 1; }', {})}
+      ]
 
 Additional Information
 ----------------------

From c126f62d8a012b3b7cd71a21e67021169fd941ff Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Fri, 4 Apr 2025 16:11:22 -0400
Subject: [PATCH 05/14] edit ouputs

---
 source/data-formats/extended-json.txt | 54 ++++++++++++++-------------
 1 file changed, 28 insertions(+), 26 deletions(-)

diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index f05efbd08..fe77bf681 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -31,9 +31,9 @@ Extended JSON Formats
 
 MongoDB Extended JSON features different string formats to represent BSON data.
 Each of the different formats conform to the JSON RFC
-and meet specific use cases. The **extended** format, also known as the
+and meet specific use cases. The **Extended** format, also known as the
 **canonical** format, features specific representations for every BSON type
-for bidirectional conversion without loss of information. The **Relaxed mode**
+for bidirectional conversion without loss of information. The **Relaxed Mode**
 format is more concise and closer to ordinary JSON, but does not represent
 all the type information such as the specific byte size of number fields.
 
@@ -58,14 +58,6 @@ See the following table to see a description of each format:
        | This format prioritizes human-readability and interoperability at the loss of
          certain type information.
 
-.. note::
-
-   The driver parses the ``$uuid`` Extended JSON type from a string to a
-   ``BsonBinary`` object of binary subtype 4. For more information about ``$uuid`` field
-   parsing, see the
-   :spec:`special rules for parsing $uuid fields </extended-json.rst#special-rules-for-parsing-uuid-fields>`
-   section in the extended JSON specification.
-
 To learn more about JSON, BSON, and Extended JSON, see
 `our article about JSON and BSON <https://www.mongodb.com/resources/basics/json-and-bson>`__
 and :manual:`Extended JSON </reference/mongodb-extended-json/>` in the {+mdb-server+} manual.
@@ -76,7 +68,7 @@ Extended JSON Examples
 ~~~~~~~~~~~~~~~~~~~~~~
 
 The following examples show a document containing an ObjectId, date, and long
-number field represented in each Extended JSON format. Click the tab that
+number field represented in the Extended JSON format. Click the tab that
 corresponds to the format of the example you want to see:
 
 .. tabs::
@@ -116,13 +108,13 @@ The following example outputs an Extended JSON string in the Relaxed format:
    .. input::
       :language: js
 
-      const { EJSON } = require('bson');
+      const { Binary, Code, EJSON } = require('bson');
 
       doc = [
-         {'foo': [1, 2]},
-         {'bar': {'hello': 'world'}},
-         {'code': Code('function x() { return 1; }', {})},
-         {"$binary": {"base64":"AQIDBA==","subType":"00"}}
+         {"foo": [1, 2]},
+         {"bar": {"hello": "world"}},
+         {"code": new Code("function x() { return 1; }", {})},
+         {"bin": Binary.createFromBase64("AQIDBA==", 0)}
       ]
 
       const ejson_str = EJSON.stringify(doc);
@@ -132,7 +124,7 @@ The following example outputs an Extended JSON string in the Relaxed format:
       :language: none
       :visible: false
 
-      [{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}},{"$binary":{"base64":"AQIDBA==","subType":"00"}}]
+      [{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"00"}}}]
 
 By default, the ``stringify()`` method returns the Extended JSON string in the 
 Relaxed format. To specify the Canonical format, set the ``relaxed`` 
@@ -145,12 +137,13 @@ The following example shows how to output Extended JSON in the Canonical format:
    .. input::
       :language: js
 
-      const { EJSON } = require('bson');
+      const { Binary, Code, EJSON } = require('bson');
 
       doc = [
-         {'foo': [1, 2]},
-         {'bar': {'hello': 'world'}},
-         {'code': Code('function x() { return 1; }', {})}
+         {"foo": [1, 2]},
+         {"bar": {"hello": "world"}},
+         {"code": new Code("function x() { return 1; }", {})},
+         {"bin": Binary.createFromBase64("AQIDBA==", 0)}
       ]
 
       const ejson_str = EJSON.stringify(doc, { relaxed: false });
@@ -160,7 +153,7 @@ The following example shows how to output Extended JSON in the Canonical format:
       :language: none
       :visible: false
 
-      [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}}, {"$binary":{"base64":"AQIDBA==","subType":"00"}}]
+      [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"00"}}}]
 
 Read Extended JSON
 ------------------
@@ -179,7 +172,7 @@ JavaScript value or object by using the ``parse()`` method:
       import { BSON } from 'mongodb';
       const EJSON = BSON.EJSON;
 
-      const ejson_str = '[{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}}]'
+      const ejson_str = '[{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$code":"function x() { return 1; }","$scope":{}}},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"00"}}}]'
 
       const doc = EJSON.parse(ejson_str);
       console.log(doc)
@@ -189,11 +182,20 @@ JavaScript value or object by using the ``parse()`` method:
       :visible: false
 
       [
-         {'foo': [1, 2]},
-         {'bar': {'hello': 'world'}},
-         {'code': Code('function x() { return 1; }', {})}
+        { foo: [ 1, 2 ] },
+        { bar: { hello: 'world' } },
+        { code: new Code('function x() { return 1; }', {}) },
+        { bin: Binary.createFromBase64('AQIDBA==', 0) }
       ]
 
+.. note::
+
+   The driver parses the ``$uuid`` Extended JSON type from a string to a
+   ``BsonBinary`` object of binary subtype 4. For more information about ``$uuid`` field
+   parsing, see the
+   :spec:`special rules for parsing $uuid fields </extended-json.rst#special-rules-for-parsing-uuid-fields>`
+   section in the extended JSON specification.
+
 Additional Information
 ----------------------
 

From 4b9dfa980b8f0bd345f78f3ed4886cae614c384d Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Fri, 4 Apr 2025 16:17:27 -0400
Subject: [PATCH 06/14] remove additional info section

---
 source/data-formats/extended-json.txt | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index fe77bf681..4fa587f97 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -196,14 +196,8 @@ JavaScript value or object by using the ``parse()`` method:
    :spec:`special rules for parsing $uuid fields </extended-json.rst#special-rules-for-parsing-uuid-fields>`
    section in the extended JSON specification.
 
-Additional Information
-----------------------
-
-The resources in the following sections provide more information about working
-with Extended JSON.
-
 API Documentation
-~~~~~~~~~~~~~~~~~
+-----------------
 
 To learn more about any of the methods or types discussed in this
 guide, see the `EJSON <https://github.com/mongodb/js-bson#ejson>`__ API documentation.

From 9675fa9ff7e88a5a4b8998f74e3b2f47e5b85fb7 Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Fri, 4 Apr 2025 16:22:43 -0400
Subject: [PATCH 07/14] last small edits

---
 source/data-formats/bson.txt          | 2 +-
 source/data-formats/extended-json.txt | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt
index 331db738b..d37a34e84 100644
--- a/source/data-formats/bson.txt
+++ b/source/data-formats/bson.txt
@@ -46,7 +46,7 @@ The code samples in this guide use the following BSON document as an example:
    compatibility issues with other BSON packages. You can import the {+driver-short+}'s 
    BSON package with the following import statement:
 
-   .. code-block::
+   .. code-block:: js
 
        import { BSON } from 'mongodb';  
 
diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index 4fa587f97..1107c41e4 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -32,7 +32,7 @@ Extended JSON Formats
 MongoDB Extended JSON features different string formats to represent BSON data.
 Each of the different formats conform to the JSON RFC
 and meet specific use cases. The **Extended** format, also known as the
-**canonical** format, features specific representations for every BSON type
+**Canonical** format, features specific representations for every BSON type
 for bidirectional conversion without loss of information. The **Relaxed Mode**
 format is more concise and closer to ordinary JSON, but does not represent
 all the type information such as the specific byte size of number fields.
@@ -48,7 +48,7 @@ See the following table to see a description of each format:
      - Description
 
    * - **Extended**
-     - | Also known as the *canonical* format, this JSON representation avoids loss of
+     - | Also known as the *Canonical* format, this JSON representation avoids loss of
          BSON type information.
        | This format prioritizes type preservation at the loss of human-readability and
          interoperability with older formats.
@@ -193,7 +193,7 @@ JavaScript value or object by using the ``parse()`` method:
    The driver parses the ``$uuid`` Extended JSON type from a string to a
    ``BsonBinary`` object of binary subtype 4. For more information about ``$uuid`` field
    parsing, see the
-   :spec:`special rules for parsing $uuid fields </extended-json.rst#special-rules-for-parsing-uuid-fields>`
+   :spec:`special rules for parsing $uuid fields <extended-json/extended-json.md#special-rules-for-parsing-uuid-fields>`
    section in the extended JSON specification.
 
 API Documentation

From a1666e840f52af63ce749119342a795c8717749f Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Fri, 4 Apr 2025 16:28:30 -0400
Subject: [PATCH 08/14] fix link

---
 source/data-formats/extended-json.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index 1107c41e4..c66983a45 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -193,7 +193,7 @@ JavaScript value or object by using the ``parse()`` method:
    The driver parses the ``$uuid`` Extended JSON type from a string to a
    ``BsonBinary`` object of binary subtype 4. For more information about ``$uuid`` field
    parsing, see the
-   :spec:`special rules for parsing $uuid fields <extended-json/extended-json.md#special-rules-for-parsing-uuid-fields>`
+   :spec:`special rules for parsing $uuid fields </extended-json/extended-json.md#special-rules-for-parsing-uuid-fields>`
    section in the extended JSON specification.
 
 API Documentation

From 72f0019a7ef3f5c07ff0ee6fab54341959fb9fa8 Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Fri, 4 Apr 2025 16:35:09 -0400
Subject: [PATCH 09/14] edit

---
 source/data-formats/extended-json.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index c66983a45..929fbe63e 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -193,7 +193,7 @@ JavaScript value or object by using the ``parse()`` method:
    The driver parses the ``$uuid`` Extended JSON type from a string to a
    ``BsonBinary`` object of binary subtype 4. For more information about ``$uuid`` field
    parsing, see the
-   :spec:`special rules for parsing $uuid fields </extended-json/extended-json.md#special-rules-for-parsing-uuid-fields>`
+   :spec:`Special Rules for Parsing $uuid Fields </extended-json/extended-json.md#special-rules-for-parsing-uuid-fields>`
    section in the extended JSON specification.
 
 API Documentation

From 8c4971ede7b73a22e14df0f4a2c3317723261d3d Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Wed, 9 Apr 2025 17:14:56 -0400
Subject: [PATCH 10/14] tech review

---
 source/data-formats/extended-json.txt | 60 ++++++++++++++++-----------
 1 file changed, 36 insertions(+), 24 deletions(-)

diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index 929fbe63e..614e2685b 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -35,7 +35,7 @@ and meet specific use cases. The **Extended** format, also known as the
 **Canonical** format, features specific representations for every BSON type
 for bidirectional conversion without loss of information. The **Relaxed Mode**
 format is more concise and closer to ordinary JSON, but does not represent
-all the type information such as the specific byte size of number fields.
+all the type information such as the specific bit width of numeric fields.
 
 See the following table to see a description of each format:
 
@@ -108,23 +108,24 @@ The following example outputs an Extended JSON string in the Relaxed format:
    .. input::
       :language: js
 
-      const { Binary, Code, EJSON } = require('bson');
+      import { Binary, Code, BSON } from 'mongodb';
+      const EJSON = BSON.EJSON;
 
-      doc = [
-         {"foo": [1, 2]},
-         {"bar": {"hello": "world"}},
-         {"code": new Code("function x() { return 1; }", {})},
-         {"bin": Binary.createFromBase64("AQIDBA==", 0)}
-      ]
+      const doc = {
+         { foo: [1, 2] },
+         { bar: { hello: "world" } },
+         { code: new Code("function x() { return 1; }", {}) },
+         { date: new Date(2024, 6, 20, 10, 30, 0) },
+      };
 
-      const ejson_str = EJSON.stringify(doc);
-      console.log(ejson_str);
+      const ejsonStr = EJSON.stringify(doc);
+      console.log(ejsonStr);
 
    .. output::
       :language: none
       :visible: false
 
-      [{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"00"}}}]
+      [{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$code":"function x() { return 1; }","$scope":{}}},{"date":{"$date":"2024-07-20T14:30:00Z"}}]
 
 By default, the ``stringify()`` method returns the Extended JSON string in the 
 Relaxed format. To specify the Canonical format, set the ``relaxed`` 
@@ -139,21 +140,21 @@ The following example shows how to output Extended JSON in the Canonical format:
 
       const { Binary, Code, EJSON } = require('bson');
 
-      doc = [
-         {"foo": [1, 2]},
-         {"bar": {"hello": "world"}},
-         {"code": new Code("function x() { return 1; }", {})},
-         {"bin": Binary.createFromBase64("AQIDBA==", 0)}
-      ]
+      const doc = {
+         { foo: [1, 2] },
+         { bar: { hello: "world" } },
+         { code: new Code("function x() { return 1; }", {}) },
+         { date: new Date(2024, 6, 20, 10, 30, 0) },
+      };
 
-      const ejson_str = EJSON.stringify(doc, { relaxed: false });
-      print(ejson_str)
+      const ejsonStr = EJSON.stringify(doc, { relaxed: false });
+      print(ejsonStr)
 
    .. output::
       :language: none
       :visible: false
 
-      [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bar":{"hello":"world"}},{"code":{"$scope":{},"$code":"function x() { return 1; }"}},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"00"}}}]
+      [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bar":{"hello":"world"}},{"code":{"$code":"function x() { return 1; }","$scope":{}}},{"date":{"$date":{"$numberLong":"1721485800000"}}}]
 
 Read Extended JSON
 ------------------
@@ -172,10 +173,21 @@ JavaScript value or object by using the ``parse()`` method:
       import { BSON } from 'mongodb';
       const EJSON = BSON.EJSON;
 
-      const ejson_str = '[{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$code":"function x() { return 1; }","$scope":{}}},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"00"}}}]'
-
-      const doc = EJSON.parse(ejson_str);
-      console.log(doc)
+      const ejsonStr = const ejsonStr = `{
+         "foo": [
+            { "$numberInt": "1" },
+            { "$numberInt": "2" }
+         ],
+         "bar": { "hello": "world" },
+         "code": {
+            "$code": "function x() { return 1; }",
+            "$scope": {}
+         },
+         "bin": { "$binary": { "base64": "AQIDBA==", "subType": "00" } }
+      }`;
+
+      const doc = EJSON.parse(ejsonStr);
+      console.log(doc);
 
    .. output::
       :language: none

From 86af80415c542992c615c72b8a3dfe53ee100b68 Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Thu, 10 Apr 2025 17:00:25 -0400
Subject: [PATCH 11/14] edits

---
 source/data-formats/extended-json.txt | 21 +++++----------------
 1 file changed, 5 insertions(+), 16 deletions(-)

diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index 614e2685b..80b5b39ef 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -173,18 +173,7 @@ JavaScript value or object by using the ``parse()`` method:
       import { BSON } from 'mongodb';
       const EJSON = BSON.EJSON;
 
-      const ejsonStr = const ejsonStr = `{
-         "foo": [
-            { "$numberInt": "1" },
-            { "$numberInt": "2" }
-         ],
-         "bar": { "hello": "world" },
-         "code": {
-            "$code": "function x() { return 1; }",
-            "$scope": {}
-         },
-         "bin": { "$binary": { "base64": "AQIDBA==", "subType": "00" } }
-      }`;
+      const ejsonStr = '[{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bar":{"hello":"world"}},{"code":{"$code":"function x() { return 1; }","$scope":{}}},{"date":{"$date":{"$numberLong":"1721485800000"}}}]'
 
       const doc = EJSON.parse(ejsonStr);
       console.log(doc);
@@ -194,10 +183,10 @@ JavaScript value or object by using the ``parse()`` method:
       :visible: false
 
       [
-        { foo: [ 1, 2 ] },
-        { bar: { hello: 'world' } },
-        { code: new Code('function x() { return 1; }', {}) },
-        { bin: Binary.createFromBase64('AQIDBA==', 0) }
+         { foo: [ 1, 2 ] },
+         { bar: { hello: 'world' } },
+         { code: new Code('function x() { return 1; }', {}) },
+         { date: 2024-07-20T14:30:00.000Z }
       ]
 
 .. note::

From 8833125dc9cf2590af0a66510c9596758e68e5bd Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Fri, 11 Apr 2025 16:01:05 -0400
Subject: [PATCH 12/14] tech review 2

---
 source/data-formats/extended-json.txt | 30 +++++++++++++++++++--------
 1 file changed, 21 insertions(+), 9 deletions(-)

diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index 80b5b39ef..f91874b9e 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -112,10 +112,10 @@ The following example outputs an Extended JSON string in the Relaxed format:
       const EJSON = BSON.EJSON;
 
       const doc = {
-         { foo: [1, 2] },
-         { bar: { hello: "world" } },
-         { code: new Code("function x() { return 1; }", {}) },
-         { date: new Date(2024, 6, 20, 10, 30, 0) },
+         foo: [1, 2],
+         bar: { hello: "world" },
+         code: new Code("function x() { return 1; }", {}),
+         date: new Date(2024, 6, 20, 10, 30, 0),
       };
 
       const ejsonStr = EJSON.stringify(doc);
@@ -141,10 +141,10 @@ The following example shows how to output Extended JSON in the Canonical format:
       const { Binary, Code, EJSON } = require('bson');
 
       const doc = {
-         { foo: [1, 2] },
-         { bar: { hello: "world" } },
-         { code: new Code("function x() { return 1; }", {}) },
-         { date: new Date(2024, 6, 20, 10, 30, 0) },
+         foo: [1, 2],
+         bar: { hello: "world" },
+         code: new Code("function x() { return 1; }", {}),
+         date: new Date(2024, 6, 20, 10, 30, 0),
       };
 
       const ejsonStr = EJSON.stringify(doc, { relaxed: false });
@@ -173,7 +173,19 @@ JavaScript value or object by using the ``parse()`` method:
       import { BSON } from 'mongodb';
       const EJSON = BSON.EJSON;
 
-      const ejsonStr = '[{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bar":{"hello":"world"}},{"code":{"$code":"function x() { return 1; }","$scope":{}}},{"date":{"$date":{"$numberLong":"1721485800000"}}}]'
+      const ejsonStr = `{
+         "foo": [
+            { "$numberInt": "1" },
+            { "$numberInt": "2" }
+         ],
+         "bar": { "hello": "world" },
+         "code": {
+            "$code": "function x() { return 1; }",
+            "$scope": {}
+         },
+         "bin": { "$binary": { "base64": "AQIDBA==", "subType": "00" } }
+         }`;
+
 
       const doc = EJSON.parse(ejsonStr);
       console.log(doc);

From 704e27c69736cea50861f54a3a5287747b5b9472 Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Fri, 11 Apr 2025 16:10:46 -0400
Subject: [PATCH 13/14] add note about bad orange highlighting

---
 source/data-formats/extended-json.txt | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index f91874b9e..12694c593 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -165,6 +165,9 @@ by the string by using the ``EJSON.parse()`` method.
 The following example shows how you can read an Extended JSON string into a
 JavaScript value or object by using the ``parse()`` method:
 
+.. The back ticks on ejsonStr in the below code example causes the orange 
+.. highlighting in this file, but the page still renders correctly.
+
 .. io-code-block::
 
    .. input::

From da4b6f20e8f1f14bd858f7573b19eff029e1a0b8 Mon Sep 17 00:00:00 2001
From: Lindsey Moore <lindsey.moore@mongodb.com>
Date: Mon, 14 Apr 2025 14:56:50 -0400
Subject: [PATCH 14/14] tech review

---
 source/data-formats/extended-json.txt | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt
index 12694c593..0f1a93bd0 100644
--- a/source/data-formats/extended-json.txt
+++ b/source/data-formats/extended-json.txt
@@ -108,7 +108,7 @@ The following example outputs an Extended JSON string in the Relaxed format:
    .. input::
       :language: js
 
-      import { Binary, Code, BSON } from 'mongodb';
+      import { Code, BSON } from 'mongodb';
       const EJSON = BSON.EJSON;
 
       const doc = {
@@ -125,7 +125,7 @@ The following example outputs an Extended JSON string in the Relaxed format:
       :language: none
       :visible: false
 
-      [{"foo":[1,2]},{"bar":{"hello":"world"}},{"code":{"$code":"function x() { return 1; }","$scope":{}}},{"date":{"$date":"2024-07-20T14:30:00Z"}}]
+      {"foo":[1,2],"bar":{"hello":"world"},"code":{"$code":"function x() { return 1; }","$scope":{}},"date":{"$date":"2024-07-20T14:30:00Z"}}
 
 By default, the ``stringify()`` method returns the Extended JSON string in the 
 Relaxed format. To specify the Canonical format, set the ``relaxed`` 
@@ -138,7 +138,8 @@ The following example shows how to output Extended JSON in the Canonical format:
    .. input::
       :language: js
 
-      const { Binary, Code, EJSON } = require('bson');
+      import { Code, BSON } from 'mongodb';
+      const EJSON = BSON.EJSON;
 
       const doc = {
          foo: [1, 2],
@@ -154,7 +155,7 @@ The following example shows how to output Extended JSON in the Canonical format:
       :language: none
       :visible: false
 
-      [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bar":{"hello":"world"}},{"code":{"$code":"function x() { return 1; }","$scope":{}}},{"date":{"$date":{"$numberLong":"1721485800000"}}}]
+      {"foo":[{"$numberInt":"1"},{"$numberInt":"2"}],"bar":{"hello":"world"},"code":{"$code":"function x() { return 1; }","$scope":{}},"date":{"$date":{"$numberLong":"1721485800000"}}}  
 
 Read Extended JSON
 ------------------
@@ -187,8 +188,7 @@ JavaScript value or object by using the ``parse()`` method:
             "$scope": {}
          },
          "bin": { "$binary": { "base64": "AQIDBA==", "subType": "00" } }
-         }`;
-
+      }`;
 
       const doc = EJSON.parse(ejsonStr);
       console.log(doc);
@@ -197,12 +197,12 @@ JavaScript value or object by using the ``parse()`` method:
       :language: none
       :visible: false
 
-      [
-         { foo: [ 1, 2 ] },
-         { bar: { hello: 'world' } },
-         { code: new Code('function x() { return 1; }', {}) },
-         { date: 2024-07-20T14:30:00.000Z }
-      ]
+      {
+        foo: [ 1, 2 ],
+        bar: { hello: 'world' },
+        code: new Code('function x() { return 1; }', {}),
+        bin: Binary.createFromBase64('AQIDBA==', 0)
+      }
 
 .. note::