Merge pull request #678 from vbatts/annotations_cleanup_1

annotations: addressing comments

annotations.md

@@ -19,15 +19,17 @@ This property contains arbitrary metadata.
 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.image.created** date and time 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.url** 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.version** [Semantic versioning-compatible](http://semver.org/) version of the packaged software. The version MAY match a label or tag in the source code repository.
+* **org.opencontainers.image.url** URL to find more information on the image (string)
+* **org.opencontainers.image.documentation** URL to get documentation on the image (string)
+* **org.opencontainers.image.source** URL to get source code for building the image (string)
+* **org.opencontainers.image.version** version of the packaged software
+  * The version MAY match a label or tag in the source code repository
+  * version MAY be [Semantic versioning-compatible](http://semver.org/)
 * **org.opencontainers.image.revision** Source control revision identifier for the packaged software.
 * **org.opencontainers.image.vendor** Name of the distributing entity, organization or individual.
 * **org.opencontainers.image.licenses** Comma-separated list of licenses under which contained software is distributed, in [SPDX Short identifier](https://spdx.org/licenses/) form.
 * **org.opencontainers.image.ref.name** Name of the reference for a target (string). SHOULD only be considered valid when on descriptors on `index.json` within [image layout](image-layout.md).
-* **org.opencontainers.image.name** Human-readable name of the software packaged in the image (string)
+* **org.opencontainers.image.title** Human-readable title of the image (string)
 * **org.opencontainers.image.description** Human-readable description of the software packaged in the image (string)
 
 ## Back-compatibility with Label Schema
@@ -44,7 +46,7 @@ While users are encouraged to use the **org.opencontainers.image** keys, tools M
 | `version` | `version` | Compatible |
 | `revision` | `vcs-ref` | Compatible |
 | `vendor` | `vendor` | Compatible |
-| `name` | `name` | Compatible |
+| `title` | `name` | Compatible |
 | `description` | `description` | Compatible |
 | `documentation` | `usage` | Value is compatible if the documentation is located by a URL |
 | `authors` |  | No equivalent in Label Schema |