Add some text about extensions #164

duglin · 2016-06-26T19:35:16Z

Need to be kept in-sync with: opencontainers/runtime-spec#510

Signed-off-by: Doug Davis dug@us.ibm.com

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

vbatts · 2016-06-26T19:57:58Z

manifest.md

-    Keys are unique, and best practice is to namespace the keys.
+    Keys MUST be unique, and best practice is to namespace the keys.
+    If there are no annotations then this property MAY either be absent or be an empty hashmap.
+    Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown annotation.


s/unknown annotation/unknown annotation key/ ?

vbatts · 2016-06-26T19:58:29Z

SGTM, also, there are two annotations sections in this doc, but your PR only covers one of them.

duglin · 2016-06-26T20:03:37Z

oops - got the other one now

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

vbatts · 2016-06-26T20:18:34Z

manifest.md

-    Keys are unique, and best practice is to namespace the keys.
+    Keys MUST be unique, and best practice is to namespace the keys.
+    If there are no annotations then this property MAY either be absent or be an empty hashmap.
+    Implementations that are reading/processing manifest lists MUST NOT generate an error if they encounter an unknown annotation key.


do you want to see this same sentence on the other section too?

darn- I think I moved instead of copied. fixed -thanks!

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

stevvooe · 2016-07-06T17:28:37Z

manifest.md

    Common annotation keys include:
    * **created** date on which the image was built (string, timestamps type)
    * **authors** contact details of the people or organization responsible for the image (freeform string)
    * **homepage** URL to find more information on the image (string, must be a URL with scheme HTTP or HTTPS)
    * **documentation** URL to get documentation on the image (string, must be a URL with scheme HTTP or HTTPS)

+### Extensibility
+The `annotations` property MAY be used as an extensibility point to include additional information that is not defined as part of this specification.


"extension point"

duglin · 2016-07-07T02:27:54Z

updated based on today's conf call

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

vbatts · 2016-07-07T19:25:18Z

manifest.md

@@ -85,13 +85,20 @@ A client will distinguish a manifest list from an image manifest based on the Co

    This OPTIONAL property contains arbitrary metadata for the manifest list.
    Annotations is a key-value, unordered hashmap.
-    Keys are unique, and best practice is to namespace the keys.
+    Keys MUST be unique, and best practice is to namespace the keys.
+	Keys starting with the `opencontainers.org` namespace are reserved and MUST NOT be used.


Mostly I like it. I'm wondering if just saying "... are reserved." would be enough? If not to be used, then should this cover when the are used?

Is this not org.opencontainers or is that not how it is done here?

that ought to be clarified. I had in mind that it would be namespaced more
like an URL, rather than a java package.

On Thu, Jul 7, 2016 at 6:44 PM, Stephen Day notifications@github.com
wrote:

In manifest.md
#164 (comment)
:

@@ -85,13 +85,20 @@ A client will distinguish a manifest list from an image manifest based on the Co

This OPTIONAL property contains arbitrary metadata for the manifest list. Annotations is a key-value, unordered hashmap.

Keys are unique, and best practice is to namespace the keys.

Keys MUST be unique, and best practice is to namespace the keys.

Keys starting with the opencontainers.org namespace are reserved and MUST NOT be used.

Is this not org.opencontainers or is that not how it is done here?

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/opencontainers/image-spec/pull/164/files/e969158a0e4371760a72da3492b1b6803b03dc90#r70000997,
or mute the thread
https://github.com/notifications/unsubscribe/AAEF6dv8Fi4ZqyfxK79cBiFMdZTamp01ks5qTYFjgaJpZM4I-n6z
.

On Mon, Jul 18, 2016 at 10:20:04AM -0700, Vincent Batts wrote:

Keys are unique, and best practice is to namespace the keys.

Keys MUST be unique, and best practice is to namespace the keys.

Keys starting with the opencontainers.org namespace are reserved and MUST NOT be used.

that ought to be clarified. I had in mind that it would be namespaced more
like an URL, rather than a java package.

Does it matter? And as long as folks don't have actual hosts like
net.example.com, folks could use both. If we pick one ordering we
don't even have to worry about that, but I don't see any technical
difference between the two orderings.

for all the specifics of clarification, it's interesting you don't see a
difference in the two

On Mon, Jul 18, 2016 at 1:27 PM, W. Trevor King notifications@github.com
wrote:

In manifest.md
#164 (comment)
:

@@ -85,13 +85,20 @@ A client will distinguish a manifest list from an image manifest based on the Co

This OPTIONAL property contains arbitrary metadata for the manifest list. Annotations is a key-value, unordered hashmap.

Keys are unique, and best practice is to namespace the keys.

Keys MUST be unique, and best practice is to namespace the keys.

Keys starting with the opencontainers.org namespace are reserved and MUST NOT be used.

On Mon, Jul 18, 2016 at 10:20:04AM -0700, Vincent Batts wrote: > - Keys
are unique, and best practice is to namespace the keys. > + Keys MUST be
unique, and best practice is to namespace the keys. > + Keys starting with
the opencontainers.org namespace are reserved and MUST NOT be used.
that ought to be clarified. I had in mind that it would be namespaced more
like an URL, rather than a java package.
Does it matter? And as long as folks don't have actual hosts like
net.example.com, folks could use both. If we pick one ordering we don't
even have to worry about that, but I don't see any technical difference
between the two orderings.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/opencontainers/image-spec/pull/164/files/e969158a0e4371760a72da3492b1b6803b03dc90#r71190607,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAEF6bAfkHfDwksO7ouvp3gqeL1_LUfqks5qW7eBgaJpZM4I-n6z
.

On Mon, Jul 18, 2016 at 10:31:59AM -0700, Vincent Batts wrote:

@@ -85,13 +85,20 @@ A client will distinguish a manifest list from an image manifest based on the Co

This OPTIONAL property contains arbitrary metadata for the manifest list. Annotations is a key-value, unordered hashmap.

Keys are unique, and best practice is to namespace the keys.

Keys MUST be unique, and best practice is to namespace the keys.

Keys starting with the opencontainers.org namespace are reserved and MUST NOT be used.

for all the specifics of clarification, it's interesting you don't
see a difference in the two

I'm all for picking one ordering to recommend, but I'm happy to flip a
coin to pick ;). Does anyone have a reason to not choose via
coin-flip?

It also looks like there's inconsistent whitespace on the indent here,
with the final new line using a tab while everyone else uses spaces.

vbatts · 2016-07-20T21:33:11Z

do y'all think we can clear up this conversation on this feature? like maybe for v0.4.0?

I'm for this feature. Perhaps just with clarity around the prefixing?

duglin · 2016-07-21T11:56:57Z

I looked at both Docker and Kubernetes for examples and Docker seems to use the reverse notation (org.docker.*) while Kubernetes actually uses both based on (I guess) who wrote the code. Averaging it out, that pushes it a bit towards reverse domain notation, so I switched it to that and added a bit of text pushing people to follow that pattern.

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

vbatts · 2016-07-21T12:36:20Z

@duglin good thoughts, though to me that seems we should cover both use cases.

duglin · 2016-07-21T12:53:43Z

you want to reserve org.opencontainers.* and *.opencontainers.org ?

I guess we could, but I have to admit, the inconsistency I saw in Kube's docs on this, while not a show-stopper, is kind of weird - so my preference would be to pick one and stick with it.

vbatts · 2016-07-21T12:56:16Z

@brendandburns (or @thockin or @smarterclayton) have opinions on annotations prefixes?

wking · 2016-07-21T14:30:52Z

On Thu, Jul 21, 2016 at 05:53:43AM -0700, Doug Davis wrote:

you want to reserve org.opencontainers.* and *.opencontainers.org ?

I guess we could, but I have to admit, the inconsistency I saw in
Kube's docs on this, while not a show-stopper, is kind of weird - so
my preference would be to pick one and stick with it.

I agree on picking one to reserve, and recommending other folks use
the same order (although they can obviously use the other order if
they have a strong preference and are ok with the collision risk).

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

thockin · 2016-07-21T17:02:08Z

I don't think there's much value in reserving both the forward and backward domains. The backward domain is pretty annoying, frankly, and I don't understand why anyone would prefer it. It's human-hostile, and we don't tend to use annotations as a hierarchy (like Java does).

Decide which way is standard and run with it. I happen to think what is documented here is wrong, but Docker already chose that answer.

vbatts · 2016-07-21T17:57:49Z

the other benefit to having an opencontainers.org/ style, is that it is directly translatable to what could be a resolving path for folks looking for more info on the particular key. (much in the same vein of XML namespacing and validation)

stevvooe · 2016-09-09T01:16:35Z

LGTM

stevvooe · 2016-09-09T21:40:47Z

@duglin There are some whitespace errors that is choking the CI. Want to fix those so we can re-LGTM and get this merged?

Signed-off-by: Doug Davis <dug@us.ibm.com>

duglin · 2016-09-09T22:30:55Z

@stevvooe CI is fixed now

stevvooe · 2016-09-09T22:31:28Z

LGTM

@opencontainers/image-spec-maintainers

philips · 2016-09-13T05:19:49Z

LGTM

As I suggested in the PR landing these blocks [1,2,3]. I've shifted the extensibility section to stand alone at the end of the file, and pushed the annotations meat into the lower-level manifest specification (linking there from the higher-level manifest-list specification). The extensibility requirements and annotations field might arguably apply to our other JSON types as well, but I've left them off this commit to focus on making the current requirements more DRY without changing the specified behavior. [1]: opencontainers#164 (comment) [2]: opencontainers#164 (comment) [3]: opencontainers#164 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

We're not forbidding other OCI specs from using these fields, we're forbidding all specs (except for future versions of image-spec) from using these fields. The wording I'm bringing in here matches what 873b9b6 (Add some text about extensions, 2016-06-26, opencontainers#164) landed for the org.opencontainers.* annotation namespace. Signed-off-by: W. Trevor King <wking@tremily.us>

We're not forbidding other OCI specs from using these fields, we're forbidding all specs (except for future versions of image-spec) from using these fields [1,2]. The wording I'm bringing in here matches what 873b9b6 (Add some text about extensions, 2016-06-26, opencontainers#164) landed for the org.opencontainers.* annotation namespace. My personal preference would be to use JSON-LD to assign explicit semantics to every field (after which you don't have to worry about namespacing the fields themselves) [2], but that would be a larger change ;). [1]: opencontainers#111 (comment) [2]: opencontainers#111 (comment) [3]: opencontainers#111 (comment) And later comments in that sub-thread. Signed-off-by: W. Trevor King <wking@tremily.us>

We're not forbidding other OCI specs from using these fields, we're forbidding all specs (except for future versions of image-spec) from using these fields [1,2]. The wording I'm bringing in here matches what 873b9b6 (Add some text about extensions, 2016-06-26, opencontainers#164) landed for the org.opencontainers.* annotation namespace. My personal preference would be to use JSON-LD to assign explicit semantics to every field (after which you don't have to worry about namespacing the fields themselves) [3], but that would be a larger change ;). [1]: opencontainers#111 (comment) [2]: opencontainers#111 (comment) [3]: opencontainers#111 (comment) And later comments in that sub-thread. Signed-off-by: W. Trevor King <wking@tremily.us>

As I suggested in the PR landing these blocks [1,2,3]. I've shifted the extensibility section to a separate file, since it's a generic policy that applies to both our manifest and manifest-list. I've pushed the annotations meat into the lower-level manifest specification (linking there from the higher-level manifest-list specification). The extensibility requirements and annotations field might arguably apply to our other JSON types as well. The separate extensibility file sets the stage for that, but I've the other types off this commit to focus on making the current requirements more DRY without changing the specified behavior. [1]: opencontainers#164 (comment) [2]: opencontainers#164 (comment) [3]: opencontainers#164 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

As I suggested in the PR landing these blocks [1,2,3]. I've shifted the extensibility section to a separate considerations.md, since it's a generic policy that applies to both our manifest and manifest-list. I've pushed the annotations meat into the lower-level manifest specification (linking there from the higher-level manifest-list specification). The extensibility requirements and annotations field might arguably apply to our other JSON types as well. The separate extensibility file sets the stage for that, but I've left the other types off this commit to focus on making the current requirements more DRY without changing the specified behavior. My personal preference would be to have separate canonicalization.md and extensibility.md files, but Jonathan wanted the single file: On Mon, Oct 10, 2016 at 09:22:46AM -0700, Jonathan Boulle wrote [4]: > Ehh, I preferred it where it was - now worried about death by a > thousand files (extensibility, canonicalization, etc etc). Can we > combine them (into a generic "considerations" document or similar), > or just put this back? [1]: opencontainers#164 (comment) [2]: opencontainers#164 (comment) [3]: opencontainers#164 (comment) [4]: opencontainers#340 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

As I suggested in the PR landing these blocks [1,2,3]. I've shifted the extensibility section to a separate considerations.md, since it's a generic policy that applies to both our manifest and manifest-list. The extensibility requirements might arguably apply to our other JSON types as well (like annotations, which were recently DRYed up in f15a268, annotations: make a designated doc and DRY a bit, 2016-12-15, opencontainers#501). The new extensibility section sets the stage for that, but I've left the other types off this commit to focus on making the current requirements more DRY without changing the specified behavior. My personal preference would be to have separate canonicalization.md and extensibility.md files, but Jonathan wanted the single file: On Mon, Oct 10, 2016 at 09:22:46AM -0700, Jonathan Boulle wrote [4]: > Ehh, I preferred it where it was - now worried about death by a > thousand files (extensibility, canonicalization, etc etc). Can we > combine them (into a generic "considerations" document or similar), > or just put this back? [1]: opencontainers#164 (comment) [2]: opencontainers#164 (comment) [3]: opencontainers#164 (comment) [4]: opencontainers#340 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

The 'null' option has been in the JSON Schema since 78c7ff7 (manifest: add annotations, 2016-04-27, opencontainers#44), although I expect it was accidental. The spec has clearly not allowed: "annotations": null since 873b9b6 (Add some text about extensions, 2016-06-26, opencontainers#164) landed with the following (still current) requirements: Annotations MUST be a key-value map where both the key and value MUST be strings. and: If there are no annotations then this property MUST either be absent or be an empty map. Folks without annotations should not set the property at all, or they should set it to: "annotations": {} Signed-off-by: W. Trevor King <wking@tremily.us>

Generating an error seems like one potential violation of the requirement to ignore unknown properties. Compliance testing for the ignore requirement can cite the MUST I've written here for any noticeable runtime activity around the unknown property without needing a error-specific MUST. We've had the two MUSTs since 27a05de (Add text about extensions, 2016-06-26, opencontainers#510), citing [1]. I'd asked for consolidated phrasing then [2,3], but hadn't followed up after the commit landed. I've left a line mentioning the error activity as non-normative clarification, but am also happy to drop that line completely. Also: * Update the unknown annotation entry to reference the generic extensibility section, because there's nothing annotation-specific in how we want runtimes to handle unknown keys. * Remove "reading or processing" language. This initially landed in 27a05de with a bump in b92cf90 (consistency and style fix, 2017-05-12, opencontainers#811). Some thought was put into this phrasing there [4,5] and earlier in opencontainers#510 [6], but we never got around to dropping this qualifier. However, the purpose of this qualifier is unclear to me. What is the point of compliance requirements for runtimes which don't read or process a configuration? [1]: opencontainers/image-spec#164 [2]: opencontainers#510 (comment) [3]: opencontainers#510 (comment) [4]: opencontainers#811 (comment) [5]: opencontainers#811 (comment) [6]: opencontainers#510 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

As I suggested in the PR landing these blocks [1,2,3]. I've shifted the extensibility section to a separate considerations.md, since it's a generic policy that applies to both our manifest and manifest-list. The extensibility requirements might arguably apply to our other JSON types as well (like annotations, which were recently DRYed up in f15a268, annotations: make a designated doc and DRY a bit, 2016-12-15, #501). The new extensibility section sets the stage for that, but I've left the other types off this commit to focus on making the current requirements more DRY without changing the specified behavior. My personal preference would be to have separate canonicalization.md and extensibility.md files, but Jonathan wanted the single file: On Mon, Oct 10, 2016 at 09:22:46AM -0700, Jonathan Boulle wrote [4]: > Ehh, I preferred it where it was - now worried about death by a > thousand files (extensibility, canonicalization, etc etc). Can we > combine them (into a generic "considerations" document or similar), > or just put this back? [1]: opencontainers/image-spec#164 (comment) [2]: opencontainers/image-spec#164 (comment) [3]: opencontainers/image-spec#164 (comment) [4]: opencontainers/image-spec#340 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

duglin force-pushed the extensions branch from 0f830d0 to 6ec256d Compare June 26, 2016 19:46

duglin pushed a commit to duglin/runtime-spec that referenced this pull request Jun 26, 2016

Add text about extensions

7f02d98

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

duglin mentioned this pull request Jun 26, 2016

Add text about extensions opencontainers/runtime-spec#510

Merged

vbatts reviewed Jun 26, 2016
View reviewed changes

duglin force-pushed the extensions branch from 6ec256d to 75d58f5 Compare June 26, 2016 20:03

duglin pushed a commit to duglin/runtime-spec that referenced this pull request Jun 26, 2016

Add text about extensions

1f2a4e3

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

vbatts reviewed Jun 26, 2016
View reviewed changes

duglin force-pushed the extensions branch from 75d58f5 to ca04c0a Compare June 26, 2016 20:21

duglin pushed a commit to duglin/runtime-spec that referenced this pull request Jul 5, 2016

Add text about extensions

b06521f

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

stevvooe reviewed Jul 6, 2016
View reviewed changes

duglin force-pushed the extensions branch from ca04c0a to e969158 Compare July 7, 2016 02:27

duglin pushed a commit to duglin/runtime-spec that referenced this pull request Jul 7, 2016

Add text about extensions

aea2039

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

vbatts reviewed Jul 7, 2016
View reviewed changes

duglin force-pushed the extensions branch from e969158 to f6f3f51 Compare July 21, 2016 11:55

duglin force-pushed the extensions branch from f6f3f51 to d7e648b Compare July 21, 2016 12:06

duglin pushed a commit to duglin/runtime-spec that referenced this pull request Jul 21, 2016

Add text about extensions

2c6c407

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

duglin pushed a commit to duglin/runtime-spec that referenced this pull request Jul 21, 2016

Add text about extensions

8987aad

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

duglin force-pushed the extensions branch from d7e648b to 256910e Compare July 21, 2016 16:32

duglin pushed a commit to duglin/runtime-spec that referenced this pull request Jul 21, 2016

Add text about extensions

44e2135

Mimic opencontainers/image-spec#164 and they should be kept in-sync Signed-off-by: Doug Davis <dug@us.ibm.com>

Add some text about extensions

873b9b6

Signed-off-by: Doug Davis <dug@us.ibm.com>

duglin force-pushed the extensions branch from 7350d6c to 873b9b6 Compare September 9, 2016 22:27

philips merged commit ddc89f2 into opencontainers:master Sep 13, 2016

wking mentioned this pull request Sep 23, 2016

manifest: DRY annotations and extensibility #340

Closed

wking mentioned this pull request Sep 29, 2016

descriptor: Rephrase reserved wording #348

Merged

wking mentioned this pull request Jan 24, 2017

considerations: DRY extensibility #526

Merged

wking mentioned this pull request Jan 28, 2017

schema/defs-image: Remove 'null' from valid annotations #539

Merged

wking mentioned this pull request Aug 31, 2017

config: Collapse extensibility to a single MUST opencontainers/runtime-spec#916

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add some text about extensions #164

Add some text about extensions #164

duglin commented Jun 26, 2016 •

edited

Loading

vbatts Jun 26, 2016

duglin Jun 26, 2016

vbatts commented Jun 26, 2016

duglin commented Jun 26, 2016

vbatts Jun 26, 2016

duglin Jun 26, 2016

stevvooe Jul 6, 2016

duglin commented Jul 7, 2016

vbatts Jul 7, 2016

stevvooe Jul 7, 2016

vbatts Jul 18, 2016

wking Jul 18, 2016

vbatts Jul 18, 2016

wking Jul 18, 2016

vbatts commented Jul 20, 2016

duglin commented Jul 21, 2016

vbatts commented Jul 21, 2016

duglin commented Jul 21, 2016

vbatts commented Jul 21, 2016

wking commented Jul 21, 2016

thockin commented Jul 21, 2016

vbatts commented Jul 21, 2016

stevvooe commented Sep 9, 2016 •

edited by caniszczyk

Loading

stevvooe commented Sep 9, 2016

duglin commented Sep 9, 2016

stevvooe commented Sep 9, 2016 •

edited by caniszczyk

Loading

philips commented Sep 13, 2016 •

edited by caniszczyk

Loading

Add some text about extensions #164

Add some text about extensions #164

Conversation

duglin commented Jun 26, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vbatts commented Jun 26, 2016

duglin commented Jun 26, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

duglin commented Jul 7, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vbatts commented Jul 20, 2016

duglin commented Jul 21, 2016

vbatts commented Jul 21, 2016

duglin commented Jul 21, 2016

vbatts commented Jul 21, 2016

wking commented Jul 21, 2016

thockin commented Jul 21, 2016

vbatts commented Jul 21, 2016

stevvooe commented Sep 9, 2016 • edited by caniszczyk Loading

stevvooe commented Sep 9, 2016

duglin commented Sep 9, 2016

stevvooe commented Sep 9, 2016 • edited by caniszczyk Loading

philips commented Sep 13, 2016 • edited by caniszczyk Loading

duglin commented Jun 26, 2016 •

edited

Loading

stevvooe commented Sep 9, 2016 •

edited by caniszczyk

Loading

stevvooe commented Sep 9, 2016 •

edited by caniszczyk

Loading

philips commented Sep 13, 2016 •

edited by caniszczyk

Loading