considerations: 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 considerations.md, 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 left the other types off this
commit to focus on making the current requirements more DRY without
changing the specified behavior.

My personal preference would be to have separate canonicalization.md
and extensibility.md files, but Jonathan wanted the single file:

On Mon, Oct 10, 2016 at 09:22:46AM -0700, Jonathan Boulle wrote [4]:
> Ehh, I preferred it where it was - now worried about death by a
> thousand files (extensibility, canonicalization, etc etc). Can we
> combine them (into a generic "considerations" document or similar),
> or just put this back?

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

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

Makefile

@@ -31,7 +31,7 @@ DOC_FILES := \
 	config.md \
 	manifest.md \
 	manifest-list.md \
-	canonicalization.md
+	considerations.md
 
 FIGURE_FILES := \
 	img/media-types.png

README.md

@@ -14,7 +14,9 @@ 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)
-- [Canonicalization](canonicalization.md)
+- [Considerations](considerations.md)
+    - [Extensibility](considerations.md#extensibility)
+    - [Canonicalization](considerations.md#canonicalization)
 
 ## Overview
 

canonicalization.md renamed to considerations.md

@@ -1,3 +1,8 @@
+# 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.
+
 # Canonicalization
 
 OCI Images [are](descriptor.md) [content-addressable](image-layout.md).

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:*