Add some text about extensions

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

manifest.md

@@ -85,13 +85,20 @@ 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.
+	Keys starting with the `opencontainers.org` 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 +200,23 @@ 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.
+	Keys starting with the `opencontainers.org` 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