Merge pull request opencontainers#820 from jhowardmsft/clarifyrootpath

Clarify root path

bundle.md

@@ -8,17 +8,22 @@ See also [MacOS application bundles][macos_bundle] for a similar use of the term
 The definition of a bundle is only concerned with how a container, and its configuration data, are stored on a local filesystem so that it can be consumed by a compliant runtime.
 
 A Standard Container bundle contains all the information needed to load and run a container.
-This MUST include the following artifacts:
+This includes the following artifacts:
 
 1. <a name="containerFormat01" />`config.json`: contains configuration data.
 This REQUIRED file MUST reside in the root of the bundle directory and MUST be named `config.json`.
 See [`config.json`](config.md) for more details.
 
 2. <a name="containerFormat02" />A directory representing the root filesystem of the container.
-While the name of this REQUIRED directory may be arbitrary, users should consider using a conventional name, such as `rootfs`.
-This directory MUST be referenced by [`root`](config.md#root) within the `config.json` file.
+    While the name of this directory may be arbitrary, users should consider using a conventional name, such as `rootfs`.
 
-While these artifacts MUST all be present in a single directory on the local filesystem, that directory itself is not part of the bundle.
+    On Windows, for Windows Server containers, this directory is REQUIRED. For Hyper-V containers, it MUST be omitted.
+
+    On all other platforms, this field is REQUIRED.
+
+    If set, this directory MUST be referenced by [`root`](config.md#root) within the `config.json` file.
+
+When supplied, while these artifacts MUST all be present in a single directory on the local filesystem, that directory itself is not part of the bundle.
 In other words, a tar archive of a *bundle* will have these artifacts at the root of the archive, not nested within a top-level directory.
 
 [macos_bundle]: https://en.wikipedia.org/wiki/Bundle_%28macOS%29

config.md

@@ -28,10 +28,15 @@ For example, if a configuration is compliant with version 1.1 of this specificat
 
 **`root`** (object, REQUIRED) specifies the container's root filesystem.
 
-* **`path`** (string, REQUIRED) Specifies the path to the root filesystem for the container.
-  The path is either an absolute path or a relative path to the bundle.
-  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`.
-  A directory MUST exist at the path declared by the field.
+* **`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.
+
+    On Windows, for Windows Server Containers, this field is REQUIRED. For Hyper-V Containers, this field MUST be omitted.
+
+    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.
 
 ### Example

schema/config-schema.json

@@ -59,9 +59,6 @@
             "description": "Configures the container's root filesystem.",
             "id": "https://opencontainers.org/schema/bundle/root",
             "type": "object",
-            "required": [
-                "path"
-            ],
             "properties": {
                 "path": {
                     "id": "https://opencontainers.org/schema/bundle/root/path",

specs-go/config.go

@@ -96,7 +96,7 @@ type User struct {
 // Root contains information about the container's root filesystem on the host.
 type Root struct {
 	// Path is the absolute path to the container's root filesystem.
-	Path string `json:"path"`
+	Path string `json:"path,omitempty"`
 	// Readonly makes the root filesystem for the container readonly before the process is executed.
 	Readonly bool `json:"readonly,omitempty"`
 }