From 256910e0a6620b687baf36acf524ffaf477befb5 Mon Sep 17 00:00:00 2001 From: Doug Davis Date: Sun, 26 Jun 2016 12:32:36 -0700 Subject: [PATCH] Add some text about extensions Signed-off-by: Doug Davis --- manifest.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/manifest.md b/manifest.md index c9428fe48..1bf18ccca 100644 --- a/manifest.md +++ b/manifest.md @@ -84,14 +84,23 @@ A client will distinguish a manifest list from an image manifest based on the Co - **`annotations`** *string-string hashmap* This OPTIONAL property contains arbitrary metadata for the manifest list. - Annotations is a key-value, unordered hashmap. - Keys are unique, and best practice is to namespace the keys. + Annotations MUST BE a key-value, unordered hashmap 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, 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. + If there are no annotations then this property MAY either be absent or be an empty hashmap. + Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown annotation key. Common annotation keys include: * **created** date on which the image was built (string, timestamps type) * **authors** contact details of the people or organization responsible for the image (freeform string) * **homepage** URL to find more information on the image (string, must be a URL with scheme HTTP or HTTPS) * **documentation** URL to get documentation on the image (string, must be a URL with scheme HTTP or HTTPS) +### Extensibility +The `annotations` property MAY be used as an extension point to include additional information that is not defined as part of this specification. +Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown property. +Instead they MUST ignore unknown properties. ## Example Manifest List @@ -193,9 +202,14 @@ Unlike the [Manifest List](#manifest-list), which contains information about a s - **`annotations`** *hashmap* - This OPTIONAL property contains arbitrary metadata for the manifest list. - Annotations is a key-value, unordered hashmap. + This OPTIONAL property contains arbitrary metadata for the image manifest. + Annotations MUST be a key-value, unordered hashmap 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 the hashmap, 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. + If there are no annotations then this property MAY either be absent or be an empty hashmap. + Implementations that are reading/processing the image manifest MUST NOT generate an error if they encounter an unknown annotation key. Common annotation keys include: * **created** date on which the image was built (string, timestamps type) * **authors** contact details of the people or organization responsible for the image (freeform string) @@ -203,6 +217,10 @@ Unlike the [Manifest List](#manifest-list), which contains information about a s * **documentation** URL to get documentation on the image (string, must be a URL with scheme HTTP or HTTPS) * **source** URL to get the source code for the binary files in the image (string, must be a URL with scheme HTTP or HTTPS) +### Extensibility +The `annotations` property MAY be used as an extension point to include additional information that is not defined as part of this specification. +Implementations that are reading/processing image manifests MUST NOT generate an error if they encounter an unknown property. +Instead they MUST ignore unknown properties. ## Example Image Manifest