docs(conventions): define artefact-linking label convention

[bedirhan-yilmaz]

What this PR does / why we need it

Adds a convention to the OCM spec for expressing cross-artefact relationships via labels. This allows a derived resource (e.g. an SBoM) to declare which subject resource it relates to within the same component version, using a structured label placed on the derived artefact.

Which issue(s) this PR is related to

open-component-model/open-delivery-gear#126

[8R0WNI3]

To be consistent with existing concepts like the srcRefs property, I'd suggest to rename this field to identitySelector and only allow a flat mapping of identity relevant properties, e.g.:

identitySelector:
  name: my-image
  version: 1.2.3
  architecture: amd64

[a-thaler]

The label name names the semantical convention we want to define as part of the ocm spec. It should not be odg specific and should contain the convention name. The version should be moved to the version field. The values then should focus on the actual reference logic. My idea:

Suggested change

	labels:
	- name: odg.ocm.software/labels/artefact-ref/v1
	value:
	artefactReference:
	name: my-image
	metadata:
	relation: describes
	labels:
	- name: ocm.software/artefactReference
	version: v1
	value:
	identitySelector:
	name: my-image
	version: 1.2.3
	architecture: amd64

Is the metadata really needed? If the type of the resource which has the label is sbom, isn't that already descriptive enough?

[8R0WNI3]

The label name names the semantical convention we want to define as part of the ocm spec.

Looking at the spec, shouldn't the label name then rather just be artefactReference?

The version should be moved to the version field.

+1

Is the metadata really needed?

I agree that we probably don't require the current metadata property. However, as also discussed in the hackathon, we will need some sort of mechanism to further specify the kind of reference (e.g. in case there are multiple SBOMs for the same artefact). I would suggest to use the extraIdentity field of the referencing artefact (here: the OCM resource for the SBoM) for this, e.g.:

resources:
  - name: my-image
    version: 1.2.3
    type: ociImage
    extraIdentity:
      foo: bar
  - name: my-image-sbom
    version: 1.2.3
    type: sbom
    extraIdentity:
      architecture: amd64
    labels:
      - name: artefactReference
        version: v1
        value:
          identitySelector:
            name: my-image
            version: 1.2.3
            foo: bar
  - name: my-image-sbom
    version: 1.2.3
    type: sbom
    extraIdentity:
      architecture: arm64
    labels:
      - name: artefactReference
        version: v1
        value:
          identitySelector:
            name: my-image
            version: 1.2.3
            foo: bar  

Wdyt about this approach?

[a-thaler]

The resource type should be sbom, see

ocm-spec/doc/04-extensions/01-artifact-types/sbom.md

Line 4 in b286e28

The media type of the resource access should be spdx+json