# Reference Type Requirements

## Definitions

- **Artifact** - One conceptual piece of content stored as Blobs, represented as a Manifest. An artifact has a distinct lifecycle, represented by an associated tag.
*(Examples: container images, wasm, helm charts)*
- **Reference Type** - One or more additional (detached) pieces of content, that enhances the content of referenced artifact without mutating referneced artifact.
*(Examples: signatures, SBoM, Scan Results)*

## Requirements

A set of requirements around reference types to guide various design options. Not all design options will serve all requirements. The goal is to serve as many critical requirements for existing and unchanged 1.0 distribution spec registries, while accounting for the full set of requirements with enhancements to registries.

| # | Item | Description |
| - | - | - |
| 1 | Push a single level reference | Enable signature on an image, sbom on an image, but may not support signature on sbom for an image |
| 2 | Push multi-level references, without registry changes | Similar to above, with n-depth support. (`image <--sbom <-- signature <-- receipt`) |
| 3 | Doesn't mutate the tag or digest of the subject artifact | Adding a reference must not change the manifest or layers of the artifact being referenced |
| 4 | Works with registries that enforce immutable tags | Some registries support locking a tag for further mutation. Any tag pushed can not be updated. |
| 4 | Each reference type is independent | To support pulling individual reference artifacts, or promoting a filtered set of artifacts, each reference must exist independently. |
| 5 | Support multiple blobs in a reference type | An artifact may have multiple blobs that make up the artifact. A helm chart is a reference type, which has two layers || | | |
| 6 | Lifecycle management, based on the subject tag | Reference types are extensions to the artifact they reference. Deleting the root artifact should enable the registry to the graph of references |
| 7 | | |

!# TO BE MERGED ABOVE

- Works with registries that enforce immutable tags
- Does not break existing container runtimes
- Able to copy signatures to other repositories and registries
- Able to pull signature by tag
- Able to pull signature by target image digest
- Able to deploy by digest to a signed image (looser version of above requirement, allowing the digest to be an index containing the signature and image)
- Able to push multiple signatures for the same image
- Able to copy a subset of signatures
- Local signatures coexist with upstream signatures that are periodically synced
- Avoids race conditions
- Able to attach a signature to an already pushed image
- Does not modify the manifest/digest of the image
- Able to sign individual images
- Able to sign a manifest list
- Avoids cluttering the tag listing
- Signatures are deleted with the signed artifact
-
### Comparison of Options

A matrix of which designs support each requirment

| # | Item | Fallback 1 | Fallback 2 | Existing Manifest Updates | New Manifest |
| - | - | - | - | - | - |
| 1 | foo | :grey_question: | :grey_question: | :grey_question: | :grey_question: |
| 2 | bar | :grey_question: | :grey_question: | :grey_question: | :grey_question: |

Key:

- :heavy_check_mark: : supported
- :white_check_mark: : requires workarounds to support
- :grey_question: : research needed
- :x: : unsupported