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 :ref:`jsonschema_product`.