Adding a "componentref" structure in the product definition

[oej]

This is to be able to reference a specific release of a component in addition to referencing the component itself.

The product now includes a list of "componentref" objects where each object contains one or two items - the first is a reference to the component, which is required, the second is a reference to specific release of that component, which is optional.

[oej]

This allows this "dependency track" model where a release of DP includes specific releases of sub-components

[ppkarwasz]

Hi @oej,

Thanks for this PR — it’s a solid step in the right direction! I appreciate how it enables a TEA Product to reference precise versions of TEA Components. This seems well-suited for use cases like physical devices, where the hardware version is fixed and TEA can provide the initial software revision.

That said, I’m not sure it fully covers all the scenarios we discussed during the workshop. In particular, for products like Dependency-Track, we might need to support multiple releases of the same product.

To support that, I suggest introducing a product-release object, distinct from product, which includes fields like version and releaseDate. Both could coexist in the model but be served via separate endpoints:

• product → /product/{uuid}
• product-release → /product/{productUuid}/release/{releaseUuid}
• All releases → /product/{productUuid}/releases

If this direction makes sense to you, I’d be happy to draft a PR to explore it further.

What do you think?

[ppkarwasz]

Suggested change

	description: Unique identifier of the TEA componentref
	"$ref": "#/components/schemas/uuid"
	description: Reference to a TEA Component
	"$ref": "#/components/schemas/component-ref"

If I understand the intent correctly, the goal is to embed the component reference directly into the object, rather than introducing an additional level of indirection.

[ppkarwasz]

I believe we should remove all three PURL identifiers, including the one for log4j-api.

Also, it looks like the components section in this example wasn’t updated. Follow the updated format it should be:

components:
  - uuid: 3910e0fd-aff4-48d6-b75f-8bf6b84687f0
    release: c1f2f9c4-d86e-4007-b61c-a53dc36f3e72
  - uuid: b844c9bd-55d6-478c-af59-954a932b6ad3
  - uuid: d6d3f754-d4f4-4672-b096-b994b064ca2d

[oej]

Hi @oej,

Thanks for this PR — it’s a solid step in the right direction! I appreciate how it enables a TEA Product to reference precise versions of TEA Components. This seems well-suited for use cases like physical devices, where the hardware version is fixed and TEA can provide the initial software revision.

That said, I’m not sure it fully covers all the scenarios we discussed during the workshop. In particular, for products like Dependency-Track, we might need to support multiple releases of the same product.

To support that, I suggest introducing a product-release object, distinct from product, which includes fields like version and releaseDate. Both could coexist in the model but be served via separate endpoints:

• product → /product/{uuid}
• product-release → /product/{productUuid}/release/{releaseUuid}
• All releases → /product/{productUuid}/releases

If this direction makes sense to you, I’d be happy to draft a PR to explore it further.

What do you think?

In the meeting we agreed that the version of the hardware is part of the name and that we don't need any new releases object for the product - this was confirmed by @nscuro .
Let's start with this and then see if we need to go back to the potential need to add a new object.

[ppkarwasz]

In the meeting we agreed that the version of the hardware is part of the name and that we don't need any new releases object for the product - this was confirmed by @nscuro.

I agree that for physical devices, including the version in the product name makes sense — there are few variants, and the hardware doesn't change.

But for software, it's different. Products like Dependency-Track may have many versions (e.g., 4.0.0, 4.0.1, etc.). Should we treat each as a separate product? If it were commercial, which version would appear on an invoice?

[oej]

In the meeting we agreed that the version of the hardware is part of the name and that we don't need any new releases object for the product - this was confirmed by @nscuro.

I agree that for physical devices, including the version in the product name makes sense — there are few variants, and the hardware doesn't change.

But for software, it's different. Products like Dependency-Track may have many versions (e.g., 4.0.0, 4.0.1, etc.). Should we treat each as a separate product? If it were commercial, which version would appear on an invoice?

In most cases there will be a product that doesn't lock on specific versions, because the version of components in the sold product keeps changing. But with DT Niclas wanted to create separate products for all releases, like 4.0, 4.1

[ppkarwasz]

For Apache, we will likely align TEA concepts with those used in the Apache Trusted Releases platform. A possible mapping would be:

• Each PMC (Project Management Committee) has its own domain, which can be used in TEI identifiers.
• Each subproject (e.g., Log4cxx, Log4j, Log4net) within a PMC would correspond to a TEA Product.
• Each released source or binary archive would be modeled as a distribution of a TEA Component Release.

However, TEA does not currently have a direct equivalent of a subproject release—that is, a versioned unit that groups together multiple TEA Component Releases (possibly across multiple components) and corresponds to a PMC release vote.

[oej]

For Apache, we will likely align TEA concepts with those used in the Apache Trusted Releases platform. A possible mapping would be:

• Each PMC (Project Management Committee) has its own domain, which can be used in TEI identifiers.
• Each subproject (e.g., Log4cxx, Log4j, Log4net) within a PMC would correspond to a TEA Product.
• Each released source or binary archive would be modeled as a distribution of a TEA Component Release.

However, TEA does not currently have a direct equivalent of a subproject release—that is, a versioned unit that groups together multiple TEA Component Releases (possibly across multiple components) and corresponds to a PMC release vote.

Isn't that what we fix here? Or doesn't it work for you?

[ppkarwasz]

Isn't that what we fix here? Or doesn't it work for you?

The proposed PR still forces us to make a choice: should we map subprojects or subproject releases to TEA Products? Depending on that choice, we'll end up with one of the following:

• TEA Products like "Apache Log4j 2.24.3", "Apache Log4j 2.25.0" — representing subproject releases. In this case we will profit from the release property you introduced, but lose links between releases of the same subproject.
• Or TEA Products like "Apache Log4cxx", "Apache Log4j", "Apache Log4net" — representing subprojects. In this case we will not use the new release property.

[taleodor]

@oej Here is one more use case I thought about that we are losing on without product - product release split.

Let's take DT example, and say a user makes a discovery based on TEI for product version 4.12.0 - so far so good.

However, image that at some point CLE references for all component releases will show that they are not supported. And what user is expected to do is to migrate to DT product version 4.13.0 instead.

Without product - product release split, there is no good way to show to the user that 4.12.0 and 4.13.0 are actually different iterations of the same product and you can (and should) upgrade to the latest one.

Another (unrelated) consideration to having open (without pinned release versions) Component references in Product releases:
Should we extend options to support Vers there and/or possibly a list of supported Component releases?

Basically, what I'm thinking a Component may contain for versions that for any reason should not be used in this particular product - i.e. I saw scenarios where particular firmware would brick a certain product and should never be used even though it may look newer than the existing one, but the consumer would have no way of knowing this. CLE data may be imperfect here, as the problems may exist only in the context of a single product, while the Component may be used in multiple products.

[oej]

@taleodor You need to be more specific in a pull request review. You are expanding the discussion far beyond this actual PR in my view. Are you against merging this or are you merely adding a new use case to the list of stuff we need to do -- then it's another issue? Niklas from dependency track agreed on this change, so he's fine with this.
I can move the resolution of your comment to another issue, but don't really understand your standing to this pull request. Please clarify.

[taleodor]

I'm very busy for the rest of this week and early next week, so apologies if this and my comment above look too brief, but:

1. I don't think this PR should be merged as is. I would prefer if we have an additional 1 hour workshop on the subject, where we could clarify issues, alternatives and make a decision. I can prepare more detailed suggestions by then.
2. Further, I believe that this PR, while looking minor, changes the definition of the Product to what I personally would understand as a Product Release and at the same time makes it confusing for the implementers - for example, see Piotr's comment above -

The proposed PR still forces us to make a choice: should we map subprojects or subproject releases to TEA Products?

3. I don't feel like clarifications in documentation will help here and we'll just end up with messy implementations that are not compatible between each other. By claiming the definition "Product" for something that is traditionally known as "Product Version" (mainly, in the software world, but also in the hardware - where we have i.e. hardware versions of the same router) we are also making future extension of the API difficult, which is the main issue for me here regarding your reference to putting this subject in future discussions unrelated to this PR.
4. I used Dependency-Track only as an example of multi-component software with which all of us are familiar. I'm currently personally involved in at least 3 software Products with richer component structure than Dependency-Track and they all would suffer from the same issue - namely, how do we communicate CLE change for a Product Release within the TEA paradigm proposed in this PR? Within the paradigm suggested in this PR, I would have a way to say that the version X of my Product is not good, but no way to point consumer to the version Y that is good.
   So my argument is in now way related to Dependency-Track specifically. I'm just adding a use case in addition to the Piotr's use case above where I see the suggested paradigm breaking.
5. I think that your idea to introduce componentref is great, but I also think it should be expanded to add optional constraints on the component - at minimum, instead of a single release ref I think we should have an array of releases, but I would also suggest adding a separate Vers constraint field. However, this specific point can actually be deferred to future conversations.

Bottom line, I would like to see another 1 hour workshop on this, from my side I can prepare clear suggestions on the points mentioned above - balancing the need for Product / Product Release split and at the same time making Product optional so only the projects who needs it would use it.

On my side I can commit to June 27 to prepare detailed materials on this.

Now, I understand the desire to rush this PR through, but I believe this is very important to get right and I see significant issues in the current form.

[ppkarwasz]

@taleodor,

I'm somewhat conflicted on your remark about CLE metadata:

• On one hand, certain events — such as end-of-sale — are clearly defined at the product level by marketing and therefore naturally belong to the TEA Product.
• On the other hand, many lifecycle events align more closely with TEA Components. For example, my phone was originally shipped with Android 12, which was later upgraded to Android 14. At some point, Android 12 may become unsupported — yet the manufacturer is still required to support the hardware.

[taleodor]

I agree, but actually the CLE conversation is something I think should be out of scope for now (and of this PR in particular). Here is why - given my use case:

1. Assuming, I have a Product Release which has a Component with a fixed Component Release
2. On the Component Release level, I can indicate the End of Support
3. This essentially taints the whole Product Release (since this is the fixed Release in the Product Release)
4. I would then expect the consumer to look for the newer Release of the Product, rather than the newer Release of the Component

The above fits the existing paradigm, so we can defer the CLE discussion to the future.

[taleodor]

This is what I propose:

Here, we keep the meaning of Product to what we originally had in the OpenAPI spec. We introduce Product Release which is actually a packaged box and that has references to the actual Components available to the consumer (either fixed or established via Componentref).

One important note is that the Discovery mechanism points to Product Release and not Product.

A clear benefit of this model is we clearly define what Product Release is - an actual box or software package that the user gets and what Product is - a logical grouping of related Product Releases. This will ensure implementations are not adding their own meaning that may be inconsistent with other implementations.

Now, for folks who don't want to use the concept of Product, we make that optional. This should be fine because Product is no longer an entry point of Discovery. I hope this can satisfy Apache requirements and my requirements across several OSS and COTS projects where we do need a separate Product category as well as Dependency-Track maintainers' requirements not to keep a separate Product category.

Again, I would suggest to have another 1 hour workshop on this to discuss - I believe we had 2 workshops scheduled originally for this, so that should be reasonable to have the second one.