Question: What is the correct value for the "OCI-Filters-Applied" header?

[Wwwsylvia]

I have a question about the "Listing Referrers" section of the distribution-spec v1.1.0-rc3, which states that:

The registry SHOULD support filtering on artifactType. To fetch the list of referrers with a filter, perform a GET request to a path in the following format: /v2//referrers/?artifactType= end-12b. If filtering is requested and applied, the response MUST include a header OCI-Filters-Applied: artifactType denoting that an artifactType filter was applied. If multiple filters are applied, the header MUST contain a comma separated list of applied filters.

Example request with filtering:

GET /v2/<name>/referrers/<digest>?artifactType=application/vnd.example.sbom.v1

Example response with filtering:

OCI-Filters-Applied: artifactType
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "size": 1234,
      "digest": "sha256:a1a1a1...",
      "artifactType": "application/vnd.example.sbom.v1",
      "annotations": {
        "org.opencontainers.artifact.created": "2022-01-01T14:42:55Z",
        "org.example.sbom.format": "json"
      }
    }
  ],
}

Question

From the above statement, it appears that the value of the OCI-Filters-Applied header should be a hard-coded string artifactType, rather than the concrete artifact type (such as application/vnd.example.sbom.v1 in this example).

However, the conformance test checks the concrete artifact type (application/vnd.example.sbom.v1 in this example) instead of the string artifactType. This seems to contradict the spec. https://github.com/opencontainers/distribution-spec/blob/42d2d6e60d8d989a61d33bbead61f93a1795b392/conformance/03_discovery_test.go#L323-L326

Could someone please help clarify what the correct value of the OCI-Filters-Applied header should be? Should it be the hard-coded string artifactType or the concrete artifact type?

Thank you!

[sudo-bmitch]

That's a bug in the conformance test, it should be the hard coded string.

[rchincha]

"If multiple filters are applied, the header MUST contain a comma separated list of applied filters."

^ this language seems to indicate that (in future probably) one could ask for "artifactType=A&artifactType=B..." etc and the response header returns what then?

If we were looking for a boolean, then just the presence of the header key should suffice?

[sudo-bmitch]

We haven't added additional filter types yet, but the note there is for clients to expect a comma separated list. In the future, there could be options to filter on annotation, sort, and limit the number of responses (e.g. return the most recent signature artifact signed by a given fingerprint).

Multiple artifactType parameters are not currently supported.

[rchincha]

I see, so the idea was to support multiple filter types? artifactType being one of them, maybe "annotation=X" is another. This would be a generally applicable interpretation across all endpoints.

Revisiting my earlier question for this specific endpoint, GET /v2//referrers/?artifactType=application/vnd.example.sbom.v1 one could ask for "artifactType=A&artifactType=B...", and you still expect "OCI-Filters-Applied: artifactType"?

[sudo-bmitch]

Revisiting my earlier question for this specific endpoint, GET /v2//referrers/?artifactType=application/vnd.example.sbom.v1 one could ask for "artifactType=A&artifactType=B...", and you still expect "OCI-Filters-Applied: artifactType"?

At present, that's undefined. I could see some registries applying both filters with either OCI-Filters-Applied: artifactType or even OCI-Filters-Applied: artifactType,artifactType. I could also see a registry applying a single filter. And a registry may be appropriate to return a 400 / bad request error. The safest is to probably apply no filters and not return a header, until a behavior is defined.

[Wwwsylvia]

Got it! Thanks @sudo-bmitch @rchincha for taking care of this!