Document duplicate keys behavior in BSON documents

language-snippets.ent

@@ -3448,6 +3448,21 @@ local: {
     </simpara>
    </note>
 '>
+<!ENTITY mongodb.note.duplicate-keys.tojson '
+  <note xmlns="http://docbook.org/ns/docbook">
+   <simpara>
+    If the BSON document contains duplicate keys, all of them are preserved in
+    the JSON output.
+   </simpara>
+  </note>
+'>
+<!ENTITY mongodb.note.duplicate-keys.fromjson '
+  <note xmlns="http://docbook.org/ns/docbook">
+   <simpara>
+    Duplicate keys in the JSON string are preserved in the order they appear.
+   </simpara>
+  </note>
+'>
 <!ENTITY mongodb.note.extended-json '
   <note xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
    <simpara>
@@ -3511,10 +3526,18 @@ local: {
    <warning xmlns="http://docbook.org/ns/docbook">
     <simpara>
      BSON documents can technically contain duplicate keys because documents are
-     stored as a list of key-value pairs; however, applications should refrain
-     from generating documents with duplicate keys as server and driver behavior
-     may be undefined. Since PHP objects and arrays cannot have duplicate keys,
-     data could also be lost when decoding a BSON document with duplicate keys.
+     stored as a list of key-value pairs; however, applications should avoid
+     creating documents with duplicate keys. The server and other drivers may
+     handle them differently, and PHP objects and arrays cannot have duplicate
+     keys, so data is lost when decoding a BSON document with duplicate keys.
+    </simpara>
+    <simpara>
+     The driver does not validate duplicate keys and its current behavior is
+     covered by tests, but it is not a supported feature. When decoding to PHP,
+     the last value for a duplicate key is used. A
+     <classname>MongoDB\BSON\Document</classname> keeps all duplicate keys in
+     their original order, and its <methodname>MongoDB\BSON\Document::get</methodname>
+     method returns the first value.
     </simpara>
    </warning>
 '>

reference/mongodb/bson/document/fromjson.xml

@@ -39,6 +39,7 @@
   <simpara>
    Returns a new <classname>MongoDB\BSON\Document</classname> instance.
   </simpara>
+  &mongodb.note.duplicate-keys.fromjson;
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/bson/document/get.xml

@@ -42,6 +42,12 @@
     <classname>MongoDB\BSON\Int64</classname> instance.
    </simpara>
   </note>
+  <note>
+   <simpara>
+    If the document contains duplicate keys, the value of the first matching key
+    is returned.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/bson/document/getiterator.xml

@@ -26,6 +26,12 @@
    Returns a <classname>MongoDB\BSON\Iterator</classname> instance that can be
    used to iterate over all keys in the document.
   </simpara>
+  <note>
+   <simpara>
+    If the document contains duplicate keys, the iterator returns every
+    element in the original order.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/bson/document/offsetget.xml

@@ -42,6 +42,12 @@
     <classname>MongoDB\BSON\Int64</classname> instance.
    </simpara>
   </note>
+  <note>
+   <simpara>
+    If the document contains duplicate keys, the value of the first matching key
+    is returned.
+   </simpara>
+  </note>
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/bson/document/tocanonicalextendedjson.xml

@@ -35,6 +35,7 @@
    <link xlink:href="&url.mongodb.specs.extendedjson;#canonical-extended-json-example">Canonical Extended JSON</link>
    representation of the BSON document.
   </simpara>
+  &mongodb.note.duplicate-keys.tojson;
  </refsect1>
 
  <refsect1 role="examples">

reference/mongodb/bson/document/torelaxedextendedjson.xml

@@ -34,6 +34,7 @@
    <link xlink:href="&url.mongodb.specs.extendedjson;#relaxed-extended-json-example">Relaxed Extended JSON</link>
    representation of the BSON document.
   </simpara>
+  &mongodb.note.duplicate-keys.tojson;
  </refsect1>
 
  <refsect1 role="examples">

reference/mongodb/functions/bson/fromjson.xml

@@ -49,6 +49,7 @@
   <simpara>
    The serialized BSON document as a binary string.
   </simpara>
+  &mongodb.note.duplicate-keys.fromjson;
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/functions/bson/tocanonicalextendedjson.xml

@@ -53,6 +53,7 @@
   <simpara>
    The converted JSON value.
   </simpara>
+  &mongodb.note.duplicate-keys.tojson;
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/functions/bson/tojson.xml

@@ -78,6 +78,7 @@
   <simpara>
    The converted JSON value.
   </simpara>
+  &mongodb.note.duplicate-keys.tojson;
  </refsect1>
 
  <refsect1 role="errors">

reference/mongodb/functions/bson/torelaxedextendedjson.xml

@@ -52,6 +52,7 @@
   <simpara>
    The converted JSON value.
   </simpara>
+  &mongodb.note.duplicate-keys.tojson;
  </refsect1>
 
  <refsect1 role="errors">