ocm-labels

Description#

Labels are a set of arbitrary properties, which can be attached to elements of a component version:

• a component version itself
• the provider of a component version
• resources
• sources
• component references

The dedicated elements support this by providing a field labels, which is a list of label definitions. Every label definition has several fields:

• name string

  The name of the label also determines the interpretation of its value. All labels with a dedicated name must have the same globally unique meaning, enabling a common understanding of label content for tools working of such properties of an element.

  There are several predefined labels, they just use flat names. To guarantee globally unique meanings of labels a label name may have a hierarchical structure. Names defined in dedicated definition realms must be prefixed by a DNS domain-like string identifying the organization of realm defining the label’s value structure. For example: acme.org/maturity/level.

  Hereby, the name defines the meaning of the value and its value structure. To support the evolution of the value structure a label field optionally contains a version field, which finally defines the concrete value structure in the context of the meaning of the label name. A version is just a number prefixed with a v. If not specified, the version v1 is assumed.

• version string (optional) (default: v1)

  The format version of the label value in the context of the label name.

• value any

  The value of the label according to the specified format version of the label in the context of its name.

• signing bool (optional)

  By default, labels are not signature-relevant and they will nor influence the digest of the component version. This allows adding, deleting or modifying labels as part of a process chain during the lifecycle of a component version.

  Labels which should describe relevant and unmodifiable content can be marked to be signing relevant by setting this label field to true.

• merge merge spec (optional)

  Modifiable labels can be changed independently in any transport target location of a component version. This might require to update label values when importing a new setting for a component version. This means a merging of content to reflect the combination of changes in the transport source and target.

  This is supported by the possibility to specify merge algorithms. The can be bound to a dedicated label incarnation or to the label name.

Merge Specification#

A merge specification consists of two fields:

• algorithm string (optional) (default: default)

  The name of the algorithm to be used for the merge process.

• config any (optional)

  An algorithm specific configuration to control the merge process.

There is an often used configuration field overwrite with a common meaning for all algorithms supporting it. It controls the conflict resolution and has the following values:

• none: conflicting values prevent the merging. An update transfer process will be aborted.

• local: a conflict will be resolved to the local change (in the target environment)

• inbound: a conflict will be resolved to the value provided by the source environment

• <empty>: use a default provided by the dedicated algorithm.

The default behaviour might mean to apply a cascaded merge specification, if the merge specification supports to specify appropriate fields to specify this specification (for example a field entries).

Determining a Merge Specification#

A merge specification directly attached to a label is always preferred. If no algorithm is specified a merge assignment for the label name and its version is evaluated. The assignment hint is composed with

The label version is defaulted to v1.

Supported Merge Algorithms#

There are some built-in algorithms featuring a flat name. But it will be possible to add arbitrary algorithms using the plugin concept.

The following algorithms are possible:

• default (default): This handler merges arbitrary label values by deciding for one or none side.

  It supports the following config structure:

  • overwrite string (optional) determines how to handle conflicts.

    • none no change possible, if entry differs the merge is rejected.
    • local the local value is preserved.
    • inbound (default) the inbound value overwrites the local one.

• mapListMerge: This handler merges values with a list of map values by observing a key field to identify similar map entries. The default entry key is taken from map field name.

  It supports the following config structure:

  • keyField string (optional)

    the key field to identify entries in the maps.

  • overwrite string (optional) determines how to handle conflicts.

    • none (default) no change possible, if entry differs the merge is rejected.
    • local the local value is preserved.
    • inbound the inbound value overwrites the local one.

  • *entries merge spec (optional)

    The merge specification (algorithm and config) used to merge conflicting changes in list entries.

• simpleListMerge: This handler merges simple list labels values.

  It supports the following config structure:

  • overwrite string (optional) determines how to handle conflicts.

• simpleMapMerge: This handler merges simple map labels values.

  It supports the following config structure:

  • overwrite string (optional) determines how to handle conflicts.

    • none (default) no change possible, if entry differs the merge is rejected.
    • local the local value is preserved.
    • inbound the inbound value overwrites the local one.

  • *entries merge spec (optional)

    The merge specification (algorithm and config) used to merge conflicting changes in map entries.

The following label assignments are configured:

• label:routing-slips: simpleMapMerge

See Also#