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).

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

config.md

@@ -229,17 +229,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 the same semantics as Go's [`Cmd.Path`][go-cmd].
+      Hook paths are absolute and are executed from the host's filesystem in the [runtime namespace][runtime-namespace].
+    * **`args`** (array of strings, optional) with the same semantics as Go's [`Cmd.Args`][go-cmd].
+    * **`env`** (array of strings, optional) with the same semantics as Go's [`Cmd.Env`][go-cmd].
+    * **`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
 
@@ -291,11 +297,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.
@@ -684,3 +685,4 @@ Here is a full example `config.json` for reference.
 
 [runtime-namespace]: glossary.md#runtime-namespace
 [uts-namespace]: http://man7.org/linux/man-pages/man7/namespaces.7.html
+[go-cmd]: https://golang.org/pkg/os/exec/#Cmd

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