*: manifest-list -> image-index

It has come up a number of times that the manifest-list, while
intentionally suited for pointing to a list of manifests, is intended to
be a general index and entry-point. During the image-layout addition of
`/index.json`, replacing the ./refs/ directory, it was recommended that
we finally make this distinction in the manifest-list as well.

This rename does not affect the compatibility with the docker v2.s2
manifest-list, as it is primarily a semantic change.

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

Makefile

@@ -26,7 +26,7 @@ DOC_FILES := \
 	descriptor.md \
 	image-layout.md \
 	manifest.md \
-	manifest-list.md \
+	image-index.md \
 	layer.md \
 	config.md \
 	annotations.md \

annotations.md

@@ -15,7 +15,7 @@ Consumers MUST NOT generate an error if they encounter an unknown annotation key
 
 ## Pre-Defined Annotation Keys
 
-This specification defines the following annotation keys, intended for but not limited to manifest list and image manifest authors:
+This specification defines the following annotation keys, intended for but not limited to [image-index](image-index.md) and image [manifest](manifest.md) authors:
 * **org.opencontainers.created** date on which the image was built (string, date-time as defined by [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6)).
 * **org.opencontainers.authors** contact details of the people or organization responsible for the image (freeform string)
 * **org.opencontainers.homepage** URL to find more information on the image (string, a URL with scheme HTTP or HTTPS)

considerations.md

@@ -1,6 +1,6 @@
 # Extensibility
 
-Implementations that are reading/processing [manifests](manifest.md) or [manifest lists](manifest-list.md) MUST NOT generate an error if they encounter an unknown property.
+Implementations that are reading/processing [manifests](manifest.md) or [image index](image-index.md) MUST NOT generate an error if they encounter an unknown property.
 Instead they MUST ignore unknown properties.
 
 # Canonicalization

manifest-list.md → image-index.md

@@ -1,12 +1,12 @@
-# OCI Image Manifest List Specification
+# OCI Image Index Specification
 
-The manifest list is a higher-level manifest which points to specific [image manifests](manifest.md) for one or more platforms.
-While the use of a manifest list is OPTIONAL for image providers, image consumers SHOULD be prepared to process them.
+The Image Index is a higher-level manifest which points to specific [image manifests](manifest.md), ideal for one or more platforms.
+While the use of an image index is OPTIONAL for image providers, image consumers SHOULD be prepared to process them.
 
-This section defines the `application/vnd.oci.image.manifest.list.v1+json` [media type](media-types.md).
+This section defines the `application/vnd.oci.image.index.v1+json` [media type](media-types.md).
 For the media type(s) that this document is compatible with, see the [matrix][matrix].
 
-## *Manifest List* Property Descriptions
+## *Image Index* Property Descriptions
 
 - **`schemaVersion`** *int*
 
@@ -34,7 +34,7 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
 
     - [`application/vnd.oci.image.manifest.v1+json`](manifest.md)
 
-    Manifest lists concerned with portability SHOULD use one of the above media types.
+    Image Indexes are 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.
 
@@ -46,12 +46,12 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
     - **`architecture`** *string*
 
         This REQUIRED property specifies the CPU architecture.
-        Manifest lists SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.arch`][runtime-platform2].
+        Image Indexes SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.arch`][runtime-platform2].
 
     - **`os`** *string*
 
         This REQUIRED property specifies the operating system.
-        Manifest lists SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.os`][runtime-platform2].
+        Image Indexes SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.os`][runtime-platform2].
 
     - **`os.version`** *string*
 
@@ -71,15 +71,15 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
 
 - **`annotations`** *string-string map*
 
-    This OPTIONAL property contains arbitrary metadata for the manifest list.
+    This OPTIONAL property contains arbitrary metadata for the image index.
     This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
 
     See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
 
-## Example Manifest List
+## Example Image Index
 
-*Example showing a simple manifest list pointing to image manifests for two platforms:*
-```json,title=Manifest%20List&mediatype=application/vnd.oci.image.manifest.list.v1%2Bjson
+*Example showing a simple image index pointing to image manifests for two platforms:*
+```json,title=Image%20Index&mediatype=application/vnd.oci.image.index.v1%2Bjson
 {
   "schemaVersion": 2,
   "manifests": [

image-layout.md

@@ -5,7 +5,7 @@ This layout MAY be used in a variety of different transport mechanisms: archive
 
 Given an image layout and a ref, a tool can create an [OCI Runtime Specification bundle](https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc3/bundle.md) by:
 
-* Following the ref to find a [manifest](manifest.md#image-manifest), possibly via a [manifest list](manifest-list.md#manifest-list)
+* Following the ref to find a [manifest](manifest.md#image-manifest), possibly via an [image index](image-index.md)
 * [Applying the filesystem layers](layer.md#applying) in the specified order
 * Converting the [image configuration](config.md) into an [OCI Runtime Specification `config.json`](https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc3/config.md)
 
@@ -27,7 +27,7 @@ The image layout is as follows:
 - `index.json` file
     - It MUST exist
     - It MUST be a JSON object
-    - It MUST have the base properties of [manifest-list](manifest-list.md).
+    - It MUST have the base properties of an [image index](image-index.md).
     - See [index.json](#indexjson-file) section
 
 ## Example Layout
@@ -143,12 +143,12 @@ The `imageLayoutVersion` value will align with the OCI Image Specification versi
 ## index.json file
 
 This REQUIRED file is the entry point for references and descriptors of the image-layout.
-The [manifest-list](manifest-list.md) is a multi-descriptor entry point.
+The [image index](image-index.md) is a multi-descriptor entry point.
 
 This index provides an established path (`/index.json`) to have an entry point for an image-layout and to discover auxiliary descriptors.
 
 No semantic restriction is given for the "org.opencontainers.ref.name" annotation of descriptors.
-In general the `mediaType` of each [descriptor][descriptors] object in the `manifests` field will be either `application/vnd.oci.image.manifest.list.v1+json` or `application/vnd.oci.image.manifest.v1+json`
+In general the `mediaType` of each [descriptor][descriptors] object in the `manifests` field will be either `application/vnd.oci.image.index.v1+json` or `application/vnd.oci.image.manifest.v1+json`
 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.
 
@@ -162,12 +162,12 @@ Those tags will often be represented in an image-layout repository with matching
 
 ### Index Example
 
-```json,title=Manifest%20List&mediatype=application/vnd.oci.image.manifest.list.v1%2Bjson
+```json,title=Manifest%20List&mediatype=application/vnd.oci.image.index.v1%2Bjson
 {
   "schemaVersion": 2,
   "manifests": [
     {
-      "mediaType": "application/vnd.oci.image.manifest.v1+json",
+      "mediaType": "application/vnd.oci.image.index.v1+json",
       "size": 7143,
       "digest": "sha256:0228f90e926ba6b96e4f39cf294b2586d38fbb5a1e385c05cd1ee40ea54fe7fd",
       "annotations": {
@@ -178,6 +178,10 @@ Those tags will often be represented in an image-layout repository with matching
       "mediaType": "application/vnd.oci.image.manifest.v1+json",
       "size": 7143,
       "digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
+      "platform": {
+        "architecture": "ppc64le",
+        "os": "linux"
+      },
       "annotations": {
         "org.opencontainers.ref.name": "v1.0"
       }

img/media-types.dot

@@ -1,12 +1,12 @@
 digraph G {
   {
-    manifestList [shape=note, label="Manifest list\n<<optional>>\napplication/vnd.oci.image.manifest.list.v1+json"]
+    imageIndex [shape=note, label="Image Index<<optional>>\napplication/vnd.oci.image.index.v1+json"]
     manifest [shape=note, label="Image manifest\napplication/vnd.oci.image.manifest.v1+json"]
     config [shape=note, label="Image JSON\napplication/vnd.oci.image.config.v1+json"]
     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"]
   }
 
-  manifestList -> manifest [label="1..*"]
+  imageIndex -> manifest [label="1..*"]
   manifest -> config [label="1..1"]
   manifest -> layer [label="1..*"]
 }

manifest.md

@@ -3,15 +3,15 @@
 There are three main goals of the Image Manifest Specification.
 The first goal is content-addressable images, by supporting an image model where the image's configuration can be hashed to generate a unique ID for the image and its components.
 The second goal is to allow multi-architecture images, through a "fat manifest" which references image manifests for platform-specific versions of an image.
-In OCI, this is codified in a [Manifest List](manifest-list.md).
+In OCI, this is codified in an [Image Index](image-index.md).
 The third goal is to be translatable to the [OCI Runtime Specification](https://github.com/opencontainers/runtime-spec).
 
 This section defines the `application/vnd.oci.image.manifest.v1+json` [media type](media-types.md).
 For the media type(s) that this is compatible with see the [matrix](media-types.md#compatibility-matrix).
 
 # Image Manifest
 
-Unlike the [Manifest List](manifest-list.md), which contains information about a set of images that can span a variety of architectures and operating systems, an image manifest provides a configuration and set of layers for a single container image for a specific architecture and operating system.
+Unlike the [Image Index](image-index.md), which contains information about a set of images that can span a variety of architectures and operating systems, an image manifest provides a configuration and set of layers for a single container image for a specific architecture and operating system.
 
 ## *Image Manifest* Property Descriptions
 

media-types.md

@@ -3,7 +3,7 @@
 The following media types identify the formats described here and their referenced resources:
 
 - `application/vnd.oci.descriptor.v1+json`: [Content Descriptor](descriptor.md)
-- `application/vnd.oci.image.manifest.list.v1+json`: [Manifest list](manifest-list.md#manifest-list)
+- `application/vnd.oci.image.index.v1+json`: [Image Index](image-index.md)
 - `application/vnd.oci.image.manifest.v1+json`: [Image manifest](manifest.md#image-manifest)
 - `application/vnd.oci.image.config.v1+json`: [Image config](config.md)
 - `application/vnd.oci.image.layer.v1.tar`: ["Layer", as a tar archive](layer.md)
@@ -31,7 +31,7 @@ The OCI Image Specification strives to be backwards and forwards compatible when
 Breaking compatibility with existing systems creates a burden on users whether they are build systems, distribution systems, container engines, etc.
 This section shows where the OCI Image Specification is compatible with formats external to the OCI Image and different versions of this specification.
 
-### application/vnd.oci.image.manifest.list.v1+json
+### application/vnd.oci.image.index.v1+json
 
 **Similar/related schema**
 
@@ -62,6 +62,6 @@ The following figure shows how the above media types reference each other:
 ![](img/media-types.png)
 
 [Descriptors](descriptor.md) are used for all references.
-The manifest list being a "fat manifest" references one or more image manifests per target platform. An image manifest references exactly one target configuration and possibly many layers.
+The image-index being a "fat manifest" references one or more image manifests per target platform. An image manifest references exactly one target configuration and possibly many layers.
 
 [rfc1952]: https://tools.ietf.org/html/rfc1952

schema/backwards_compatibility_test.go

@@ -25,7 +25,7 @@ import (
 )
 
 var compatMap = map[string]string{
-	"application/vnd.docker.distribution.manifest.list.v2+json": v1.MediaTypeImageManifestList,
+	"application/vnd.docker.distribution.manifest.list.v2+json": v1.MediaTypeImageIndex,
 	"application/vnd.docker.distribution.manifest.v2+json":      v1.MediaTypeImageManifest,
 	"application/vnd.docker.image.rootfs.diff.tar.gzip":         v1.MediaTypeImageLayer,
 	"application/vnd.docker.container.image.v1+json":            v1.MediaTypeImageConfig,
@@ -42,15 +42,15 @@ func convertFormats(input string) string {
 	return out
 }
 
-func TestBackwardsCompatibilityManifestList(t *testing.T) {
+func TestBackwardsCompatibilityImageIndex(t *testing.T) {
 	for i, tt := range []struct {
-		manifestlist string
-		digest       digest.Digest
-		fail         bool
+		imageIndex string
+		digest     digest.Digest
+		fail       bool
 	}{
 		{
 			digest: "sha256:219f4b61132fe9d09b0ec5c15517be2ca712e4744b0e0cc3be71295b35b2a467",
-			manifestlist: `{
+			imageIndex: `{
    "schemaVersion": 2,
    "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
    "manifests": [
@@ -109,14 +109,14 @@ func TestBackwardsCompatibilityManifestList(t *testing.T) {
 			fail: false,
 		},
 	} {
-		got := digest.FromString(tt.manifestlist)
+		got := digest.FromString(tt.imageIndex)
 		if tt.digest != got {
 			t.Errorf("test %d: expected digest %s but got %s", i, tt.digest, got)
 		}
 
-		manifestlist := convertFormats(tt.manifestlist)
-		r := strings.NewReader(manifestlist)
-		err := schema.ValidatorMediaTypeManifestList.Validate(r)
+		imageIndex := convertFormats(tt.imageIndex)
+		r := strings.NewReader(imageIndex)
+		err := schema.ValidatorMediaTypeImageIndex.Validate(r)
 
 		if got := err != nil; tt.fail != got {
 			t.Errorf("test %d: expected validation failure %t but got %t, err %v", i, tt.fail, got, err)