1# Annotations
2
3Several components of the specification, like [Image Manifests](manifest.md) and [Descriptors](descriptor.md), feature an optional annotations property, whose format is common and defined in this section.
4
5This property contains arbitrary metadata.
6
7## Rules
8
9- Annotations MUST be a key-value map where both the key and value MUST be strings.
10- While the value MUST be present, it MAY be an empty string.
11- Keys MUST be unique within this map, and best practice is to namespace the keys.
12- Keys SHOULD be named using a reverse domain notation - e.g. `com.example.myKey`.
13- 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.
14- 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.
15- If there are no annotations then this property MUST either be absent or be an empty map.
16- Consumers MUST NOT generate an error if they encounter an unknown annotation key.
17
18## Pre-Defined Annotation Keys
19
20This specification defines the following annotation keys, intended for but not limited to [image index](image-index.md), image [manifest](manifest.md), and [descriptor](descriptor.md) authors.
21
22- **org.opencontainers.image.created** date and time on which the image was built, conforming to [RFC 3339][rfc3339].
23- **org.opencontainers.image.authors** contact details of the people or organization responsible for the image (freeform string)
24- **org.opencontainers.image.url** URL to find more information on the image (string)
25- **org.opencontainers.image.documentation** URL to get documentation on the image (string)
26- **org.opencontainers.image.source** URL to get source code for building the image (string)
27- **org.opencontainers.image.version** version of the packaged software
28 - The version MAY match a label or tag in the source code repository
29 - version MAY be [Semantic versioning-compatible](https://semver.org/)
30- **org.opencontainers.image.revision** Source control revision identifier for the packaged software.
31- **org.opencontainers.image.vendor** Name of the distributing entity, organization or individual.
32- **org.opencontainers.image.licenses** License(s) under which contained software is distributed as an [SPDX License Expression][spdx-license-expression].
33- **org.opencontainers.image.ref.name** Name of the reference for a target (string).
34 - SHOULD only be considered valid when on descriptors on `index.json` within [image layout](image-layout.md).
35 - Character set of the value SHOULD conform to alphanum of `A-Za-z0-9` and separator set of `-._:@/+`
36 - The reference must match the following [grammar](considerations.md#ebnf):
37
38 ```ebnf
39 ref ::= component ("/" component)*
40 component ::= alphanum (separator alphanum)*
41 alphanum ::= [A-Za-z0-9]+
42 separator ::= [-._:@+] | "--"
43 ```
44
45- **org.opencontainers.image.title** Human-readable title of the image (string)
46- **org.opencontainers.image.description** Human-readable description of the software packaged in the image (string)
47- **org.opencontainers.image.base.digest** [Digest](descriptor.md#digests) of the image this image is based on (string)
48 - This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile `FROM` statement.
49 - This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
50- **org.opencontainers.image.base.name** Image reference of the image this image is based on (string)
51 - This SHOULD be image references in the format defined by [distribution/distribution][distribution-reference].
52 - 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`).
53 - This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile `FROM` statement.
54 - This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
55 - 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.
56
57## Back-compatibility with Label Schema
58
59[Label Schema][label-schema] defined a number of conventional labels for container images, and these are now superceded by annotations with keys starting **org.opencontainers.image**.
60
61While 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.
62
63| `org.opencontainers.image` prefix | `org.label-schema` prefix | Compatibility notes |
64|---------------------------|-------------------------|---------------------|
65| `created` | `build-date` | Compatible |
66| `url` | `url` | Compatible |
67| `source` | `vcs-url` | Compatible |
68| `version` | `version` | Compatible |
69| `revision` | `vcs-ref` | Compatible |
70| `vendor` | `vendor` | Compatible |
71| `title` | `name` | Compatible |
72| `description` | `description` | Compatible |
73| `documentation` | `usage` | Value is compatible if the documentation is located by a URL |
74| `authors` | | No equivalent in Label Schema |
75| `licenses` | | No equivalent in Label Schema |
76| `ref.name` | | No equivalent in Label Schema |
77| | `schema-version`| No equivalent in the OCI Image Spec |
78| | `docker.*`, `rkt.*` | No equivalent in the OCI Image Spec |
79
80[distribution-reference]: https://github.com/distribution/distribution/blob/d0deff9cd6c2b8c82c6f3d1c713af51df099d07b/reference/reference.go
81[label-schema]: https://github.com/label-schema/label-schema.org/blob/gh-pages/rc1.md
82[rfc3339]: https://tools.ietf.org/html/rfc3339#section-5.6
83[spdx-license-expression]: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/
View as plain text