diff --git a/docs/source/couchdb_as_state_database.rst b/docs/source/couchdb_as_state_database.rst
index 66f4d2c6a16..9e138860dbf 100644
--- a/docs/source/couchdb_as_state_database.rst
+++ b/docs/source/couchdb_as_state_database.rst
@@ -37,6 +37,14 @@ default embedded LevelDB, and move to CouchDB if you require the additional comp
 It is a good practice to model chaincode asset data as JSON, so that you have the option to perform
 complex rich queries if needed in the future.
 
+.. note:: A JSON document cannot use the following field names at the top level.
+   These are reserved for internal use.
+
+   - ``_deleted``
+   - ``_id``
+   - ``_rev``
+   - ``~version``
+
 Using CouchDB from Chaincode
 ----------------------------