Description of metadata.supplier is confusing

[nscuro]

As of v1.5, the description of metadata.supplier states:

specification/schema/bom-1.5.schema.json

Lines 268 to 271 in 299209a

	"supplier": {
	"title": "Supplier",
	"description": " The organization that supplied the component that the BOM describes. The supplier may often be the manufacturer, but may also be a distributor or repackager.",
	"$ref": "#/definitions/organizationalEntity"

This is in addition to metadata.component.supplier, which states:

specification/schema/bom-1.5.schema.json

Lines 430 to 434 in 299209a

	"supplier": {
	"title": "Component Supplier",
	"description": " The organization that supplied the component. The supplier may often be the manufacturer, but may also be a distributor or repackager.",
	"$ref": "#/definitions/organizationalEntity"
	},

Based on those descriptions, it is unclear what the subject of metadata.supplier is. metadata.component is the component that the BOM describes, meaning metadata.component.supplier would be the same as metadata.supplier.

As discussed in this Slack thread, it seems that metadata.supplier describes the supplier of the BOM itself. If that is the case, the schema documentation should be updated to include this fact.

[jkowalleck]

I was told, that metadata.supplier is meant to be the supplier of the CycloneDX document.
the other one is the supplier of the root component.

use case: you have an agency producing your documentation artifact.

I will update the docs for 1.6

PS: since the current docs state otherwise than it was meant, the mentioned facts would be a breaking-change.
will discuss with CoreWorkingGroup -- result here: #379 (comment)

[jkowalleck]

see a discussion result from the CoreWorkingGroup here: #379 (comment)

originally i had planned
the following:

• deprecate metadata.supplier in favour of metadta.component.supplier
  -- fixes Description of metadata.supplier is confusing #345

in a discussion with members of the CoreWorkingGroup, they told to do the following instead:

• state in the description, that metadata.supplier so that it stated that the field has different meaning per spec version.
  • < 1.6, the meaning was "supplier of the component described by the BOM" (old/legacy)
  • >= 1.6, the meaning will be "supplier of the BOM"
    previous capability would be shifted to in favour of metadata.component.supplier

the proposal would cause breaking semantic changes. I do not want to bring any breaking change into the spec.
Therefore I will drop the aspect 'supplier' entirely from this PR.

[jkowalleck]

@stevespringett lets move this one to 1.7
We did not find consensus here, yet. Maybe we will come up with a non-breaking solution in the future.

[jkowalleck]

see #521

we cannot simply change the meaning of an existing field. see #379 (comment)
We could deprecate the existing $.metadata.supplier in favor of $.metadata.component.supplier,
and we could add a new field [with different name] to $.metadata to represent the SBOM supplier.

[jkowalleck]

#345 (comment)

and we could add a new field [with different name] to $.metadata to represent the SBOM supplier.

any ideas how that new field should be named?
maybe bom-supplier?

[stevespringett]

I think we need to seriously consider a minor, but breaking change in the 1.7 release and capture that change in the release notes.

[jkowalleck]

I think we need to seriously consider a minor, but breaking change in the 1.7 release and capture that change in the release notes.

A breaking change just for the fact that the preferred name of a field is not free anymore? I do not like this.
A breaking change in a minor version? I'd veto this.

CycloneDX is about the data and the specification.
For example, as long as the spec tells that a field called "blueberrypie" must be used for purpose XYZ, all is good.
We should not thrive for elegance, just decide on a name and write the specs for it.