Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Use composition for parent references and component-ref

Open
  • Is something wrong?
#317 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Domain
api, backend-api-design

Research direction

Start by reviewing the productRelease, componentRelease, release, and component-ref schemas, then read issues #127 and #195 for the current model's rationale. Done means the proposed object references, removed name fields, optional release pin, and added identifiers are specified consistently for the 2.0.0 breaking change.

Written by the indexing model from the issue text.

Description

Backlog

TL;DR: component and product are lightweight objects. Let's inline them in TEA 2.0.0 instead of referencing them by UUID.

This is not a request to change 1.0.0. The specification is finalized, and I do not want to touch it at the eleventh hour. I am filing the idea now, for 2.0.0, so that it is on record while the reasons are fresh, and because it is a breaking change whose cost only grows once clients ship.

My interest is in components. Seen from that side, the Product API returns too little to be useful on its own: a product release does not even give the names of its components.

The TEA object model is a tree: product, product release, component, component release, then distributions, collections and artifacts. Below the release level every endpoint embeds the next level in full: a component release carries its distributions, a collection carries its artifacts, an artifact carries its formats and checksums.

The two release endpoints sit at the same level of that tree and behave very differently:

  • /productRelease/{uuid} returns only the UUIDs of its components. A component-ref is { uuid, release? }, with no name and no identifiers. Showing the bill of components, or matching your own PURLs against it, costs one /component/{uuid} call per entry.
  • /componentRelease/{uuid} returns several levels down: its distributions and even the latest collection, in the same shape as /componentRelease/{uuid}/collection/latest.

A component is three fields: uuid, name, identifiers. A product is the same three. Embedding either costs a few hundred bytes.

Proposal

Replace the UUID references by the objects they point to:

release:
  properties:
    component:
      $ref: "#/components/schemas/component"   # was uuid; componentName removed

productRelease:
  properties:
    product:
      $ref: "#/components/schemas/product"     # was uuid; productName removed

component-ref:
  properties:
    component:
      $ref: "#/components/schemas/component"   # was uuid
    release:
      $ref: "#/components/schemas/uuid"        # optional pin, unchanged
  required: [component]

On the wire, three fields change from string to object and two denormalized name fields (componentName and productName) disappear. Each of component release and product release gain also the identifiers of the component or product.

Impact

Breaking change to three response schemas, hence the 2.0.0 target. For the motivations behind the current shape, see where it was introduced:

  • component-ref and the split of product and component: #127
  • productName and componentName: #195
Dominant language
Shell
Stars
120
Forks
24
Avg merge
1d 6h
Merged PRs (30d)
67

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from CycloneDX/transparency-exchange-api

All issues in CycloneDX/transparency-exchange-api

Similar issues

More Shell/Bash issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.