spec: Clarify Referrers Tag Schema vs. alternative algorithms

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 of the 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.

I'm requiring clients to truncate the encoded section to 64
characters, in addition to the overall tag truncation at 128
characters, because that's one possible reading of the outgoing "limit
of 64 characters" parenthetical, and at least one client had
implemented it that way [1].

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.

[1]: https://github.com/regclient/regclient/blob/dbb1434fd4b8b650983e8c51933789712e05eeaa/types/referrer/referrer.go#L157

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

spec.md

@@ -721,14 +721,16 @@ A client querying the [referrers API](#listing-referrers) and receiving a `404 N
 
 ##### Referrers Tag Schema
 
-```text
-<alg>-<ref>
-```
+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 Truncated-Encoded Digest further truncated to 128 characters with any characters not allowed by [`<reference>` tags](#pulling-manifests) replaced with `-`.
+The Truncated-Encoded Digest associated with a Content Digest MUST match the digest with its `encoded` portion truncated to 64 characters.
 
-- `<alg>`: the digest algorithm (e.g. `sha256` or `sha512`)
-- `<ref>`: the digest from the `subject` field (limit of 64 characters)
+For example, the following list maps `subject` field digests to Referrers Tags:
 
-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`.
+| Digest | Truncated-Encoded Digest | Referrers Tag |
+| ------ | ------------------------ | ------------- |
+| sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa |
+| sha512:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha512:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha512-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa |
+| test+algorithm+using+algorithm+separators+and+lots+of+characters+to+excercise+overall+truncation:alsoSome=InTheEncodedSectionToShowHyphenReplacementAndLotsAndLotsOfCharactersToExcerciseEncodedTruncation | test+algorithm+using+algorithm+separators+and+lots+of+characters+to+excercise+overall+truncation:alsoSome=InTheEncodedSectionToShowHyphenReplacementAndLotsAndLot | test-algorithm-using-algorithm-separators-and-lots-of-characters-to-excercise-overall-truncation-alsoSome-InTheEncodedSectionToS |
 
 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.