image-layout: describe an OPTIONAL index

Depending on where and how an OCI image-layout is provided (tar, zip,
HTTP, etc) the mechanism to "walk" the refs can vary in complexity and
expense. For HTTP in example, getting a directory listing is often
disabled, but even would require multiple fetches to build the map of refs.

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

image-layout.md

@@ -21,6 +21,7 @@ Both `blobs` and `refs` MAY be empty.
 The image layout MUST also contain a file that is used to identify the layout version:
 
 - `oci-layout` MUST contain a JSON object with a version field `{"imageLayoutVersion": "1.0.0"}` and MAY include additional fields.
+- `oci-layout` MAY contain an `index` field ([described below](#index))
 
 This is an example image layout:
 
@@ -118,4 +119,42 @@ $ cat ./blobs/sha256/e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7f
 [tar stream]
 ```
 
+## Index
+
+Index is intended to be generated from the content in an image-layout after any updates have been made.
+Allows for mapping random access to the references in the image-layout, and needing only to read from the `oci-layout` once to build this map of references.
+
+**index** *array of objects*, OPTIONAL
+
+  Provides a single access to top-level information about the layout.
+  Each object has the following properties:
+
+  - **ref** *string*, REQUIRED
+
+    The name of the ref (correspond JSON descriptor found in `./refs/`)
+
+  - **annotations** *string-string map*, OPTIONAL
+
+    This field is under the same constraints as [manifest `annotations`](manifest.md#image-manifest-property-descriptions)
+
+### Index Example
+
+```json
+{
+  "imageLayoutVersion": "1.0.0",
+  "index": [
+    {
+      "ref": "v1.0.0"
+    },
+    {
+      "ref": "stable",
+      "annotations": {
+        "org.waffles.with": "syrup,raspberries",
+        "io.flatpak.app.name": "org.gnome.gedit"
+      }
+    }
+  ]
+}
+```
+
 [descriptors]: ./descriptor.md