image-layout: OPTIONAL index.json

From the 2017-01-25 call we agreed to keep the manifest list as the
entry point for accessing objects. The index concept is only a more
generic use of the manifest-list.
opencontainers#438 (comment)

This change uses the manifest-list as an index that allows
implementations to work around needing to walk/traverse the `./refs/` or
`./blobs/` directories.

Obsoletes opencontainers#438

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>

image-layout.md

@@ -14,11 +14,13 @@ Given an image layout and a ref, a tool can create an [OCI Runtime Specification
 The image layout MUST contain two top level directories:
 
 - `blobs` contains content-addressable blobs.
-  A blob has no schema and should be considered opaque.
+    - A blob has no schema and should be considered opaque.
+    - Directory MAY be empty.
+    - See [blobs](#blobs) section
 - `refs` contains [descriptors][descriptors].
-  Commonly pointing to an [image manifest](manifest.md#image-manifest) or an [image manifest list](manifest-list.md#oci-image-manifest-list-specification).
-
-Both `blobs` and `refs` MAY be empty.
+    - Commonly pointing to an [image manifest](manifest.md#image-manifest) or an [image manifest list](manifest-list.md#oci-image-manifest-list-specification).
+    - Directory MAY be empty.
+    - See [refs](#refs) section
 
 The image layout MUST also contain an `oci-layout` file:
 
@@ -27,23 +29,26 @@ The image layout MUST also contain an `oci-layout` file:
     - The `imageLayoutVersion` value will align with the OCI Image Specification version at the time changes to the layout are made, and will pin a given version until changes to the layout are required
 - It MAY include additional fields
 
+The image layout MAY also contain an `index.json` file:
+
+- It MUST be a JSON object
+- It MUST have the base properties of [manifest-list](manifest-list.md).
+- See [index.json](#index.json) section
+
 ## Example Layout
 
 This is an example image layout:
 
 ```
 $ cd example.com/app/
-$ find .
-.
-./blobs
-./blobs/sha256/e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f
-./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51
-./blobs/sha256/9b97579de92b1c195b85bb42a11011378ee549b02d7fe9c17bf2a6b35d5cb079
-./blobs/sha256/5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270
-./oci-layout
-./refs
+$ find . -type f
+./index.json
 ./refs/v1.0
 ./refs/stable-release
+./oci-layout
+./blobs/sha256/3588d02542238316759cbf24502f4344ffcc8a60c803870022f335d1390c13b4
+./blobs/sha256/4b0bc1c4050b03c95ef2a8e36e25feac42fd31283e8c30b3ee5df6b043155d3c
+./blobs/sha256/7968321274dc6b6171697c33df7815310468e694ac5be0ec03ff053bb135e768
 ```
 
 Blobs are named by their contents:
@@ -156,4 +161,43 @@ $ cat ./blobs/sha256/e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7f
 [tar stream]
 ```
 
+## index.json
+
+This OPTIONAL file is for use indexing references and elements of the image-layout, where walking the `refs` and `blobs` is sub-optimal.
+It is intended to be generated from the content in an image-layout after any changes.
+
+From the base properties of the [manifest-list](manifest-list.md), this object will us
+
+### Index Example
+
+```json,title=Manifest%20List&mediatype=application/vnd.oci.image.manifest.list.v1%2Bjson
+{
+  "schemaVersion": 2,
+  "manifests": [
+    {
+      "mediaType": "application/vnd.oci.image.manifest.v1+json",
+      "size": 7143,
+      "digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
+      "annotations": {
+        "org.opencontainers.ref.name": "v1.0"
+      }
+    }
+  ],
+  "elements": [
+    {
+      "mediaType": "application/xml",
+      "size": 7143,
+      "digest": "sha256:b3d63d132d21c3ff4c35a061adf23cf43da8ae054247e32faa95494d904a007e",
+      "annotations": {
+        "org.freedesktop.specifications.metainfo.version": "1.0",
+        "org.freedesktop.specifications.metainfo.type": "AppStream"
+      }
+    }
+  ],
+  "annotations": {
+    "com.example.index.revision": "r124356"
+  }
+}
+```
+
 [descriptors]: ./descriptor.md