diff --git a/reference/mongodb/bson/document/fromjson.xml b/reference/mongodb/bson/document/fromjson.xml
index ea074b822..24b17e15d 100644
--- a/reference/mongodb/bson/document/fromjson.xml
+++ b/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">
diff --git a/reference/mongodb/bson/document/get.xml b/reference/mongodb/bson/document/get.xml
index 6548b1e81..2d3da9d00 100644
--- a/reference/mongodb/bson/document/get.xml
+++ b/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">
diff --git a/reference/mongodb/bson/document/getiterator.xml b/reference/mongodb/bson/document/getiterator.xml
index ddf84822d..851fdea3e 100644
--- a/reference/mongodb/bson/document/getiterator.xml
+++ b/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">
diff --git a/reference/mongodb/bson/document/offsetget.xml b/reference/mongodb/bson/document/offsetget.xml
index 6d3b546a1..c43f0765b 100644
--- a/reference/mongodb/bson/document/offsetget.xml
+++ b/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">
diff --git a/reference/mongodb/bson/document/tocanonicalextendedjson.xml b/reference/mongodb/bson/document/tocanonicalextendedjson.xml
index 55413c48d..30815e5c1 100644
--- a/reference/mongodb/bson/document/tocanonicalextendedjson.xml
+++ b/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">
diff --git a/reference/mongodb/bson/document/torelaxedextendedjson.xml b/reference/mongodb/bson/document/torelaxedextendedjson.xml
index 569f7a0d5..8682b84e6 100644
--- a/reference/mongodb/bson/document/torelaxedextendedjson.xml
+++ b/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">
diff --git a/reference/mongodb/entities.mongodb.ent b/reference/mongodb/entities.mongodb.ent
index bc461b02d..21abd79b9 100644
--- a/reference/mongodb/entities.mongodb.ent
+++ b/reference/mongodb/entities.mongodb.ent
@@ -752,6 +752,23 @@ local: {
    </note>
 </entity>
 
+<entity name="mongodb.note.duplicate-keys.tojson">
+  <note>
+   <simpara>
+    If the BSON document contains duplicate keys, all of them are preserved in
+    the JSON output.
+   </simpara>
+  </note>
+</entity>
+
+<entity name="mongodb.note.duplicate-keys.fromjson">
+  <note>
+   <simpara>
+    Duplicate keys in the JSON string are preserved in the order they appear.
+   </simpara>
+  </note>
+</entity>
+
 <entity name="mongodb.note.extended-json">
   <note>
    <simpara>
@@ -816,10 +833,10 @@ local: {
    <warning>
     <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>
    </warning>
 </entity>
diff --git a/reference/mongodb/functions/bson/fromjson.xml b/reference/mongodb/functions/bson/fromjson.xml
index da1514e3f..b42b3c7eb 100644
--- a/reference/mongodb/functions/bson/fromjson.xml
+++ b/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">
diff --git a/reference/mongodb/functions/bson/tocanonicalextendedjson.xml b/reference/mongodb/functions/bson/tocanonicalextendedjson.xml
index 63f8cde31..23d4a56e5 100644
--- a/reference/mongodb/functions/bson/tocanonicalextendedjson.xml
+++ b/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">
diff --git a/reference/mongodb/functions/bson/tojson.xml b/reference/mongodb/functions/bson/tojson.xml
index d504c61cf..0c403f15b 100644
--- a/reference/mongodb/functions/bson/tojson.xml
+++ b/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">
diff --git a/reference/mongodb/functions/bson/torelaxedextendedjson.xml b/reference/mongodb/functions/bson/torelaxedextendedjson.xml
index e767d51ae..a4fe3135b 100644
--- a/reference/mongodb/functions/bson/torelaxedextendedjson.xml
+++ b/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">