From 75d58f5e97b1ab36d21e18019f391bb05268d3f3 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 | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/manifest.md b/manifest.md index c9428fe48..c93eb3dcd 100644 --- a/manifest.md +++ b/manifest.md @@ -85,13 +85,18 @@ A client will distinguish a manifest list from an image manifest based on the Co 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. + Keys MUST be unique, and best practice is to namespace the keys. + 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 extensibility point to include additional information that is not defined as part of this specification. +Excluding the `annotations` property, implementations that are reading/processing manifest lists MUST generate an error if they encounter an unknown property. ## Example Manifest List @@ -193,9 +198,10 @@ Unlike the [Manifest List](#manifest-list), which contains information about a s - **`annotations`** *hashmap* - This OPTIONAL property contains arbitrary metadata for the manifest list. + This OPTIONAL property contains arbitrary metadata for the image manifest. Annotations is a key-value, unordered hashmap. Keys MUST be unique within the hashmap, and best practice is to namespace the keys. + If there are no annotations then this property MAY either be absent or be an empty hashmap. 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 +209,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 extensibility point to include additional information that is not defined as part of this specification. +Excluding the `annotations` property, implementations that are reading/processing image manifests MUST generate an error if they encounter an unknown property. + ## Example Image Manifest