CycloneDX / CycloneDX/transparency-exchange-api

Release without a collection — optional latestCollection or always require one?

Open
#286 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
113
Forks
22
Avg merge
8d 12h
Merged PRs (30d)
5

Description

## Summary

Supporting docs describe collections as optional for a Component Release, but the OpenAPI response model for a component release with collection requires `latestCollection`. A release that has no collection yet therefore has no defined successful representation.

This is separate from #264’s decision to allow `artifacts: []` on a collection that exists. Empty collection ≠ missing collection.

## Current gaps

- `component-release-with-collection` requires both `release` and `latestCollection`.
- README states each Component Release *may* have its own TEA Collection.
- There is no stated successful representation for GET of a release that has never published a collection, or for list endpoints when none exists.
- The dedicated “latest collection” endpoint reuses the same generic `404-object-by-id-not-found` for both “release doesn’t exist” and “release exists but has no collection” — ambiguous, not distinguishable by clients (same pattern as signature-absent `404`).

## Decision needed

- A — Keep collections optional:
Require only `release` on the combined response; omit `latestCollection` when none exists. Collection list endpoints may return an empty result. When no collection has been published, the dedicated latest-collection endpoint still returns `404`, but that outcome should be distinguishable from “release not found” (e.g. a distinct error code, similar to the signature-absent `404` discussion). Align OpenAPI `required` and docs with that model.

- B — Require a collection for every release:
Every Component Release (and, if the same rule applies, Product Release) always has a collection, which may be empty (`artifacts: []` per #264). Keep `latestCollection` required. Update README and related docs that currently say collections are optional.

Half-fixing (e.g. only dropping `required` without endpoint behavior) leaves clients without an interoperable “no collection” path?

## Relation to other work

- #264 / #259: required fields and empty `artifacts: []` — complementary.
- Does not change artifact download, auth, or discovery issues.

## My question

For TEA 1.0, should a release without a collection be representable (A), or must every release always have a collection (B)?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.