index-template.md

OCI Index Template Protocol

This is version 1 of this specification.

The index-template protocol is configured via a single URI Template. When configured via a refEngines entry, the uri property MUST be set, and its value is the URI Template.

Consumers MUST provide at least the following variables:

• name, matching host-based-image-name in the host-based-image-name rule.
• host, matching host in the host-based-image-name rule.
• path, matching path-rootless in the host-based-image-name rule.
• fragment, matching fragment in the host-based-image-name rule. If fragment was not provided in the image name, it defaults to an empty string.

and expand the URI Template as defined in RFC 6570 section 3. If the expanded URI reference is a relative reference, it MUST be resolved following RFC 3986 section 5.

The server providing the expanded URI MUST support requests for media type application/vnd.oci.image.index.v1+json. Servers MAY support other media types using HTTP content negotiation, as described in RFC 7231 section 3.4 (which is also supported over HTTP/2).

Consumers retrieving application/vnd.oci.image.index.v1+json SHOULD process it like a layout's index.json, respecting org.opencontainers.image.ref.name and other annotations which are recommended for index.json.

Example

An example refEngines entry using the registered oci-index-template-v1 protocol identifier is:

{
  "protocol": "oci-index-template-v1",
  "uri": "https://{host}/ref/{host}/{path}"
}

An image name like a.b.example.com/c/d#1.0 matches host-based-image-name with a.b.example.com as host, c/d as path-rootless, and 1.0 as fragment so the expanded URI is:

https://a.b.example.com/ref/a.b.example.com/c/d

Retrieving that URI (with a pretend result, since example.com is reserved):

$ curl -H 'Accept: application/vnd.oci.image.index.v1+json' https://a.b.example.com/ref/a.b.example.com/c/d
{
  "schemaVersion": 2,
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 799,
      "digest": "sha256:e9770a03fbdccdd4632895151a93f9af58bbe2c91fdfaaf73160648d250e6ec3",
      "platform": {
        "architecture": "ppc64le",
        "os": "linux"
      },
      "annotations": {
        "org.opencontainers.image.ref.name": "1.0"
      },
      "casEngines": [
        {
          "protocol": "oci-cas-template-v1",
          "uri": "https://a.example.com/cas/{algorithm}/{encoded:2}/{encoded}"
        }
      ]
    },
    {
      "mediaType": "application/xml",
      "size": 7143,
      "digest": "sha256:b3d63d132d21c3ff4c35a061adf23cf43da8ae054247e32faa95494d904a007e",
      "annotations": {
        "org.freedesktop.specifications.metainfo.version": "1.0",
        "org.freedesktop.specifications.metainfo.type": "AppStream"
      },
      "casEngines": [
        {
          "protocol": "oci-cas-template-v1",
          "uri": "https://b.example.com/cas/{algorithm}/{encoded}"
        }
      ]
    }
  ]
}

The oci-cas-template-v1 protocol is registered.

Deciding whether to look for 1.0 (the fragment) or the full a.b.example.com/c/d#1.0 name is left as an exercise for the reader, as is switching based on platform entries or chosing between multiple entries with the same name.