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
, matchinghost-based-image-name
in thehost-based-image-name
rule.host
, matchinghost
in thehost-based-image-name
rule.path
, matchingpath-rootless
in thehost-based-image-name
rule.fragment
, matchingfragment
in thehost-based-image-name
rule. Iffragment
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
.
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.