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 an [image index](image-index.md). The third goal is to be [translatable](conversion.md) 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).
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.
This REQUIRED property specifies the image manifest schema version. 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.
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. When used, this field MUST contain the media type `application/vnd.oci.image.manifest.v1+json`. This field usage differs from the [descriptor](descriptor.md#properties) use of `mediaType`.
This OPTIONAL property contains the type of an artifact when the manifest is used for an artifact. This MUST be set when `config.mediaType` is set to the [empty value](#guidance-for-an-empty-descriptor). 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]. Implementations storing or copying image manifests MUST NOT error on encountering an `artifactType` that is unknown to the implementation.
This REQUIRED property references a configuration object for a container, by digest. Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions:
This [descriptor property](descriptor.md#properties) has additional restrictions for `config`.
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`).
Implementations storing or copying image manifests MUST NOT error on encountering a value that is unknown to the implementation.
Implementations MUST support at least the following media types:
Manifests for container images concerned with portability SHOULD use one of the above media types. Manifests for artifacts concerned with portability SHOULD use `config.mediaType` as described in [Guidelines for Artifact Usage](#guidelines-for-artifact-usage).
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].
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.
If this image manifest will be "runnable" by a runtime of some kind, it is strongly recommended to ensure it includes enough data to be unique (such as the `rootfs` and `diff_ids` included in `application/vnd.oci.image.config.v1+json`) so that it has a unique [`ImageID`](config.md#imageid).
Each item in the array MUST be a [descriptor](descriptor.md). For portability, `layers` SHOULD have at least one entry. See the [guidance for an empty descriptor](#guidance-for-an-empty-descriptor) below, and `DescriptorEmptyJSON` of the reference code.
When the `config.mediaType` is set to `application/vnd.oci.image.config.v1+json`, the following additional restrictions apply:
Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions:
This [descriptor property](descriptor.md#properties) has additional restrictions for `layers[]`. Implementations MUST support at least the following media types:
Manifests concerned with portability SHOULD use one of the above media types. Entries in this field will frequently use the `+gzip` types.
Implementations SHOULD also support the following media types:
Implementations storing or copying image manifests MUST NOT error on encountering a `mediaType` that is unknown to the implementation.
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].
See [Guidelines for Artifact Usage](#guidelines-for-artifact-usage) for other uses of the `layers`.
This OPTIONAL property specifies a [descriptor](descriptor.md) of another manifest. 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.
This OPTIONAL property contains arbitrary metadata for the image manifest. This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
*Example showing an image manifest:*
*Implementers note*: The following is considered GUIDANCE for portability.
Parts of the spec necessitate including a descriptor to a blob where some implementations of artifacts do not have associated content. While an empty blob (`size` of 0) may be preferable, practice has shown that not to be ubiquitously supported. The media type `application/vnd.oci.empty.v1+json` (`MediaTypeEmptyJSON`) has been specified for a descriptor that has no content for the implementation. The blob payload is the most minimal content that is still a valid JSON object: `{}` (`size` of 2). The blob digest of `{}` is `sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a`. The data field is optional, and if included is the base64 encoding of `{}`: `e30=`.
The resulting descriptor shown here is also defined in reference code as `DescriptorEmptyJSON`:
Content other than OCI container images MAY be packaged using the image manifest. When 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). If the `config.mediaType` is set to the empty value, the `artifactType` MUST be defined. If the artifact does not need layers, a single layer SHOULD be included with a non-zero size. The suggested content for an unused `layers` array is the [empty descriptor](#guidance-for-an-empty-descriptor).
The design of the artifact depends on what content is being packaged with the artifact. The decision tree below and the associated examples MAY be used to design new artifacts:
_Implementers note:_ artifacts have historically been created without an `artifactType` field, and tooling to work with artifacts should fallback to the `config.mediaType` value.
[dag]: https://en.wikipedia.org/wiki/Merkle_tree [iana]: https://www.iana.org/assignments/media-types/media-types.xhtml [referrers-api]: https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers [rfc6838]: https://tools.ietf.org/html/rfc6838 [rfc6838-s4.2]: https://tools.ietf.org/html/rfc6838#section-4.2