Add some text about extensions

Signed-off-by: Doug Davis <dug@us.ibm.com>

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,16 +198,21 @@ 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)
     * **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 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