diff --git a/language-snippets.ent b/language-snippets.ent
index a721f1edb553..2c5297819c53 100644
--- a/language-snippets.ent
+++ b/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>
 '>
diff --git a/reference/mongodb/bson/document/fromjson.xml b/reference/mongodb/bson/document/fromjson.xml
index 23e460fb9eb8..aa38b9a77753 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 c9f4186e1f1c..2f53901f29e6 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 1992625f6daa..f574c80df95d 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 8463b5aef5cc..31e87eac6b07 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 55413c48df96..30815e5c19a2 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 569f7a0d5754..8682b84e6856 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/functions/bson/fromjson.xml b/reference/mongodb/functions/bson/fromjson.xml
index a91e0e0b2df1..d673f85a6b7d 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 63f8cde31402..23d4a56e57af 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 44d1aff0d19b..3e5e4254911c 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 e767d51aedfe..a4fe3135b3b3 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">