config: Explicitly list 'hooks' as optional

And make it omitempty, otherwise:

  $ ocitools generate --template <(echo '{}')
  $ cat config.json | jq -S .
  {
    "hooks": {},
    ...
  }

To provide space for the type information and 'optional', I've
shuffled the hook docs to follow our usual:

  * **`{property}`** ({type}, {when-needed}) {notes}

format.  I've kept the separate event-trigger sections (e.g. "###
Prestart") since they go into more detail on the timing, purpose, and
exit handling for the different events (and that seemed like too much
information to put into the nested lists).

I've replaced the Go reference from 48049d2 (Clarify the semantics of
hook elements, 2015-11-25, opencontainers#255) with POSIX references (following the
new process docs) to address pushback against referencing Go [1,2] in
favor of POSIX links [3].  Rob Dolin had suggested
"platform-appropriate" wording [4], but it seems like Visual Studio
2015 supports execv [5], and providing an explicit
"platform-appropriate" wiggle seems like it's adding useless
complication.

[1]: opencontainers#427 (comment)
[2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-46
[3]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-52
[4]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-54
[5]: https://msdn.microsoft.com/en-us/library/886kc0as.aspx

Signed-off-by: W. Trevor King <wking@tremily.us>

config.md

@@ -239,17 +239,23 @@ _Note: For Solaris, uid and gid specify the uid and gid of the process inside th
 ## Hooks
 
 Lifecycle hooks allow custom events for different points in a container's runtime.
-Presently there are `Prestart`, `Poststart` and `Poststop`.
 
-* [`Prestart`](#prestart) is a list of hooks to be run before the container process is executed
-* [`Poststart`](#poststart) is a list of hooks to be run immediately after the container process is started
-* [`Poststop`](#poststop) is a list of hooks to be run after the container process exits
+* **`hooks`** (object, optional) MAY contain any of the following properties:
+  * **`prestart`** (array, optional) is an array of [pre-start hooks](#prestart).
+    Entries in the array contain the following properties:
+    * **`path`** (string, required) with similar semantics to [IEEE Std 1003.1-2001 `execv`'s *path*][ieee-1003.1-2001-xsh-exec].
+      This specification extends the IEEE standard in that **`path`** MUST be absolute.
+    * **`args`** (array of strings, required) 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.
+  * **`poststart`** (array, optional) is an array of [post-start hooks](#poststart).
+    Entries in the array have the same schema as pre-start entries.
+  * **`poststop`** (array, optional) is an array of [post-stop hooks](#poststop).
+    Entries in the array have the same schema as pre-start entries.
 
 Hooks allow one to run code before/after various lifecycle events of the container.
 Hooks MUST be called in the listed order.
-The state of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work.
-
-Hook paths are absolute and are executed from the host's filesystem in the [runtime namespace][runtime-namespace].
+The [state](runtime.md#state) of the container is passed to the hooks over stdin, so the hooks could get the information they need to do their work.
 
 ### Prestart
 
@@ -301,11 +307,6 @@ If a hook returns a non-zero exit code, then an error is logged and the remainin
     }
 ```
 
-`path` is required for a hook.
-`args` and `env` are optional.
-`timeout` is the number of seconds before aborting the hook.
-The semantics are the same as `Path`, `Args` and `Env` in [golang Cmd](https://golang.org/pkg/os/exec/#Cmd).
-
 ## Annotations
 
 This OPTIONAL property contains arbitrary metadata for the container.

specs-go/config.go

@@ -19,7 +19,7 @@ type Spec struct {
 	// Mounts profile configuration for adding mounts to the container's filesystem.
 	Mounts []Mount `json:"mounts,omitempty"`
 	// Hooks are the commands run at various lifecycle events of the container.
-	Hooks Hooks `json:"hooks"`
+	Hooks Hooks `json:"hooks,omitempty"`
 	// Annotations is an unstructured key value map that may be set by external tools to store and retrieve arbitrary metadata.
 	Annotations map[string]string `json:"annotations,omitempty"`