OCI Image Index Specification

Image Index Property Descriptions

• 04schemaVersion int

05This 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.

• 06mediaType string

07This property SHOULD be used and [remain compatible][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.index.v1+json. This field usage differs from the descriptor use of mediaType.

• 08artifactType string

09This OPTIONAL property contains the type of an artifact when the manifest is used for an artifact. 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].

• 10manifests array of objects

11This REQUIRED property contains a list of manifests for specific platforms. While this property MUST be present, the size of the array MAY be zero.

12Each object in manifests includes a set of descriptor properties with the following additional properties and restrictions:

• 13mediaType string

14This descriptor property has additional restrictions for manifests. Implementations MUST support at least the following media types:

• 15application/vnd.oci.image.manifest.v1+json

16Also, implementations SHOULD support the following media types:

• 17application/vnd.oci.image.index.v1+json (nested index)

18Image indexes 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 to the implementation MUST NOT generate an error.

• 19platform object

20This OPTIONAL property describes the minimum runtime requirements of the image. This property SHOULD be present if its target is platform-specific.

• 21architecture string

22This REQUIRED property specifies the CPU architecture. Image indexes SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [GOARCH][go-environment2].

• 23os string

24This REQUIRED property specifies the operating system. Image indexes SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [GOOS][go-environment2].

• 25os.version string

26This OPTIONAL property specifies the version of the operating system targeted by the referenced blob. Implementations MAY refuse to use manifests where os.version is not known to work with the host OS version. Valid values are implementation-defined. e.g. 10.0.14393.1066 on windows.

• 27os.features array of strings

28This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature. When os is windows, image indexes SHOULD use, and implementations SHOULD understand the following values:

• 29win32k: image requires win32k.sys on the host (Note: win32k.sys is missing on Nano Server)

30When os is not windows, values are implementation-defined and SHOULD be submitted to this specification for standardization.

• 31variant string

32This OPTIONAL property specifies the variant of the CPU. Image indexes SHOULD use, and implementations SHOULD understand, variant values listed in the Platform Variants table.

• 33features array of strings

34This property is RESERVED for future versions of the specification.

35If multiple manifests match a client or runtime's requirements, the first matching entry SHOULD be used.

• 36subject descriptor

37This OPTIONAL property specifies a descriptor 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.

• 38annotations string-string map

39This OPTIONAL property contains arbitrary metadata for the image index. This OPTIONAL property MUST use the annotation rules.

40See Pre-Defined Annotation Keys.

Platform Variants

41When the variant of the CPU is not listed in the table, values are implementation-defined and SHOULD be submitted to this specification for standardization. These values SHOULD match (or be similar to) their analog listed in [the Go Language document][go-environment2].

Example Image Index

43Example showing a simple image index pointing to image manifests for two platforms:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 7143,
      "digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
      "platform": {
        "architecture": "ppc64le",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 7682,
      "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270",
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    }
  ],
  "annotations": {
    "com.example.key1": "value1",
    "com.example.key2": "value2"
  }
}

Example Image Index with multiple media types

45Example showing an image index pointing to manifests with multiple media types:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 7143,
      "digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f",
      "platform": {
        "architecture": "ppc64le",
        "os": "linux"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.index.v1+json",
      "size": 7682,
      "digest": "sha256:601570aaff1b68a61eb9c85b8beca1644e698003e0cdb5bce960f193d265a8b7"
    }
  ],
  "annotations": {
    "com.example.key1": "value1",
    "com.example.key2": "value2"
  }
}

47[dag]: https://en.wikipedia.org/wiki/Merkle_tree [go-environment2]: https://golang.org/doc/install/source#environment [iana]: https://www.iana.org/assignments/media-types/media-types.xhtml [matrix]: media-types.md#compatibility-matrix [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