From 4986a7ebe0dee50d985742b355613d19d53d227e Mon Sep 17 00:00:00 2001 From: Vincent Batts Date: Fri, 9 Dec 2016 09:10:03 -0500 Subject: [PATCH 1/4] descriptor: fix example formatting Signed-off-by: Vincent Batts --- descriptor.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/descriptor.md b/descriptor.md index 659d5a54a..2a21975f4 100644 --- a/descriptor.md +++ b/descriptor.md @@ -118,9 +118,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, From f15a268b30156c21dcc5d5e21d746d17db26c2a8 Mon Sep 17 00:00:00 2001 From: Vincent Batts Date: Thu, 15 Dec 2016 15:39:15 -0500 Subject: [PATCH 2/4] annotations: make a designated doc and DRY a bit In DRY'ing up the references to annotations. This makes the defined keys in a very logical place rather than the bottom of one of the other docs. Signed-off-by: Vincent Batts --- annotations.md | 23 +++++++++++++++++++++++ manifest-list.md | 12 +++--------- manifest.md | 18 ++---------------- 3 files changed, 28 insertions(+), 25 deletions(-) create mode 100644 annotations.md diff --git a/annotations.md b/annotations.md new file mode 100644 index 000000000..2bcc6e7db --- /dev/null +++ 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/manifest-list.md b/manifest-list.md index 2bb22804f..fe6b71775 100644 --- 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 index 83cc34e8c..a720fcd90 100644 --- 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) From 84b6a2856480590f79ecd09244504bb935f8ebbe Mon Sep 17 00:00:00 2001 From: Vincent Batts Date: Thu, 15 Dec 2016 15:47:45 -0500 Subject: [PATCH 3/4] descriptor: add OPTIONAL annotations to this object this has come up in discussion and is needed for adding discoverable arbitrary data to the descriptor references. Especially in making an index for image layout. Signed-off-by: Vincent Batts --- descriptor.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/descriptor.md b/descriptor.md index 2a21975f4..f14d7cb48 100644 --- 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. From f185dd553bff0161590ed62a3bbcc3726498f406 Mon Sep 17 00:00:00 2001 From: Vincent Batts Date: Wed, 11 Jan 2017 09:51:49 -0500 Subject: [PATCH 4/4] *: add new file to the TOC and docs Signed-off-by: Vincent Batts --- Makefile | 1 + spec.md | 1 + 2 files changed, 2 insertions(+) diff --git a/Makefile b/Makefile index e4480971b..3f46d8b80 100644 --- 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/spec.md b/spec.md index 6655ff72e..a6590e1ed 100644 --- 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