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 punting to platforms with POSIX links for POSIX systems [3].

[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-54

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

config.md

@@ -237,17 +237,29 @@ _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) contains the location of the executable in the [runtime namespace][runtime-namespace].
+      The semantics of the string are specified in a platform-appropriate way.
+      On POSIX platforms the semantics are similar 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, optional) contains a list of arguments passed to the executable.
+      The semantics of the array are specified in a platform-appropriate way.
+      On POSIX platforms the semantics are the same as [IEEE Std 1003.1-2001 `execv`'s *argv*][ieee-1003.1-2001-xsh-exec].
+    * **`env`** (array of strings, optional) contains a list of variables that will be set in the process's environment prior to execution.
+      Elements in the array are specified in a platform-appropriate way.
+      On POSIX platforms the strings MUST have the form *name=value*, where *name* MUST NOT contain the character `=`, as outlined in [IEEE Std 1003.1-2001][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
 
@@ -299,11 +311,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"`