From a78e3817ab3a308430c9b08cbb10f4e6e49f1cb8 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 23 Apr 2025 16:26:20 -0400 Subject: [PATCH 1/8] DOCSP-49078: Extended JSON --- source/data-formats/extended-json.txt | 189 +++++++++++++++++- .../code-examples/ExtendedJson.cs | 46 +++++ 2 files changed, 234 insertions(+), 1 deletion(-) create mode 100644 source/includes/fundamentals/code-examples/ExtendedJson.cs diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index c2a69aa8..f916102e 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -8,4 +8,191 @@ Extended JSON :local: :backlinks: none :depth: 2 - :class: singlecol \ No newline at end of file + :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. + + * - **Shell** + - | JSON representation that matches the syntax used in the MongoDB shell. + | This format prioritizes compatibility with the MongoDB shell, which often uses + JavaScript functions to represent types. + + * - **Strict** + - | *Deprecated.* This representation is the legacy format that fully conforms to + the `JSON RFC `__ which allows any JSON parser to read the type information. + +.. _extended_json_example_section: + +.. 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 ` + section in the extended JSON specification. + +To learn more about JSON, BSON, and Extended JSON, see +`our article about JSON and BSON `__ +and :manual:`Extended JSON ` in the {+mdb-server+} manual. + +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 + } + + .. tab:: Shell + :tabid: shell-format + + .. code-block:: json + + { + "_id": ObjectId("573a1391f29313caabcd9637"), + "createdAt": ISODate("2020-09-30T18:22:51.648Z"), + "numViews": NumberLong("36520312") + } + + .. tab:: Strict + :tabid: strict-format + + .. code-block:: json + + { + "_id": { "$oid": "573a1391f29313caabcd9637" }, + "createdAt": { "$date": 1601499609 }, + "numViews": { "$numberLong": "36520312" } + } + +Read Extended JSON +------------------ + +You can read an Extended JSON documents into a {+language+} object by using the +``BsonSerializer.Deserialize()`` method. The following example reads an +Extended JSON document into a ``BsonDocument`` object: + +.. io-code-block:: + + .. input:: /includes/fundamentals/code-examples/ExtendedJson.cs + :language: csharp + :start-after: start-read-ejson + :end-before: end-read-ejson + :dedent: + + .. output:: + :visible: false + + { "_id" : { "$oid" : "573a1391f29313caabcd9637" }, "createdAt" : { "$date" : "1970-01-19T12:51:39.609Z" }, "numViews" : 36520312 } + +Write Extended JSON +------------------- + +You can write an Extended JSON string by calling the ``ToJson()`` method on a +``BsonDocument`` object or custom class. You must specify a ``JsonWriterSettings`` object +with the ``OutputMode`` property set to the desired Extended JSON format as a parameter to +the ``ToJson()`` method. + +Consider the following custom class: + +.. literalinclude:: /includes/fundamentals/code-examples/ExtendedJson.cs + :language: csharp + :start-after: start-custom-class + :end-before: end-custom-class + +The following example outputs an instance of ``MyDocument`` in +Extended JSON format by specifying the ``CanonicalExtendedJson`` value to the ``OutputMode`` +property: + +.. io-code-block:: + + .. input:: /includes/fundamentals/code-examples/ExtendedJson.cs + :language: csharp + :start-after: start-read-ejson + :end-before: end-read-ejson + :dedent: + + .. output:: + :visible: false + + { "_id" : { "$oid" : "68094769744af81f368ff1c1" }, "CreatedAt" : { "$date" : { "$numberLong" : "1745438569994" } }, "NumViews" : { "$numberLong" : "1234567890" } } + +API Documentation +----------------- + +To learn more about the methods and classes used on this page, see the following API +documentation: + +- `BsonDocument <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonDocument.html>`__ +- `BsonSerializer <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.BsonSerializer.html>`__ +- `ToJson() <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonExtensionMethods.ToJson.html>`__ +- `JsonWriterSettings <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonWriterSettings.html>`__ \ No newline at end of file diff --git a/source/includes/fundamentals/code-examples/ExtendedJson.cs b/source/includes/fundamentals/code-examples/ExtendedJson.cs new file mode 100644 index 00000000..2f198ea3 --- /dev/null +++ b/source/includes/fundamentals/code-examples/ExtendedJson.cs @@ -0,0 +1,46 @@ +using MongoDB.Bson; +using MongoDB.Bson.IO; +using MongoDB.Driver; +using MongoDB.Driver.Core.Clusters; +using MongoDB.Driver.Core.Clusters.ServerSelectors; +using MongoDB.Driver.Core.Servers; +using MongoDB.Bson.Serialization; + +public class ExtendedJson +{ + public static void Main(string[] args) + { + { + // start-read-ejson + var ejson = "{\n\"_id\": { \"$oid\": \"573a1391f29313caabcd9637\" },\n \"createdAt\": { \"$date\": { \"$numberLong\": \"1601499609\" }},\n\"numViews\": { \"$numberLong\": \"36520312\" }\n}\n\n"; + + var document = BsonSerializer.Deserialize(ejson); + Console.WriteLine(document.ToJson()); + // end-read-ejson + } + + { + // start-write-ejson + var document = new MyDocument(); + document.Id = ObjectId.GenerateNewId(); + document.CreatedAt = DateTime.UtcNow; + document.NumViews = 1234567890; + + var json = document.ToJson(new JsonWriterSettings + { + OutputMode = JsonOutputMode.CanonicalExtendedJson + }); + Console.WriteLine(json); + // end-write-ejson + } + } +} + +// start-custom-class +public class MyDocument +{ + public ObjectId Id { get; set; } + public DateTime CreatedAt { get; set; } + public long NumViews { get; set; } +} +// end-custom-class \ No newline at end of file From 5c178bf7e3af7a73368bd9d565cc21890b4a3f34 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 23 Apr 2025 16:51:48 -0400 Subject: [PATCH 2/8] Fix --- source/data-formats/extended-json.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index f916102e..30fe22d7 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -177,8 +177,8 @@ property: .. input:: /includes/fundamentals/code-examples/ExtendedJson.cs :language: csharp - :start-after: start-read-ejson - :end-before: end-read-ejson + :start-after: start-write-ejson + :end-before: end-write-ejson :dedent: .. output:: From 7d844590621d59cdc79c53787976ead9bc27aeeb Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 24 Apr 2025 09:24:30 -0400 Subject: [PATCH 3/8] Fix --- source/data-formats/extended-json.txt | 6 +++++- source/includes/fundamentals/code-examples/ExtendedJson.cs | 4 ---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index 30fe22d7..9438b708 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -195,4 +195,8 @@ documentation: - `BsonDocument <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonDocument.html>`__ - `BsonSerializer <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.BsonSerializer.html>`__ - `ToJson() <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonExtensionMethods.ToJson.html>`__ -- `JsonWriterSettings <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonWriterSettings.html>`__ \ No newline at end of file +- `JsonWriter <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonWriter.html>`__ +- `JsonReader <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonReader.html>`__ +- `JsonWriterSettings <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonWriterSettings.html>`__ +- `JsonReaderSettings <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonReaderSettings.html>`__ +- `JsonOutputMode <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonOutputMode.html>`__ \ No newline at end of file diff --git a/source/includes/fundamentals/code-examples/ExtendedJson.cs b/source/includes/fundamentals/code-examples/ExtendedJson.cs index 2f198ea3..1f0f1a8e 100644 --- a/source/includes/fundamentals/code-examples/ExtendedJson.cs +++ b/source/includes/fundamentals/code-examples/ExtendedJson.cs @@ -1,9 +1,5 @@ using MongoDB.Bson; using MongoDB.Bson.IO; -using MongoDB.Driver; -using MongoDB.Driver.Core.Clusters; -using MongoDB.Driver.Core.Clusters.ServerSelectors; -using MongoDB.Driver.Core.Servers; using MongoDB.Bson.Serialization; public class ExtendedJson From c921cfc32090da7e76f9b992c08c06c4cb570afd Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 24 Apr 2025 11:54:06 -0400 Subject: [PATCH 4/8] RM feedback --- source/data-formats/extended-json.txt | 74 ++------------------------- 1 file changed, 5 insertions(+), 69 deletions(-) diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index 9438b708..14898048 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -17,70 +17,18 @@ Extended JSON .. 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. - - * - **Shell** - - | JSON representation that matches the syntax used in the MongoDB shell. - | This format prioritizes compatibility with the MongoDB shell, which often uses - JavaScript functions to represent types. - - * - **Strict** - - | *Deprecated.* This representation is the legacy format that fully conforms to - the `JSON RFC `__ which allows any JSON parser to read the type information. +.. sharedinclude:: dbx/extended-json.rst .. _extended_json_example_section: .. note:: - The driver parses the ``$uuid`` Extended JSON type from a string to a + The {+driver-short+} 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 ` + :spec:`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 `__ -and :manual:`Extended JSON ` in the {+mdb-server+} manual. - Extended JSON Examples ~~~~~~~~~~~~~~~~~~~~~~ @@ -123,17 +71,6 @@ corresponds to the format of the example you want to see: "numViews": NumberLong("36520312") } - .. tab:: Strict - :tabid: strict-format - - .. code-block:: json - - { - "_id": { "$oid": "573a1391f29313caabcd9637" }, - "createdAt": { "$date": 1601499609 }, - "numViews": { "$numberLong": "36520312" } - } - Read Extended JSON ------------------ @@ -159,8 +96,7 @@ Write Extended JSON You can write an Extended JSON string by calling the ``ToJson()`` method on a ``BsonDocument`` object or custom class. You must specify a ``JsonWriterSettings`` object -with the ``OutputMode`` property set to the desired Extended JSON format as a parameter to -the ``ToJson()`` method. +with the ``OutputMode`` property set to the desired Extended JSON format as a parameter. Consider the following custom class: @@ -170,7 +106,7 @@ Consider the following custom class: :end-before: end-custom-class The following example outputs an instance of ``MyDocument`` in -Extended JSON format by specifying the ``CanonicalExtendedJson`` value to the ``OutputMode`` +Extended JSON format by specifying the ``CanonicalExtendedJson`` value as an ``OutputMode`` property: .. io-code-block:: From c583f9fefaf6aeea975a140dda8d3940db1f78a4 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 24 Apr 2025 12:07:54 -0400 Subject: [PATCH 5/8] Fix --- source/data-formats/extended-json.txt | 52 --------------------------- 1 file changed, 52 deletions(-) diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index 14898048..29c21eaa 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -19,58 +19,6 @@ Extended JSON .. sharedinclude:: dbx/extended-json.rst -.. _extended_json_example_section: - -.. note:: - - The {+driver-short+} 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 ` - section in the extended JSON specification. - -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 - } - - .. tab:: Shell - :tabid: shell-format - - .. code-block:: json - - { - "_id": ObjectId("573a1391f29313caabcd9637"), - "createdAt": ISODate("2020-09-30T18:22:51.648Z"), - "numViews": NumberLong("36520312") - } - Read Extended JSON ------------------ From 7d0c7d323db2d7222c01ebaa7e7c7c0e26c41932 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 29 Apr 2025 15:22:09 -0400 Subject: [PATCH 6/8] Technical feedback --- source/data-formats/extended-json.txt | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index 29c21eaa..352bf18c 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -19,6 +19,11 @@ Extended JSON .. sharedinclude:: dbx/extended-json.rst + .. replacement:: default-text + + The {+driver-short+} uses Relaxed mode by default. + + Read Extended JSON ------------------ From 7efe2050f91150fbc9338dd4fe5ebfd2bb5b3eaf Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 30 Apr 2025 13:13:00 -0400 Subject: [PATCH 7/8] Fix --- 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 352bf18c..3d62ec4e 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -19,7 +19,7 @@ Extended JSON .. sharedinclude:: dbx/extended-json.rst - .. replacement:: default-text + .. replacement:: driver-specific-text-relaxed The {+driver-short+} uses Relaxed mode by default. From 1d64a2b6efb55f28a757081e1d512afcaaa7b71a Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 30 Apr 2025 13:23:47 -0400 Subject: [PATCH 8/8] Trigger autobuild