Initial PR to propose updates to tag listing #579
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -559,10 +559,53 @@ 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 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` | ||
|
There was a problem hiding this comment. A future update can include some sort of filter option, but has been left out for now. |
||
|
|
||
| The response MUST be a json body in the following format: | ||
|
There was a problem hiding this comment. Just a note: This example response looks like an There was a problem hiding this comment. That's entirely intentional, and even why it's reusing the annotation that's "only for 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. |
||
| ```json | ||
|
There was a problem hiding this comment. Linting nit, add whitespace line between code block and paragraph. |
||
| { | ||
| "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": "<tag1>" | ||
|
There was a problem hiding this comment. If a manifest has more than one tags attached, would it be more efficient to merge all the tags into one entry here? There was a problem hiding this comment. 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
Comment on lines
+579
to
+580
There was a problem hiding this comment. Do these annotations originate from the original manifest data, or are they generated by the registry and added to the descriptors? 🤔
There was a problem hiding this comment. 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 There was a problem hiding this comment. 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). |
||
| } | ||
| }, | ||
| { | ||
| "mediaType": "application/vnd.oci.image.manifest.v1+json", | ||
| "size": 1234, | ||
| "digest": "sha256:a2a2a2...", | ||
| "annotations": { | ||
|
There was a problem hiding this comment. Note: This will not contain all annotations specified on the manifest |
||
| "org.opencontainers.image.ref.created": "2022-01-01T07:21:33Z", | ||
| "org.opencontainers.image.ref.name": "<tag2>" | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| The following annotations MUST be included: | ||
|
There was a problem hiding this comment. Linting nit, add whitespace line here too for the code block. |
||
| * `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. | ||
|
There was a problem hiding this comment. A resource usually has two timestamps: one for creation and another for modification. For example, tag There was a problem hiding this comment. 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. |
||
| * `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). | ||
| * `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. | ||
| If using enhanced tag listing, clients MUST use the `Link` header for pagination. | ||
|
|
||
| ##### Listing Referrers | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Linting nit, add white space line between bulleted list and the preceding paragraph.