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?