From fa0eb40cba18079bf9490c4f334db04eed0d17a0 Mon Sep 17 00:00:00 2001
From: Valeri Karpov <val@karpov.io>
Date: Tue, 26 Dec 2023 14:05:42 -0500
Subject: [PATCH 1/2] docs: clarify disabling `_id` on subdocs

Fix #14194
---
 docs/guide.md | 45 +++++++++++++++++++++++++++++++++++++--------
 lib/schema.js |  2 +-
 2 files changed, 38 insertions(+), 9 deletions(-)

diff --git a/docs/guide.md b/docs/guide.md
index c505d82392b..06e3ab3f5bd 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -109,9 +109,7 @@ const schema = new Schema();
 schema.path('_id'); // ObjectId { ... }
 ```
 
-When you create a new document with the automatically added
-`_id` property, Mongoose creates a new [`_id` of type ObjectId](https://masteringjs.io/tutorials/mongoose/objectid)
-to your document.
+When you create a new document with the automatically added `_id` property, Mongoose creates a new [`_id` of type ObjectId](https://masteringjs.io/tutorials/mongoose/objectid) to your document.
 
 ```javascript
 const Model = mongoose.model('Test', schema);
@@ -120,13 +118,13 @@ const doc = new Model();
 doc._id instanceof mongoose.Types.ObjectId; // true
 ```
 
-You can also overwrite Mongoose's default `_id` with your
-own `_id`. Just be careful: Mongoose will refuse to save a
-document that doesn't have an `_id`, so you're responsible
-for setting `_id` if you define your own `_id` path.
+You can also overwrite Mongoose's default `_id` with your own `_id`.
+Just be careful: Mongoose will refuse to save a top-level document that doesn't have an `_id`, so you're responsible for setting `_id` if you define your own `_id` path.
 
 ```javascript
-const schema = new Schema({ _id: Number });
+const schema = new Schema({
+  _id: Number // <-- overwrite Mongoose's default `_id`
+});
 const Model = mongoose.model('Test', schema);
 
 const doc = new Model();
@@ -136,6 +134,37 @@ doc._id = 1;
 await doc.save(); // works
 ```
 
+Mongoose also adds an `_id` property to subdocuments.
+You can disable the `_id` property on your subdocuments as follows.
+Mongoose does allow saving subdocuments without an `_id` property.
+
+```javascript
+const nestedSchema = new Schema(
+  { name: String },
+  { _id: false } // <-- disable `_id`
+);
+const schema = new Schema({
+  subdoc: nestedSchema,
+  docArray: [nestedSchema]
+});
+const Test = mongoose.model('Test', schema);
+
+// Neither `subdoc` nor `docArray.0` will have an `_id`
+await Test.create({
+  subdoc: { name: 'test 1' },
+  docArray: [{ name: 'test 2' }]
+});
+```
+
+Alternatively, you can disable `_id` using the following syntax:
+
+```javascript
+const nestedSchema = new Schema({
+  _id: false, // <-- disable _id
+  name: String
+});
+```
+
 <h2 id="methods"><a href="#methods">Instance methods</a></h2>
 
 Instances of `Models` are [documents](documents.html). Documents have
diff --git a/lib/schema.js b/lib/schema.js
index a0b44e21c64..8b44e9fe8bb 100644
--- a/lib/schema.js
+++ b/lib/schema.js
@@ -49,7 +49,7 @@ const numberRE = /^\d+$/;
  *     const Tree = mongoose.model('Tree', schema);
  *
  *     // setting schema options
- *     new Schema({ name: String }, { _id: false, autoIndex: false })
+ *     new Schema({ name: String }, { id: false, autoIndex: false })
  *
  * #### Options:
  *

From 4240edd90da44261670071d386279fd77b81a370 Mon Sep 17 00:00:00 2001
From: Valeri Karpov <val@karpov.io>
Date: Wed, 27 Dec 2023 14:28:45 -0500
Subject: [PATCH 2/2] style: fix lint

---
 docs/migrating_to_8.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/migrating_to_8.md b/docs/migrating_to_8.md
index 02267bfe733..55b9d12a4ee 100644
--- a/docs/migrating_to_8.md
+++ b/docs/migrating_to_8.md
@@ -73,13 +73,13 @@ There's a few noteable changes in MongoDB Node driver v6 that affect Mongoose:
 
 1. Deprecated SSL options have been removed
 
-   - `sslCA` -> `tlsCAFile`
-   - `sslCRL` -> `tlsCRLFile`
-   - `sslCert` -> `tlsCertificateKeyFile`
-   - `sslKey` -> `tlsCertificateKeyFile`
-   - `sslPass` -> `tlsCertificateKeyFilePassword`
-   - `sslValidate` -> `tlsAllowInvalidCertificates`
-   - `tlsCertificateFile` -> `tlsCertificateKeyFile`
+   * `sslCA` -> `tlsCAFile`
+   * `sslCRL` -> `tlsCRLFile`
+   * `sslCert` -> `tlsCertificateKeyFile`
+   * `sslKey` -> `tlsCertificateKeyFile`
+   * `sslPass` -> `tlsCertificateKeyFilePassword`
+   * `sslValidate` -> `tlsAllowInvalidCertificates`
+   * `tlsCertificateFile` -> `tlsCertificateKeyFile`
 
 <h2 id="removed-findoneandremove"><a href="#removed-findoneandremove">Removed <code>findOneAndRemove()</code></a></h2>