Add annotations back-compability table with Label Schema

Part of issue opencontainers#658. Added table to show compatibility with
label-schema.org conventions. Changed some of the existing keys
to be compatible as there seems no reason for them to differ (this
also gives more consistency with label names originally defined in
Project Atomic, which Label Schema deliberately reused.)

Signed-off-by: Liz Rice <liz@lizrice.com>

annotations.md

@@ -17,13 +17,40 @@ 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.build-date** 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.vcs-url** 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.vcs-ref** Version control reference for the source code for the binary files in the image.
 * **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 |
+|---------------------------|-------------------------|---------------------|
+| `build-date` | `build-date` | Compatible |
+| `url` | `url` | Compatible |
+| `vcs-url` | `vcs-url` | Compatible | 
+| `version` | `version` | Compatible |
+| `vcs-ref` | `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 | 
+
+