Merge pull request #606 from stevvooe/namespace-image-annotations

spec: namespace annotations defined in image spec

Author: vbatts

annotations.md

@@ -9,16 +9,17 @@ 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.
+The prefix `org.opencontainers` is reserved for keys defined in Open Container Initiative (OCI) specifications and MUST NOT be used by other specifications and extensions.
+Keys using the `org.opencontainers.image` namespace are reserved for use in the OCI Image Specification and MUST NOT be used by other specifications and extensions, including other OCI specifications.
 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 [image index](image-index.md) and image [manifest](manifest.md) 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)
-* **org.opencontainers.ref.name** Name of the reference (string)
+* **org.opencontainers.image.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.image.authors** contact details of the people or organization responsible for the image (freeform string)
+* **org.opencontainers.image.homepage** URL to find more information on the image (string, a URL with scheme HTTP or HTTPS)
+* **org.opencontainers.image.documentation** URL to get documentation on the image (string, a URL with scheme HTTP or HTTPS)
+* **org.opencontainers.image.source** URL to get source code for the binary files in the image (string, a URL with scheme HTTP or HTTPS)
+* **org.opencontainers.image.ref.name** Name of the reference (string)

config.md

@@ -162,7 +162,7 @@ Note: Any OPTIONAL field MAY also be set to null, which is equivalent to being a
      Labels MUST be a key-value map where both the key and value MUST be strings.
      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 subsequent specifications.
+     Keys using the `org.opencontainers.image` namespace are reserved and MUST NOT be used by subsequent specifications.
      If there are no labels then this property MAY either be absent or an empty map.
      Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown labels key.
 

image-layout.md

@@ -147,17 +147,17 @@ The [image index](image-index.md) is a multi-descriptor entry point.
 
 This index provides an established path (`/index.json`) to have an entry point for an image-layout and to discover auxiliary descriptors.
 
-No semantic restriction is given for the "org.opencontainers.ref.name" annotation of descriptors.
+No semantic restriction is given for the "org.opencontainers.image.ref.name" annotation of descriptors.
 In general the `mediaType` of each [descriptor][descriptors] object in the `manifests` field will be either `application/vnd.oci.image.index.v1+json` or `application/vnd.oci.image.manifest.v1+json`.
 Future versions of the spec MAY use a different mediatype (i.e. a new versioned format).
 An encountered `mediaType` that is unknown SHOULD be safely ignored.
 
 
 **Implementor's Note:**
-A common use case of descriptors with a "org.opencontainers.ref.name" annotation is representing a "tag" for a container image.
+A common use case of descriptors with a "org.opencontainers.image.ref.name" annotation is representing a "tag" for a container image.
 For example, an image may have a tag for different versions or builds of the software.
 In the wild you often see "tags" like "v1.0.0-vendor.0", "2.0.0-debug", etc.
-Those tags will often be represented in an image-layout repository with matching "org.opencontainers.ref.name" annotations like "v1.0.0-vendor.0", "2.0.0-debug", etc.
+Those tags will often be represented in an image-layout repository with matching "org.opencontainers.image.ref.name" annotations like "v1.0.0-vendor.0", "2.0.0-debug", etc.
 
 
 ### Index Example
@@ -171,7 +171,7 @@ Those tags will often be represented in an image-layout repository with matching
       "size": 7143,
       "digest": "sha256:0228f90e926ba6b96e4f39cf294b2586d38fbb5a1e385c05cd1ee40ea54fe7fd",
       "annotations": {
-        "org.opencontainers.ref.name": "stable-release"
+        "org.opencontainers.image.ref.name": "stable-release"
       }
     },
     {
@@ -183,7 +183,7 @@ Those tags will often be represented in an image-layout repository with matching
         "os": "linux"
       },
       "annotations": {
-        "org.opencontainers.ref.name": "v1.0"
+        "org.opencontainers.image.ref.name": "v1.0"
       }
     },
     {