diff --git a/spec.md b/spec.md index 8d57a188..2374403f 100644 --- a/spec.md +++ b/spec.md @@ -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` + +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` - 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