Merge pull request #676 from stevvooe/label-schema-compatibility-table

annotations.md: label schema compatibility table

annotations.md

@@ -17,13 +17,38 @@ This property contains arbitrary metadata.
 ## 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.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.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.homepage** URL to find more information on the image (string, a URL with scheme HTTP or HTTPS)
+* **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.
-* **org.opencontainers.image.revision** Source control revision identifier for packaged software.
+* **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.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.description** Human-readable description of the software packaged in the image (string)
+
+## Back-compatibility with Label Schema
+
+[Label Schema](https://label-schema.org) defined a number of conventional labels for container images, and these are now superceded by annotations with keys starting **org.opencontainers.image**.
+
+While users are encouraged to use the **org.opencontainers.image** keys, tools MAY choose to support compatible annotations using the **org.label-schema** prefix as follows.
+
+| `org.opencontainers.image` prefix | `org.label-schema prefix` | Compatibility notes |
+|---------------------------|-------------------------|---------------------|
+| `created` | `build-date` | Compatible |
+| `url` | `url` | Compatible |
+| `source` | `vcs-url` | Compatible |
+| `version` | `version` | Compatible |
+| `revision` | `vcs-ref` | Compatible |
+| `vendor` | `vendor` | Compatible |
+| `name` | `name` | Compatible |
+| `description` | `description` | Compatible |
+| `documentation` | `usage` | Value is compatible if the documentation is located by a URL |
+| `authors` |  | No equivalent in Label Schema |
+| `licenses` | | No equivalent in Label Schema |
+| `ref.name` | | No equivalent in Label Schema |
+| | `schema-version`| No equivalent in the OCI Image Spec |
+| | `docker.*`, `rkt.*` | No equivalent in the OCI Image Spec |