diff --git a/docs/modules/security/pages/client-authorization.adoc b/docs/modules/security/pages/client-authorization.adoc
index 57d9d75fc..cb37cef40 100644
--- a/docs/modules/security/pages/client-authorization.adoc
+++ b/docs/modules/security/pages/client-authorization.adoc
@@ -188,6 +188,18 @@ can be configured as required.
 
 The following is the list of client permissions that can be configured on the member:
 
+[NOTE]
+====
+In YAML configuration, permission types use one of two formats:
+
+* **Single object format** (used by `all`, `config`, and `transaction`): These singleton permissions can only have one configuration entry, so they are defined directly as an object without the `-` list indicator.
+* **Array format** (used by all other permission types): These permissions support multiple entries with different `name` attributes or configurations, so each entry begins with a `-` to indicate it is a list item.
+
+For example, `all: principal: admin` (single object) versus `map: - name: myMap` (array).
+
+If you see an error like `expected type: JSONArray, found: JSONObject`, check whether you are using the correct format for the permission type.
+====
+
 === All permissions
 
 `<all-permissions>` grants clients access to all data and features.
@@ -1150,7 +1162,7 @@ XML::
 
 [source,xml]
 ----
-<user-code-namespace-permission principal="principal">
+<user-code-namespace-permission principal="principal" name="my_namespace">
     <endpoints>
         ...
     </endpoints>
@@ -1166,11 +1178,12 @@ YAML::
 [source,yaml]
 ----
 user-code-namespace:
-  principal: principal
-  endpoints:
-    - ..
-  actions:
-    - ..
+  - name: my_namespace
+    principal: principal
+    endpoints:
+      - ..
+    actions:
+      - ..
 ----
 ====