spec: Standardize language for actions ((un)packing, etc.)

To set ourselves up for more consistent discussions.  This also
unifies the old "Overview" and "Understanding the Specification"
sections, which had a fair amount of overlap.

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

layer.md

@@ -91,7 +91,7 @@ END FOR
 
 With this approach, the link map and links names of a directory could be compared against that of another directory to derive additions and changes to hardlinks.
 
-## Creating
+## Packing
 
 ### Initial Root Filesystem
 
@@ -211,17 +211,17 @@ The resulting tar archive for `rootfs-c9d-v1.s1` has the following entries:
 
 To signify that the resource `./etc/my-app-config` MUST be removed when the changeset is applied, the basename of the entry is prefixed with `.wh.`.
 
-## Applying Changesets
+## Unpacking
 
-Layer Changesets of [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` are _applied_, rather than simply extracted as tar archives.
+Layer Changesets of [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` are _unpacked_, rather than simply extracted as tar archives.
 
-Applying a layer changeset requires special consideration for the [whiteout](#whiteouts) files.
+Unpacking a layer changeset requires special consideration for the [whiteout](#whiteouts) files.
 
 In the absence of any [whiteout](#whiteouts) files in a layer changeset, the archive is extracted like a regular tar archive.
 
 ### Changeset over existing files
 
-This section specifies applying an entry from a layer changeset if the target path already exists.
+This section specifies unpacking an entry from a layer changeset if the target path already exists.
 
 If the entry and the existing path are both directories, then the existing path's attributes MUST be replaced by those of the entry in the changeset.
 In all other cases, the implementation MUST do the semantic equivalent of the following:

spec.md

@@ -9,8 +9,11 @@ The goal of this specification is to enable the creation of interoperable tools
 - [Introduction](spec.md)
 - [Notational Conventions](#notational-conventions)
 - [Overview](#overview)
-    - [Understanding the Specification](#understanding-the-specification)
-    - [Media Types](media-types.md)
+    - [Components](#componets)
+    - [Actions](#actions)
+    - [Publishing Images](#publishing-images)
+    - [Consuming Images](#consuming-images)
+    - [Media Types](#media-types.md)
 - [Content Descriptors](descriptor.md)
 - [Image Layout](image-layout.md)
 - [Image Manifest](manifest.md)
@@ -33,18 +36,7 @@ An implementation is compliant if it satisfies all the MUST, REQUIRED, and SHALL
 
 # Overview
 
-At a high level the image manifest contains metadata about the contents and dependencies of the image including the content-addressable identity of one or more [filesystem layer changeset](layer.md) archives that will be unpacked to make up the final runnable filesystem.
-The image configuration includes information such as application arguments, environments, etc.
-The manifest list is a higher-level manifest which points to one or more manifests.
-Typically, these manifests may provide different implementations of the image, possibly varying by platform or other attributes.
-
-![](img/build-diagram.png)
-
-Once built the OCI Image can then be discovered by name, downloaded, verified by hash, trusted through a signature, and unpacked into an [OCI Runtime Bundle](https://github.com/opencontainers/runtime-spec/blob/master/bundle.md).
-
-![](img/run-diagram.png)
-
-## Understanding the Specification
+## Components
 
 The [OCI Image Media Types](media-types.md) document is a starting point to understanding the overall structure of the specification.
 
@@ -56,4 +48,42 @@ The high-level components of the spec include:
 * Signatures that are based on signing image content address (optional OCI layer)
 * Naming that is federated based on DNS and can be delegated (optional OCI layer)
 
+## Actions
+
+The specified [components](#components) MAY be manipulated with actions.
+
+* **pack**: Create a blob from the local filesystem (or other storage).
+* **unpack**: Update the local filesystem (or other storage) based on data found in a blob.
+* **validate**: Verify that blobs [comply](#notational-conventions) with the specification for their [media type](media-types.md).
+    Blobs can be validated on their own (**intra-blob validation**) or recursively including [referenced](descriptor.md) ancestors (**recursive validation**).
+* **translate**: Convert a blob between similar formats.
+    Translation may be **lossy** or **lossless** depending on how well the formats align.
+
+## Publishing Images
+
+In publishing a new image, an example workflow is:
+
+* The [bundle][]'s [root filesystem][runtime-spec-root] is packed into a [layer](layer.md) (or layers).
+* The [bundle's `config.json`][bundle] is translated into an [image configuration](config.md).
+* The image configuration and layer(s) are packed into a [manifest](manifest.md).
+* That manifest (and potentially other manifests) are packed into a [manifest-list](manifest-list.md) (optional).
+* A reference to the manifest-list (and/or manifest) is published.
+
+![](img/build-diagram.png)
+
+## Consuming Images
+
+In consuming an existing image, an example workflow is:
+
+* The image reference is discovered (possibly via an [index of references](image-layout.md#refs) and [associated annotations](descriptor.md#properties).
+* The referenced [manifest-list](manifest-list.md) (optional) is unpacked to find the appropriate [manifest](manifest.md) for the target platform.
+* The referenced [manifest](manifest.md) is unpacked to find the [image configuration](config.md) and [layer(s)](layer.md).
+* The referenced [layer(s)](layer.md) are unpacked into the [bundle][]'s [root filesystem][runtime-spec-root].
+* The referenced [image configuration](config.md) is translated to a [runtime configuration][runtime-spec-config] and written to the [bundle's `config.json`][bundle].
+
+![](img/run-diagram.png)
+
 [c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18
+[bundle]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/bundle.md
+[runtime-spec-root]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md#root-configuration
+[runtime-spec-config]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md