diff --git a/doc/01-model/06-conventions.md b/doc/01-model/06-conventions.md index e156ef9..aff5c42 100644 --- a/doc/01-model/06-conventions.md +++ b/doc/01-model/06-conventions.md @@ -29,3 +29,125 @@ 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 + +``` +ocm.software/artefact-references +``` + +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. + +### 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 derived artefacts of the subject. diff --git a/doc/01-model/07-extensions.md b/doc/01-model/07-extensions.md index 835625c..d8af833 100644 --- a/doc/01-model/07-extensions.md +++ b/doc/01-model/07-extensions.md @@ -666,35 +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. - 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. - - Their format is described by the following regexp: - - ```regexp - [a-z][a-zA-Z0-9]* - ``` + They use the reserved `ocm.software` DNS prefix. - 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 (`/`). - - So, the complete pattern looks as follows: - - ```regexp - /[a-z][a-zA-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 @@ -709,4 +692,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-references` | `v1` | Expresses a cross-artefact relationship within the same component version. See [Artefact-Linking Label](./06-conventions.md#artefact-linking-label). |