[docs] Discrepancies between Rekor types documentation and schemas?

[woodruffw]

Hey there! I'm looking into increasing the breadth of Rekor types supported by sigstore-python (sigstore/sigstore-python#252), and I've been consulting the Rekor types documentation for the different types currently supported: https://github.com/sigstore/rekor/blob/main/types.md

As part of that, I've been trying to understand the relationship between those types and the schemas stored here: https://github.com/sigstore/rekor/tree/main/pkg/types

In particular, it looks like there are a couple of discrepancies between the two:

• The types documentation mentions SSH and Minisign as separate types, but I can't find separate schemas for these.
• The types documentation has TODO blocks for a couple of types that seem to be already schematized (like RPM).
• The types documentation has payload examples for a few types, but these don't directly match the schemas.

Is there a more up-to-date reference somewhere?

[lkatalin]

@woodruffw I had questions around the types too, and got clarification in this Slack thread.

I think the main tl;dr is there are two types of "types" - pluggable types, and PKI types. Each pluggable type supports certain PKI types. SSH and Minisign (and all the types in rekor/pkg/pki) are PKI types. The types listed under rekor/pkg/types are pluggable types. The pluggable types have schemas, the PKI types don't. So, SSH and Minisign would not have schemas. The documentation page is out of date and so the pluggable and PKI types are mixed together on there.

I have a backburner goal to update the docs on this, but will not get to it before November in case anyone else wants to grab it.

[woodruffw]

Thanks @lkatalin!