Skip to content

Docker Container (Image/Tag) Name Syntax

This document describes the syntax of a docker container name, an image name w/ or w/o tag or digest (supported since 0.0.64).

Created for the image name validation in pipelines and kept for reference and further improvements.

Syntax | Known Issues | Grammar | References

Syntax

The textual description is taken from the Docker documentation and following is a transposition into a more formal grammar similar to EBNF.

Encoding is US-ASCII; grammar at once.

   container             ::= image-name ( ":" tag-name | "@" digest )?

   /*  ":" ASCII 58 x3A colon        */

Image Name | Tag Name | Digest

Image Name

A container consists of the name of an image optionally followed by a tag or digest (both separated by a colon).

   image-name            ::= prefix? name-components
   prefix                ::= hostname port? "/"
   hostname              ::= [a-zA-Z0-9.-]+
   port                  ::= ":" [0-9]+

   /*  "/" ASCII 47 x2F slash        */
   /*  "-" ASCII 45 x2D dash         */

An image name is made up of slash-separated name components, optionally prefixed by a registry hostname.

The hostname must comply with standard DNS rules, but may not contain underscores.

If a hostname is present, it may optionally be followed by a port number in the format :8080.

If not present, the command uses Docker’s public registry located at registry-1.docker.io by default.

   name-components       ::= name-component ( "/" name-component )?
   name-component        ::= name ( name-separator name )*
   name                  ::= [a-z0-9]+
   name-separator        ::= ( "." | "_" "_"? | "-"+ )

   /*  "." ASCII 46 x2E period       */
   /*  "_" ASCII 95 x5F underscore   */

Name components may contain lowercase letters, digits and separators. A separator is defined as a period, one or two underscores, or one or more dashes. A name component may not start or end with a separator.

Tag Name

A tag name must be valid ASCII and may contain lowercase and uppercase letters, digits, underscores, periods and dashes. A tag name may not start with a period or a dash and may contain a maximum of 128 characters.

   tag-name              ::= tag-start tag-follow{0,127}
   tag-start             ::= [a-zA-Z0-9_]
   tag-follow            ::= tag-start | [.-]

Digest

In pipelines the digest is first of all supported to allow docker to fetch container images from docker-hub by content / collision-resistant hash of the bytes (the digest) and not by tag (only; tags are not stable).

Image with:

  • Tag: ktomk/pipelines:busybox
  • Digest: ktomk/pipelines@sha256:2ef9a59041a7c4f36001abaec4fe7c10c26c1ead4da11515ba2af346fe60ddac

In practice the SHA-256 is in use by all compliant implementations (this is Open Container Interface (OCI) material).

   digest                ::= algorithm ":" encoded
   algorithm             ::= algorithm-component (algorithm-separator algorithm-component)*
   algorithm-component   ::= [a-z0-9]+
   algorithm-separator   ::= [+._-]
   encoded               ::= [a-zA-Z0-9=_-]+

   /*  "=" ASCII 61 x3D equals-sign  */

Known Issues

  • The hostname part is not RFC conform (also depending on which RFC) and has not yet been double checked with standard DNS rules.

  • The digest part currently only verifies per the grammar for forward compatibility. No constraint is made on validation on the algorithm component for example.

Often this level of specific is not needed for pipelines so prone to errors apart of the validation itself. Image/container names are passed to docker(1) which might then unable to pull an image even if the regular expression based validation in the pipelines utility did let it pass as valid. Double check the hostname and the digest then.

Grammar

For field formats described in this document, we use a limited subset of Extended Backus-Naur Form[EBNF], similar to that used by the XML specification[XML-EBNF].

Encoding is US-ASCII.

   container             ::= image-name ( ":" ( tag-name | digest ) )?

   image-name            ::= prefix? name-components

   prefix                ::= hostname port? "/"
   hostname              ::= [a-zA-Z0-9.-]+
   port                  ::= ":" [0-9]+

   name-components       ::= name-comp ( "/" name-component )?
   name-component        ::= name ( name-separator name )*
   name                  ::= [a-z0-9]+
   name-separator        ::= ( "." | "_" "_"? | "-"+ )

   tag-name              ::= tag-start tag-follow{0,127}
   tag-start             ::= [a-zA-Z0-9_]
   tag-follow            ::= tag-start | [.-]

   digest                ::= algorithm ":" encoded
   algorithm             ::= algorithm-component (algorithm-separator algorithm-component)*
   algorithm-component   ::= [a-z0-9]+
   algorithm-separator   ::= [+._-]
   encoded               ::= [a-zA-Z0-9=_-]+

   /*  ":" ASCII 58 x3A colon        */
   /*  "/" ASCII 47 x2F slash        */
   /*  "-" ASCII 45 x2D dash         */
   /*  "." ASCII 46 x2E period       */
   /*  "_" ASCII 95 x5F underscore   */
   /*  "=" ASCII 61 x3D equals-sign  */

References