Skip to main content

Coordinates

Coordinates are used for referring to and identifying images.

As opposed to Docker coordinates, BatchX coordinates are monomorphic (can only be expressed in a single way) and uniquely identify an image.

Using BNF notation, BatchX coordinates are defined as:

<bathx-coordinates> ::= <base-name> ":" <version>
<base-name> ::= <environment> "@" <name>
  • environment: Environment the image has been imported into.
  • name: Image name, as specified in the image manifest.
  • version: Semantic core version of the image, as specified in the image manifest.

Coordinates are partially defined (name and version) by the image manifest, and fully qualified during the import process (by the id of the active environment).

Examples:

  • batchx@tutorial/hello-world:1.0.1
  • batchx@tutorial/word-count:1.0.1
  • batchx@tutorial/word-count:0.0.1

Base name

Images with the same base name (whose coordinates differ only in their version) are considered different versions of the same asset.

Even though each image is independent, base names are relevant in the following way:

  • By default, image listing only shows latest major versions for a given base name.
  • Some platform features operate on all versions at once, like image deletion.

Examples:

  • batchx@tutorial/hello-world
  • batchx@tutorial/word-count

Environment

Images belong to the environment they are imported into, and this is reflected in their coordinates.

Name

Image name is defined by the image author in the image manifest.

Semantic versioning

Image version is defined by the author in the manifest according to the following format:

<version> ::= <major> "." <minor> "." <patch>

being major, minor and patch integer values.

Additionally, version values have semantic connotations, as defined in the SemVer specification:

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards compatible manner, and
  3. PATCH version when you make backwards compatible bug fixes.

These rules help image users understanding the implications of upgrading the version of an image dependency.

Example:

Suppose that a colleague has created two images and imported them into a shared environment:

  • my-org@foo:0.0.1
  • my-org@bar:0.0.1

Also, suppose you have created a script that links these images into a workflow, so the output of foo is used as the input of bar. Obviously this script is suited to the specific semantics and behavior of my-org@foo:0.0.1 and my-org@bar:0.0.1.

Now, after some time, you come back and realize that these images have been improved and new versions are available:

  • my-org@foo:0.1.1
  • my-org@foo:0.1.0
  • my-org@foo:0.0.2
  • my-org@foo:0.0.1
  • my-org@bar:1.0.1
  • my-org@bar:1.0.0
  • my-org@bar:0.0.1

Semantic versioning helps you understanding what would be the latest versions you could use in your script without requiring any other change in it (keeping backwards compatibility).

If the image author would had followed the semantic rules, you could expect your script keep working when upgrading to my-org@foo:0.1.1 (latest backwards-compatible version). Notice though that for my-org@bar, you only have available newer versions with different major, meaning that the image contract has changed somehow, and your script might need to be changed accordingly.