diff --git a/README.md b/README.md index 7fa3669..25c41c4 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,7 @@ The following chapters provide a formal description of the format to describe so * 4.4.2 [Digest Algorithms](doc/04-extensions/04-algorithms/label-merge-algorithms.md) * 4.4.3 [Label Merge Algorithm](doc/04-extensions/04-algorithms/digest-algorithms.md) * 4.4.4 [Component Descriptor Normalization Algorithms](doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md) - * 4.4.5 [Signing Algorithms](doc/04-algorithms/04-algorithms/signing-algorithms.md) + * 4.4.5 [Signing Algorithms](doc/04-extensions/04-algorithms/signing-algorithms.md) ### Guidelines and Conventions diff --git a/doc/01-model/06-conventions.md b/doc/01-model/06-conventions.md index df3cfc4..46d761c 100644 --- a/doc/01-model/06-conventions.md +++ b/doc/01-model/06-conventions.md @@ -26,6 +26,6 @@ If platform specific images are described as separate resources instead of using ## Selection of Usage Scenarios -Usage scenarios for sets of described artifacts are best described by a dedicated [description artifacts](../../specification/contract/README.md#how-does-it-look-like-in-the-open-component-model) 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. +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. diff --git a/doc/02-processing/03-signing-process.md b/doc/02-processing/03-signing-process.md index 5a837e0..a750719 100644 --- a/doc/02-processing/03-signing-process.md +++ b/doc/02-processing/03-signing-process.md @@ -76,7 +76,7 @@ Normalization algorithm types may be versioned and SHOULD match the following re For example: `ociArtifactDigest/v1` or `jsonNormalisationV2` -The normalization algorithms are listed in the [extensible parts](../04-extensions/01-extensions.md#normalization-algorithms) of the specification +The normalization algorithms are listed in the [extensible parts](../04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md) of the specification ## Serialization Format diff --git a/doc/02-processing/05-component-descriptor-normalization.md b/doc/02-processing/05-component-descriptor-normalization.md index 2b8c551..10a7db4 100644 --- a/doc/02-processing/05-component-descriptor-normalization.md +++ b/doc/02-processing/05-component-descriptor-normalization.md @@ -20,7 +20,7 @@ A normalized component descriptor is a subset of its elements containing only th Like for signature algorithms, the model offers the possibility to work with different normalization algorithms and formats. -The algorithms used for normalization are listed in the [extensible parts](../04-extensions/01-extensions.md#normalization-algorithms) of the specification. +The algorithms used for normalization are listed in the [extensible parts](../04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md) of the specification. ## Signing-relevant Information in Component Descriptors diff --git a/doc/03-persistence/02-mappings.md b/doc/03-persistence/02-mappings.md index a21bee9..f1a23c5 100644 --- a/doc/03-persistence/02-mappings.md +++ b/doc/03-persistence/02-mappings.md @@ -4,7 +4,7 @@ This chapter describes how OCM model elements are mapped to elements of a persis OCM model elements are mapped to various storage technologies. The interoperability layer for a client tool is typically the API of the storage backend. This avoids the need for providing an OCM server infrastructure. -An implementation of this layer MUST implement this mapping by supporting the [mandatory abstract model operations](./01-operations#mandatory-operations). It SHOULD implement the [optional operations](./01-operations#optional-operations) too. +An implementation of this layer MUST implement this mapping by supporting the [mandatory abstract model operations](./01-operations.md#mandatory-operations). It SHOULD implement the [optional operations](./01-operations#optional-operations) too. ## Storage Backend Mappings for the Open Component Model diff --git a/doc/04-extensions/01-artifact-types/README.md b/doc/04-extensions/01-artifact-types/README.md index e8fd144..b435b97 100644 --- a/doc/04-extensions/01-artifact-types/README.md +++ b/doc/04-extensions/01-artifact-types/README.md @@ -31,5 +31,5 @@ Some additional types are defined, but not part of the core specification. Suppo | TYPE NAME |DESCRIPTION | |--------------------|-------------------------------------| | [`blueprint`](blueprint.md) | An installation description for the [landscaper](https://github.com/gardener/landscaper) installation | -| [`toiExecutor`](toiExecutor.md) | A toolset for simple installation in the [OCM CLI](https://github.com/open-component-model/ocm/blob/cm_toi.md) installation environment. | -| [`toiPackage`](toiPackackage.md) | A YAML resource describing the installation for the [OCM CLI](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi.md) TOI installation. | +| [`toiExecutor`](toiexecutor.md) | A toolset for simple installation in the [OCM CLI](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi.md) installation environment. | +| [`toiPackage`](toipackage.md) | A YAML resource describing the installation for the [OCM CLI](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi.md) TOI installation. | diff --git a/doc/04-extensions/01-artifact-types/helmchart.md b/doc/04-extensions/01-artifact-types/helmchart.md index 4c0fbf7..7ddd41e 100644 --- a/doc/04-extensions/01-artifact-types/helmchart.md +++ b/doc/04-extensions/01-artifact-types/helmchart.md @@ -12,7 +12,7 @@ A Kubernetes installation resource representing a Helm chart, either stored as O - **OCI Artifact** - A Helm chart might be stored as OCI artifact following the [Artifact Set Archive Format](../common/formatspec.md#artifact-set-archive-format). This format is for example provided by the access method type [`ociArtifact`](../02-access-types/oci-artifact.md) + A Helm chart might be stored as OCI artifact following the [Artifact Set Archive Format](../common/formatspec.md#artifact-set-archive-format). This format is for example provided by the access method type [`ociArtifact`](../02-access-types/ociartifact.md) Media types: - `application/vnd.oci.image.manifest.v1+tar` diff --git a/doc/04-extensions/01-artifact-types/toiexecutor.md b/doc/04-extensions/01-artifact-types/toiexecutor.md index a848329..ec74d17 100644 --- a/doc/04-extensions/01-artifact-types/toiexecutor.md +++ b/doc/04-extensions/01-artifact-types/toiexecutor.md @@ -11,5 +11,5 @@ steps based on content described by the Open Component Model A TOI executor is YAML resource describing the features of an TOI executor image. -It is used by a [`toiPackage` resource](toiPackage.md), which +It is used by a [`toiPackage` resource](./toipackage.md), which describes its instantiation for a dedicated installation object. diff --git a/doc/04-extensions/README.md b/doc/04-extensions/README.md index 60d443a..9fbf309 100644 --- a/doc/04-extensions/README.md +++ b/doc/04-extensions/README.md @@ -18,18 +18,18 @@ addendums or for customer-specific environments. * 1.8 [executable](01-artifact-types/executable.md) * 1.9 [sbom](01-artifact-types/sbom.md) * 2 [Access Method Types](02-access-types/README.md) - * 2.1 [localBlob](02-access-typeslocalblob.md) - * 2.2 [ociArtifact](02-access-typesociartifact.md) - * 2.3 [ociBlob](02-access-typesociblob.md) - * 2.4 [helm](h02-access-typeselm.md) - * 2.5 [gitHub](02-access-typesgithub.md) - * 2.6 [s3](02-access-typess3.md) - * 2.7 [npm](02-access-typesnpm.md) + * 2.1 [localBlob](02-access-types/localblob.md) + * 2.2 [ociArtifact](02-access-types/ociartifact.md) + * 2.3 [ociBlob](02-access-types/ociblob.md) + * 2.4 [helm](h02-access-types/elm.md) + * 2.5 [gitHub](02-access-types/github.md) + * 2.6 [s3](02-access-types/s3.md) + * 2.7 [npm](02-access-types/npm.md) * 3 [Storage Backend Mappings](03-storage-backends/README.md) - * 3.1 [OCIRegistry](03-storage-backendsoci.md) - * 3.2 [FileSystem (CTF)](03-storage-backendsctf.md) - * 3.3 [FileSystem (Component Archive)](03-storage-backendscomponent-archive.md) - * 3.4 [AWS S3](03-storage-backendss3.md) + * 3.1 [OCIRegistry](03-storage-backends/oci.md) + * 3.2 [FileSystem (CTF)](03-storage-backends/ctf.md) + * 3.3 [FileSystem (Component Archive)](03-storage-backends/component-archive.md) + * 3.4 [AWS S3](03-storage-backends/s3.md) * 4 [Algorithms](04-algorithms/README.md) * 4.1 [Artifact Normalization](04-algorithms/artifact-normalization-types.md) * 4.2 [Digest Algorithms](04-algorithms/label-merge-algorithms.md) diff --git a/doc/04-extensions/common/formatspec.md b/doc/04-extensions/common/formatspec.md index 6017c6c..ce0fb36 100644 --- a/doc/04-extensions/common/formatspec.md +++ b/doc/04-extensions/common/formatspec.md @@ -172,7 +172,7 @@ It is a directory containing - **`component-descriptor.yaml`** *YAML file* - This yaml is the serialized form of a [component descriptor](../../specification/elements#component-descriptor). + This yaml is the serialized form of a [component descriptor](../../01-model/01-model.md#components-and-component-versions). - **`blobs`** *directory* @@ -182,7 +182,7 @@ It is a directory containing Hereby the algorithm separator character is replaced by a dot ("."). Every file SHOULD be referenced, directly or indirectly, in the component descriptor by a - [`localBlob` access specification](../../appendix/B/localBlob.md). The `localReference` value is the file name of the blob file in the `blobs` directory. + [`localBlob` access specification](../../04-extensions/01-artifact-types/blob.md). The `localReference` value is the file name of the blob file in the `blobs` directory. This format might be used in various technical forms: as structure of an operating system file system, a virtual file system or as content of diff --git a/doc/glossary.md b/doc/glossary.md index 952ecdb..83071dd 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -8,11 +8,11 @@ defines how to access the content of an [artifact](#artifact) -### [Access Method Operations](03-operations/01-operations.md#access-method-operations) +### [Access Method Operations](01-model/07-extensions.md#access-method-operations) the operations an implementation of an [access method](#accmeth) has to support. -### [Access Method Type](01-model/02-elements.md/#access-types) +### [Access Method Type](04-extensions/02-access-types/README.md) the type of an [access specification](#accspec) determining the formal procedure to use to access the blob content of an [artifact](#artifact). @@ -40,7 +40,7 @@ the (logical) digest of an [artifact](#artifact). 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#referencing) +### [Artifact Reference](02-processing/01-references.md#referencing) a relative or absolute reference to an [artifact](#artifact) described by a [component version](#compvers). @@ -156,7 +156,7 @@ the process of adapting content delivered as [artifacts](#artifacts) in a [compo ### [Mapping](./03-persistence/02-mappings.md#mappings-for-ocm-persistence) -the mapping of the [elements](01-model/02-elements.md) of the Open Component Model onto a storage technology described by a [repository type](#repotype). +the mapping of the [elements](01-model/02-elements-toplevel.md) of the Open Component Model onto a storage technology described by a [repository type](#repotype). ### [Model-Tool Contract](./05-guidelines/02-contract.md) @@ -216,13 +216,13 @@ a reference to an [artifact](#artifact) described by a [component version](#comp 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/0-operations.md) +### [Repository Operations](03-persistence/01-operations.md#repository-operations) 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](./04-persistence/01-mappings.md#mappings-for-ocm-persistence) +### [Repository Type](./03-persistence/02-mappings.md#mappings-for-ocm-persistence) the type of a [mapping](#mapping) of the [Open Component Model](#ocm) specification to a storage technology. @@ -233,7 +233,7 @@ a delivery artifact described by a [component version](#compvers). ## S -### [Signature](02-processing/03-signing.md#signing) +### [Signature](02-processing/02-signing.md#signing) 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. @@ -255,7 +255,7 @@ dedicated variants of some [extension points](#ext). See [access methods](#accme ## T -### [Transport](02-guidelines/01-transport.md) +### [Transport](05-guidelines/01-transport.md) the operation on [component versions](#compvers) transferring content from one OCM repository into another one.