distribution: Reword scope table to avoid repository/image distinction

Mike and I have had a lengthy discussion before realizing that we were
not interpreting these terms the same way [1].  This commit replaces
some explicit object-type lists with "objects defined in the image
specification", which is more concrete than using terms without local
definitions.  I've also added image-spec links where I do use
object-type terms.  And I've used the wordy but more explicit "groups
of image indexes" instead of "repositories" in most cases.

I've also explicitly listed /v2/_catalog as out of scope.  It's a
higher-level endpoint than the image-spec objects.  As Patrick [2] and
Stephen [3] pointed out when the endpoint landed, it's for internal
administration.  Matt suggested keeping it out of the user-facing API
on those grounds [4], and while that didn't happen in
docker/distribution, I think we want to keep the endpoint out of our
distribution spec in order to avoid burdening implementors (because as
Patrick pointed out [2], it's an expensive endpoint unrelated to image
push/pull).

[1]: opencontainers#44 (comment)
[2]: distribution/distribution#653 (comment)
[3]: distribution/distribution#653 (comment)
[4]: distribution/distribution#653 (comment)

proposals/distribution.md

@@ -104,30 +104,30 @@ The following entries should be added to the [scope table][scope]:
 * “Specifying a distribution method”.
     This entry replaces part of the previous “Creating Reference spec for optional DNS based naming & distribution” and “Standardizing on a particular Distribution method” entries.
 
-    Retrieving images covers the current “tag listing” (e.g. “what named manifests are in `library/busybox`?”), because tags are entries in the image format's [`manifests` array][manifests].
+    Retrieving image indexes covers the current “tag listing” (e.g. “what named manifests are in `library/busybox`?”), because tags are entries in the image format's [`manifests` array][manifests].
     Other tag-listing endpoints needed for backwards-compatibility are therefore in scope as well.
 
-    Repository actions and listing images within a repository are considered part of distribution policy or content management and are out of scope for this entry's per-image action.
+    Grouping image indexes in repositories is considered part of distribution policy or content management and are out of scope for this entry's per-image action.
     For example, “what images are under `library/`?” is out of scope for this project.
 
     * What: Specifying a distribution method
     * In/Out/Future: In scope
     * Status: In progress (see opencontainers/distribution-spec)
-    * Description: Define a protocol for image, manifest, config, and blob creation, retrieval, and deletion.
-        Listing repositories is a multi-repository action, which is out of scope for this entry.
-        Creating and deleting repositories are per-repository actions, which are out of scope for this entry.
-        Listing images within repositories is a per-repository action, which is out of scope for this entry.
+    * Description: Define a protocol for creating, retrieving, updating, and deleting objects defined in the [image specification][image-spec].
+        Listing repositories (like [`/v2/_catalog`][catalog]) is a multi-[image-index][] action, which is out of scope for this entry.
+        Managing groups of image indexes requires multi-[image-index][] actions, which are out of scope for this entry.
+        Listing image indexes within a group is a multi-[image-index][] action, which is out of scope for this entry.
     * Why: This specification will provide one (of possibly many) distribution specifications.
         Alternative distribution specifications may be developed for uses cases not covered by this specification, but defining them is currently out of scope for the OCI.
 
-* “Retrieving images by their content-addressable hash”.
-    Docker's registery API already provides endpoints for fetching manifest objects by digest][get-manifest].
-    Docker's registery API does not currently provide endpoints for fetching image objects by digest, but this is the project where that will happen.
+* “Retrieving image content by its content-addressable hash”.
+    Docker's registery API already provides [endpoints for fetching manifest objects by digest][get-manifest].
+    Docker's registery API does not currently provide endpoints for fetching [image-index][] objects by digest, but this is the project where that will happen.
 
-    * What: Retrieving images by their content-addressable hash
+    * What: Retrieving image content by its content-addressable hash
     * In/Out/Future: In scope
     * Status: In progress (see opencontainers/distribution-spec)
-    * Description: Specify a protocol for retrieving an image from a distribution engine by the image's content-addressable hash.
+    * Description: Specify a protocol for retrieving an [image index][image-index], manifest, or other [image specification][image-spec] object from a distribution engine by its content-addressable hash.
     * Why: Using a hash as a name is a way to ensure a unique image name without relying on a particular naming authority or system.
         Using hashing for name is an acceptable addition as it does not encode any centralized namespace.
 
@@ -142,8 +142,11 @@ The following entries should remain in the [scope table][scope] but not be addre
 * Allows listing of manifests: docker/distribution#2199
 
 [api.md]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md
+[catalog]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#catalog
 [get-manifest]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md#pulling-an-image-manifest
 [iana-auth]: http://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml
+[image-spec]: https://github.com/opencontainers/image-spec/
+[image-index]: https://github.com/opencontainers/image-spec/blame/v1.0.1/image-index.md
 [manifests]: https://github.com/opencontainers/image-spec/blame/v1.0.1/image-index.md#L23
 [rfc6750]: https://tools.ietf.org/html/rfc6750
 [rfc7230]: https://tools.ietf.org/html/rfc7230