1# OCI Image Index Specification
2
3The image index is a higher-level manifest which points to specific [image manifests](manifest.md), ideal for one or more platforms.
4While the use of an image index is OPTIONAL for image providers, image consumers SHOULD be prepared to process them.
5
6This section defines the `application/vnd.oci.image.index.v1+json` [media type](media-types.md).
7
8For the media type(s) that this document is compatible with, see the [matrix][matrix].
9
10## _Image Index_ Property Descriptions
11
12- **`schemaVersion`** *int*
13
14 This REQUIRED property specifies the image manifest schema version.
15 For this version of the specification, this MUST be `2` to ensure backward compatibility with older versions of Docker.
16 The value of this field will not change.
17 This field MAY be removed in a future version of the specification.
18
19- **`mediaType`** *string*
20
21 This property SHOULD be used and [remain compatible][matrix] with earlier versions of this specification and with other similar external formats.
22 When used, this field MUST contain the media type `application/vnd.oci.image.index.v1+json`.
23 This field usage differs from the [descriptor](descriptor.md#properties) use of `mediaType`.
24
25- **`artifactType`** *string*
26
27 This OPTIONAL property contains the type of an artifact when the manifest is used for an artifact.
28 If defined, the value MUST comply with [RFC 6838][rfc6838], including the [naming requirements in its section 4.2][rfc6838-s4.2], and MAY be registered with [IANA][iana].
29
30- **`manifests`** *array of objects*
31
32 This REQUIRED property contains a list of [manifests](manifest.md) for specific platforms.
33 While this property MUST be present, the size of the array MAY be zero.
34
35 Each object in `manifests` includes a set of [descriptor properties](descriptor.md#properties) with the following additional properties and restrictions:
36
37 - **`mediaType`** *string*
38
39 This [descriptor property](descriptor.md#properties) has additional restrictions for `manifests`.
40 Implementations MUST support at least the following media types:
41
42 - [`application/vnd.oci.image.manifest.v1+json`](manifest.md)
43
44 Also, implementations SHOULD support the following media types:
45
46 - `application/vnd.oci.image.index.v1+json` (nested index)
47
48 Image indexes concerned with portability SHOULD use one of the above media types.
49 Future versions of the spec MAY use a different mediatype (i.e. a new versioned format).
50 An encountered `mediaType` that is unknown to the implementation MUST NOT generate an error.
51
52 - **`platform`** *object*
53
54 This OPTIONAL property describes the minimum runtime requirements of the image.
55 This property SHOULD be present if its target is platform-specific.
56
57 - **`architecture`** *string*
58
59 This REQUIRED property specifies the CPU architecture.
60 Image indexes SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOARCH`][go-environment2].
61
62 - **`os`** *string*
63
64 This REQUIRED property specifies the operating system.
65 Image indexes SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOOS`][go-environment2].
66
67 - **`os.version`** *string*
68
69 This OPTIONAL property specifies the version of the operating system targeted by the referenced blob.
70 Implementations MAY refuse to use manifests where `os.version` is not known to work with the host OS version.
71 Valid values are implementation-defined. e.g. `10.0.14393.1066` on `windows`.
72
73 - **`os.features`** *array of strings*
74
75 This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature.
76 When `os` is `windows`, image indexes SHOULD use, and implementations SHOULD understand the following values:
77
78 - `win32k`: image requires `win32k.sys` on the host (Note: `win32k.sys` is missing on Nano Server)
79
80 When `os` is not `windows`, values are implementation-defined and SHOULD be submitted to this specification for standardization.
81
82 - **`variant`** *string*
83
84 This OPTIONAL property specifies the variant of the CPU.
85 Image indexes SHOULD use, and implementations SHOULD understand, `variant` values listed in the [Platform Variants](#platform-variants) table.
86
87 - **`features`** *array of strings*
88
89 This property is RESERVED for future versions of the specification.
90
91 If multiple manifests match a client or runtime's requirements, the first matching entry SHOULD be used.
92
93- **`subject`** *[descriptor](descriptor.md)*
94
95 This OPTIONAL property specifies a [descriptor](descriptor.md) of another manifest.
96 This value defines a weak association to a separate [Merkle Directed Acyclic Graph (DAG)][dag] structure, and is used by the [`referrers` API][referrers-api] to include this manifest in the list of responses for the subject digest.
97
98- **`annotations`** *string-string map*
99
100 This OPTIONAL property contains arbitrary metadata for the image index.
101 This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
102
103 See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
104
105## Platform Variants
106
107When the variant of the CPU is not listed in the table, values are implementation-defined and SHOULD be submitted to this specification for standardization.
108
109| ISA/ABI | `architecture` | `variant` |
110|-----------------|----------------|-------------|
111| ARM 32-bit, v6 | `arm` | `v6` |
112| ARM 32-bit, v7 | `arm` | `v7` |
113| ARM 32-bit, v8 | `arm` | `v8` |
114| ARM 64-bit, v8 | `arm64` | `v8` |
115
116## Example Image Index
117
118*Example showing a simple image index pointing to image manifests for two platforms:*
119
120```json,title=Image%20Index&mediatype=application/vnd.oci.image.index.v1%2Bjson
121{
122 "schemaVersion": 2,
123 "mediaType": "application/vnd.oci.image.index.v1+json",
124 "manifests": [
125 {
126 "mediaType": "application/vnd.oci.image.manifest.v1+json",
127 "size": 7143,
128 "digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
129 "platform": {
130 "architecture": "ppc64le",
131 "os": "linux"
132 }
133 },
134 {
135 "mediaType": "application/vnd.oci.image.manifest.v1+json",
136 "size": 7682,
137 "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
138 "platform": {
139 "architecture": "amd64",
140 "os": "linux"
141 }
142 }
143 ],
144 "annotations": {
145 "com.example.key1": "value1",
146 "com.example.key2": "value2"
147 }
148}
149```
150
151## Example Image Index with multiple media types
152
153*Example showing an image index pointing to manifests with multiple media types:*
154
155```json,title=Image%20Index&mediatype=application/vnd.oci.image.index.v1%2Bjson
156{
157 "schemaVersion": 2,
158 "mediaType": "application/vnd.oci.image.index.v1+json",
159 "manifests": [
160 {
161 "mediaType": "application/vnd.oci.image.manifest.v1+json",
162 "size": 7143,
163 "digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
164 "platform": {
165 "architecture": "ppc64le",
166 "os": "linux"
167 }
168 },
169 {
170 "mediaType": "application/vnd.oci.image.index.v1+json",
171 "size": 7682,
172 "digest": "sha256:601570aaff1b68a61eb9c85b8beca1644e698003e0cdb5bce960f193d265a8b7"
173 }
174 ],
175 "annotations": {
176 "com.example.key1": "value1",
177 "com.example.key2": "value2"
178 }
179}
180```
181
182[dag]: https://en.wikipedia.org/wiki/Merkle_tree
183[go-environment2]: https://golang.org/doc/install/source#environment
184[iana]: https://www.iana.org/assignments/media-types/media-types.xhtml
185[matrix]: media-types.md#compatibility-matrix
186[referrers-api]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers
187[rfc6838]: https://tools.ietf.org/html/rfc6838
188[rfc6838-s4.2]: https://tools.ietf.org/html/rfc6838#section-4.2
View as plain text