Referrers spec feedback
Closed this issue · 1 comments
(First off: Feel free to ask me to open separate issues for these, I wasn't sure whether spamming issues would be less disruptive than opening one laundry list issue.)
(Also: Apologies in advance if these issues have already been discussed and resolved, if there are links to discussions where these have already been hashed out I'm happy to go read those instead)
I've read through the referrers spec proposal (this specific version, for future readers), and have some feedback I thought I'd share, with the goal of clarifying/generalizing the spec, and toward making it easier to propose and accept into distribution-spec when the time comes.
Example media types
I'd suggest not explicitly referring to any specific real-world artifact type, e.g., Notary v2 signatures. When references are successful and prevalent we expect a lot of referencing artifact types to exist, and we don't want to make it seem like the spec is preferring or omitting one or another.
Instead, you can use some clearly-example-text artifact type (e.g., "application/vnd.com.example.signature") as a clearer placeholder value.
Similarly, I'd omit the aside "such as a Notary v2 client", with the same reasoning.
In a similar vein, the artifacts spec also lists example media types at https://github.com/opencontainers/artifacts/blob/master/artifact-authors.md#example-layer-types
I'm not sure the spec repo is a good place to list example media types. The list will by definition be incomplete, and having some included while others aren't, even ordering them non-alphabetically, can make it seem like the spec is preferring one type of artifact over another.
There have been examples in the OCI specs where an example media type can be confused to refer to a real expected value, confusing readers and implementors. We should take steps to avoid this confusion in new specs.
Paging
The proposal for pagination is at https://github.com/oras-project/artifacts-spec/blob/main/manifest-referrers-api.md#paging-results
It specifies consulting the Link rel="next" response header, which should be consider opaque (RFC5988 FTW).
distribution-spec's pagination is described at https://github.com/opencontainers/distribution-spec/blob/main/spec.md#content-discovery
distribution-spec specifies the parameters &n= and &last=<tagname> specifically, and except for specifying that implementations MUST NOT include a Link header when there are no more items, makes no mention of the Link rel="next" header or RFC5988 at all (though some registry implementations might use it; I don't know)
While I agree that leveraging RFC5988 is definitely better, I think consistency with the rest of distribution-spec is paramount. We don't want registry clients or implementations to have to implement two pagination flows, even if the new one is obviously better.
The proposal could instead suggest ("SHOULD") that registries fully leverage RFC5988, for both referrers and traditional tag listing. This SHOULD amendment could be proposed against distribution-spec today, separate from this proposal, probably contingent on a survey of registry implementations in the wild to see how they stack up.
If distribution-spec moves to suggest/SHOULD RFC5988 then perhaps the referrers API could require/MUST it, since it's a new API, but I wouldn't want to leave room for registries to have to support two pagination schemes, or for clients to have to negotiate or navigate them.
Filtering
distribution-spec doesn't currently have any concept of filtering list results.
While I definitely agree that filtering is useful, especially since we expect potentially many artifacts referring to an image, and since we'd prefer to have one interface of that clearly specified for compatibility, I'd suggest it might be easier to put a pin filtering for now to remove one more area of conversation and potential disagreement, and come back to address it after the bulk of the proposal has been ironed out and accepted into distribution-spec.
This should also lead to less churn and work for you if there are other changes to artifact types suggested, since you won't have to update the filtering specification to match those changes.
Slight typo: vnd.org.cncf....
In filtering examples, you reference the artifact type application/vnd.org.cncf.notary.v2. I think you mean to use application/vnd.cncf.notary.v2 (no org.), since this makes it seem like it's a reverse-domain-name scheme referring to cncf.org which is unaffiliated with the CNCF (https://cncf.io).
This is moot if filtering is pinned for later, or if specific example media types are removed, but in case those don't come to pass, we should fix the typo.