glossary: Define "set" and "unset"

wking · wking · commit 87f66dca9276 · 2017-06-01T08:32:51.000-07:00
There seems to be confusion about whether the empty string (and possible other values that match Go's zero values) qualifies as "set" or not [1]. This commit clarifies that Go zero values are not relevant to the spec, but it does not address how they should be handled (I'm leaving that to follow-up work). [1]: opencontainers#823 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>
diff --git a/config-linux.md b/config-linux.md
@@ -39,7 +39,7 @@ The following parameters can be specified to set up namespaces:
     The runtime MUST place the container process in the namespace associated with that `path`.
     The runtime MUST [generate an error](runtime.md#errors) if `path` is not associated with a namespace of type `type`.
 
-    If `path` is not specified, the runtime MUST create a new [container namespace](glossary.md#container-namespace) of type `type`.
+    If `path` is [unset](glossary.md#set), the runtime MUST create a new [container namespace](glossary.md#container-namespace) of type `type`.
 
 If a namespace type is not specified in the `namespaces` array, the container MUST inherit the [runtime namespace](glossary.md#runtime-namespace) of that type.
 If a `namespaces` field contains duplicated namespaces with same `type`, the runtime MUST [generate an error](runtime.md#errors).
@@ -176,18 +176,18 @@ The path to the cgroups can be specified in the Spec via `cgroupsPath`.
 If `cgroupsPath` is:
 * ... an absolute path (starting with `/`), the runtime MUST take the path to be relative to the cgroup mount point.
 * ... a relative path (not starting with `/`), the runtime MAY interpret the path relative to a runtime-determined location in the cgroup hierarchy.
-* ... not specified, the runtime MAY define the default cgroup path.
+* ... [unset](glossary.md#set), the runtime MAY define the default cgroup path.
 Runtimes MAY consider certain `cgroupsPath` values to be invalid, and MUST generate an error if this is the case.
-If a `cgroupsPath` value is specified, the runtime MUST consistently attach to the same place in the cgroup hierarchy given the same value of `cgroupsPath`.
+If a `cgroupsPath` value is [set](glossary.md#set), the runtime MUST consistently attach to the same place in the cgroup hierarchy given the same value of `cgroupsPath`.
 
 Implementations of the Spec can choose to name cgroups in any manner.
 The Spec does not include naming schema for cgroups.
 The Spec does not support per-controller paths for the reasons discussed in the [cgroupv2 documentation][cgroup-v2].
 The cgroups will be created if they don't exist.
 
 You can configure a container's cgroups via the `resources` field of the Linux configuration.
-Do not specify `resources` unless limits have to be updated.
-For example, to run a new process in an existing container without updating limits, `resources` need not be specified.
+Do not [set](glossary.md#set) `resources` unless limits have to be updated.
+To run a new process in an existing container without updating limits, `resources` SHOULD be [unset](glossary.md#set).
 
 Runtimes MAY attach the container process to additional cgroup controllers beyond those necessary to fulfill the `resources` settings.
 
@@ -218,9 +218,9 @@ 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).
-    Unset values mean "all", mapping to `a`.
+    Defaults to `a`.
 * **`major, minor`** *(int64, OPTIONAL)* - [major, minor numbers][devices] for the device.
-    Unset values mean "all", mapping to [`*` in the filesystem API][cgroup-v1-devices].
+    Defaults to `*`, the semantics of which are documented [in the filesystem API][cgroup-v1-devices].
 * **`access`** *(string, OPTIONAL)* - cgroup permissions for device.
     A composition of `r` (read), `w` (write), and `m` (mknod).
 
@@ -335,7 +335,7 @@ The following parameters can be specified to set up the controller:
     * **`weight`** *(uint16, OPTIONAL)* - bandwidth rate for the device.
     * **`leafWeight`** *(uint16, OPTIONAL)* - bandwidth rate for the device while competing with the cgroup's child cgroups, CFQ scheduler only
 
-    You MUST specify at least one of `weight` or `leafWeight` in a given entry, and MAY specify both.
+    You MUST [set](glossary.md#set) at least one of `weight` or `leafWeight` in a given entry, and MAY [set](glossary.md#set) both.
 
 * **`blkioThrottleReadBpsDevice`**, **`blkioThrottleWriteBpsDevice`**, **`blkioThrottleReadIOPSDevice`**, **`blkioThrottleWriteIOPSDevice`** *(array of objects, OPTIONAL)* - specify the list of devices which will be IO rate limited.
     The following parameters can be specified per-device:
@@ -451,17 +451,17 @@ The following parameters can be specified to set up the controller:
 ## <a name="configLinuxIntelRdt" />IntelRdt
 
 **`intelRdt`** (object, OPTIONAL) represents the [Intel Resource Director Technology][intel-rdt-cat-kernel-interface].
-    If `intelRdt` is set, the runtime MUST write the container process ID to the `<container-id>/tasks` file in a mounted `resctrl` pseudo-filesystem, using the container ID from [`start`](runtime.md#start) and creating the `<container-id>` directory if necessary.
+    If `intelRdt` is [set](glossary.md#set), the runtime MUST write the container process ID to the `<container-id>/tasks` file in a mounted `resctrl` pseudo-filesystem, using the container ID from [`start`](runtime.md#start) and creating the `<container-id>` directory if necessary.
     If no mounted `resctrl` pseudo-filesystem is available in the [runtime mount namespace](glossary.md#runtime-namespace), the runtime MUST [generate an error](runtime.md#errors).
 
-    If `intelRdt` is not set, the runtime MUST NOT manipulate any `resctrl` psuedo-filesystems.
+    If `intelRdt` is [unset](glossary.md#set), the runtime MUST NOT manipulate any `resctrl` psuedo-filesystems.
 
 The following parameters can be specified for the container:
 
 * **`l3CacheSchema`** *(string, OPTIONAL)* - specifies the schema for L3 cache id and capacity bitmask (CBM).
-    If `l3CacheSchema` is set, runtimes MUST write the value to the `schemata` file in the `<container-id>` directory discussed in `intelRdt`.
+    If `l3CacheSchema` is [set](glossary.md#set), runtimes MUST write the value to the `schemata` file in the `<container-id>` directory discussed in `intelRdt`.
 
-    If `l3CacheSchema` is not set, runtimes MUST NOT write to `schemata` files in any `resctrl` psuedo-filesystems.
+    If `l3CacheSchema` is [unset](glossary.md#set), runtimes MUST NOT write to `schemata` files in any `resctrl` psuedo-filesystems.
 
 ### Example
 
@@ -528,7 +528,7 @@ The following parameters can be specified to set up seccomp:
 * **`syscalls`** *(array of objects, OPTIONAL)* - match a syscall in seccomp.
 
     While this property is OPTIONAL, some values of `defaultAction` are not useful without `syscalls` entries.
-    For example, if `defaultAction` is `SCMP_ACT_KILL` and `syscalls` is empty or unset, the kernel will kill the container process on its first syscall.
+    For example, if `defaultAction` is `SCMP_ACT_KILL` and `syscalls` is empty or [unset](glossary.md#set), the kernel will kill the container process on its first syscall.
 
     Each entry has the following structure:
 
diff --git a/config-solaris.md b/config-solaris.md
@@ -84,11 +84,11 @@ For additional information on properties, check the [zonecfg(1M)][zonecfg.1m_2]
 * **`lowerLink`** *(string, OPTIONAL)* Specify the link over which the VNIC will be created.
 Mapped to `lower-link` in the [zonecfg(1M)][zonecfg.1m_2] man page.
 * **`allowedAddress`** *(string, OPTIONAL)* The set of IP addresses that the container can use might be constrained by specifying the `allowedAddress` property.
-    If `allowedAddress` has not been specified, then they can use any IP address on the associated physical interface for the network resource.
-    Otherwise, when `allowedAddress` is specified, the container cannot use IP addresses that are not in the `allowedAddress` list for the physical address.
+    If `allowedAddress` is [unset](glossary.md#set), then they can use any IP address on the associated physical interface for the network resource.
+    Otherwise, when `allowedAddress` is [set](glossary.md#set), the container cannot use IP addresses that are not in the `allowedAddress` list for the physical address.
     Mapped to `allowed-address` in the [zonecfg(1M)][zonecfg.1m_2] man page.
-* **`configureAllowedAddress`** *(string, OPTIONAL)* If `configureAllowedAddress` is set to true, the addresses specified by `allowedAddress` are automatically configured on the interface each time the container starts.
-    When it is set to false, the `allowedAddress` will not be configured on container start.
+* **`configureAllowedAddress`** *(string, OPTIONAL)* If `configureAllowedAddress` is `true`, the addresses specified by `allowedAddress` are automatically configured on the interface each time the container starts.
+    When it is `false`, the `allowedAddress` will not be configured on container start.
     Mapped to `configure-allowed-address` in the [zonecfg(1M)][zonecfg.1m_2] man page.
 * **`defrouter`** *(string, OPTIONAL)* The value for the OPTIONAL default router.
 * **`macAddress`** *(string, OPTIONAL)* Set the VNIC's MAC addresses based on the specified value or keyword.
diff --git a/config-windows.md b/config-windows.md
@@ -155,14 +155,14 @@ You can indicate that a container should be started in an a mode where disk flus
 ## <a name="configWindowsHyperV" />HyperV
 
 `hyperv` is an OPTIONAL field of the Windows configuration.
-If present, the container MUST be run with Hyper-V isolation.
-If omitted, the container MUST be run as a Windows Server container.
+If [set](glossary.md#set), the container MUST be run with Hyper-V isolation.
+If [unset](glossary.md#set), the container MUST be run as a Windows Server container.
 
 The following parameters can be specified:
 
 * **`utilityVMPath`** *(string, OPTIONAL)* - specifies the path to the image used for the utility VM.
     This would be specified if using a base image which does not contain a utility VM image.
-    If not supplied, the runtime will search the container filesystem layers from the bottom-most layer upwards, until it locates "UtilityVM", and default to that path.
+    If [unset](glossary.md#set), the runtime MUST search the container filesystem layers from the bottom-most layer upwards, until it locates "UtilityVM", and default to that path.
 
 ### Example
 
diff --git a/config.md b/config.md
@@ -32,14 +32,15 @@ For all platform-specific configuration values, the scope defined below in the [
     The path is either an absolute path or a relative path to the bundle.
     Users SHOULD consider using a conventional name, such as `rootfs`.
 
-    * On Windows, for Windows Server Containers, this field is REQUIRED and MUST be specified as a [volume GUID path][naming-a-volume].
-      For Hyper-V Containers, this field MUST be omitted.
+    * On Windows, for Windows Server Containers, this field is REQUIRED and MUST be a [volume GUID path][naming-a-volume].
+      For Hyper-V Containers, this field MUST be [unset](glossary.md#set).
     * On all other platforms, this field is REQUIRED.
     * On Linux, for example, with a bundle at `/to/bundle` and a root filesystem at `/to/bundle/rootfs`, the `path` value can be either `/to/bundle/rootfs` or `rootfs`.
 
     If defined, a directory MUST exist at the path declared by the field.
-* **`readonly`** (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container, defaults to false.
-    * On Windows, this field MUST be omitted or false.
+* **`readonly`** (bool, OPTIONAL) If true then the root filesystem MUST be read-only inside the container.
+    Defaults to `false`.
+    * On Windows, this field MUST be [unset](glossary.md#set) or `false`.
 
 ### Example (POSIX)
 
@@ -173,8 +174,8 @@ For Linux-based systems the process structure supports the following process-spe
 * **`apparmorProfile`** (string, OPTIONAL) specifies the name of the AppArmor profile to be applied to processes in the container.
     For more information about AppArmor, see [AppArmor documentation][apparmor].
 * **`oomScoreAdj`** *(int, OPTIONAL)* adjusts the oom-killer score in `[pid]/oom_score_adj` for the container process's `[pid]` in a [proc pseudo-filesystem][procfs].
-    If `oomScoreAdj` is set, the runtime MUST set `oom_score_adj` to the given value.
-    If `oomScoreAdj` is not set, the runtime MUST NOT change the value of `oom_score_adj`.
+    If `oomScoreAdj` is [set](glossary.md#set), the runtime MUST set `oom_score_adj` to the given value.
+    If `oomScoreAdj` is [unset](glossary.md#set), the runtime MUST NOT change the value of `oom_score_adj`.
 
     This is a per-process setting, where as [`disableOOMKiller`](config-linux.md#disable-out-of-memory-killer) is scoped for a memory cgroup.
     For more information on how these two settings work together, see [the memory cgroup documentation section 10. OOM Contol][cgroup-v1-memory_2].
@@ -343,11 +344,11 @@ For Windows based systems the user structure has the following fields:
     Runtime implementations MAY support any valid values for platform-specific fields as part of this configuration.
 
 * **`linux`** (object, OPTIONAL) [Linux-specific configuration](config-linux.md).
-    This MAY be set if **`platform.os`** is `linux` and MUST NOT be set otherwise.
+    This MAY be [set](glossary.md#set) if **`platform.os`** is `linux` and MUST be [unset](glossary.md#set) otherwise.
 * **`windows`** (object, OPTIONAL) [Windows-specific configuration](config-windows.md).
-    This MUST be set if **`platform.os`** is `windows` and MUST NOT be set otherwise.
+    This MUST be [set](glossary.md#set) if **`platform.os`** is `windows` and MUST NOT be set otherwise.
 * **`solaris`** (object, OPTIONAL) [Solaris-specific configuration](config-solaris.md).
-    This MAY be set if **`platform.os`** is `solaris` and MUST NOT be set otherwise.
+    This MAY be [set](glossary.md#set) if **`platform.os`** is `solaris` and MUST be [unset](glossary.md#set) otherwise.
 
 ### Example (Linux)
 
@@ -380,7 +381,7 @@ On Linux, they are run after the container namespaces are created.
         * **`args`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2001 `execv`'s *argv*][ieee-1003.1-2001-xsh-exec].
         * **`env`** (array of strings, OPTIONAL) with the same semantics as [IEEE Std 1003.1-2001's `environ`][ieee-1003.1-2001-xbd-c8.1].
         * **`timeout`** (int, OPTIONAL) is the number of seconds before aborting the hook.
-            If set, `timeout` MUST be greater than zero.
+            If [set](glossary.md#set), `timeout` MUST be greater than zero.
     * **`poststart`** (array of objects, OPTIONAL) is an array of [post-start hooks](#poststart).
         Entries in the array have the same schema as pre-start entries.
     * **`poststop`** (array of objects, OPTIONAL) is an array of [post-stop hooks](#poststop).
diff --git a/glossary.md b/glossary.md
@@ -33,6 +33,9 @@ It reads the [configuration files](#configuration) from a [bundle](#bundle), use
 On Linux, a leaf in the [namespace][namespaces.7] hierarchy from which the [runtime](#runtime) process is executed.
 New container namespaces will be created as children of the runtime namespaces.
 
+## <a name="glossarySet" />Set
+
+A property is "set" if its key appears in the parent JSON object and "unset" if its key does not appear in the parent JSON object.
 
 [JSON]: https://tools.ietf.org/html/rfc7159
 [UTF-8]: http://www.unicode.org/versions/Unicode8.0.0/ch03.pdf
diff --git a/runtime.md b/runtime.md
@@ -117,7 +117,7 @@ This operation MUST [generate an error](#errors) if it is not provided the conta
 Attempting to start a container that does not exist MUST [generate an error](#errors).
 Attempting to start an already started container MUST have no effect on the container and MUST [generate an error](#errors).
 This operation MUST run the user-specified program as specified by [`process`](config.md#process).
-This operation MUST generate an error if `process` was not set.
+This operation MUST generate an error if `process` was [unset](glossary.md#set).
 
 ### <a name="runtimeKill" />Kill
 `kill <container-id> <signal>`
