Docker image tag spec is ambiguous

[pbrisbin]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

I can't find what I'm looking for

Description

The documented format for an image tag is,

[HOST[:PORT_NUMBER]/]PATH[:TAG]

Along with,

PATH: The path consists of slash-separated components. Each component may contain lowercase letters, digits and separators. A separator is defined as a period. ...

This is ambiguous and it seems impossible to write a parser for it. There are two equally valid ways to parse: quay.io/namespace/image:tag

1. HOST=quay.io, PATH=namespace/image, TAG=tag
2. HOST=, PATH=quay.io/namespace/image, TAG=tag

Location

https://docs.docker.com/reference/cli/docker/image/tag/#extended-description

Suggestion

I'd like to see the documentation for this format updated and expanded to be more precise and comprehensive, such that it is unambiguous how to parse such an example.

[thaJeztah]

You can find the reference format in the CNCF Distribution org; https://github.com/distribution/reference

The Go documentation is a good starting point; https://pkg.go.dev/github.com/distribution/reference

w.r.t. ambiguity between "host" or "path"; the first element is considered a hostname if it contains a period; there's also a special case for localhost.

[pbrisbin]

Ah thanks for pointing me in the right direction. Could this still be considered a docs bug (or feature-request) to link to those locations and/or include the tidbits about period and localhost?

[thaJeztah]

Probably "both" 😅

I think the current simplified way of presenting the format in the docs was (somewhat) intentional, to not overwhelm the user, and for "most" cases it did the job.

That said, this part of the docs is pretty old, and I think a bit of a refresh with a bit more detail (and examples) won't hurt.

A link to the reference repo documentation (for those that need the full details) definitely won't be out of place.

The format definitely has its fair share of "quirks"; the format organically grew from the early beginnings of Docker when there was only 1 registry (the "docker index") and originally only 10 images maintained by Docker, so there was no ambiguity.

Once the docker index was opened up for users to push their images, namespaces were introduced ("yourname/yourimage:latest"), and to keep backward compatibility, the official images (e.g. ubuntu) got an implicit namespace (library/ubuntu).

And finally, when the registry code was open-sourced to allow running your own registry, the format was extended to allow a host[:port] (with an implied docker.io/, to preserve compatibility with the existing references)

So, yes, so some quirks were needed for this! There was no formal specification (the implementation was the spec), and I don't think anyone at the time anticipated how popular containers would become 🙈

[pbrisbin]

Yeah, it definitely makes sense to keep it simple in this context. I think you could present something even simpler, provided the link to the reference repo was added. Currently, the docs are a straddling the line in a bit of a worst-of-both-worlds way, they look like they're being precise, but they aren't -- and then there's no link for someone who just wants the grammar anyway 😂