DRIVERS-1408 - Add guidance on adding _id fields to documents to CRUD spec

source/crud/crud.md

@@ -820,6 +820,13 @@ database-level aggregation will allow users to receive a cursor from these colle
 
 ##### Insert, Update, Replace, Delete, and Bulk Writes
 
+###### Generated identifiers
+
+The insert and bulk insert operations described below MUST generate identifiers for all documents that do not already
+have them. These identifiers SHOULD be prepended to the document so they are the first field, in order to prevent the
+server from spending time re-ordering the document. If a document already has a user-provided identifier, the driver MAY
+re-order the document so the identifier is the first field.
+
 ```typescript
 interface Collection {
 
@@ -2481,6 +2488,8 @@ aforementioned allowance in the SemVer spec.
 
 - 2024-10-30: Document query limitations in `countDocuments`.
 
+- 2024-10-28: Clarified that generated identifiers should be prepended to documents.
+
 - 2024-10-01: Add sort option to `replaceOne` and `updateOne`.
 
 - 2024-09-12: Specify that explain helpers support maxTimeMS.

source/crud/tests/README.md

@@ -737,3 +737,15 @@ that `firstEvent.operationId` is equal to `secondEvent.operationId`. Assert both
 To force completion of the `w:0` writes, execute `coll.countDocuments` and expect the returned count is
 `maxMessageSizeBytes / maxBsonObjectSize + 1`. This is intended to avoid incomplete writes interfering with other tests
 that may use this collection.
+
+### 16. Generated document identifiers are the first field in their document
+
+Construct a `MongoClient` (referred to as `client`) with
+[command monitoring](../../command-logging-and-monitoring/command-logging-and-monitoring.md) enabled to observe
+CommandStartedEvents. For each of `insertOne`, client `bulkWrite`, and collection `bulkWrite`, do the following:
+
+- Execute the command with a document that does not contain an `_id` field.
+- If possible, capture the wire protocol message (referred to as `request`) of the command and assert that the first
+    field of `request.documents[0]` is `_id`.
+- Otherwise, capture the CommandStartedEvent (referred to as `event`) emitted by the command and assert that the first
+    field of `event.command.documents[0]` is `_id`.