clarification about nested index

image-index.md

@@ -34,6 +34,10 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
 
     - [`application/vnd.oci.image.manifest.v1+json`](manifest.md)
 
+    Also, implementations SHOULD support the following media types:
+
+    - `application/vnd.oci.image.index.v1+json` (nested index)
+
     Image indexes concerned with portability SHOULD use one of the above media types.
     Future versions of the spec MAY use a different mediatype (i.e. a new versioned format).
     An encountered `mediaType` that is unknown SHOULD be safely ignored.

image-layout.md

@@ -199,7 +199,11 @@ Those tags will often be represented in an image-layout repository with matching
 }
 ```
 
-This illustrates an index that provides two named manifest references and an auxiliary mediatype for this image layout.
+This illustrates an index that provides two named references and an auxiliary mediatype for this image layout.
 
+The first named reference (`stable-release`) points to another index that might contain multiple references with distinct platforms and annotations.
+Note that the [`org.opencontainers.image.ref.name` annotation](annotations.md) SHOULD only be considered valid when on descriptors on `index.json`.
+
+The second named reference (`v1.0`) points to a manifest that is specific to the linux/ppc64le platform.
 
 [descriptors]: ./descriptor.md

img/media-types.dot

@@ -6,6 +6,7 @@ digraph G {
     layer [shape=note, label="Layer tar archive\napplication/vnd.oci.image.layer.v1.tar\napplication/vnd.oci.image.layer.v1.tar+gzip\napplication/vnd.oci.image.layer.nondistributable.v1.tar\napplication/vnd.oci.image.layer.nondistributable.v1.tar+gzip"]
   }
 
+  imageIndex -> imageIndex [label="1..*"]
   imageIndex -> manifest [label="1..*"]
   manifest -> config [label="1..1"]
   manifest -> layer [label="1..*"]