Add some text about extensions

Signed-off-by: Doug Davis <[email protected]>

Author: Doug Davis

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 key and value MUST be present, they MAY be empty strings.
+    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 starting with 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,16 +202,25 @@ 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 key and value MUST be present, they MAY be empty strings.
     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 starting with 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)
     * **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)
     * **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