From a40dce51734eccecf5caa40cc21b338a80e993b6 Mon Sep 17 00:00:00 2001 From: "Bedirhan Yilmaz (bedirhan-yilmaz)" Date: Wed, 15 Jul 2026 16:16:45 +0200 Subject: [PATCH 1/4] docs: define artefact-linking label convention for cross-artefact relationships Signed-off-by: Bedirhan Yilmaz (bedirhan-yilmaz) --- doc/01-model/06-conventions.md | 128 +++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) diff --git a/doc/01-model/06-conventions.md b/doc/01-model/06-conventions.md index e156ef9..81311b0 100644 --- a/doc/01-model/06-conventions.md +++ b/doc/01-model/06-conventions.md @@ -29,3 +29,131 @@ If platform specific images are described as separate resources instead of using 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 + +``` +odg.ocm.software/labels/artefact-ref/v1 +``` + +The label follows the [vendor-specific label naming scheme](./07-extensions.md#label-types). +The version suffix (`v1`) is encoded in the label name; consumers MUST NOT treat a +label with a different version suffix 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 +``` + +### Label Value + +The label value is a YAML object with the following fields: + +**`artefactReference`** (required) - 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. +- `extraIdentity` (optional) *map[string]string* — extra identity key-value pairs. + Every entry listed here MUST be present and equal in the subject's `extraIdentity`. + Required when multiple resources share the same name (e.g. arch-specific image variants). + +**`metadata`** (optional) — additional context about the relationship: + +- `relation` (optional) *string* — token describing the nature of the relationship. + Recommended values: + - `describes` — the derived artefact describes the subject (e.g. an SBoM). + - `attests` — the derived artefact attests a property of the subject. + + Additional values MAY be defined by tooling. Consumers that do not recognise a + value SHOULD treat the label as a generic artefact reference. + +### 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: application/spdx+json + labels: + - name: odg.ocm.software/labels/artefact-ref/v1 + value: + artefactReference: + name: my-image + metadata: + relation: describes +``` + +Two derived artefacts referencing a specific architecture variant via `extraIdentity`: + +```yaml +resources: + - name: my-image + version: 1.2.3 + type: ociImage + extraIdentity: + arch: amd64 + + - name: my-image-sbom + version: 1.2.3 + type: application/spdx+json + labels: + - name: odg.ocm.software/labels/artefact-ref/v1 + value: + artefactReference: + name: my-image + version: 1.2.3 + extraIdentity: + arch: amd64 + metadata: + relation: describes + + - name: my-image-attestation + version: 1.2.3 + type: application/vnd.in-toto+json + labels: + - name: odg.ocm.software/labels/artefact-ref/v1 + value: + artefactReference: + name: my-image + version: 1.2.3 + extraIdentity: + arch: amd64 + metadata: + relation: attests +``` + +### 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 `odg.ocm.software/labels/artefact-ref/v1`. +4. If present, apply the following matching rules against `artefactReference`: + - `name` MUST equal the subject's `name`. + - If `version` is set, it MUST equal the subject's `version`. + - If `extraIdentity` is set, every key-value pair it contains MUST be present + and equal in the subject's `extraIdentity`. +5. Optionally filter the collected resources by `metadata.relation`. + +Resources that pass all checks are companions of the subject. From a3a7f2e5106c4972724acf6522624c0ef6e76a7f Mon Sep 17 00:00:00 2001 From: "Bedirhan Yilmaz (bedirhan-yilmaz)" Date: Tue, 28 Jul 2026 08:48:35 +0200 Subject: [PATCH 2/4] docs: refine artefact-linking label convention Signed-off-by: Bedirhan Yilmaz (bedirhan-yilmaz) --- doc/01-model/06-conventions.md | 85 ++++++++++++++++------------------ 1 file changed, 39 insertions(+), 46 deletions(-) diff --git a/doc/01-model/06-conventions.md b/doc/01-model/06-conventions.md index 81311b0..5e1aed2 100644 --- a/doc/01-model/06-conventions.md +++ b/doc/01-model/06-conventions.md @@ -39,12 +39,13 @@ OCI image resource within the same component version. ### Label Name ``` -odg.ocm.software/labels/artefact-ref/v1 +ocm.software/artefactReference ``` The label follows the [vendor-specific label naming scheme](./07-extensions.md#label-types). -The version suffix (`v1`) is encoded in the label name; consumers MUST NOT treat a -label with a different version suffix as conforming to this convention. +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 @@ -58,29 +59,25 @@ Component Descriptor └── 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 `extraIdentity`. The `identitySelector` 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 YAML object with the following fields: -**`artefactReference`** (required) - identifies the subject artefact within the same -component version: +**`identitySelector`** (required) - identifies the subject artefact within the same +component version as a flat map of identity-relevant properties: - `name` (required) *string* — resource name of the subject artefact. - `version` (optional) *string* — resource version. If omitted, any version matches. -- `extraIdentity` (optional) *map[string]string* — extra identity key-value pairs. - Every entry listed here MUST be present and equal in the subject's `extraIdentity`. +- 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). -**`metadata`** (optional) — additional context about the relationship: - -- `relation` (optional) *string* — token describing the nature of the relationship. - Recommended values: - - `describes` — the derived artefact describes the subject (e.g. an SBoM). - - `attests` — the derived artefact attests a property of the subject. - - Additional values MAY be defined by tooling. Consumers that do not recognise a - value SHOULD treat the label as a generic artefact reference. - ### Examples An SBoM describing a single-variant image: @@ -93,17 +90,16 @@ resources: - name: my-image-sbom version: 1.2.3 - type: application/spdx+json + type: sbom labels: - - name: odg.ocm.software/labels/artefact-ref/v1 + - name: ocm.software/artefactReference + version: v1 value: - artefactReference: + identitySelector: name: my-image - metadata: - relation: describes ``` -Two derived artefacts referencing a specific architecture variant via `extraIdentity`: +Two SBoMs referencing the same subject, told apart by their own `extraIdentity`: ```yaml resources: @@ -111,35 +107,35 @@ resources: version: 1.2.3 type: ociImage extraIdentity: - arch: amd64 + foo: bar - name: my-image-sbom version: 1.2.3 - type: application/spdx+json + type: sbom + extraIdentity: + architecture: amd64 labels: - - name: odg.ocm.software/labels/artefact-ref/v1 + - name: ocm.software/artefactReference + version: v1 value: - artefactReference: + identitySelector: name: my-image version: 1.2.3 - extraIdentity: - arch: amd64 - metadata: - relation: describes + foo: bar - - name: my-image-attestation + - name: my-image-sbom version: 1.2.3 - type: application/vnd.in-toto+json + type: sbom + extraIdentity: + architecture: arm64 labels: - - name: odg.ocm.software/labels/artefact-ref/v1 + - name: ocm.software/artefactReference + version: v1 value: - artefactReference: + identitySelector: name: my-image version: 1.2.3 - extraIdentity: - arch: amd64 - metadata: - relation: attests + foo: bar ``` ### Lookup Algorithm @@ -148,12 +144,9 @@ 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 `odg.ocm.software/labels/artefact-ref/v1`. -4. If present, apply the following matching rules against `artefactReference`: +3. For each resource, check whether it carries a label named `ocm.software/artefactReference` with `version: v1`. +4. If present, apply the following matching rules against `identitySelector`: - `name` MUST equal the subject's `name`. - If `version` is set, it MUST equal the subject's `version`. - - If `extraIdentity` is set, every key-value pair it contains MUST be present - and equal in the subject's `extraIdentity`. -5. Optionally filter the collected resources by `metadata.relation`. - -Resources that pass all checks are companions of the subject. + - Every additional key-value pair MUST be present and equal in the subject's `extraIdentity`. +5. Resources that pass all checks are companions of the subject. From ef044c94a4e7278d9599737f81a0c8fc70630a71 Mon Sep 17 00:00:00 2001 From: "Bedirhan Yilmaz (bedirhan-yilmaz)" Date: Tue, 28 Jul 2026 11:49:52 +0200 Subject: [PATCH 3/4] docs: update artefact-linking label convention and clarify label value structure Signed-off-by: Bedirhan Yilmaz (bedirhan-yilmaz) --- doc/01-model/06-conventions.md | 45 +++++++++++++++++----------------- doc/01-model/07-extensions.md | 21 ++++++++-------- 2 files changed, 34 insertions(+), 32 deletions(-) diff --git a/doc/01-model/06-conventions.md b/doc/01-model/06-conventions.md index 5e1aed2..3432ab0 100644 --- a/doc/01-model/06-conventions.md +++ b/doc/01-model/06-conventions.md @@ -39,10 +39,10 @@ OCI image resource within the same component version. ### Label Name ``` -ocm.software/artefactReference +ocm.software/artefact-references ``` -The label follows the [vendor-specific label naming scheme](./07-extensions.md#label-types). +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. @@ -61,16 +61,15 @@ Component Descriptor 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 `extraIdentity`. The `identitySelector` in each label still points to the +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 YAML object with the following fields: +The label value is a list of objects. Each object has the following field: -**`identitySelector`** (required) - identifies the subject artefact within the same -component version as a flat map of identity-relevant properties: +**`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. @@ -92,11 +91,11 @@ resources: version: 1.2.3 type: sbom labels: - - name: ocm.software/artefactReference + - name: ocm.software/artefact-references version: v1 value: - identitySelector: - name: my-image + - identity: + name: my-image ``` Two SBoMs referencing the same subject, told apart by their own `extraIdentity`: @@ -115,13 +114,13 @@ resources: extraIdentity: architecture: amd64 labels: - - name: ocm.software/artefactReference + - name: ocm.software/artefact-references version: v1 value: - identitySelector: - name: my-image - version: 1.2.3 - foo: bar + - identity: + name: my-image + version: 1.2.3 + foo: bar - name: my-image-sbom version: 1.2.3 @@ -129,13 +128,13 @@ resources: extraIdentity: architecture: arm64 labels: - - name: ocm.software/artefactReference + - name: ocm.software/artefact-references version: v1 value: - identitySelector: - name: my-image - version: 1.2.3 - foo: bar + - identity: + name: my-image + version: 1.2.3 + foo: bar ``` ### Lookup Algorithm @@ -144,9 +143,11 @@ 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/artefactReference` with `version: v1`. -4. If present, apply the following matching rules against `identitySelector`: +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`. - - Every additional key-value pair MUST be present and equal in the subject's `extraIdentity`. + - 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. diff --git a/doc/01-model/07-extensions.md b/doc/01-model/07-extensions.md index 835625c..4dcaa06 100644 --- a/doc/01-model/07-extensions.md +++ b/doc/01-model/07-extensions.md @@ -666,19 +666,17 @@ 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. @@ -686,14 +684,13 @@ There are two flavors of labels: 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 - /[a-z][a-zA-Z0-9]* + /[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). | From 3555c19795ba438b5d38d8d8f34e40b21560810a Mon Sep 17 00:00:00 2001 From: "Bedirhan Yilmaz (bedirhan-yilmaz)" Date: Tue, 28 Jul 2026 16:55:59 +0200 Subject: [PATCH 4/4] docs: clarify label naming conventions and update examples in extensions Signed-off-by: Bedirhan Yilmaz (bedirhan-yilmaz) --- doc/01-model/06-conventions.md | 4 ++-- doc/01-model/07-extensions.md | 28 +++++++--------------------- 2 files changed, 9 insertions(+), 23 deletions(-) diff --git a/doc/01-model/06-conventions.md b/doc/01-model/06-conventions.md index 3432ab0..aff5c42 100644 --- a/doc/01-model/06-conventions.md +++ b/doc/01-model/06-conventions.md @@ -42,7 +42,7 @@ OCI image resource within the same component version. ocm.software/artefact-references ``` -The label is a predefined label within the component model (see [Label Types](./07-extensions.md#label-types)). +The label is a predefined label within the open 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. @@ -150,4 +150,4 @@ To find all artefacts related to a given subject resource: - 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. +5. Resources that pass all checks are derived artefacts of the subject. diff --git a/doc/01-model/07-extensions.md b/doc/01-model/07-extensions.md index 4dcaa06..d8af833 100644 --- a/doc/01-model/07-extensions.md +++ b/doc/01-model/07-extensions.md @@ -666,32 +666,18 @@ 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. - Predefined labels use the `ocm.software` prefix and a kebab-case local name. - - Their format is described by the following regexp: - - ```regexp - ocm\.software/[a-z][a-z0-9-]* - ``` + They use the reserved `ocm.software` DNS prefix. - vendor specific 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 `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 - /[a-z][a-z0-9-]* - ``` +All label names follow a hierarchical naming scheme based on DNS domain names, +conforming to the [Kubernetes label syntax and character set](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). +The label name is composed of a DNS domain owned by the providing organization, +followed by a slash (`/`) and a kebab-case local name +(for example `ocm.software/artefact-references` or `odg.ocm.software/binary-scan-policy`). ### Format Versions @@ -710,4 +696,4 @@ 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). | +| `ocm.software/artefact-references` | `v1` | Expresses a cross-artefact relationship within the same component version. See [Artefact-Linking Label](./06-conventions.md#artefact-linking-label). |