Example media types

[imjasonh]

(Apologies in advance if this has 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.

---

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.

[SteveLasker]

The references and resulting artifacts-spec originated from the Notary v2 designs, and at the time was the only signature format. So, these are just remnants around momentum for naming real examples. I do think concreate examples help, to avoid the vague xml reference in the distribution spec,
We did use generic sbom/example to avoid specific SBoM formats being proposed. We can do the same for making signature/example