manifest: DRY annotations and extensibility

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