Working group for Reference Spec

[sudo-bmitch]

I'd like to propose a new working group to create a reference-spec that would define a reference in OCI. At present, this is just a convention, originated by Docker, where alpine gets mapped to docker.io/library/alpine:latest (where docker.io isn't even the real registry name). There is currently an implementation for this in distribution/distribution that many have used. I believe it would be useful for OCI to formalize this, and even include a Go implementation.

Other use cases I can think of (or have seen):

• OCI Layout
• Immutable Tags
• Alternate layer formats like eStargz
• Querying for an artifact that refers another manifest (see wg-reference-types for more details)

Signed-off-by: Brandon Mitchell [email protected]

[AkihiroSuda]

Does this cover the reference string for local OCI archives?

[sudo-bmitch]

Is that OCI Image Layout? I've updated this with a link to make it clear that's what I meant by OCI Layout.

[sudo-bmitch]

We discussed this during the OCI meeting at KubeCon today and decided it makes more sense to add this to image-spec instead of a separate repo. I'm closing this and we can coordinate with PR's to image-spec.
https://hackmd.io/nZzK_4AfRz-xgya6KkqseA

[sudo-bmitch]

Reopening to continue the discussion from the mailing list: https://groups.google.com/a/opencontainers.org/g/dev/c/PpzsQMOnda4

cc @vbatts @Jamstah @sajayantony

[sajayantony]

Thanks for reopening this @sudo-bmitch. I think clarifying meaning of reference in distribution and OCI layout is valuable since parsing that regex depending on context and language choice would make it easier if there was a clear definition in image spec (on which distribution indirectly depends on anyway). e.g. write up (but doesn't include the regex) - https://oras.land/docs/concepts/reference

[harche]

cc @lumjjb

[Jamstah]

There's not a lot in the minutes explaining the decision to include it in image-spec, can anyone remember the reasoning?

Personally, I think defining references separately makes sense. The image spec as written is very cleanly encapsulated around what an image is and not where an image is. It also gives more flexibility for the future, if we need to refer to things other than images. Putting it in the image spec would also tie up the lifecycles, and I'm not sure that's a good thing.

[sudo-bmitch]

There's not a lot in the minutes explaining the decision to include it in image-spec, can anyone remember the reasoning?

I believe @imjasonh weighed in on that. The impression I got was that creating a new spec is more effort than extending an existing one, and they felt that image spec was the closest fit. Given that I originally opened this to create a new spec myself, I tend to agree with you that it doesn't feel like a great fit.

Personally, I think defining references separately makes sense. The image spec as written is very cleanly encapsulated around what an image is and not where an image is. It also gives more flexibility for the future, if we need to refer to things other than images. Putting it in the image spec would also tie up the lifecycles, and I'm not sure that's a good thing.

We've muddied the definition, particularly with defining the usage for artifacts, and the image layout. The spec also uses "image" for a lot of things that aren't necessarily an image, like the image index.

[Jamstah]

Linking my thoughts on what the spec could include here: https://github.com/Jamstah/reference-spec/blob/main/spec.md

[mtrmac]

I think such a codification of existing practice would make sense. (I’m a tiny bit worried about a separate spec working group finding opportunities to invent new features with little previous precedent.)

---

https://github.com/Jamstah/reference-spec/blob/main/spec.md
Worth referencing different transports? Even if it's just to say they exist and are client specific?

(As the maintainer of the linked Skopeo tool), at best as a warning. Strings are notoriously ambiguous. IMHO every string field / syntax should strictly define whether it is an “image reference” in the sense of the rest of that text, or a transport:… string.

E.g. consider dir:foo. That could be Skopeo’s docker:https://docker.io/library/dir:foo when interpreted by Docker CLI, or it could be Skopeo’s dir:$(pwd)/foo when interpreted as a transport:… syntax. Hence Skopeo requires the user to always include a transport (OTOH Podman does rely on heuristics).

Accepting both syntaxes in the same field forces the consumer to resort to heuristics to disambiguate. And while it would certainly be more useful for every software to use the same heuristics, it seems to me to be very hard to design and standardize heuristics that will stand the test of time, as other registry features, and new c/image transports (or transports in other image codebases?), are added.