Skip to content

Commit a78e381

Browse files
mcmorisimcmorisi
committed
DOCSP-49078: Extended JSON
1 parent 012b476 commit a78e381

File tree

2 files changed

+234
-1
lines changed

2 files changed

+234
-1
lines changed

‎source/data-formats/extended-json.txt

Lines changed: 188 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,191 @@ Extended JSON
88
:local:
99
:backlinks: none
1010
:depth: 2
11-
:class: singlecol
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: code examples, bson, relaxed, canonical, legacy
19+
20+
Overview
21+
--------
22+
23+
JSON is a data format that represents the values of objects, arrays, numbers,
24+
strings, booleans, and nulls. The **Extended JSON** format defines a reserved
25+
set of keys prefixed with "``$``" to represent field type information that
26+
directly corresponds to each type in BSON, the format that MongoDB uses to
27+
store data.
28+
29+
Extended JSON Formats
30+
---------------------
31+
32+
MongoDB Extended JSON features different string formats to represent BSON data.
33+
Each of the different formats conform to the JSON RFC
34+
and meet specific use cases. The **extended** format, also known as the
35+
**canonical** format, features specific representations for every BSON type
36+
for bidirectional conversion without loss of information. The **Relaxed mode**
37+
format is more concise and closer to ordinary JSON, but does not represent
38+
all the type information such as the specific byte size of number fields.
39+
40+
See the following table to see a description of each format:
41+
42+
.. list-table::
43+
:header-rows: 1
44+
:stub-columns: 1
45+
:widths: 10 40
46+
47+
* - Name
48+
- Description
49+
50+
* - **Extended**
51+
- | Also known as the *canonical* format, this JSON representation avoids loss of
52+
BSON type information.
53+
| This format prioritizes type preservation at the loss of human-readability and
54+
interoperability with older formats.
55+
56+
* - **Relaxed Mode**
57+
- | JSON representation that describes BSON documents with some type information loss.
58+
| This format prioritizes human-readability and interoperability at the loss of
59+
certain type information.
60+
61+
* - **Shell**
62+
- | JSON representation that matches the syntax used in the MongoDB shell.
63+
| This format prioritizes compatibility with the MongoDB shell, which often uses
64+
JavaScript functions to represent types.
65+
66+
* - **Strict**
67+
- | *Deprecated.* This representation is the legacy format that fully conforms to
68+
the `JSON RFC <http://www.json.org/>`__ which allows any JSON parser to read the type information.
69+
70+
.. _extended_json_example_section:
71+
72+
.. note::
73+
74+
The driver parses the ``$uuid`` Extended JSON type from a string to a
75+
``BsonBinary`` object of binary subtype 4. For more information about ``$uuid`` field
76+
parsing, see the
77+
:spec:`special rules for parsing $uuid fields </extended-json.rst#special-rules-for-parsing-uuid-fields>`
78+
section in the extended JSON specification.
79+
80+
To learn more about JSON, BSON, and Extended JSON, see
81+
`our article about JSON and BSON <https://www.mongodb.com/resources/basics/json-and-bson>`__
82+
and :manual:`Extended JSON </reference/mongodb-extended-json/>` in the {+mdb-server+} manual.
83+
84+
Extended JSON Examples
85+
~~~~~~~~~~~~~~~~~~~~~~
86+
87+
The following examples show a document containing an ObjectId, date, and long
88+
number field represented in each Extended JSON format. Click the tab that
89+
corresponds to the format of the example you want to see:
90+
91+
.. tabs::
92+
93+
.. tab:: Extended
94+
:tabid: extended-format
95+
96+
.. code-block:: json
97+
98+
{
99+
"_id": { "$oid": "573a1391f29313caabcd9637" },
100+
"createdAt": { "$date": { "$numberLong": "1601499609" }},
101+
"numViews": { "$numberLong": "36520312" }
102+
}
103+
104+
.. tab:: Relaxed Mode
105+
:tabid: relaxed-mode-format
106+
107+
.. code-block:: json
108+
109+
{
110+
"_id": { "$oid": "573a1391f29313caabcd9637" },
111+
"createdAt": { "$date": "2020-09-30T18:22:51.648Z" },
112+
"numViews": 36520312
113+
}
114+
115+
.. tab:: Shell
116+
:tabid: shell-format
117+
118+
.. code-block:: json
119+
120+
{
121+
"_id": ObjectId("573a1391f29313caabcd9637"),
122+
"createdAt": ISODate("2020-09-30T18:22:51.648Z"),
123+
"numViews": NumberLong("36520312")
124+
}
125+
126+
.. tab:: Strict
127+
:tabid: strict-format
128+
129+
.. code-block:: json
130+
131+
{
132+
"_id": { "$oid": "573a1391f29313caabcd9637" },
133+
"createdAt": { "$date": 1601499609 },
134+
"numViews": { "$numberLong": "36520312" }
135+
}
136+
137+
Read Extended JSON
138+
------------------
139+
140+
You can read an Extended JSON documents into a {+language+} object by using the
141+
``BsonSerializer.Deserialize<T>()`` method. The following example reads an
142+
Extended JSON document into a ``BsonDocument`` object:
143+
144+
.. io-code-block::
145+
146+
.. input:: /includes/fundamentals/code-examples/ExtendedJson.cs
147+
:language: csharp
148+
:start-after: start-read-ejson
149+
:end-before: end-read-ejson
150+
:dedent:
151+
152+
.. output::
153+
:visible: false
154+
155+
{ "_id" : { "$oid" : "573a1391f29313caabcd9637" }, "createdAt" : { "$date" : "1970-01-19T12:51:39.609Z" }, "numViews" : 36520312 }
156+
157+
Write Extended JSON
158+
-------------------
159+
160+
You can write an Extended JSON string by calling the ``ToJson()`` method on a
161+
``BsonDocument`` object or custom class. You must specify a ``JsonWriterSettings`` object
162+
with the ``OutputMode`` property set to the desired Extended JSON format as a parameter to
163+
the ``ToJson()`` method.
164+
165+
Consider the following custom class:
166+
167+
.. literalinclude:: /includes/fundamentals/code-examples/ExtendedJson.cs
168+
:language: csharp
169+
:start-after: start-custom-class
170+
:end-before: end-custom-class
171+
172+
The following example outputs an instance of ``MyDocument`` in
173+
Extended JSON format by specifying the ``CanonicalExtendedJson`` value to the ``OutputMode``
174+
property:
175+
176+
.. io-code-block::
177+
178+
.. input:: /includes/fundamentals/code-examples/ExtendedJson.cs
179+
:language: csharp
180+
:start-after: start-read-ejson
181+
:end-before: end-read-ejson
182+
:dedent:
183+
184+
.. output::
185+
:visible: false
186+
187+
{ "_id" : { "$oid" : "68094769744af81f368ff1c1" }, "CreatedAt" : { "$date" : { "$numberLong" : "1745438569994" } }, "NumViews" : { "$numberLong" : "1234567890" } }
188+
189+
API Documentation
190+
-----------------
191+
192+
To learn more about the methods and classes used on this page, see the following API
193+
documentation:
194+
195+
- `BsonDocument <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonDocument.html>`__
196+
- `BsonSerializer <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.BsonSerializer.html>`__
197+
- `ToJson() <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.BsonExtensionMethods.ToJson.html>`__
198+
- `JsonWriterSettings <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.IO.JsonWriterSettings.html>`__

‎source/includes/fundamentals/code-examples/ExtendedJson.cs

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
using MongoDB.Bson;
2+
using MongoDB.Bson.IO;
3+
using MongoDB.Driver;
4+
using MongoDB.Driver.Core.Clusters;
5+
using MongoDB.Driver.Core.Clusters.ServerSelectors;
6+
using MongoDB.Driver.Core.Servers;
7+
using MongoDB.Bson.Serialization;
8+
9+
public class ExtendedJson
10+
{
11+
public static void Main(string[] args)
12+
{
13+
{
14+
// start-read-ejson
15+
var ejson = "{\n\"_id\": { \"$oid\": \"573a1391f29313caabcd9637\" },\n \"createdAt\": { \"$date\": { \"$numberLong\": \"1601499609\" }},\n\"numViews\": { \"$numberLong\": \"36520312\" }\n}\n\n";
16+
17+
var document = BsonSerializer.Deserialize<BsonDocument>(ejson);
18+
Console.WriteLine(document.ToJson());
19+
// end-read-ejson
20+
}
21+
22+
{
23+
// start-write-ejson
24+
var document = new MyDocument();
25+
document.Id = ObjectId.GenerateNewId();
26+
document.CreatedAt = DateTime.UtcNow;
27+
document.NumViews = 1234567890;
28+
29+
var json = document.ToJson(new JsonWriterSettings
30+
{
31+
OutputMode = JsonOutputMode.CanonicalExtendedJson
32+
});
33+
Console.WriteLine(json);
34+
// end-write-ejson
35+
}
36+
}
37+
}
38+
39+
// start-custom-class
40+
public class MyDocument
41+
{
42+
public ObjectId Id { get; set; }
43+
public DateTime CreatedAt { get; set; }
44+
public long NumViews { get; set; }
45+
}
46+
// end-custom-class

0 commit comments

Comments
 (0)