diff --git a/docs/namespaces.md b/docs/namespaces.md
index 54ea625bb..95f2a97cf 100644
--- a/docs/namespaces.md
+++ b/docs/namespaces.md
@@ -24,6 +24,8 @@ ns, ok := namespaces.Namespace(ctx)
 
 Because the client calls containerd's gRPC API to interact with the daemon, all API calls require a context with a namespace set.
 
+> Note that a namespace cannot be named `"version"` ([#6944](https://github.com/containerd/containerd/issues/6944)).
+
 ## How low level is the implementation?
 
 Namespaces are passed through the containerd API to the underlying plugins providing functionality.
diff --git a/metadata/buckets.go b/metadata/buckets.go
index af3318306..19e0f91ea 100644
--- a/metadata/buckets.go
+++ b/metadata/buckets.go
@@ -44,10 +44,15 @@
 //
 // Below is the current database schema. This should be updated each time
 // the structure is changed in addition to adding a migration and incrementing
-// the database version. Note that `╘══*...*` refers to maps with arbitrary
-// keys.
-//  ├──version : <varint>                        - Latest version, see migrations
+// the database version.
+// Notes:
+//  * `╘══*...*` refers to maps with arbitrary keys
+//  * `version` is a key to a numeric value identifying the minor revisions
+//    of schema version
+//  * a namespace in a schema bucket cannot be named "version"
+//
 //  └──v1                                        - Schema version bucket
+//     ├──version : <varint>                     - Latest version, see migrations
 //     ╘══*namespace*
 //        ├──labels
 //        │  ╘══*key* : <string>                 - Label value