Define the Specification for Tags

[JeremyLoy]

The OCI specification lacks a strict definition of valid tags.

I believe that image tags should support the full semver specification. To be clear, I am not saying all tags must be valid semver, I am merely stating that a valid semver should also be a valid tag.

There are some technical limitations on the Docker/Moby side, as the + character is not allowed. Hopefully ratifying the addition (upstream? downstream? not exactly sure of the politics here) will spur this along. The issue has been open for 5 years with no progress.

https://semver.org https://github.com/docker/distribution/issues/1201 https://github.com/docker/distribution/pull/1202#issuecomment-160761964

[hallyn]

Sorry, could you point to where in the spec.md right now the supported tags are enumerated? I took a quic klook but did not find it.

[JeremyLoy]

I don’t believe it’s defined at all. I’m hoping that this issue will track the inclusion of the tag specification, and that it should allow for semver strings.

[amouat]

This is a good point, but maybe the title is a bit misleading - what you're really asking is that tags support the "+" character, right?

[JeremyLoy]

Yes and no. Lack of support for the + character is a limitation of Docker/Moby. With that sole modification, it’s possible for a Docker tag to be a valid semver string.

This issue is really two fold

1. define what a valid tag is for OCI compliance
2. suggesting that the tag specification allows for semver strings

Right now since there is no specification, nothing is preventing an implementation that lacks support for . or v etc.

[JeremyLoy]

I guess a better title would be “define a specification for tags” I’ll make it so

[amouat]

To gather more context, the image spec does talk a little about tags. In particular note that https://github.com/opencontainers/image-spec/blob/e562b04403929d582d449ae5386ff79dd7961a11/image-layout.md#indexjson-file mentions

A common use case of descriptors with a "org.opencontainers.image.ref.name" annotation is representing a "tag" for a container image

The description for this annotation is intriguing:

org.opencontainers.image.ref.name Name of the reference for a target (string).

SHOULD only be considered valid when on descriptors on index.json within image layout.
Character set of the value SHOULD conform to alphanum of A-Za-z0-9 and separator set of -._:@/+
The reference must match the following grammar:

ref       ::= component ("/" component)*
component ::= alphanum (separator alphanum)*
alphanum  ::= [A-Za-z0-9]+
separator ::= [-._:@+] | "--"

https://github.com/opencontainers/image-spec/blob/master/annotations.md

I don't really follow the intent of this at all. It seems to be representing the full image name, including repo, rather than just the "tag" as it allows "components" and the ':' character. This more or less contradicts the first link.

And it gets even stranger if you consider that "middle" components can validly contain things like ":" e.g. myrepo:something/mytag:1.0. (I wonder if that's to allow myrepo:8443/bla/bla/name:tag)

[dmcgowan]

@JeremyLoy the original issue was stalled not on politics, but rather a full assessment done on the impact and a recommendation for how to change the spec. It is related to + as that has special meaning during the interpretation of the URL. Clients and servers must account for this otherwise tags will get rejected or confused by containing spaces or '%' characters. It may be possible to move forward with this by defining how it should be interpreted in the specification and tested for in the conformance testing. If we moved forward with defining a strict definition of a tag for 1.0 without this effort, then + would not be a part of it and make semver forever backwards incompatible with 1.0. So I would change the definition to mention this is about supporting +, I assume a strict definition is not what you want unless someone is going to volunteer to champion the + support :smile: