From 8d87d35e1d3210bef925ec72cb4e70278354a29a Mon Sep 17 00:00:00 2001 From: Jeff Carter Date: Thu, 26 Jun 2025 12:12:22 -0400 Subject: [PATCH 1/2] Initial PR to propose updates to tag listing Signed-off-by: Jeff Carter --- spec.md | 44 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 8d57a188..740dd196 100644 --- a/spec.md +++ b/spec.md @@ -559,10 +559,52 @@ The tags MUST be in lexical order. When using the `last` query parameter, the `n` parameter is OPTIONAL. +Registries MAY support an enhanced tag listing experience when clients pass an `Accept` header value of +`application/vnd.oci.image.index.v1+json`. If a registry supports this mode, they MUST support these additional query parameters: +* `sort_by` - allowed values are `created_at`, `name` +* `sort_order` - allowed values are `asc` and `desc` + +The response MUST be a json body in the following format: +```json +{ + "schemaVersion": 2, + "mediaType": "application/vnd.oci.image.index.v1+json", + "manifests": [ + { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "size": 1234, + "digest": "sha256:a1a1a1...", + "annotations": { + "org.opencontainers.image.ref.created": "2022-01-01T14:42:55Z", + "org.opencontainers.image.ref.name": "" + } + }, + { + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "size": 1234, + "digest": "sha256:a2a2a2...", + "annotations": { + "org.opencontainers.image.ref.created": "2022-01-01T07:21:33Z", + "org.opencontainers.image.ref.name": "" + } + } + ] +} +``` +The following annotations MUST be included: +* `org.opencontainers.image.ref.created` - Date and time the reference was created (date-time string as defined by RFC 3339). If unknown, default to epoch. +* `org.opencontainers.image.ref.name` - Reference name of the manifest. + +The following annotations MAY be included: +* `org.opencontainers.image.created` - Date and time on which the image was built (date-time string as defined by RFC 3339). +* `org.opencontainers.image.pull.count` - Number of times the image has been pulled from the registry. +* `org.opencontainers.image.pull.timestamp` - Date and time on which the image was last pulled from the registry. + _Implementers note:_ Previous versions of this specification did not include the `Link` header. Clients depending on the number of tags returned matching `n` may prematurely stop pagination on registries using the `Link` header. -When available, clients should prefer the `Link` header over using the `last` parameter for pagination. +When available, clients should prefer the `Link` header over using the `last` parameter for pagination. If using enhanced +tag listing, the `Link` header MUST be provided. ##### Listing Referrers From c290a0a2f843a90e8489dc6e0993a504096e7715 Mon Sep 17 00:00:00 2001 From: Jeff Date: Fri, 27 Jun 2025 17:37:28 -0400 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Brandon Mitchell Co-authored-by: Tianon Gravi Signed-off-by: Jeff --- spec.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/spec.md b/spec.md index 740dd196..2374403f 100644 --- a/spec.md +++ b/spec.md @@ -559,8 +559,9 @@ The tags MUST be in lexical order. When using the `last` query parameter, the `n` parameter is OPTIONAL. -Registries MAY support an enhanced tag listing experience when clients pass an `Accept` header value of -`application/vnd.oci.image.index.v1+json`. If a registry supports this mode, they MUST support these additional query parameters: +Registries MAY support an enhanced tag listing experience when clients pass an `Accept` header value of `application/vnd.oci.image.index.v1+json`. +If a registry supports this mode, they MUST set the `Content-Type: application/vnd.oci.image.index.v1+json` header. +Registries supporting the enhanced tag list MUST support these additional query parameters: * `sort_by` - allowed values are `created_at`, `name` * `sort_order` - allowed values are `asc` and `desc` @@ -593,7 +594,7 @@ The response MUST be a json body in the following format: ``` The following annotations MUST be included: * `org.opencontainers.image.ref.created` - Date and time the reference was created (date-time string as defined by RFC 3339). If unknown, default to epoch. -* `org.opencontainers.image.ref.name` - Reference name of the manifest. +* `org.opencontainers.image.ref.name` - Name of the tag. The following annotations MAY be included: * `org.opencontainers.image.created` - Date and time on which the image was built (date-time string as defined by RFC 3339). @@ -603,8 +604,8 @@ The following annotations MAY be included: _Implementers note:_ Previous versions of this specification did not include the `Link` header. Clients depending on the number of tags returned matching `n` may prematurely stop pagination on registries using the `Link` header. -When available, clients should prefer the `Link` header over using the `last` parameter for pagination. If using enhanced -tag listing, the `Link` header MUST be provided. +When available, clients should prefer the `Link` header over using the `last` parameter for pagination. +If using enhanced tag listing, clients MUST use the `Link` header for pagination. ##### Listing Referrers