1# OCI Image Media Types
2
3The following media types identify the formats described here and their referenced resources:
4
5- `application/vnd.oci.descriptor.v1+json`: [Content Descriptor](descriptor.md)
6- `application/vnd.oci.layout.header.v1+json`: [OCI Layout](image-layout.md#oci-layout-file)
7- `application/vnd.oci.image.index.v1+json`: [Image Index](image-index.md)
8- `application/vnd.oci.image.manifest.v1+json`: [Image manifest](manifest.md#image-manifest)
9- `application/vnd.oci.image.config.v1+json`: [Image config](config.md)
10- `application/vnd.oci.image.layer.v1.tar`: ["Layer", as a tar archive](layer.md)
11- `application/vnd.oci.image.layer.v1.tar+gzip`: ["Layer", as a tar archive](layer.md#gzip-media-types) compressed with [gzip][rfc1952]
12- `application/vnd.oci.image.layer.v1.tar+zstd`: ["Layer", as a tar archive](layer.md#zstd-media-types) compressed with [zstd][rfc8478]
13- `application/vnd.oci.empty.v1+json`: [Empty for unused descriptors](manifest.md#guidance-for-an-empty-descriptor)
14
15The following media types identify a ["Layer" with distribution restrictions](layer.md#non-distributable-layers), but are **deprecated** and not recommended for future use:
16
17- `application/vnd.oci.image.layer.nondistributable.v1.tar`: "Layer", as a tar archive
18- `application/vnd.oci.image.layer.nondistributable.v1.tar+gzip`: ["Layer", as a tar archive with distribution restrictions](layer.md#gzip-media-types) compressed with [gzip][rfc1952]
19- `application/vnd.oci.image.layer.nondistributable.v1.tar+zstd`: ["Layer", as a tar archive with distribution restrictions](layer.md#zstd-media-types) compressed with [zstd][rfc8478]
20
21## Media Type Conflicts
22
23[Blob](image-layout.md) retrieval methods MAY return media type metadata.
24For example, a HTTP response might return a manifest with the Content-Type header set to `application/vnd.oci.image.manifest.v1+json`.
25Implementations MAY also have expectations for the blob's media type and digest (e.g. from a [descriptor](descriptor.md) referencing the blob).
26
27- Implementations that do not have an expected media type for the blob SHOULD respect the returned media type.
28- Implementations that have an expected media type which matches the returned media type SHOULD respect the matched media type.
29- Implementations that have an expected media type which does not match the returned media type SHOULD:
30 - Respect the expected media type if the blob matches the expected digest.
31 Implementations MAY warn about the media type mismatch.
32 - Return an error if the blob does not match the expected digest (as [recommended for descriptors](descriptor.md#properties)).
33 - Return an error if they do not have an expected digest.
34
35## Compatibility Matrix
36
37The OCI Image Specification strives to be backwards and forwards compatible when possible.
38Breaking compatibility with existing systems creates a burden on users whether they are build systems, distribution systems, container engines, etc.
39This section shows where the OCI Image Specification is compatible with formats external to the OCI Image and different versions of this specification.
40
41### application/vnd.oci.image.index.v1+json
42
43Similar/related schema:
44
45- [application/vnd.docker.distribution.manifest.list.v2+json](https://github.com/distribution/distribution/blob/master/docs/spec/manifest-v2-2.md#manifest-list)
46 - `.annotations`: only present in OCI
47 - `.[]manifests.annotations`: only present in OCI
48 - `.[]manifests.urls`: only present in OCI
49
50### application/vnd.oci.image.manifest.v1+json
51
52Similar/related schema:
53
54- [application/vnd.docker.distribution.manifest.v2+json](https://github.com/distribution/distribution/blob/master/docs/spec/manifest-v2-2.md#image-manifest-field-descriptions)
55 - `.annotations`: only present in OCI
56 - `.config.annotations`: only present in OCI
57 - `.config.urls`: only present in OCI
58 - `.[]layers.annotations`: only present in OCI
59
60### application/vnd.oci.image.layer.v1.tar+gzip
61
62Interchangeable and fully compatible mime-types:
63
64- [application/vnd.docker.image.rootfs.diff.tar.gzip](https://github.com/moby/moby/blob/v20.10.8/image/spec/v1.2.md#creating-an-image-filesystem-changeset)
65
66### application/vnd.oci.image.config.v1+json
67
68Similar/related schema:
69
70- [application/vnd.docker.container.image.v1+json](https://github.com/moby/moby/blob/v20.10.8/image/spec/v1.2.md#image-json-description) (Docker Image Spec v1.2)
71 - `.config.Memory`: only present in Docker, and reserved in OCI
72 - `.config.MemorySwap`: only present in Docker, and reserved in OCI
73 - `.config.CpuShares`: only present in Docker, and reserved in OCI
74 - `.config.Healthcheck`: only present in Docker, and reserved in OCI
75- [Moby/Docker](https://github.com/moby/moby)
76 - `.config.ArgsEscaped`: Windows-specific Moby/Docker extension, deprecated in OCI, available for compatibility with older images.
77
78`.config.StopSignal` and `.config.Labels` are accidentally undocumented in Docker Image Spec v1.2, but these fields are not OCI-specific concepts.
79
80## Relations
81
82The following figure shows how the above media types reference each other:
83
84
85
86[Descriptors](descriptor.md) are used for all references.
87The image-index being a "fat manifest" references a list of image manifests per target platform. An image manifest references exactly one target configuration and possibly many layers.
88
89[rfc1952]: https://tools.ietf.org/html/rfc1952
90[rfc8478]: https://tools.ietf.org/html/rfc8478
View as plain text