glossary: Define "set" and "unset"

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 <[email protected]>

Author: wking

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).
 
@@ -348,7 +348,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:
@@ -466,17 +466,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
 
@@ -543,7 +543,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:
 

config-solaris.md

@@ -87,8 +87,8 @@ Mapped to `lower-link` in the [zonecfg(1M)][zonecfg.1m_2] man page.
 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.
 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.

config-windows.md

@@ -142,11 +142,15 @@ 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.
+`hyperv` is an OPTIONAL field of the Windows configuration.
+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.
+* **`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 [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
 

config.md

@@ -31,14 +31,17 @@ For example, if a configuration is compliant with version 1.1 of this specificat
 * **`path`** (string, OPTIONAL) Specifies the path to the root filesystem for the container. 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)
 
@@ -163,13 +166,13 @@ For Solaris, the mount entry corresponds to the 'fs' resource in the [zonecfg(1M
 * **`noNewPrivileges`** (bool, OPTIONAL) setting `noNewPrivileges` to true prevents the processes in the container from gaining additional privileges.
   As an example, the ['no_new_privs'][no-new-privs] article in the kernel documentation has information on how this is achieved using a prctl system call on Linux.
 
-For Linux-based systems the process structure supports the following process-specific fields.
+For Linux-based systems, the `process` structure also contains:
 
 * **`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].
@@ -338,11 +341,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 MAY be set if **`platform.os`** is `windows` and MUST NOT be set otherwise.
+  This MAY be [set](glossary.md#set) if **`platform.os`** is `windows` and MUST be [unset](glossary.md#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)
 
@@ -374,7 +377,7 @@ Hooks allow for the configuration of custom actions related to the [lifecycle](r
         * **`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).

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

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>`