Merge pull request #501 from vbatts/descriptor_annotations

stevvooe · web-flow · commit 84a74b0cec93 · 2017-01-24T10:39:57.000-08:00
Descriptor annotations
diff --git a/Makefile b/Makefile
@@ -29,6 +29,7 @@ DOC_FILES := \
 	manifest-list.md \
 	layer.md \
 	config.md \
+	annotations.md \
 	canonicalization.md
 
 FIGURE_FILES := \
diff --git a/annotations.md b/annotations.md
@@ -0,0 +1,23 @@
+# Annotations
+Several components of the specification, like [Image Manifests](manifest.md) and [Descriptors](descriptor.md), feature an optional annotations property, whose format is common and defined in this section.
+
+This property contains arbitrary metadata.
+
+## Rules
+
+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 and extensions.
+If there are no annotations then this property MUST either be absent or be an empty map.
+Consumers MUST NOT generate an error if they encounter an unknown annotation key.
+
+## Pre-Defined Annotation Keys
+
+This specification defines the following annotation keys, intended for but not limited to manifest list and image manifest authors:
+* **org.opencontainers.created** date on which the image was built (string, date-time as defined by [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6)).
+* **org.opencontainers.authors** contact details of the people or organization responsible for the image (freeform string)
+* **org.opencontainers.homepage** URL to find more information on the image (string, a URL with scheme HTTP or HTTPS)
+* **org.opencontainers.documentation** URL to get documentation on the image (string, a URL with scheme HTTP or HTTPS)
+* **org.opencontainers.source** URL to get source code for the binary files in the image (string, a URL with scheme HTTP or HTTPS)
diff --git a/descriptor.md b/descriptor.md
@@ -40,6 +40,11 @@ The following fields contain the primary properties that constitute a Descriptor
   Each entry MUST conform to [RFC 3986][rfc3986].
   Entries SHOULD use the `http` and `https` schemes, as defined in [RFC 7230][rfc7230-s2.7].
 
+- **`annotations`** *string-string map*
+
+    This OPTIONAL property contains arbitrary metadata for this descriptor.
+    This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
+
 ### Reserved
 
 The following field keys are reserved and MUST NOT be used by other specifications.
@@ -118,9 +123,11 @@ The following example describes a [_Manifest_](manifest.md#image-manifest) with
   "size": 7682,
   "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270"
 }
+```
 
 In the following example, the descriptor indicates that the referenced manifest is retrievable from a particular URL:
 
+```json,title=Content%20Descriptor&mediatype=application/vnd.oci.descriptor.v1%2Bjson
 {
   "mediaType": "application/vnd.oci.image.manifest.v1+json",
   "size": 7682,
diff --git a/manifest-list.md b/manifest-list.md
@@ -67,15 +67,9 @@ For the media type(s) that this document is compatible with, see the [matrix][ma
 - **`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).
+    This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
+
+    See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
 
 ### Extensibility
 Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown property.
diff --git a/manifest.md b/manifest.md
@@ -62,15 +62,9 @@ Unlike the [Manifest List](manifest-list.md), which contains information about a
 - **`annotations`** *string-string map*
 
     This OPTIONAL property contains arbitrary metadata for the image manifest.
-    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 the image manifest MUST NOT generate an error if they encounter an unknown annotation key.
+    This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
 
-    See [Pre-Defined Annotation Keys](#pre-defined-annotation-keys).
+    See [Pre-Defined Annotation Keys](annotations.md#pre-defined-annotation-keys).
 
 ### Extensibility
 Implementations that are reading/processing image manifests MUST NOT generate an error if they encounter an unknown property.
@@ -111,11 +105,3 @@ Instead they MUST ignore unknown properties.
   }
 }
 ```
-
-# Pre-Defined Annotation Keys
-This specification defines the following annotation keys, which MAY be used by manifest list and image manifest authors:
-* **org.opencontainers.created** date on which the image was built (string, date-time as defined by [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6)).
-* **org.opencontainers.authors** contact details of the people or organization responsible for the image (freeform string)
-* **org.opencontainers.homepage** URL to find more information on the image (string, must be a URL with scheme HTTP or HTTPS)
-* **org.opencontainers.documentation** URL to get documentation on the image (string, must be a URL with scheme HTTP or HTTPS)
-* **org.opencontainers.source** URL to get source code for the binary files in the image (string, must be a URL with scheme HTTP or HTTPS)
diff --git a/spec.md b/spec.md
@@ -17,6 +17,7 @@ The goal of this specification is to enable the creation of interoperable tools
 - [Image Manifest List](manifest-list.md)
 - [Filesystem Layers](layer.md)
 - [Image Configuration](config.md)
+- [Annotations](annotations.md)
 - [Canonicalization](canonicalization.md)
 
 # Notational Conventions
