Merge pull request opencontainers#820 from jhowardmsft/clarifyrootpath

vbatts · web-flow · commit c83b8c80fd87 · 2017-05-18T14:16:14.000-04:00
Clarify root path
diff --git a/bundle.md b/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
diff --git a/config.md b/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
diff --git a/schema/config-schema.json b/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",
diff --git a/specs-go/config.go b/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"`
 }

Original file line number	Diff line number	Diff line change
`@@ -96,7 +96,7 @@ type User struct {`
`96`	`96`	`// Root contains information about the container's root filesystem on the host.`
`97`	`97`	`type Root struct {`
`98`	`98`	`// Path is the absolute path to the container's root filesystem.`
`99`		- Path string `json:"path"`
	`99`	+ Path string `json:"path,omitempty"`
`100`	`100`	`// Readonly makes the root filesystem for the container readonly before the process is executed.`
`101`	`101`	Readonly bool `json:"readonly,omitempty"`
`102`	`102`	`}`