extensibility: DRY annotations and extensibility

As I suggested in the PR landing these blocks [1,2,3].  I've shifted
the extensibility section to a separate file, since it's a generic
policy that applies to both our manifest and manifest-list.  I've
pushed the annotations meat into the lower-level manifest
specification (linking there from the higher-level manifest-list
specification).

The extensibility requirements and annotations field might arguably
apply to our other JSON types as well.  The separate extensibility
file sets the stage for that, but I've the other types off this commit
to focus on making the current requirements more DRY without changing
the specified behavior.

[1]: opencontainers#164 (comment)
[2]: opencontainers#164 (comment)
[3]: opencontainers#164 (comment)

Signed-off-by: W. Trevor King <wking@tremily.us>

Makefile

@@ -31,6 +31,7 @@ DOC_FILES := \
 	config.md \
 	manifest.md \
 	manifest-list.md \
+	extensibility.md \
 	canonicalization.md
 
 FIGURE_FILES := \

README.md

@@ -14,6 +14,7 @@ The OCI Image Format project creates and maintains the software shipping contain
 - [Image Configuration](config.md)
 - [Image Manifest](manifest.md)
 - [Image Manifest List](manifest-list.md)
+- [Extensibility](extensibility.md)
 - [Canonicalization](canonicalization.md)
 
 ## Overview

extensibility.md

@@ -0,0 +1,4 @@
+# Extensibility
+
+Implementations that are reading/processing [manifests](manifest.md) or [manifest lists](manifest-list.md) MUST NOT generate an error if they encounter an unknown property.
+Instead they MUST ignore unknown properties.

manifest-list.md

@@ -66,20 +66,7 @@ This section defines the `application/vnd.oci.image.manifest.list.v1+json` [medi
 
 - **`annotations`** *string-string map*
 
-    This OPTIONAL property contains arbitrary metadata for the manifest list.
-    Annotations MUST be a key-value map 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 this map, 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 by other specifications.
-    If there are no annotations then this property MUST either be absent or be an empty map.
-    Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown annotation key.
-
-    See [Pre-Defined Annotation Keys](manifest.md#pre-defined-annotation-keys).
-
-### Extensibility
-Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown property.
-Instead they MUST ignore unknown properties.
+    This OPTIONAL property contains arbitrary metadata for the manifest list with the same semantics as the [manifest's `annotations`](manifest.md#image-manifest-property-descriptions)
 
 ## Example Manifest List
 

manifest.md

@@ -71,10 +71,6 @@ Unlike the [Manifest List](manifest-list.md), which contains information about a
 
     See [Pre-Defined Annotation Keys](#pre-defined-annotation-keys).
 
-### Extensibility
-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
 
 *Example showing an image manifest:*