annotation / schema items

[vbatts]

Following on to the DockerCon conversation:

• backwards compatibility table
• annotations.md: added useful annotations #636
• work with label-schema site folks for their domain, etc

[stevvooe]

@lizrice @amouat Would you be interested in taking a crack at the compatibility table?

[lizrice]

Sure, I can take a stab at this if you like (might be a couple of days)

[lizrice]

I've been working on this and have a few questions.

• I think revision in Image Spec is probably equivalent to vcs-ref in Label Schema i.e. the Git or other VCS reference for the version built into this image. Is that correct? I'm a bit thrown by the phrase specifying "for packaged software" in the Image Spec definition of this key.

• Image Spec has keys homepage and documentation. Label Schema has url and usage. I think that homepage and url are equivalent, and that documentation is similar to usage except that the latter (Label Schema version) allows for usage to refer to a file within the image or to a URL. Firstly do you agree with my assessment of the equivalence of these keys, and secondly how would you feel about extending the definition of documentation to allow for a reference within the image?

• The definition for ref.name says "Name of the reference" but it's not clear to me which reference it's, er, referring to?

[vbatts]

wording or name of revision could be more clear, as that term was used in cvs and subversion, but git commits are in no way referred to as a revision. The "for packaged software" is either redundant or ambiguous. Feel free to improve on that as well.

I agree with your assessment of the second bullet.

ref.name is equivalent to the tag of an image,in docker terms.

[stevvooe]

@vbatts A Git Revision is the correct term. The rev-parse tool will resolve to a specific commit. This allows one to put in a tag, qualified tag or specific commit.

The "for packaged software" is either redundant or ambiguous.

Quite the dichotomy. Software is packaged in the image, presumably. Choose a git repository that represents it. The may be a missing article because the same phrase above is "the package software".

I think that homepage and url are equivalent, and that documentation is similar to usage except that the latter (Label Schema version) allows for usage to refer to a file within the image or to a URL. Firstly do you agree with my assessment of the equivalence of these keys, and secondly how would you feel about extending the definition of documentation to allow for a reference within the image?

Many projects have a landing page and a direct link to the source code. Imagine https://opencontianer.org (homepage) versus https://github.com/opencontainers/image-spec (sources). The actual documentation may be in a separate place, like https://docs.opencontainers.org (documentation). Documentation should mostly be a url. If is just a path, I suppose the consumer could assume that is a path into the image rootfs. However, I am not sure how the user could access this documentation without running the image first, making it rather inaccessible. The url workflow integrates better with web uis that might index images, but may not post-process them.

From this point of view, I don't think documentation and usage are at all equivalent.

[lizrice]

I've just created a PR. I may have gone too far (and I'm sure you'll tell me!) but I have proposed changing some of the key names to reuse the Label Schema ones (which in turn were taken from the Project Atomic names) as IMO that would be less confusing for, and make less work for, folks who are already using the Label Schema versions. Also I've proposed adding human-readable name & description, as from the Label Schema discussions those were pretty much table stakes for these to be useful.

[stevvooe]

@lizrice This PR goes far beyond the agreed actions that were made at the face to face. While I am fine with some of the changes, I would ask that we don't revert the existing names.

I have marked the exceptions in the PR.

[lizrice]

Sticking with the Label Schema version of the names is not something I'm wildly bothered about - it just seemed like a sensible thing to suggest to keep things easier for existing users.

When putting together the compatibility table it stood out that the OCI version has a bunch of keys with a different names from Label Schema, but for identical meanings. That seemed a bit at odds with "70% of the label-schema labels were already in OCI". Seems like there is still an opportunity to keep the same names (although of course there could be a bunch of OCI Images now using the new names that I'm not aware of, in which case it would totally make sense to have the new ones now).

FWIW we went through this sort of thing with Label Schema too: I'm not sure "vcs-ref" would have been my first choice when we were defining the Label Schema keys, but it had the advantage of compatibility with and heritage from Project Atomic.

What do other folks think?

[stevvooe]

@lizrice When I said "70% of the label-schema labels were already in OCI" (not sure if that is an exact quote), I meant by functionality. For the most part, the chosen names are more general, shorter or more in line with the language used in these areas. Compound names (ie vcs-url and vcs-ref) were removed in favor of names that are direct and match a wider variety of use cases. Some of the names (ie homepage) were already there from a previous PR.

I've taken the compatibility table from the PR and modified it to be inline with the agreement:

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

I understand some aspects must have been confusing, but hopefully this provides clarification.

[amouat]

Hi all,

First, apologies for not being involved in this more. In particular, I wish I'd been more up-to-speed on exactly what the state of the OCI version of the spec was during the meeting at DockerCon.

As far as I can tell, the current state is: https://github.com/opencontainers/image-spec/blob/master/annotations.md, which I believe would benefit from some expansion, details and examples before being pushed to the public. I think it should also use the moscow style wording used in the introduction.

Some points:

• My thinking for allowing usage/documentation to be a file is that it can live with the container and won't risk becoming out-of-sync with the URL. It also means the vendor does not need to worry about URLs and websites.

• I would suggest that date MUST be RFC 3339 compatible

• I would suggest version MAY be semantic.

• One conceptual problem we often ran into was whether we were referring to the main "software" in an image or the image itself e.g. if I have a wordpress container is the version the version of wordpress or the version of the image? What if the image has both wordpress and mysql?

• This problem becomes even more acute with license metadata. Is this the license for the image or all the software in it? Can I have multiple licenses? What does it mean for people who use this image as a base? As this clearly has legal implications, I advise treading carefully.

• shouldn't source allow git:// and ssh://?

• why does source specify "binary" files? And can there be multiple sources?

• org.opencontainers.image.ref.name - is this a digest? I'm not sure I follow.

Finally, are people against providing examples for each annotation? I think it would help a lot.

[amouat]

Regarding ref.name, I found the answer in https://github.com/opencontainers/image-spec/blob/master/image-layout.md (TLDR; it's the tag)

Implementor's Note: A common use case of descriptors with a "org.opencontainers.image.ref.name" annotation is representing a "tag" for a container image. For example, an image may have a tag for different versions or builds of the software. In the wild you often see "tags" like "v1.0.0-vendor.0", "2.0.0-debug", etc. Those tags will often be represented in an image-layout repository with matching "org.opencontainers.image.ref.name" annotations like "v1.0.0-vendor.0", "2.0.0-debug", etc.

[vbatts]

@amouat thanks for the review.

[stevvooe]

My thinking for allowing usage/documentation to be a file is that it can live with the container and won't risk becoming out-of-sync with the URL. It also means the vendor does not need to worry about URLs and websites.

I think a separate field for this purpose is fine. I would suggest the addition of usage for in container documentation.

I would suggest that date MUST be RFC 3339 compatible

Agreed.

I would suggest version MAY be semantic.

Good catch. No reason to make everyone be semantic.

One conceptual problem we often ran into was whether we were referring to the main "software" in an image or the image itself e.g. if I have a wordpress container is the version the version of wordpress or the version of the image? What if the image has both wordpress and mysql?

This is really up to the distributor. If they need compound versioning of package+xxxx, then they should use a version number that represents that.

This problem becomes even more acute with license metadata. Is this the license for the image or all the software in it? Can I have multiple licenses? What does it mean for people who use this image as a base? As this clearly has legal implications, I advise treading carefully.

Yes, you can have multiple licenses. The field should list out the licenses that may apply to the package software. It really needs to be incumbent on the user to understand the licensing constraints of the software they are using. There is no specification that will make a field that will provide enough information to make decisions about this that work in all legal situations.

shouldn't source allow git:// and ssh://?

Do we not allow a URL there? If not, we should allow a url. This might just be simple over-specification.

why does source specify "binary" files? And can there be multiple sources?

Only a single source. We should probably specify it as "artifact".

[amouat]

shouldn't source allow git:// and ssh://?
Do we not allow a URL there? If not, we should allow a url. This might just be simple over-specification.

The wording is "string, a URL with scheme HTTP or HTTPS". I'd suggest "URL pointing to source code used in building the image". I'm not sure if it even needs to mention version control or binary/artifact. A couple of examples would then help clarify.

[lizrice]

shouldn't source allow git:// and ssh://?
Do we not allow a URL there? If not, we should allow a url. This might just be simple over-specification.

The wording is "string, a URL with scheme HTTP or HTTPS". I'd suggest "URL pointing to source code used in building the image". I'm not sure if it even needs to mention version control or binary/artifact. A couple of examples would then help clarify.

I agree, "binary" is over-specifying and I think "artefact" is unnecessarily confusing. IMO "URL pointing to the source code used to build the image" or "URL pointing to the source code from which the image was built" would be even more clear.

A couple of examples would then help clarify.

We had some examples (for this and other fields) in Label Schema that we could copy in. I'm happy to do a PR for that if folks like the idea.

Do we also want to absorb some or all of any of the other sections from Label Schema e.g. the background ?

This problem becomes even more acute with license metadata. Is this the license for the image or all the software in it? Can I have multiple licenses? What does it mean for people who use this image as a base? As this clearly has legal implications, I advise treading carefully.

Yes, you can have multiple licenses. The field should list out the licenses that may apply to the package software. It really needs to be incumbent on the user to understand the licensing constraints of the software they are using. There is no specification that will make a field that will provide enough information to make decisions about this that work in all legal situations.

Personally I like the option to include license information in a standard way in the container image, but I'm sure there will be lawyers who have much more nuanced opinions. This concern about the legal implications was why we never got consensus in Label Schema to include a license field. The worry as I understand it (IANAL) is whether, by including a license field, the provider of the container image is making a statement (or even a "warranty") that the end user might reasonably believe they could rely on.

[stevvooe]

The worry as I understand it (IANAL) is whether, by including a license field, the provider of the container image is making a statement (or even a "warranty") that the end user might reasonably believe they could rely on.

This is a valid concern. Such a field cannot provide any legal guarantees or warranty. Licensing arrangements are between the distributor and the consumer. Most assumptions like this are explicitly called out as invalid in most minimal licenses, such as MIT, BSD and ISC.

I wonder if this is provided implicitly through the Apache License under which this project is distributed.

Perhaps, we should explicitly call this out.

@caniszczyk Do we have any legal guidance on this?

[caniszczyk]

LF Legal was looped in when this was discussed previously in old issues linked off of #501, so please keep the licenses field.

@lizrice in terms of the domain, I'm fine with OCI/LF paying for the upkeep / domain etc, just send me info to cra@linuxfoundation.org and we can start the process

[stevvooe]

@caniszczyk @lizrice Let us know if anything was missed here, we closing to move forward with the 1.0 milestone.

Thanks for all the help!