docs(conventions): define artefact-linking label convention

doc/01-model/06-conventions.md

@@ -29,3 +29,125 @@
 Usage scenarios for sets of described artifacts are best described by a dedicated description artifact with a dedicated tool-specific artifact type. Here, there is the complete freedom to describe the conditions and environments artifacts are to be used. The artifacts are described by [relative resource references](../05-guidelines/03-references.md#relative-artifact-references) in relation to the component version containing the description artifact.
 
 Another possibility is to use dedicated [labels](./03-elements-sub.md#labels) to describe the usage scenario for dedicated artifacts. Here, the tool working on a component versions does not read a description artifact, but has to analyse the label settings of all the provided artifacts. In both cases there is a dedicated OCM specific interpretation of content provided by the component model. But while the first solution allows to describe a closed scenario in a dedicated resource, where resources from dependent component version can be described by relative resource references and multiple scenarios can be separated by multiple flavors of this resource, the label-based approach is restricted to a local component version and a single scenario. Instead of an artifact type for the description, labels with a defined [name structure](./03-elements-sub.md#labels) are required.
+
+## Artefact-Linking Label
+
+This section defines a label convention for expressing cross-artefact relationships.
+For example, it can be used to indicate that an SBoM resource describes a specific
+OCI image resource within the same component version.
+
+### Label Name
+
+```
+ocm.software/artefact-references
+```
+
+The label is a predefined label within the component model (see [Label Types](./07-extensions.md#label-types)).
+The label version is expressed via the separate `version` field on the label object
+(e.g. `version: v1`); consumers MUST NOT treat a label with a different version as
+conforming to this convention.
+
+### Placement
+
+The label is placed on the **derived artefact**. The resource that is related to a
+subject artefact carries the label pointing back to that subject. The subject
+artefact itself requires no modification.
+
+```
+Component Descriptor
+├── Resource: my-image          ← subject artefact, unchanged
+└── Resource: my-image-sbom     ← derived artefact, carries the label
+```
+
+When multiple derived artefacts reference the same subject (e.g. two SBoMs produced
+by different tools for the same image), they MUST be told apart from each other by
+their own artefact identity. The `identity` in each label still points to the
+same subject; it is the derived artefact's own identity that makes the two resources
+unique within the component version.
+
+### Label Value
+
+The label value is a list of objects. Each object has the following field:
+
+**`identity`** (required) - a flat map of identity-relevant properties that identifies the subject artefact within the same component version:
+
+- `name` (required) *string* — resource name of the subject artefact.
+- `version` (optional) *string* — resource version. If omitted, any version matches.
+- Any additional key-value pair is treated as an extra identity property.
+  Every such entry MUST be present and equal in the subject's `extraIdentity`.
+  Required when multiple resources share the same name (e.g. arch-specific image variants).
+
+### Examples
+
+An SBoM describing a single-variant image:
+
+```yaml
+resources:
+  - name: my-image
+    version: 1.2.3
+    type: ociImage
+
+  - name: my-image-sbom
+    version: 1.2.3
+    type: sbom
+    labels:
+      - name: ocm.software/artefact-references
+        version: v1
+        value:
+          - identity:
+              name: my-image
+```
+
+Two SBoMs referencing the same subject, told apart by their own `extraIdentity`:
+
+```yaml
+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: ocm.software/artefact-references
+        version: v1
+        value:
+          - identity:
+              name: my-image
+              version: 1.2.3
+              foo: bar
+
+  - name: my-image-sbom
+    version: 1.2.3
+    type: sbom
+    extraIdentity:
+      architecture: arm64
+    labels:
+      - name: ocm.software/artefact-references
+        version: v1
+        value:
+          - identity:
+              name: my-image
+              version: 1.2.3
+              foo: bar
+```
+
+### Lookup Algorithm
+
+To find all artefacts related to a given subject resource:
+
+1. Determine the identity of the subject resource: its `name`, `version`, and `extraIdentity`.
+2. Iterate over all resources in the component descriptor.
+3. For each resource, check whether it carries a label named `ocm.software/artefact-references` with `version: v1`.
+4. If present, apply the following matching rules against each `identity` entry in the label value:
+   - `name` MUST equal the subject's `name`.
+   - If `version` is set, it MUST equal the subject's `version`.
+   - The set of additional key-value pairs MUST exactly match the subject's `extraIdentity`:
+     every key in the `identity` entry MUST be present and equal in the subject's `extraIdentity`,
+     and the subject's `extraIdentity` MUST NOT contain any keys not present in the `identity` entry.
+5. Resources that pass all checks are companions of the subject.

doc/01-model/07-extensions.md

@@ -666,34 +666,31 @@ There are two flavors of labels:
 - labels with a predefined meaning within the component model.
 
   Those labels are used by the standard OCM library and tool set to control some behaviour.
-  Labels without a namespace are relevant for the component model itself.
-
-  Such labels use flat names following a camel case scheme with the first character in lower case.
+  Predefined labels use the `ocm.software` prefix and a kebab-case local name.
 
   Their format is described by the following regexp:
 
   ```regexp
-  [a-z][a-zA-Z0-9]*
+  ocm\.software/[a-z][a-z0-9-]*
   ```
 
 - vendor specific labels
 
-  any organization using the open component model may define own labels.
+  Any organization using the open component model may define own labels.
   Nevertheless, these names must be globally unique.
   Basically there may be multiple such labels provided by different organizations
   with the same meaning. Such label names MUST use a namespace.
 
   To support a unique namespace vendor specific labels
   have to follow a hierarchical naming scheme based on DNS domain names.
   Every label name has to be preceded by a DNS domain owned by the providing
-  organization (for example `landscaper.gardener.cloud/blueprint`).
-  The local name MUST follow the above rules for centrally defined names
-  and is appended, separated by a slash (`/`).
+  organization (for example `odg.ocm.software/binary-scan-policy`).
+  The local name MUST use kebab-case and is appended, separated by a slash (`/`).
 
   So, the complete pattern looks as follows:
 
   ```regexp
-  <DNS domain name>/[a-z][a-zA-Z0-9]*
+  <DNS domain name>/[a-z][a-z0-9-]*
   ```
 
 ### Format Versions
@@ -709,4 +706,8 @@ v[0-9]+([a-z][a-z0-9]*)?
 
 #### Predefined Labels
 
-So far, no centrally predefined labels have been defined.
+The following labels are centrally defined:
+
+| Label name | Version | Description |
+|---|---|---|
+| `ocm.software/artefact-reference` | `v1` | Expresses a cross-artefact relationship within the same component version. See [Artefact-Linking Label](./06-conventions.md#artefact-linking-label). |