Skip to content

Latest commit

 

History

History
83 lines (69 loc) · 5.89 KB

annotations.md

File metadata and controls

83 lines (69 loc) · 5.89 KB
Raw

Annotations

Several components of the specification, like Image Manifests and Descriptors, feature an optional annotations property, whose format is common and defined in this section.

This property contains arbitrary metadata.

Rules

  • Annotations MUST be a key-value map where both the key and value MUST be strings.
  • While the value MUST be present, it MAY be an empty string.
  • Keys MUST be unique within this map, and best practice is to namespace the keys.
  • Keys SHOULD be named using a reverse domain notation - e.g. com.example.myKey.
  • The prefix org.opencontainers is reserved for keys defined in Open Container Initiative (OCI) specifications and MUST NOT be used by other specifications and extensions.
  • Keys using the org.opencontainers.image namespace are reserved for use in the OCI Image Specification and MUST NOT be used by other specifications and extensions, including other OCI specifications.
  • If there are no annotations then this property MUST either be absent or be an empty map.
  • Consumers MUST NOT generate an error if they encounter an unknown annotation key.

Pre-Defined Annotation Keys

This specification defines the following annotation keys, intended for but not limited to image index, image manifest, and descriptor authors.

  • org.opencontainers.image.created date and time on which the image was built, conforming to RFC 3339.

  • org.opencontainers.image.authors contact details of the people or organization responsible for the image (freeform string)

  • org.opencontainers.image.url URL to find more information on the image (string)

  • org.opencontainers.image.documentation URL to get documentation on the image (string)

  • org.opencontainers.image.source URL to get source code for building the image (string)

  • org.opencontainers.image.version version of the packaged software

  • org.opencontainers.image.revision Source control revision identifier for the packaged software.

  • org.opencontainers.image.vendor Name of the distributing entity, organization or individual.

  • org.opencontainers.image.licenses License(s) under which contained software is distributed as an SPDX License Expression.

  • org.opencontainers.image.ref.name Name of the reference for a target (string).

    • SHOULD only be considered valid when on descriptors on index.json within image layout.

    • Character set of the value SHOULD conform to alphanum of A-Za-z0-9 and separator set of -._:@/+

    • A valid reference matches the following grammar:

      ref       ::= component ("/" component)*
component ::= alphanum (separator alphanum)*
alphanum  ::= [A-Za-z0-9]+
separator ::= [-._:@+] | "--"

  • org.opencontainers.image.title Human-readable title of the image (string)

  • org.opencontainers.image.description Human-readable description of the software packaged in the image (string)

  • org.opencontainers.image.base.digest Digest of the image this image is based on (string)

    • This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile FROM statement.
    • This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).

  • org.opencontainers.image.base.name Image reference of the image this image is based on (string)

    • This SHOULD be image references in the format defined by distribution/distribution.
    • This SHOULD be a fully qualified reference name, without any assumed default registry. (e.g., registry.example.com/my-org/my-image:tag instead of my-org/my-image:tag).
    • This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile FROM statement.
    • This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
    • If the image.base.name annotation is specified, the image.base.digest annotation SHOULD be the digest of the manifest referenced by the image.ref.name annotation.

Back-compatibility with Label Schema

Label Schema defined a number of conventional labels for container images, and these are now superseded by annotations with keys starting org.opencontainers.image.

While users are encouraged to use the org.opencontainers.image keys, tools MAY choose to support compatible annotations using the org.label-schema prefix as follows.

org.opencontainers.image prefix org.label-schema prefix Compatibility notes
created build-date Compatible
url url Compatible
source vcs-url Compatible
version version Compatible
revision vcs-ref Compatible
vendor vendor Compatible
title name Compatible
description description Compatible
documentation usage Value is compatible if the documentation is located by a URL
authors No equivalent in Label Schema
licenses No equivalent in Label Schema
ref.name No equivalent in Label Schema
schema-version No equivalent in the OCI Image Spec
docker.*, rkt.* No equivalent in the OCI Image Spec