diff --git a/config-linux.md b/config-linux.md
index cdd868e04..29e100ca6 100644
--- a/config-linux.md
+++ b/config-linux.md
@@ -73,6 +73,18 @@ If a new namespace is not created (because the namespace type is not listed, or
 
 ## User namespace mappings
 
+**`uidMappings`** (array of objects, OPTIONAL) describes the user namespace uid mappings from the host to the container.
+**`gidMappings`** (array of objects, OPTIONAL) describes the user namespace gid mappings from the host to the container.
+
+Each entry has the following structure:
+
+* **`hostID`** (uint32, REQUIRED)* - is the starting uid/gid on the host to be mapped to *containerID*.
+* **`containerID`** (uint32, REQUIRED)* - is the starting uid/gid in the container.
+* **`size`** (uint32, REQUIRED)* - is the number of ids to be mapped.
+
+The runtime SHOULD NOT modify the ownership of referenced filesystems to realize the mapping.
+There is a limit of 5 mappings which is the Linux kernel hard limit.
+
 ###### Example
 
 ```json
@@ -92,17 +104,12 @@ If a new namespace is not created (because the namespace type is not listed, or
     ]
 ```
 
-uid/gid mappings describe the user namespace mappings from the host to the container.
-The runtime SHOULD NOT modify the ownership of referenced filesystems to realize the mapping.
-*hostID* is the starting uid/gid on the host to be mapped to *containerID* which is the starting uid/gid in the container and *size* refers to the number of ids to be mapped.
-There is a limit of 5 mappings which is the Linux kernel hard limit.
-
 ## Devices
 
 **`devices`** (array of objects, OPTIONAL) lists devices that MUST be available in the container.
 The runtime may supply them however it likes (with [mknod][mknod.2], by bind mounting from the runtime mount namespace, etc.).
 
-The following parameters can be specified:
+Each entry has the following structure:
 
 * **`type`** *(string, REQUIRED)* - type of device: `c`, `b`, `u` or `p`.
   More info in [mknod(1)][mknod.1].
@@ -202,7 +209,7 @@ However, a runtime MAY attach the container process to additional cgroup control
 **`devices`** (array of objects, OPTIONAL) configures the [device whitelist][cgroup-v1-devices].
 The runtime MUST apply entries in the listed order.
 
-The following parameters can be specified:
+Each entry has the following structure:
 
 * **`allow`** *(boolean, REQUIRED)* - whether the entry is allowed or denied.
 * **`type`** *(string, OPTIONAL)* - type of device: `a` (all), `c` (char), or `b` (block).
@@ -421,7 +428,7 @@ Each entry has the following structure:
 **`network`** (object, OPTIONAL) represents the cgroup subsystems `net_cls` and `net_prio`.
 For more information, see [the net\_cls cgroup man page][cgroup-v1-net-cls] and [the net\_prio cgroup man page][cgroup-v1-net-prio].
 
-The following parameters can be specified to setup these cgroup controllers:
+The following parameters can be specified to setup the controller:
 
 * **`classID`** *(uint32, OPTIONAL)* - is the network class identifier the cgroup's network packets will be tagged with
 
diff --git a/specs-go/config.go b/specs-go/config.go
index 222ab6797..edb947d1b 100644
--- a/specs-go/config.go
+++ b/specs-go/config.go
@@ -187,11 +187,11 @@ const (
 
 // LinuxIDMapping specifies UID/GID mappings
 type LinuxIDMapping struct {
-	// HostID is the UID/GID of the host user or group
+	// HostID is the starting UID/GID on the host to be mapped to 'ContainerID'
 	HostID uint32 `json:"hostID"`
-	// ContainerID is the UID/GID of the container's user or group
+	// ContainerID is the starting UID/GID in the container
 	ContainerID uint32 `json:"containerID"`
-	// Size is the length of the range of IDs mapped between the two namespaces
+	// Size is the number of IDs to be mapped
 	Size uint32 `json:"size"`
 }