Skip to content

Support referrers responses in the Image Layout #1171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Support referrers responses in the Image Layout #1171

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions annotations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,9 @@ This specification defines the following annotation keys, intended for but not l
- This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile `FROM` statement.
- This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds).
- If the `image.base.name` annotation is specified, the `image.base.digest` annotation SHOULD be the digest of the manifest referenced by the `image.ref.name` annotation.
- **org.opencontainers.image.referrer.subject** Digest of the subject referenced by the referrers response (string)
- This SHOULD only be considered valid when on descriptors on `index.json` within [image layout](image-layout.md).
- The descriptor SHOULD be the referrers response for the subject digest.
Comment on lines +56 to +58
Copy link
Member

@tianon tianon Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at this with fresh eyes, I'm much more strongly -1 on this specific annotation unless it's for pulling up the subject field of the manifest we're listing.

For the use case you've described (having the "registry view" referrers response object as part of the image layout), that would be more obviously annotated by setting org.opencontainers.image.ref.name to the fallback tag format, which would have the same fidelity as the proposed new field (with the added benefit that it could/would be per-"name" instead of per-digest, because referrers are technically scoped to a namespace just like manifests are, and would make conversions to/from the fallback automatic and transparent and even trivial to support querying in both ways with a consistent view).

Copy link
Contributor Author

@sudo-bmitch sudo-bmitch Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Making the annotation point to the same content as the fallback tag pointed to was intentional, just as the registry referrers response should look just like a manifest get to the fallback tag. One key advantage of not using the fallback tag is getting rid of the tags in the tag listing.

I can convert my implementations to use an annotation of the individual artifacts, but it's going to be a lot more code to write, without the reuse of the existing fallback tag code. I'd be curious to know how many of the projects looking to store these as individual entries in the top level index.json have also implemented the fallback tag logic in addition to the referrers query logic in their code.

Copy link
Member

@tianon tianon Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know I certainly have not, and have no intention to (for my uses, the fallback tag as a solution is completely dead on arrival; if we don't have referrers support in the registry, I just won't use them at all).


## Back-compatibility with Label Schema

Expand Down
15 changes: 14 additions & 1 deletion image-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,10 @@ For example, an image may have a tag for different versions or builds of the sof
In the wild you often see "tags" like "v1.0.0-vendor.0", "2.0.0-debug", etc.
Those tags will often be represented in an image-layout repository with matching "org.opencontainers.image.ref.name" annotations like "v1.0.0-vendor.0", "2.0.0-debug", etc.

**Referrers Support:**
Manifests included in an OCI Layout that contain a `subject` field SHOULD be listed in a [referrers response][referrers-response].
The referrers response is then saved as a blob and listed in the `index.json` with the media type set to `application/vnd.oci.image.index.v1+json` and the annotation `org.opencontainers.image.referrer.subject` set to the `subject` digest value.

### Index Example

```json,title=Image%20Index&mediatype=application/vnd.oci.image.index.v1%2Bjson
Expand Down Expand Up @@ -195,6 +199,14 @@ Those tags will often be represented in an image-layout repository with matching
"org.freedesktop.specifications.metainfo.version": "1.0",
"org.freedesktop.specifications.metainfo.type": "AppStream"
}
},
{
"mediaType": "application/vnd.oci.image.index.v1+json",
"size": 7143,
"digest": "sha256:1efe7ab979c486a5af7a29d2c4603d84a3b934a7253d61b37e8573afecf47c03",
"annotations": {
"org.opencontainers.image.referrer.subject": "sha256:0228f90e926ba6b96e4f39cf294b2586d38fbb5a1e385c05cd1ee40ea54fe7fd"
}
}
],
"annotations": {
Expand All @@ -206,8 +218,9 @@ Those tags will often be represented in an image-layout repository with matching
This illustrates an index that provides two named references and an auxiliary mediatype for this image layout.

The first named reference (`stable-release`) points to another index that might contain multiple references with distinct platforms and annotations.
Note that the [`org.opencontainers.image.ref.name` annotation](annotations.md) SHOULD only be considered valid when on descriptors on `index.json`.
Note that the [`org.opencontainers.image.ref.name` and `org.opencontainers.image.referrer.subject` annotations](annotations.md) SHOULD only be considered valid when on descriptors on `index.json`.

The second named reference (`v1.0`) points to a manifest that is specific to the linux/ppc64le platform.

[descriptors]: ./descriptor.md
[referrers-response]: https://github.com/opencontainers/distribution-spec/blob/v1.1.1/spec.md#listing-referrers
5 changes: 5 additions & 0 deletions specs-go/v1/annotations.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,4 +59,9 @@ const (

// AnnotationBaseImageName is the annotation key for the image reference of the image's base image.
AnnotationBaseImageName = "org.opencontainers.image.base.name"

// AnnotationReferrerSubject is the annotation key for the digest of the subject referenced by the referrers response.
// This SHOULD only be considered valid when on descriptors on `index.json` within image layout.
// The descriptor SHOULD be the referrers response for the subject digest.
AnnotationReferrerSubject = "org.opencontainers.image.referrer.subject"
)