Initial PR to propose updates to tag listing #579

jcarter3 · 2025-06-26T16:12:31Z

Motivation:
Provide registry agnostic mechanism to get new tags

Related to discussions at:

jcarter3 · 2025-06-26T16:54:56Z

spec.md

+      "mediaType": "application/vnd.oci.image.manifest.v1+json",
+      "size": 1234,
+      "digest": "sha256:a2a2a2...",
+      "annotations": {


Note: This will not contain all annotations specified on the manifest

Signed-off-by: Jeff Carter <[email protected]>

jcarter3 · 2025-06-26T19:01:22Z

spec.md

+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`


A future update can include some sort of filter option, but has been left out for now.

qweeah · 2025-06-27T01:01:42Z

spec.md

+      "digest": "sha256:a1a1a1...",
+      "annotations": {
+        "org.opencontainers.image.ref.created": "2022-01-01T14:42:55Z",
+        "org.opencontainers.image.ref.name": "<tag1>"


If a manifest has more than one tags attached, would it be more efficient to merge all the tags into one entry here?

It'd be more efficient, yes. But then it makes it harder to pass back a separate created timestamp for each, plus it'd mess up the ordering. If this was a manifest list, it'd make sense to merge the tags, but for a tag listing, it's easier to keep them separate

Wwwsylvia · 2025-06-27T02:36:10Z

spec.md

+        "org.opencontainers.image.ref.created": "2022-01-01T14:42:55Z",
+        "org.opencontainers.image.ref.name": "<tag1>"


Do these annotations originate from the original manifest data, or are they generated by the registry and added to the descriptors? 🤔

If they come from the manifest data, how does the API handle manifests that do not contain these annotations?

If they are generated by the registry, how does the API manage potential conflicts between the manifest annotation values and the registry-recorded values, such as creation time?

They are generated by the registry. The registry may optionally include other annotations, including those from the manifest if it chooses.

For conflicts, there shoudn't be any. The ...image.ref.* tags are specific to a reference, not to a manifest - As in, a manifest shouldn't include an annotation of the reference it will be tagged with after it's pushed. Though maybe there is some weird edge case where this happens 🤔

But also, relevant to #579 (comment), if a registry chooses to "pull up" annotations from the manifest, it should do so before setting those specified by this API, because they're defined to have a particular meaning in this context (so "pulling up" the annotations from the manifest will be limiting to future changes of this API).

sudo-bmitch

We need to add conformance tests, and get some example implementations.

Edit to add: if we add more sort orders or filters in the future, how would the client know if they were applied or if the registry only supports the first iteration of these features?

sudo-bmitch · 2025-06-27T17:38:56Z

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`


Linting nit, add white space line between bulleted list and the preceding paragraph.

sudo-bmitch · 2025-06-27T17:39:27Z

spec.md

+* `sort_order` - allowed values are `asc` and `desc`
+
+The response MUST be a json body in the following format:
+```json


Linting nit, add whitespace line between code block and paragraph.

sudo-bmitch · 2025-06-27T17:39:58Z

spec.md

+  ]
+}
+```
+The following annotations MUST be included:


Linting nit, add whitespace line here too for the code block.

spec.md

Co-authored-by: Brandon Mitchell <[email protected]> Co-authored-by: Tianon Gravi <[email protected]> Signed-off-by: Jeff <[email protected]>

shizhMSFT · 2025-07-01T07:14:42Z

spec.md

+}
+```
+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.


A resource usually has two timestamps: one for creation and another for modification. For example, tag v1 is created on 2022-01-01T07:21:33Z and later re-tagged on 2022-02-03T08:21:21Z. Do you want to introduce a new annotation for the modification / update time?

I'd say this could be an optional value added by registries, but we can specify an annotation for it. Some registries may not have this information, and it might be of little value (it wouldn't give a history) on it's own.

shizhMSFT · 2025-07-01T07:16:50Z

spec.md

+* `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:


Just a note: This example response looks like an index.json in the OCI image layout, which serves as a tag list or generally a manifest list.

That's entirely intentional, and even why it's reusing the annotation that's "only for index.json" 😅

Reusing the "image index" structure for this also matches the design of the referrers API, which is a useful pattern because it avoids defining "yet another data schema" without a really strong reason.

jcarter3 force-pushed the update_tag_listing branch 4 times, most recently from 3b61226 to c50655b Compare June 26, 2025 16:37

jcarter3 marked this pull request as ready for review June 26, 2025 16:40

jcarter3 requested review from dmcgowan, jzelinskie, jonjohnsonjr, jdolitsky, mikebrow, stevvooe and sudo-bmitch as code owners June 26, 2025 16:40

jcarter3 commented Jun 26, 2025

View reviewed changes

Initial PR to propose updates to tag listing

8d87d35

Signed-off-by: Jeff Carter <[email protected]>

jcarter3 force-pushed the update_tag_listing branch from c50655b to 8d87d35 Compare June 26, 2025 19:00

jcarter3 commented Jun 26, 2025

View reviewed changes

qweeah reviewed Jun 27, 2025

View reviewed changes

Wwwsylvia mentioned this pull request Jun 27, 2025

oras repo tags table output with option to sort by tag creation date oras-project/oras#1747

Open

1 task

Wwwsylvia reviewed Jun 27, 2025

View reviewed changes

sudo-bmitch requested changes Jun 27, 2025

View reviewed changes

Apply suggestions from code review

c290a0a

Co-authored-by: Brandon Mitchell <[email protected]> Co-authored-by: Tianon Gravi <[email protected]> Signed-off-by: Jeff <[email protected]>

shizhMSFT reviewed Jul 1, 2025

View reviewed changes

jdolitsky mentioned this pull request Jul 2, 2025

Add optional tagType query param to tags list endpoint #568

Closed

sudo-bmitch mentioned this pull request Aug 17, 2025

Proposal: search repository and filter by ordered property, prune by ordered property #584

Open

sudo-bmitch mentioned this pull request Aug 25, 2025

[Feature] regctl tag list --order-by newest regclient/regclient#982

Open

		"org.opencontainers.image.ref.created": "2022-01-01T14:42:55Z",
		"org.opencontainers.image.ref.name": "<tag1>"

Initial PR to propose updates to tag listing #579

Are you sure you want to change the base?

Initial PR to propose updates to tag listing #579

Conversation

jcarter3 commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qweeah Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sudo-bmitch left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jcarter3 commented Jun 26, 2025 •

edited

Loading

qweeah Jun 27, 2025 •

edited

Loading

sudo-bmitch left a comment •

edited

Loading