Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cleaned up Glossary and added "OCM Coordinates" term #113

Merged
merged 7 commits into from
Jun 3, 2024
Merged

Cleaned up Glossary and added "OCM Coordinates" term #113

Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3efe0b5
Cleaned up glossary
n-boshnakov May 23, 2024
78809cf
Added OCM Coordinates term
n-boshnakov May 23, 2024
15cd1a4
Resolved comment
n-boshnakov May 23, 2024
df1adec
Removed line
n-boshnakov May 23, 2024
35ae079
Resolved comments
n-boshnakov May 27, 2024
597e41e
Merge branch 'main' into add-ocm-coordinates-term
morri-son Jun 3, 2024
7c810e7
Merge branch 'main' into add-ocm-coordinates-term
morri-son Jun 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 42 additions & 76 deletions doc/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,49 +14,41 @@ The operations an implementation of an [access method](#accmeth) has to support.

### [Access Method Type](04-extensions/02-access-types/README.md)<a id="acctype"/>

The type of an [access specification](#accspec) determining the formal procedure
to use to access the blob content of an [artifact](#artifact).
The type of an [access specification](#accspec) determining the formal procedure to use to access the blob content of an [artifact](#artifact).
n-boshnakov marked this conversation as resolved.
Show resolved Hide resolved

### [Access Specification](01-model/07-extensions.md#access-specification)<a id="accspec"/>

The specification of the technical access path to the physical blob content of
An [artifact](#artifact).
The specification of the technical access path to the physical blob content of an [artifact](#artifact).
n-boshnakov marked this conversation as resolved.
Show resolved Hide resolved

### [Aggregation](02-processing/01-references.md)<a id="aggregation"/>

The ability of the Open Component Model to compose component versions
based on other component versions.
The ability of the Open Component Model to compose component versions based on other component versions.
n-boshnakov marked this conversation as resolved.
Show resolved Hide resolved

### [Artifact](01-model/02-elements-toplevel.md#artifacts-resources-and-sources)<a id="artifact"/>

Some blob content described by a [component version](#component-version).
Blob content described by a [component version](#component-version).
n-boshnakov marked this conversation as resolved.
Show resolved Hide resolved

### [Artifact Digest](02-processing/03-signing-process.md#determing-the-artifact-digests)<a id="artdigest"/>

The (logical) digest of an [artifact](#artifact).

### [Artifact Normalization](02-processing/06-artifact-normalization.md)<a id="artnorm"/>

The transformation of a technical blob content of an [artifact](#artifact) depending
on its type into a serialization-agnostic digest.
The transformation of a technical blob content of an [artifact](#artifact) depending on its type into a serialization-agnostic digest.

### [Artifact Reference](02-processing/01-references.md#referencing)<a id="artref"/>

A relative or absolute reference to an [artifact](#artifact) described by a
[component version](#compvers).
A relative or absolute reference to an [artifact](#artifact) described by a [component version](#compvers).

### [Artifact Type](01-model/02-elements-toplevel.md#artifact-types)<a id="arttype"/>

The formal type of an [artifact](#artifact) described by a
[component version](#compvers). The type implies the logical interpretation of
The artifact blob.
The formal type of an [artifact](#artifact) described by a [component version](#compvers). The type implies the logical interpretation of the artifact blob.

## C

### [Component](01-model/01-model.md#components-and-component-versions)<a id="component"/>

An abstract entity describing a dedicated usage context or
meaning for a provided piece of software.
An abstract entity describing a dedicated usage context or meaning for a provided piece of software.

### [Component Constructor](https://ocm.software/docs/getting-started/first-steps-with-ocm/#all-in-one)<a id="compconst"/>

Expand All @@ -68,8 +60,7 @@ The formal description of a [component version](#compvers).

### [Component Descriptor Normalization](02-processing/05-component-descriptor-normalization.md)<a id="compdescnorm"/>

The mapping of the elements of a [component descriptor](#compdesc) into an
immutable format containg only signature relevant information used to calculate a digest.
The mapping of the elements of a [component descriptor](#compdesc) into an immutable format containing only signature relevant information used to calculate a digest.

### [Component Identity](01-model/02-elements-toplevel.md#component-identity)<a id="compid"/>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check the linked content. Maybe we copy the text from the mail to here. The Component name should be added as own entry in the glossar, too, and also linked, same as the component version.

The Component identity consists of

  • Component Name: identifies component. Should follow conventions similar to DNS (start with URL-prefix controlled by Component-Owner)

  • Component Version: if used with a component name, identifies a specific Component Version. Must adhere to "relaxed Semver" (major, minor (+optional patchlevel) - optional v-prefix).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

considering the wording, I think immutable is not quite adequate. I think it would be better to call this form stable (iff [sic!] no content changes occur, the normalised form will remain unchanged).


Expand All @@ -81,9 +72,7 @@ An entity able to store and retrieve [component versions](#compvers). See also [

### [Component Version](01-model/01-model.md#components-and-component-versions)<a id="compvers"/>

A dedicated version of a [component](#component) described by the Open Component Model
described by a [component descriptor](#compdesc) and retrievable from
A [component repository](#comprep).
A dedicated version of a [component](#component) described by the Open Component Model described by a [component descriptor](#compdesc) and retrievable from a [component repository](#comprep).

n-boshnakov marked this conversation as resolved.
Show resolved Hide resolved
### [Component Version Digest](02-processing/05-component-descriptor-normalization.md#component-descriptor-normalization)<a id="compdigest"/>

Expand All @@ -95,8 +84,7 @@ The globally unique identity of a [component version](#compvers).

### [Component Version Reference](02-processing/01-references.md#referencing)<a id="compref"/>

A reference to a [component versions](#compvers) in a component version to
describe an aggregation relationship.
A reference to a [component versions](#compvers) in a component version to describe an aggregation relationship.
n-boshnakov marked this conversation as resolved.
Show resolved Hide resolved

## D

Expand All @@ -108,14 +96,11 @@ See [artifact digest](#artdigest) or [component version digest](#compdigest).

### [Element Identity](./01-model/03-elements-sub.md#element-identity)<a id="elemid"/>

Similar to component identity, the element identity is composed by the fields `name` and `version`.
In additon to that sources, resources and references can have an [extraIdentity](#extraid) if required.
Similar to component identity, the element identity is composed by the fields `name` and `version`. In addition to that, sources, resources, and references can have an [extraIdentity](#extraid) if required.

### [Extension Point](./03-persistence/01-operations.md#abstract-operations-defined-by-the-open-component-model)<a id="ext"/>

Parts of the [OCM](#ocm) specification, which may be extended by arbitrary
variations. The specification just defines the meaning, syntax and or functional
behaviour of such elements.
Parts of the [OCM](#ocm) specification, which may be extended by arbitrary variations. The specification just defines the meaning, syntax and or functional behavior of such elements.

### [Extra Identity](./01-model/03-elements-sub.md#element-identity)<a id="extraid"/>

Expand All @@ -125,18 +110,17 @@ Additional parts of the identity of an [element](#elemid) of a [component versio

### [gitHub](./04-extensions/02-access-types/github.md)<a id="github"/>

[access method](#accmeth) used to access Git commits in a GitHub repository.
An [access method](#accmeth) used to access Git commits in a GitHub repository.

## H

### [helm](./04-extensions/02-access-types/helm.md)<a id="helm"/>

[access method](#accmeth) used to access [Helm Charts](#helmchart) in a Helm repository.
An [access method](#accmeth) used to access [Helm Charts](#helmchart) in a Helm repository.

### Helm Chart<a id="helmchart"/>

A set of files describing the deplyoment of a Kubernetes application using
The [Helm](https://helm.sh/) deployment mechanism.
A set of files describing the deployment of a Kubernetes application using the [Helm](https://helm.sh/) deployment mechanism.

See [element identity](#elemid), [component identity](#compid), [component version identity](#compversid)

Expand All @@ -150,17 +134,15 @@ See [element identity](#elemid), [component identity](#compid), [component versi

### [Labels](01-model/03-elements-sub.md#labels)<a id="labels"/>

Arbitrary typed information snippets attached to [component versions](#compvers),
[artifacts](#artifact) and [references](#compref).
Arbitrary typed information snippets attached to [component versions](#compvers), [artifacts](#artifact), and [references](#compref).

### [localBlob](./04-extensions/02-access-types/localblob.md)<a id="localblob"/>

[access method](#accmeth) used to access blobs stored along with a component version.
An [access method](#accmeth) used to access blobs stored along with a component version.

### [Localization](./05-guidelines/02-contract.md#example-helm-deployment)<a id="localization"/>

The process of adapting content delivered as [artifacts](#artifact) in a [component versions](#compvers)
to a local repository landscape in a target environment.
The process of adapting content delivered as [artifacts](#artifact) in a [component versions](#compvers) to a local repository landscape in a target environment.

## M

Expand All @@ -170,72 +152,63 @@ The mapping of the [elements](01-model/02-elements-toplevel.md) of the Open Comp

### [Model-Tool Contract](./05-guidelines/02-contract.md)<a id="contract"/>

The agreement between the Open Component Model and tools working with content
provided by [component versions](#compvers), which regulates the cooperation
between both.
The agreement between the Open Component Model and tools working with content provided by [component versions](#compvers), which regulates the cooperation between both.

## N

### [Normalization](02-processing/03-signing-process.md#signing-process-and-normalization)<a id="norm"/>

The transformation which can be used to calculate an immutable digest for signing purposes along a transportation path. There are two normalization procedures, [artifact normalization](#artnorm) and
[component descriptor normalization](#compdescnorm).
The transformation which can be used to calculate an immutable digest for signing purposes along a transportation path. There are two normalization procedures, [artifact normalization](#artnorm) and [component descriptor normalization](#compdescnorm).

### [npm](./04-extensions/02-access-types/npm.md)<a id="npm"/>

[access method](#accmeth) used to access NodeJS packages in an NPM repository.
An [access method](#accmeth) used to access NodeJS packages in an NPM repository.

## O

### [ociArtifact](./04-extensions/02-access-types/ociartifact.md)<a id="ociartifact"/>

[access method](#accmeth) used to access OCI artifacts stored in an OCI registry.
An [access method](#accmeth) used to access OCI artifacts stored in an OCI registry.

### [ociBlob](./04-extensions/02-access-types/ociblob.md)<a id="ociblob"/>

[access method](#accmeth) used to access blobs stored in an OCI registry.
An [access method](#accmeth) used to access blobs stored in an OCI registry.

### [Open Component Model](../README.md)<a id="ocm"/>

A technology- and location-agnostic description model for software delivery
Artifacts with attached meta-data, providing environment-specific access
path to described [artifacts](#artifact).
A technology- and location-agnostic description model for software delivery artifacts with attached meta-data, providing environment-specific access path to described [artifacts](#artifact).

### OCM Coordinates

Hierarchically organized identifiers for the versions of OCM components (called `Component Identity`) and contained artifacts (called `Artifact Identity`).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the OCM coordinates will become a central term, I guess we can take over the full text of the mail to the glossary, although it contains many other definitions. This makes it easier to consume all information at one place without having the need to follow the links. @n-boshnakov what do you think?

OCM Coordinates are used to reference OCM Component Versions and artefacts within OCM Component Versions. Coordinates referring to an OCM Component Version are also called Component Identity, whereas relative coordinates referring to an artefact are called Artefact Identity. Component Identities are globally unique and may be used to refer to full Component Versions. Artefact Identities are always relative to an OCM Component Version and may only be used in conjunction with a Component Identity.

In detail:

Component Identity

  • Component Name: identifies component. Should follow conventions similar to DNS (start with URL-prefix controlled by Component-Owner)
  • Component Version: if used with a component name, identifies a specific Component Version. Must adhere to "relaxed Semver" (major, minor (+optional patchlevel) - optional v-prefix).

Artefact Identity
Within a Component Version, all artefacts must have a unique identity. The identity always includes:

  • Kind (artefacts are either sources or resources)
  • Name: A name (typically used to express the intended purpose)

Artefacts may also have additional attributes (called extraIdentity) that contribute to their identities. extraIdentity attributes are string-to-string maps.

Examples

Assuming there is a component named example.org/my-component, with two versions 1.2.3 and 1.3.0, declaring a resource named my-resource, then the following OCM Coordinates can be used to reference different things:

  • example.org/my-component: all versions of the component (1.2.3 + 1.3.0)
  • example.org/my-component:1.2.3: version 1.2.3 of the component
  • example.org/my-component:1.2.3:resource/my-resource: my-resource as declared by the component version

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The glossary should be a place for short definitions only. What we could do is take the content of the email and place it in a separate topic, then link to it from the term.

As the content of the email is already formatted in Markdown, this leads me to believe that it already exists somewhere as a topic, therefore we could just link to it. If that is not true, however, I could create a new topic with that content in this repository and link to it instead. I just need to know the correct folder to place the topic in.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@n-boshnakov : it is formatted in markdown mostly because I write in markdown(-ish) as a habit. the text was written ad-hoc.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In that case, I think it would be best if this information is placed in a repo as a topic. We can then link it to the new term being introduced for ease of access.


### Operations <a id="ops"/>

See [repository operations](#repops), [access methods](#accmeth) and
[access method operations](#accmethops).
See [repository operations](#repops), [access methods](#accmeth), and [access method operations](#accmethops).

## P

### [Platform Convention](01-model/06-conventions.md#operating-system-and-cpu-architecture)) <a id="osarch"/>
### [Platform Convention](01-model/06-conventions.md#operating-system-and-cpu-architecture) <a id="osarch"/>

Using extra identities to express the assignment of an [artifact](#artifact) to a dedicated
execution platform.
Using extra identities to express the assignment of an [artifact](#artifact) to a dedicated execution platform.

## R

### Reference <a id="ref"/>

A reference to an element of the component model, see [artifact reference](#artref)
or [component version reference](#compref)
A reference to an element of the component model, see [artifact reference](#artref) or [component version reference](#compref).

### [Relative Resource Refererences](02-processing/01-references.md#relative-artifact-references)<a id="relrefs"/>

A reference to an [artifact](#artifact) described by a [component version](#compvers) relative to
A given component version exploiting the [aggregation feature](#aggregation) of the Open Component
Model. It is part of the [model-tool contract](#contract).
A reference to an [artifact](#artifact) described by a [component version](#compvers) relative to a given component version exploiting the [aggregation feature](#aggregation) of the Open Component Model. It is part of the [model-tool contract](#contract).

### [Repository Operations](03-persistence/01-operations.md#repository-operations)<a id="repops"/>

Abstract operations that have to be provided by a language binding for a
[mapping](#mapping) of the [Open Component Model](#ocm) to a dedicated storage
technology.
Abstract operations that have to be provided by a language binding for a [mapping](#mapping) of the [Open Component Model](#ocm) to a dedicated storage technology.

### [Repository Type](./03-persistence/02-mappings.md#mappings-for-ocm-persistence)<a id="repotype"/>

The type of a [mapping](#mapping) of the [Open Component Model](#ocm) specification
to a storage technology.
The type of a [mapping](#mapping) of the [Open Component Model](#ocm) specification to a storage technology.

### [Resource](01-model/02-elements-toplevel.md#resources)<a id="resource"/>

Expand All @@ -245,33 +218,26 @@ A delivery artifact described by a [component version](#compvers).

### [Signature](02-processing/02-signing.md#signing)<a id="signature"/>

A [component version](#compvers) may be signed by an authority, the signature as
result of such a signing process is stored along with the component version.
A [component version](#compvers) may be signed by an authority, the signature as result of such a signing process is stored along with the component version.

### [Source](01-model/02-elements-toplevel.md#sources)<a id="source"/>

An artifact described by a [component version](#compvers) containing sources
used to generate one or more of the described [resources](#resource).
An artifact described by a [component version](#compvers) containing sources used to generate one or more of the described [resources](#resource).

### Specification Format

A format definition for the specification of attributes for
dedicated variants of some [extension points](#ext). See [access methods](#accmeth),
[repository types](#repotype), and [labels](#labels).
A format definition for the specification of attributes for dedicated variants of some [extension points](#ext). See [access methods](#accmeth), [repository types](#repotype), and [labels](#labels).

### [s3](./04-extensions/02-access-types/s3.md)<a id="s3"/>

[access method](#accmeth) used to access blobs in an S3 repository, a [mapping](#mapping) to store content in an S3 repository
An [access method](#accmeth) used to access blobs in an S3 repository, a [mapping](#mapping) to store content in an S3 repository

## T

### [Transport](05-guidelines/01-transport.md)<a id="transport"/>

The operation on [component versions](#compvers) transferring content from
one OCM repository into another one.
The operation on [component versions](#compvers) transferring content from one OCM repository into another one.

### Type<a id="type"/>

A formal representation of the kind of an [extension point](#ext) of the
[Open Component Model](#ocm). See [repository type](#repotype),
[access method type](#acctype), [artifact type](#arttype) [label](#labels).
A formal representation of the kind of an [extension point](#ext) of the [Open Component Model](#ocm). See [repository type](#repotype), [access method type](#acctype), [artifact type](#arttype), [label](#labels).