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

[Mehrn0ush]

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 Openapi require changes #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

• Openapi require changes #264 / Component has no required fields #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)?

[taleodor]

I believe implementation preferred B. We can discuss though.

[taleodor]

B. The model already implies it:

• The collection's uuid is defined as identical to its release's uuid. That is a one-to-one identity, not an optional attachment.
• tea-collection.md already says "for each product and version there is a TEA Collection object" and that the server normally creates it at publication time; the dynamic-TCO option means a server can synthesize it.
• An empty first version is a valid instance today: release uuid, version 1, the release's created date, updateReason.type: INITIAL_RELEASE, artifacts: [] (allowed since Openapi require changes #264).
• Under B the ambiguous 404 on /collection/latest disappears by itself: the only thing that can be missing is the release. No new error code needed.

The rule to write down. A release is never served without a collection. If no artifacts have been published when the release first becomes retrievable, the server serves collection version 1 with an empty artifacts list and updateReason.type: INITIAL_RELEASE. That version is immutable like any other (#300: published revisions do not change, latest is the greatest version), so the first artifacts are published as version 2 with ARTIFACT_ADDED. A publisher that publishes the release and its artifacts together never has an empty version and starts at version 1 with content. Both are consistent with "version 1 is whatever was first observable".

Changes (docs plus OpenAPI descriptions, one schema tightening):

Docs:

• README.md line 60: "Each Component Release may have its own TEA Collection" → "has its own TEA Collection".
• doc/tea-requirements.md line 29: "Collections are OPTIONAL." → "Every release has a collection, which may be empty."
• tea-collection/tea-collection.md: add the implicit-empty rule above. While there, it still documents date instead of createdDate and belongsTo values RELEASE / PRODUCT_RELEASE instead of COMPONENT_RELEASE / PRODUCT_RELEASE; same file, fix in the same pass.

OpenAPI:

• collection description, add:

  Every component release and product release has a collection. If no artifacts have
  been published when the release first becomes retrievable, the server serves version 1
  with an empty `artifacts` list and `updateReason.type: INITIAL_RELEASE`. That version
  is immutable like any other; the first artifacts are published as version 2.
  

• collection: make artifacts required, empty list allowed. Removes the last absent-versus-empty branch for clients.

      required:
        - uuid
        - version
        - createdDate
        - belongsTo
        - updateReason
        - artifacts

• Both /collection/latest operations, add: "404 means the release is unknown; a release always has a latest collection."

• component-release-with-collection: latestCollection stays required. No change.

[ppkarwasz]

I opened #318 to address a small inconsistency that returning a Collection together with a Component Release creates:

• /productRelease/{uuid} does not return the latest collection for that product,
• Nitpick: due to the wrapper, the structure of the objects returned by /componentReleases and /component/{uuid}/releases differs from what /componentRelease/{uuid} returns. If component-release-with-collection were to extend release by a single field, the processing of the return of these methods could be similar and reduce to “if there is a latestCollection field we are done, otherwise call /collection/{uuid}/latest”.