Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Descriptor annotations #501

Merged
merged 4 commits into from
Jan 24, 2017
Merged

Descriptor annotations #501

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4986a7e
descriptor: fix example formatting
vbatts Dec 9, 2016
f15a268
annotations: make a designated doc and DRY a bit
vbatts Dec 15, 2016
84b6a28
descriptor: add OPTIONAL annotations to this object
vbatts Dec 15, 2016
f185dd5
*: add new file to the TOC and docs
vbatts Jan 11, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ DOC_FILES := \
manifest-list.md \
layer.md \
config.md \
annotations.md \
canonicalization.md

FIGURE_FILES := \
Expand Down
23 changes: 23 additions & 0 deletions annotations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How would multiple authors be specified?

* **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)
7 changes: 7 additions & 0 deletions descriptor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -118,9 +123,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,
Expand Down
12 changes: 3 additions & 9 deletions manifest-list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
18 changes: 2 additions & 16 deletions manifest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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)
1 change: 1 addition & 0 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down