Skip to content

Commit

Permalink
spec: Clarify Referrers Tag Schema vs. alternative algorithms
Browse files Browse the repository at this point in the history
From the referenced OCI spec:

  digest                ::= algorithm ":" encoded
  algorithm             ::= algorithm-component (algorithm-separator algorithm-component)*
  algorithm-component   ::= [a-z0-9]+
  algorithm-separator   ::= [+._-]
  encoded               ::= [a-zA-Z0-9=_-]+

But from the distribution-spec:

  Throughout this document, `<reference>` as a tag MUST be at most 128 characters in length and MUST match the following regular expression:

  `[a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}`

Happily, the fist character of algorithm must match
algorithm-component, and its [a-z0-9] a subset ofthe tag regexp's
opening [a-zA-Z0-9_].  And the colon separating algorithm from encoded
was already addressed in the outgoing text.  But the digest definition
also allows + in the algorithm-separator and = in the encoded portion,
which the tag regexp does not allow, so with the incoming wording I'm
requiring that to be replaced by a - as well, so clients make
consistent choices when deciding how to handle that character while
forming distribution-spec referrer tags.

And I'm requiring clients to truncate the tag to 128 characters, again
so clients make consistent choices when trying to compress from the
strings the digest specification allows to the strings tags allow.
There is no requirement in the distribution spec as far as I can tell
that registries support tags up to 128 characters, but given that the
spec explicitly requires clients to not exceed that length, it seems
likely that registries will allow tags of that length, and not require
further truncation.

And clients are obviously free to create whatever tags they like that
the registry will accept.  The MUST I'm adding does not forbid that.
It only clarifies the single distribution-spec Referrers Tag
associated with a given digest, because if there could be multiple
Referrers Tag for each digest, all distribution-spec
referrer-retrieving clients would have to iterate over that whole set
of possibilities, in case some distribution-spec referrer-pushing
client happened to use one of that digest's other Referrers Tag
formats.
  • Loading branch information
wking committed Feb 3, 2025
1 parent 7872490 commit 07483af
Showing 1 changed file with 2 additions and 6 deletions.
8 changes: 2 additions & 6 deletions spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -721,14 +721,10 @@ A client querying the [referrers API](#listing-referrers) and receiving a `404 N

##### Referrers Tag Schema

```text
<alg>-<ref>
```

- `<alg>`: the digest algorithm (e.g. `sha256` or `sha512`)
- `<ref>`: the digest from the `subject` field (limit of 64 characters)
The Referrers Tag associated with a [Content Digest](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md#digests) <sup>[apdx-3](#appendix)</sup> MUST match the digest truncated to 128 characters with any characters not allowed by [`<reference>` tags](#pulling-manifests) replaced with `-`.

For example, a manifest with the `subject` field digest set to `sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa` in the `registry.example.org/project` repository would have a descriptor in the referrers list at `registry.example.org/project:sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`.
For example, a manifest with the `subject` field digest set to `sha512:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa` in the `registry.example.org/project` repository would have a descriptor in the referrers list at `registry.example.org/project:sha512-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`.

This tag should return an image index matching the expected response of the [referrers API](#listing-referrers).
Maintaining the content of this tag is the responsibility of clients pushing and deleting image manifests that contain a `subject` field.
Expand Down

0 comments on commit 07483af

Please sign in to comment.