opencontainers/image-spec
1
0
Fork 0
mirror of https://github.com/opencontainers/image-spec.git synced 2026-02-05 18:45:00 +01:00
Code Issues Activity

annotations: make a designated doc and DRY a bit

Browse Source 
In DRY'ing up the references to annotations. This makes the defined keys
in a very logical place rather than the bottom of one of the other docs.

Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
This commit is contained in:
Vincent Batts
2016-12-15 15:39:15 -05:00
parent 4986a7ebe0
commit f15a268b30
3 changed files with 27 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
annotations.md Normal file
View File

@@ -0,0 +1,23 @@
# Annotations
Several 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.
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`.
Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by other specifications and extensions.
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 manifest list and image manifest authors:
* **org.opencontainers.created** date on which the image was built (string, date-time as defined by [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6)).
* **org.opencontainers.authors** contact details of the people or organization responsible for the image (freeform string)
* **org.opencontainers.homepage** URL to find more information on the image (string, a URL with scheme HTTP or HTTPS)
* **org.opencontainers.documentation** URL to get documentation on the image (string, a URL with scheme HTTP or HTTPS)
* **org.opencontainers.source** URL to get source code for the binary files in the image (string, a URL with scheme HTTP or HTTPS)

10
manifest-list.md
View File

@@ -67,15 +67,9 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
- **`annotations`** *string-string map*
This OPTIONAL property contains arbitrary metadata for the manifest list.
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`.
Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by other specifications.
If there are no annotations then this property MUST either be absent or be an empty map.
Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown annotation key.
This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
See [Pre-Defined Annotation Keys](manifest.md#pre-defined-annotation-keys).
See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
### Extensibility
Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown property.

18
manifest.md
View File

@@ -62,15 +62,9 @@ Unlike the [Manifest List](manifest-list.md), which contains information about a
- **`annotations`** *string-string map*
This OPTIONAL property contains arbitrary metadata for the image manifest.
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`.
Keys using the `org.opencontainers` namespace are reserved and MUST NOT be used by other specifications.
If there are no annotations then this property MUST either be absent or be an empty map.
Implementations that are reading/processing the image manifest MUST NOT generate an error if they encounter an unknown annotation key.
This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
See [Pre-Defined Annotation Keys](#pre-defined-annotation-keys).
See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
### Extensibility
Implementations that are reading/processing image manifests MUST NOT generate an error if they encounter an unknown property.
@@ -111,11 +105,3 @@ Instead they MUST ignore unknown properties.
}
}
```
# Pre-Defined Annotation Keys
This specification defines the following annotation keys, which MAY be used by manifest list and image manifest authors:
* **org.opencontainers.created** date on which the image was built (string, date-time as defined by [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6)).
* **org.opencontainers.authors** contact details of the people or organization responsible for the image (freeform string)
* **org.opencontainers.homepage** URL to find more information on the image (string, must be a URL with scheme HTTP or HTTPS)
* **org.opencontainers.documentation** URL to get documentation on the image (string, must be a URL with scheme HTTP or HTTPS)
* **org.opencontainers.source** URL to get source code for the binary files in the image (string, must be a URL with scheme HTTP or HTTPS)