1# OCI Image Manifest Specification
2
3There are three main goals of the Image Manifest Specification.
4The 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.
5The second goal is to allow multi-architecture images, through a "fat manifest" which references image manifests for platform-specific versions of an image.
6In OCI, this is codified in an [image index](image-index.md).
7The third goal is to be [translatable](conversion.md) to the [OCI Runtime Specification](https://github.com/opencontainers/runtime-spec).
8
9This section defines the `application/vnd.oci.image.manifest.v1+json` [media type](media-types.md).
10For the media type(s) that this is compatible with see the [matrix](media-types.md#compatibility-matrix).
11
12## Image Manifest
13
14Unlike 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.
15
16## _Image Manifest_ Property Descriptions
17
18- **`schemaVersion`** *int*
19
20 This REQUIRED property specifies the image manifest schema version.
21 For this version of the specification, this MUST be `2` to ensure backward compatibility with older versions of Docker. The value of this field will not change. This field MAY be removed in a future version of the specification.
22
23- **`mediaType`** *string*
24
25 This property SHOULD be used and [remain compatible](media-types.md#compatibility-matrix) with earlier versions of this specification and with other similar external formats.
26 When used, this field MUST contain the media type `application/vnd.oci.image.manifest.v1+json`.
27 This field usage differs from the [descriptor](descriptor.md#properties) use of `mediaType`.
28
29- **`artifactType`** *string*
30
31 This OPTIONAL property contains the type of an artifact when the manifest is used for an artifact.
32 This MUST be set when `config.mediaType` is set to the [empty value](#guidance-for-an-empty-descriptor).
33 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].
34 Implementations storing or copying image manifests MUST NOT error on encountering an `artifactType` that is unknown to the implementation.
35
36- **`config`** *[descriptor](descriptor.md)*
37
38 This REQUIRED property references a configuration object for a container, by digest.
39 Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions:
40
41 - **`mediaType`** *string*
42
43 This [descriptor property](descriptor.md#properties) has additional restrictions for `config`.
44
45 Implementations MUST NOT attempt to parse the referenced content if this media type is unknown and instead consider the referenced content as arbitrary binary data (e.g.: as `application/octet-stream`).
46
47 Implementations storing or copying image manifests MUST NOT error on encountering a value that is unknown to the implementation.
48
49 Implementations MUST support at least the following media types:
50
51 - [`application/vnd.oci.image.config.v1+json`](config.md)
52
53 Manifests for container images concerned with portability SHOULD use one of the above media types.
54 Manifests for artifacts concerned with portability SHOULD use `config.mediaType` as described in [Guidelines for Artifact Usage](#guidelines-for-artifact-usage).
55
56 If the manifest uses a different media type than the above, it 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].
57
58 To set an effectively null or empty config and maintain portability see the [guidance for an empty descriptor](#guidance-for-an-empty-descriptor) below, and `DescriptorEmptyJSON` of the reference code.
59
60- **`layers`** *array of objects*
61
62 Each item in the array MUST be a [descriptor](descriptor.md).
63 For portability, `layers` SHOULD have at least one entry.
64 See the [guidance for an empty descriptor](#guidance-for-an-empty-descriptor) below, and `DescriptorEmptyJSON` of the reference code.
65
66 When the `config.mediaType` is set to `application/vnd.oci.image.config.v1+json`, the following additional restrictions apply:
67
68 - The array MUST have the base layer at index 0.
69 - Subsequent layers MUST then follow in stack order (i.e. from `layers[0]` to `layers[len(layers)-1]`).
70 - The final filesystem layout MUST match the result of [applying](layer.md#applying-changesets) the layers to an empty directory.
71 - The [ownership, mode, and other attributes](layer.md#file-attributes) of the initial empty directory are unspecified.
72
73 Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions:
74
75 - **`mediaType`** *string*
76
77 This [descriptor property](descriptor.md#properties) has additional restrictions for `layers[]`.
78 Implementations MUST support at least the following media types:
79
80 - [`application/vnd.oci.image.layer.v1.tar`](layer.md)
81 - [`application/vnd.oci.image.layer.v1.tar+gzip`](layer.md#gzip-media-types)
82 - [`application/vnd.oci.image.layer.nondistributable.v1.tar`](layer.md#non-distributable-layers)
83 - [`application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`](layer.md#gzip-media-types)
84
85 Manifests concerned with portability SHOULD use one of the above media types.
86 Implementations storing or copying image manifests MUST NOT error on encountering a `mediaType` that is unknown to the implementation.
87
88 Entries in this field will frequently use the `+gzip` types.
89
90 If the manifest uses a different media type than the above, it 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].
91
92 See [Guidelines for Artifact Usage](#guidelines-for-artifact-usage) for other uses of the `layers`.
93
94- **`subject`** *[descriptor](descriptor.md)*
95
96 This OPTIONAL property specifies a [descriptor](descriptor.md) of another manifest.
97 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.
98
99- **`annotations`** *string-string map*
100
101 This OPTIONAL property contains arbitrary metadata for the image manifest.
102 This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
103
104 See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
105
106## Example Image Manifest
107
108*Example showing an image manifest:*
109
110```json,title=Manifest&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
111{
112 "schemaVersion": 2,
113 "mediaType": "application/vnd.oci.image.manifest.v1+json",
114 "config": {
115 "mediaType": "application/vnd.oci.image.config.v1+json",
116 "digest": "sha256:b5b2b2c507a0944348e0303114d8d93aaaa081732b86451d9bce1f432a537bc7",
117 "size": 7023
118 },
119 "layers": [
120 {
121 "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
122 "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0",
123 "size": 32654
124 },
125 {
126 "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
127 "digest": "sha256:3c3a4604a545cdc127456d94e421cd355bca5b528f4a9c1905b15da2eb4a4c6b",
128 "size": 16724
129 },
130 {
131 "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
132 "digest": "sha256:ec4b8955958665577945c89419d1af06b5f7636b4ac3da7f12184802ad867736",
133 "size": 73109
134 }
135 ],
136 "subject": {
137 "mediaType": "application/vnd.oci.image.manifest.v1+json",
138 "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
139 "size": 7682
140 },
141 "annotations": {
142 "com.example.key1": "value1",
143 "com.example.key2": "value2"
144 }
145}
146```
147
148## Guidance for an Empty Descriptor
149
150*Implementers note*: The following is considered GUIDANCE for portability.
151
152Parts of the spec necessitate including a descriptor to a blob where some implementations of artifacts do not have associated content.
153While an empty blob (`size` of 0) may be preferable, practice has shown that not to be ubiquitously supported.
154The media type `application/vnd.oci.empty.v1+json` (`MediaTypeEmptyJSON`) has been specified for a descriptor that has no content for the implementation.
155The blob payload is the most minimal content that is still a valid JSON object: `{}` (`size` of 2).
156The blob digest of `{}` is `sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a`.
157The data field is optional, and if included is the base64 encoding of `{}`: `e30=`.
158
159The resulting descriptor shown here is also defined in reference code as `DescriptorEmptyJSON`:
160
161```json,title=empty%20config&mediatype=application/vnd.oci.descriptor.v1%2Bjson
162{
163 "mediaType": "application/vnd.oci.empty.v1+json",
164 "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
165 "size": 2,
166 "data": "e30="
167}
168```
169
170## Guidelines for Artifact Usage
171
172Content other than OCI container images MAY be packaged using the image manifest.
173When this is done, the `config.mediaType` value MUST be set to a value specific to the artifact type or the [empty value](#guidance-for-an-empty-descriptor).
174If the `config.mediaType` is set to the empty value, the `artifactType` MUST be defined.
175If the artifact does not need layers, a single layer SHOULD be included with a non-zero size.
176The suggested content for an unused `layers` array is the [empty descriptor](#guidance-for-an-empty-descriptor).
177
178The design of the artifact depends on what content is being packaged with the artifact.
179The decision tree below and the associated examples MAY be used to design new artifacts:
180
1811. Does the artifact consist of at least one file or blob?
182 If yes, continue to 2.
183 If no, specify the `artifactType`, and set the `config` and a single `layers` element to the empty descriptor value.
184 Here is an example of this with annotations included:
185
186 ```json,title=Minimal%20artifact&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
187 {
188 "schemaVersion": 2,
189 "mediaType": "application/vnd.oci.image.manifest.v1+json",
190 "artifactType": "application/vnd.example+type",
191 "config": {
192 "mediaType": "application/vnd.oci.empty.v1+json",
193 "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
194 "size": 2
195 },
196 "layers": [
197 {
198 "mediaType": "application/vnd.oci.empty.v1+json",
199 "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
200 "size": 2
201 }
202 ],
203 "annotations": {
204 "oci.opencontainers.image.created": "2023-01-02T03:04:05Z",
205 "com.example.data": "payload"
206 }
207 }
208 ```
209
2102. Does the artifact have additional JSON formatted metadata as configuration?
211 If yes, continue to 3.
212 If no, specify the `artifactType`, include the artifact in the `layers`, and set `config` to the empty descriptor value.
213 Here is an example of this with a single layer:
214
215 ```json,title=Artifact%20without%20config&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
216 {
217 "schemaVersion": 2,
218 "mediaType": "application/vnd.oci.image.manifest.v1+json",
219 "artifactType": "application/vnd.example+type",
220 "config": {
221 "mediaType": "application/vnd.oci.empty.v1+json",
222 "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
223 "size": 2
224 },
225 "layers": [
226 {
227 "mediaType": "application/vnd.example+type",
228 "digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
229 "size": 1234
230 }
231 ]
232 }
233 ```
234
2353. For artifacts with a config blob, specify the `artifactType` to a common value for your artifact tooling, specify the `config` with the metadata for this artifact, and include the artifact in the `layers`.
236 Here is an example of this:
237
238 ```json,title=Artifact%20with%20config&mediatype=application/vnd.oci.image.manifest.v1%2Bjson
239 {
240 "schemaVersion": 2,
241 "mediaType": "application/vnd.oci.image.manifest.v1+json",
242 "artifactType": "application/vnd.example+type",
243 "config": {
244 "mediaType": "application/vnd.example.config.v1+json",
245 "digest": "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03",
246 "size": 123
247 },
248 "layers": [
249 {
250 "mediaType": "application/vnd.example.data.v1.tar+gzip",
251 "digest": "sha256:e258d248fda94c63753607f7c4494ee0fcbe92f1a76bfdac795c9d84101eb317",
252 "size": 1234
253 }
254 ]
255 }
256 ```
257
258_Implementers note:_ artifacts have historically been created without an `artifactType` field, and tooling to work with artifacts should fallback to the `config.mediaType` value.
259
260[dag]: https://en.wikipedia.org/wiki/Merkle_tree
261[iana]: https://www.iana.org/assignments/media-types/media-types.xhtml
262[referrers-api]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers
263[rfc6838]: https://tools.ietf.org/html/rfc6838
264[rfc6838-s4.2]: https://tools.ietf.org/html/rfc6838#section-4.2
View as plain text