From 340648e22248d6af3516460f6b240e7a313b26b0 Mon Sep 17 00:00:00 2001 From: Nora Reidy Date: Tue, 15 Jul 2025 15:47:46 -0400 Subject: [PATCH 01/10] DOCSP-51932: v2.21.2 patch release (#163) --- snooty.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snooty.toml b/snooty.toml index d2e2e4a1..0c791726 100644 --- a/snooty.toml +++ b/snooty.toml @@ -21,7 +21,7 @@ mongo-enterprise = "MongoDB Enterprise Edition" docs-branch = "master" # always set this to the driver branch (i.e. 1.7 1.8, etc.) version-number = "2.21" -patch-version-number = "{+version-number+}.1" +patch-version-number = "{+version-number+}.2" version = "v{+version-number+}" stable-api = "Stable API" api-root = "https://www.mongodb.com/docs/ruby-driver/current/api/" From 2f6de1465bd8eaf796288f788469774e71968eaf Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 16 Jul 2025 14:19:25 -0400 Subject: [PATCH 02/10] shared content --- source/data-formats/extended-json.txt | 31 +++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 source/data-formats/extended-json.txt diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt new file mode 100644 index 00000000..0f17a0ab --- /dev/null +++ b/source/data-formats/extended-json.txt @@ -0,0 +1,31 @@ +.. _ruby-extended-json: + +============= +Extended JSON +============= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, json, standard formatting + :description: Learn how to use extended JSON in the MongoDB Ruby Driver. + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: twocols + +.. sharedinclude:: dbx/extended-json.rst + +Read Extended JSON +------------------ + +You can read an Extended JSON string into a Python object by calling +the ``bson.json_util.loads()`` method. This method parses an Extended +JSON string and returns a Python list containing the data. + +The following example shows how you can read an Extended JSON string into a +list of dictionaries by using the ``loads()`` method: \ No newline at end of file From 55e93e316879b2ee0007b06deab9ae4b5eda8787 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 23 Jul 2025 12:48:17 -0400 Subject: [PATCH 03/10] write --- source/data-formats/extended-json.txt | 111 +++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 4 deletions(-) diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index 0f17a0ab..e3412c61 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -23,9 +23,112 @@ Extended JSON Read Extended JSON ------------------ -You can read an Extended JSON string into a Python object by calling -the ``bson.json_util.loads()`` method. This method parses an Extended -JSON string and returns a Python list containing the data. +You can read an Extended JSON string into an Ruby array by calling +the ``BSON::ExtJSON.parse()`` method. This method parses an Extended +JSON string and returns an array containing the data. The following example shows how you can read an Extended JSON string into a -list of dictionaries by using the ``loads()`` method: \ No newline at end of file +array of hashes by using the ``parse()`` method: + +.. io-code-block:: + + .. input:: + :language: ruby + + require 'bson' + + ex_json = '''[ + {"foo": [1, 2]}, + {"bar": {"hello": "world"}}, + {"code": { + "$scope": {}, + "$code": "function x() { return 1; }" + }}, + {"bin": { + "$type": "80", + "$binary": "AQIDBA==" + }} + ]''' + + doc = BSON::ExtJSON.parse(ex_json) + + puts doc.class + puts doc + + .. output:: + :language: none + :visible: false + + {"foo" => [1, 2]} + {"bar" => {"hello" => "world"}} + {"code" => #} + {"bin" => } + +Write Extended JSON +------------------- + +You can write an Extended JSON string from a hash by using the +``as_extended_json()`` method. Using the Ruby ``map{}`` method, you can create +an Extended JSON string from an array of hashes. By default, this method returns +the Extended JSON string in canonical format, but you can specify relaxed or +legacy formats by passing a ``mode:`` argument. + +.. note:: Legacy Version + + The legacy format option tells the {+driver-short+} to serialize BSON types + using MongoDB Extended JSON v1 format, which predates the current + relaxed and canonical formats. + + For more information see the :server:`MongoDB Extended JSON v1 (legacy + format)` page in the Server manual. + +The following example outputs an Extended JSON string in the canonical, relaxed +and legacy formats: + +.. io-code-block:: + + .. input:: + :language: ruby + + require 'bson' + + hash_array = [ + { "foo" => [1, 2] }, + { "bin" => BSON::Binary.new("\x01\x02\x03\x04", :user) }, + { "number" => BSON::Int64.new(42) } + ] + + json_array_canonical = hash_array.map(&:as_extended_json) + json_array_relaxed = hash_array.map{ |hash| hash.as_extended_json(mode: :relaxed) } + json_array_legacy = hash_array.map{ |hash| hash.as_extended_json(mode: :legacy) } + + json_string_canonical = JSON.generate(json_array_canonical) + json_string_relaxed = JSON.generate(json_array_relaxed) + json_string_legacy = JSON.generate(json_array_legacy) + + puts "canonical:\t #{json_string_canonical}" + puts "relaxed:\t #{json_string_relaxed}" + puts "legacy:\t\t #{json_string_legacy}" + + .. output:: + :language: none + :visible: false + + canonical: [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"80"}}},{"number":{"$numberLong":"42"}}] + relaxed: [{"foo":[1,2]},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"80"}}},{"number":42}] + legacy: [{"foo":[1,2]},{"bin":{"$binary":"AQIDBA==","$type":"80"}},{"number":42}] + +More Information +---------------- + +For more information, see the following resources: + +API Documentation +~~~~~~~~~~~~~~~~~ + +- `BSON::ExtJSON.parse() `__ +- `#as_extended_json()`__ + +Server Manual Pages + +- :manual:`MongoDB Extended JSON (v2)` \ No newline at end of file From 0ae7c75aee870d17889576ad0b91f1ead2caa697 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 23 Jul 2025 13:27:01 -0400 Subject: [PATCH 04/10] link formatting --- 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 e3412c61..4139596f 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -79,7 +79,7 @@ legacy formats by passing a ``mode:`` argument. using MongoDB Extended JSON v1 format, which predates the current relaxed and canonical formats. - For more information see the :server:`MongoDB Extended JSON v1 (legacy + For more information see the :manual:`MongoDB Extended JSON v1 (legacy format)` page in the Server manual. The following example outputs an Extended JSON string in the canonical, relaxed @@ -127,7 +127,7 @@ API Documentation ~~~~~~~~~~~~~~~~~ - `BSON::ExtJSON.parse() `__ -- `#as_extended_json()`__ +- `#as_extended_json() `__ Server Manual Pages From c6045a9363354a94c0f77f019864940fc93a47fe Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Wed, 23 Jul 2025 14:14:05 -0400 Subject: [PATCH 05/10] link formatting --- 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 4139596f..d3b18bae 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -80,7 +80,7 @@ legacy formats by passing a ``mode:`` argument. relaxed and canonical formats. For more information see the :manual:`MongoDB Extended JSON v1 (legacy - format)` page in the Server manual. + format) ` page in the Server manual. The following example outputs an Extended JSON string in the canonical, relaxed and legacy formats: From cbcec5e58a33cb9d329e2bd5f2fa7558e2d756f0 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 25 Jul 2025 11:56:20 -0400 Subject: [PATCH 06/10] NR feedback --- source/data-formats.txt | 1 + source/data-formats/extended-json.txt | 75 ++++++------------- source/includes/data-formats/extended-json.rb | 43 +++++++++++ 3 files changed, 66 insertions(+), 53 deletions(-) create mode 100644 source/includes/data-formats/extended-json.rb diff --git a/source/data-formats.txt b/source/data-formats.txt index 5af1d6ef..442b2cae 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -24,6 +24,7 @@ Data Formats Time Series Data BSON + Extended JSON Overview -------- diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index d3b18bae..b7060079 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -31,29 +31,13 @@ The following example shows how you can read an Extended JSON string into a array of hashes by using the ``parse()`` method: .. io-code-block:: + :copyable: - .. input:: - :language: ruby - - require 'bson' - - ex_json = '''[ - {"foo": [1, 2]}, - {"bar": {"hello": "world"}}, - {"code": { - "$scope": {}, - "$code": "function x() { return 1; }" - }}, - {"bin": { - "$type": "80", - "$binary": "AQIDBA==" - }} - ]''' - - doc = BSON::ExtJSON.parse(ex_json) - - puts doc.class - puts doc + .. input:: /includes/data-formats/extended-json.rb + :start-after: start-ex-json-read + :end-before: end-ex-json-read + :language: ruby + :dedent: .. output:: :language: none @@ -68,47 +52,31 @@ Write Extended JSON ------------------- You can write an Extended JSON string from a hash by using the -``as_extended_json()`` method. Using the Ruby ``map{}`` method, you can create -an Extended JSON string from an array of hashes. By default, this method returns +``as_extended_json()`` method. By default, this method returns the Extended JSON string in canonical format, but you can specify relaxed or -legacy formats by passing a ``mode:`` argument. +legacy formats by passing a ``mode`` argument. .. note:: Legacy Version The legacy format option tells the {+driver-short+} to serialize BSON types - using MongoDB Extended JSON v1 format, which predates the current + with the MongoDB Extended JSON v1 format, which predates the current relaxed and canonical formats. - For more information see the :manual:`MongoDB Extended JSON v1 (legacy - format) ` page in the Server manual. + For more information see the :manual:`MongoDB Extended JSON v1 + ` page in the Server manual. The following example outputs an Extended JSON string in the canonical, relaxed -and legacy formats: +and legacy formats. It calls the ``as_extended_json()`` method from inside a +Ruby ``map{}`` block to create the Extended JSON string from an array of hashes: .. io-code-block:: + :copyable: - .. input:: - :language: ruby - - require 'bson' - - hash_array = [ - { "foo" => [1, 2] }, - { "bin" => BSON::Binary.new("\x01\x02\x03\x04", :user) }, - { "number" => BSON::Int64.new(42) } - ] - - json_array_canonical = hash_array.map(&:as_extended_json) - json_array_relaxed = hash_array.map{ |hash| hash.as_extended_json(mode: :relaxed) } - json_array_legacy = hash_array.map{ |hash| hash.as_extended_json(mode: :legacy) } - - json_string_canonical = JSON.generate(json_array_canonical) - json_string_relaxed = JSON.generate(json_array_relaxed) - json_string_legacy = JSON.generate(json_array_legacy) - - puts "canonical:\t #{json_string_canonical}" - puts "relaxed:\t #{json_string_relaxed}" - puts "legacy:\t\t #{json_string_legacy}" + .. input:: /includes/data-formats/extended-json.rb + :start-after: start-ex-json-write + :end-before: end-ex-json-write + :language: ruby + :dedent: .. output:: :language: none @@ -118,8 +86,8 @@ and legacy formats: relaxed: [{"foo":[1,2]},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"80"}}},{"number":42}] legacy: [{"foo":[1,2]},{"bin":{"$binary":"AQIDBA==","$type":"80"}},{"number":42}] -More Information ----------------- +Additional Information +---------------------- For more information, see the following resources: @@ -130,5 +98,6 @@ API Documentation - `#as_extended_json() `__ Server Manual Pages +~~~~~~~~~~~~~~~~~~~ - :manual:`MongoDB Extended JSON (v2)` \ No newline at end of file diff --git a/source/includes/data-formats/extended-json.rb b/source/includes/data-formats/extended-json.rb new file mode 100644 index 00000000..8e890a1b --- /dev/null +++ b/source/includes/data-formats/extended-json.rb @@ -0,0 +1,43 @@ +# start-ex-json-read +require 'bson' + +ex_json = '''[ + {"foo": [1, 2]}, + {"bar": {"hello": "world"}}, + {"code": { + "$scope": {}, + "$code": "function x() { return 1; }" + }}, + {"bin": { + "$type": "80", + "$binary": "AQIDBA==" + }} + ]''' + +doc = BSON::ExtJSON.parse(ex_json) + +puts doc.class +puts doc +# end-ex-json-read + +# start-ex-json-write +require 'bson' + +hash_array = [ + { "foo" => [1, 2] }, + { "bin" => BSON::Binary.new("\x01\x02\x03\x04", :user) }, + { "number" => BSON::Int64.new(42) } +] + +json_array_canonical = hash_array.map(&:as_extended_json) +json_array_relaxed = hash_array.map{ |hash| hash.as_extended_json(mode: :relaxed) } +json_array_legacy = hash_array.map{ |hash| hash.as_extended_json(mode: :legacy) } + +json_string_canonical = JSON.generate(json_array_canonical) +json_string_relaxed = JSON.generate(json_array_relaxed) +json_string_legacy = JSON.generate(json_array_legacy) + +puts "canonical:\t #{json_string_canonical}" +puts "relaxed:\t #{json_string_relaxed}" +puts "legacy:\t\t #{json_string_legacy}" +# end-ex-json-write \ No newline at end of file From aaba8e1b256b3e6fbcc27dad0f19120e91e78512 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 25 Jul 2025 13:38:08 -0400 Subject: [PATCH 07/10] NR feedback --- 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 b7060079..36bef2d3 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -62,10 +62,10 @@ legacy formats by passing a ``mode`` argument. with the MongoDB Extended JSON v1 format, which predates the current relaxed and canonical formats. - For more information see the :manual:`MongoDB Extended JSON v1 + For more information see, the :manual:`MongoDB Extended JSON v1 ` page in the Server manual. -The following example outputs an Extended JSON string in the canonical, relaxed +The following example outputs an Extended JSON string in the canonical, relaxed, and legacy formats. It calls the ``as_extended_json()`` method from inside a Ruby ``map{}`` block to create the Extended JSON string from an array of hashes: From eab92288d97ef8aa89f8596067f17725d43ee162 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 28 Jul 2025 12:37:46 -0400 Subject: [PATCH 08/10] JB feedback --- source/data-formats/extended-json.txt | 21 +++++++++---------- source/includes/data-formats/extended-json.rb | 10 +++------ 2 files changed, 13 insertions(+), 18 deletions(-) diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index 36bef2d3..9f2db11a 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -24,11 +24,11 @@ Read Extended JSON ------------------ You can read an Extended JSON string into an Ruby array by calling -the ``BSON::ExtJSON.parse()`` method. This method parses an Extended +the ``BSON::ExtJSON.parse`` method. This method parses an Extended JSON string and returns an array containing the data. The following example shows how you can read an Extended JSON string into a -array of hashes by using the ``parse()`` method: +array of hashes by using the ``parse`` method: .. io-code-block:: :copyable: @@ -51,10 +51,9 @@ array of hashes by using the ``parse()`` method: Write Extended JSON ------------------- -You can write an Extended JSON string from a hash by using the -``as_extended_json()`` method. By default, this method returns -the Extended JSON string in canonical format, but you can specify relaxed or -legacy formats by passing a ``mode`` argument. +You can write an Extended JSON string by using the ``as_extended_json`` +method. By default, this method returns the Extended JSON string in canonical +format, but you can specify relaxed or legacy formats by passing a ``mode`` argument. .. note:: Legacy Version @@ -65,9 +64,9 @@ legacy formats by passing a ``mode`` argument. For more information see, the :manual:`MongoDB Extended JSON v1 ` page in the Server manual. -The following example outputs an Extended JSON string in the canonical, relaxed, -and legacy formats. It calls the ``as_extended_json()`` method from inside a -Ruby ``map{}`` block to create the Extended JSON string from an array of hashes: +The ``as_extended_json`` method is available for many other core and +standard library types. The following example creates Extended JSON strings in +the canonical, relaxed, and legacy formats, from an array of hashes: .. io-code-block:: :copyable: @@ -94,8 +93,8 @@ For more information, see the following resources: API Documentation ~~~~~~~~~~~~~~~~~ -- `BSON::ExtJSON.parse() `__ -- `#as_extended_json() `__ +- `BSON::ExtJSON.parse `__ +- `#as_extended_json `__ Server Manual Pages ~~~~~~~~~~~~~~~~~~~ diff --git a/source/includes/data-formats/extended-json.rb b/source/includes/data-formats/extended-json.rb index 8e890a1b..a93a59e5 100644 --- a/source/includes/data-formats/extended-json.rb +++ b/source/includes/data-formats/extended-json.rb @@ -29,13 +29,9 @@ { "number" => BSON::Int64.new(42) } ] -json_array_canonical = hash_array.map(&:as_extended_json) -json_array_relaxed = hash_array.map{ |hash| hash.as_extended_json(mode: :relaxed) } -json_array_legacy = hash_array.map{ |hash| hash.as_extended_json(mode: :legacy) } - -json_string_canonical = JSON.generate(json_array_canonical) -json_string_relaxed = JSON.generate(json_array_relaxed) -json_string_legacy = JSON.generate(json_array_legacy) +json_string_canonical = hash_array.as_extended_json +json_string_relaxed = hash_array.as_extended_json(mode: :relaxed) +json_string_legacy = hash_array.as_extended_json(mode: :legacy) puts "canonical:\t #{json_string_canonical}" puts "relaxed:\t #{json_string_relaxed}" From c8da82df7c325943ab726a7dd2e8a5af3616ef0b Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 28 Jul 2025 12:56:45 -0400 Subject: [PATCH 09/10] rephrase --- source/data-formats/extended-json.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index 9f2db11a..9e9f47f5 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -64,9 +64,10 @@ format, but you can specify relaxed or legacy formats by passing a ``mode`` argu For more information see, the :manual:`MongoDB Extended JSON v1 ` page in the Server manual. -The ``as_extended_json`` method is available for many other core and -standard library types. The following example creates Extended JSON strings in -the canonical, relaxed, and legacy formats, from an array of hashes: +The ``as_extended_json`` method is available for several core and standard +library types, including ``Array`` and ``Hash``. The following example creates +Extended JSON strings in the canonical, relaxed, and legacy formats, from an +array of hashes: .. io-code-block:: :copyable: From 5233654b278267a30fba430801d102bbf003ff97 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 28 Jul 2025 13:03:49 -0400 Subject: [PATCH 10/10] remove extra change --- snooty.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snooty.toml b/snooty.toml index 0c791726..d2e2e4a1 100644 --- a/snooty.toml +++ b/snooty.toml @@ -21,7 +21,7 @@ mongo-enterprise = "MongoDB Enterprise Edition" docs-branch = "master" # always set this to the driver branch (i.e. 1.7 1.8, etc.) version-number = "2.21" -patch-version-number = "{+version-number+}.2" +patch-version-number = "{+version-number+}.1" version = "v{+version-number+}" stable-api = "Stable API" api-root = "https://www.mongodb.com/docs/ruby-driver/current/api/"