Product

A product file (eg. com.ubuntu.cloud:daily:download.sjson) is referenced by the index.json file via the index->content_id->path element. The product contains a content_id (eg. com.ubuntu.cloud:daily:download) and a list of products (eg. com.ubuntu.cloud.daily:server:24.04:riscv64). Each product has multiple versions and each version has multiple items. An item can be globally uniquely identified by the path to it. The content_id for a products list and the key in each element of the tree form a unique tuple of that item. That unique tuple is (content_id, product_name, version_name, item_name).

Fields

  • content_id: formed similarly to an ISCSI qualified name (IQN) It should have a reverse domain portion followed by a portion that represents a name underneath that domain.

  • product_name: product name is unique within a products list. The same product name may appear in multiple products lists. For example, in Ubuntu, server:noble:amd64 will appear in both products list com.ubuntu.cloud:released:aws and com.ubuntu.cloud:released:download. That name collision should imply that the two separate <content_id><product_name> pairs are equivalent in some manner.

  • version_name: A “version” of a product represents a release, build or collection of that product. A key in the “versions” dictionary should be sortable by rules of a ‘LANG=C sort()’. That allows the client to trivially order versions to find the most recent. Ubuntu uses “serial” numbers for these keys, in the format YYYYMMDD[.0-9].

  • item_name: Inside of a version, there may be multiple items. An example would be a binary build and a source tarball. For Ubuntu download images, these are things like .tar.gz, -disk1.img and -root.tar.gz. The item name does not need to be user-friendly. It must be consistent. Because this id is unique within the given version_name, a client needs only to store that key, rather than trying to determine which keys inside the item dictionary identify it.

  • item: this dictionary may contain a path element. path entries for a given item must be immutable. That is, for a given path under a mirror, the content must never change. A path value must be relative to the base of the mirror. If there’s a md5, sha256 or sha512 element next to a path element, the content referenced in path must have the given checksum(s). If there’s a size element next to a path element, the content referenced in path has the given size. An item dictionary may contain a ‘mirrors’ element. mirrors entries it used for supply a list of mirrors prefix where retrieve the item. When mirrors is present client must create the URL of the resource to fetch with the path entry.

There is also a JSON schema available. See Product jsonschema.