From 2797fe25a012aea15e9e525634c76eaf9e5852ba Mon Sep 17 00:00:00 2001 From: "Gerald Morrison (SAP)" Date: Fri, 10 Apr 2026 15:14:35 +0200 Subject: [PATCH 01/14] docs: align access type notation to UpperCamelCase MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename canonical access type names to UpperCamelCase as the default: - ociArtifact → OCIImage - ociBlob → OCIImageLayer - helm → Helm The lowercase forms remain as backward-compatible aliases. localBlob is intentionally left unchanged (deferred to a later PR). Updates access type spec docs, README table, and example documents. Ref: open-component-model/ocm-project#962 On-behalf-of: Gerald Morrison (SAP) Signed-off-by: Gerald Morrison (SAP) --- doc/01-model/04-example.md | 6 +++--- doc/02-processing/04-signing-examples.md | 8 ++++---- doc/04-extensions/02-access-types/README.md | 8 ++++---- doc/04-extensions/02-access-types/helm.md | 8 +++++--- doc/04-extensions/02-access-types/ociartifact.md | 6 ++++-- doc/04-extensions/02-access-types/ociblob.md | 6 ++++-- 6 files changed, 24 insertions(+), 18 deletions(-) diff --git a/doc/01-model/04-example.md b/doc/01-model/04-example.md index 9b0a304..c093e9c 100644 --- a/doc/01-model/04-example.md +++ b/doc/01-model/04-example.md @@ -30,7 +30,7 @@ component: relation: external # resource is provided by a different entity than the component access: # access information how to locate this resource imageReference: gcr.io/google_containers/echoserver:1.10 - type: ociArtifact + type: OCIImage digest: # digest of this resource used for signing hashAlgorithm: sha256 normalisationAlgorithm: ociArtifactDigest/v1 @@ -41,7 +41,7 @@ component: relation: local # resource is provided by the same entity as the component access: # access information how to locate this resource imageReference: ghcr.io/jensh007/ctf/github.com/open-component-model/ocmechoserver/echoserver:0.1.0 - type: ociArtifact + type: OCIImage digest: # digest of this resource used for signing hashAlgorithm: sha256 normalisationAlgorithm: ociArtifactDigest/v1 @@ -56,7 +56,7 @@ component: mediaType: application/vnd.toi.ocm.software.package.v1+yaml ref: ghcr.io/jensh007/ctf/component-descriptors/github.com/open-component-model/ocmechoserver size: 615 - type: ociBlob + type: OCIImageLayer localReference: sha256:57563cb451bb79eb1c4bf0e71c66fdad1daf44fe55e128f12eae5f7e5496a188 mediaType: application/vnd.toi.ocm.software.package.v1+yaml type: localBlob diff --git a/doc/02-processing/04-signing-examples.md b/doc/02-processing/04-signing-examples.md index bde6086..acc82f6 100644 --- a/doc/02-processing/04-signing-examples.md +++ b/doc/02-processing/04-signing-examples.md @@ -26,7 +26,7 @@ spec: version: 0.1.0 - access: imageReference: gcr.io/google_containers/echoserver:1.10 - type: ociArtifact + type: OCIImage name: image relation: external type: ociImage @@ -87,7 +87,7 @@ spec: version: 0.1.0 - access: imageReference: gcr.io/google_containers/echoserver:1.10 - type: ociArtifact + type: OCIImage digest: hashAlgorithm: SHA-256 normalisationAlgorithm: ociArtifactDigest/v1 @@ -127,7 +127,7 @@ spec: resources: - access: imageReference: gcr.io/google_containers/pause:3.2 - type: ociArtifact + type: OCIImage name: image relation: external type: ociImage @@ -175,7 +175,7 @@ spec: resources: - access: imageReference: gcr.io/google_containers/pause:3.2 - type: ociArtifact + type: OCIImage digest: hashAlgorithm: SHA-256 normalisationAlgorithm: ociArtifactDigest/v1 diff --git a/doc/04-extensions/02-access-types/README.md b/doc/04-extensions/02-access-types/README.md index 617f4b0..9711666 100644 --- a/doc/04-extensions/02-access-types/README.md +++ b/doc/04-extensions/02-access-types/README.md @@ -10,10 +10,10 @@ The following access method types are centrally defined: | TYPE NAME | DESCRIPTION | |---------------------------------|-----------------------------------------------------| -| [`localBlob`](localblob.md) | an artifact stored along with the component version | -| [`ociArtifact`](ociartifact.md) | an artifact in a repository of an OCI registry | -| [`ociBlob`](ociblob.md) | a blob in a repository of an OCI registry | -| [`helm`](helm.md) | a Helm chart stored in a Helm Repository | +| [`localBlob`](localblob.md) | an artifact stored along with the component version | +| [`OCIImage`](ociartifact.md) | an artifact in a repository of an OCI registry | +| [`OCIImageLayer`](ociblob.md) | a blob in a repository of an OCI registry | +| [`Helm`](helm.md) | a Helm chart stored in a Helm Repository | | [`gitHub`](github.md) | a commit in a GitHub-based Git repository | | [`s3`](s3.md) | a blob stored in an AWS S3 bucket | | [`npm`](npm.md) | a NodeJS package stored in an NPM repository | diff --git a/doc/04-extensions/02-access-types/helm.md b/doc/04-extensions/02-access-types/helm.md index 9c3eb56..bbbe079 100644 --- a/doc/04-extensions/02-access-types/helm.md +++ b/doc/04-extensions/02-access-types/helm.md @@ -1,12 +1,14 @@ -# helm — Helm Package in Helm Repository +# Helm — Helm Package in Helm Repository -*Synopsis:* +## Synopsis ```text -type: helm[/VERSION] +type: Helm[/VERSION] [ATTRIBUTES] ``` +Legacy type name `helm` is supported as a backward-compatible alias. + ## Description Access to a Helm chart in a Helm repository. diff --git a/doc/04-extensions/02-access-types/ociartifact.md b/doc/04-extensions/02-access-types/ociartifact.md index 973b5d4..f964e60 100644 --- a/doc/04-extensions/02-access-types/ociartifact.md +++ b/doc/04-extensions/02-access-types/ociartifact.md @@ -1,12 +1,14 @@ -# ociArtifact — Artifact hosted in OCI Repository +# OCIImage — Artifact hosted in OCI Repository ## Synopsis ```text -type: ociArtifact[/VERSION] +type: OCIImage[/VERSION] [ATTRIBUTES] ``` +Legacy type name `ociArtifact` is supported as a backward-compatible alias. + ## Description Access of an OCI artifact stored in an OCI registry. diff --git a/doc/04-extensions/02-access-types/ociblob.md b/doc/04-extensions/02-access-types/ociblob.md index a59f52b..30f8805 100644 --- a/doc/04-extensions/02-access-types/ociblob.md +++ b/doc/04-extensions/02-access-types/ociblob.md @@ -1,12 +1,14 @@ -# ociBlob — Blob hosted in OCI Repository +# OCIImageLayer — Blob hosted in OCI Repository ## Synopsis ```text -type: ociBlob[/VERSION] +type: OCIImageLayer[/VERSION] [ATTRIBUTES] ``` +Legacy type name `ociBlob` is supported as a backward-compatible alias. + ## Description Access of an OCI blob stored in an OCI repository. From 4c63cf16abbe7e82637696f85d61681ffa9e8a9c Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Mon, 16 Mar 2026 12:52:56 +0100 Subject: [PATCH 02/14] chore: bump and pin versions in markdown linter workflow (#136) On-behalf-of: Gerald Morrison (SAP) #### What this PR does / why we need it pin to digests and bump versions Signed-off-by: Gerald Morrison (SAP) Co-authored-by: Gerald Morrison (SAP) Signed-off-by: Gerald Morrison (SAP) On-behalf-of: Gerald Morrison (SAP) --- .github/workflows/markdown-analysis.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/markdown-analysis.yml b/.github/workflows/markdown-analysis.yml index 2db8f7c..b2a58dc 100644 --- a/.github/workflows/markdown-analysis.yml +++ b/.github/workflows/markdown-analysis.yml @@ -18,13 +18,13 @@ jobs: name: 'github actions: markdownlint' steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 - name: markdownlint - uses: nosborn/github-action-markdown-cli@v1.1.1 + uses: nosborn/github-action-markdown-cli@508d6cefd8f0cc99eab5d2d4685b1d5f470042c1 # v3 with: files: . config_file: ./.github/.markdownlint.yml - name: markdown link check - uses: gaurav-nelson/github-action-markdown-link-check@v1 + uses: gaurav-nelson/github-action-markdown-link-check@5c5dfc0ac2e225883c0e5f03a85311ec2830d368 #v1 with: config-file: ./.github/.markdown-link-check.json From b95925dfb1eb9aac6516b041f891d5c11db7e8ab Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Mon, 16 Mar 2026 14:13:22 +0100 Subject: [PATCH 03/14] chore: Align markdown linters with all our other repos (#137) #### What this PR does / why we need it align markdown linters with our other repositories --------- Signed-off-by: Gerald Morrison (SAP) Co-authored-by: Gerald Morrison (SAP) Signed-off-by: Gerald Morrison (SAP) On-behalf-of: Gerald Morrison (SAP) --- .github/.markdown-link-check.json | 13 - .github/.markdownlint.yml | 5 - .github/config/.markdownlint-cli2.yaml | 13 + .github/config/linkspector.yml | 5 + .github/config/spellcheck.yml | 35 +++ .github/config/wordlist.txt | 137 ++++++++++ .github/workflows/markdown-analysis.yml | 30 --- .github/workflows/verify-markdown.yml | 50 ++++ README.md | 24 +- doc/01-model/01-model.md | 4 +- doc/01-model/02-elements-toplevel.md | 6 +- doc/01-model/03-elements-sub.md | 2 +- doc/01-model/06-conventions.md | 6 +- doc/01-model/07-extensions.md | 21 +- doc/02-processing/03-signing-process.md | 4 +- .../06-artifact-normalization.md | 4 +- doc/02-processing/README.md | 6 +- doc/04-extensions/01-artifact-types/blob.md | 2 +- .../01-artifact-types/toipackage.md | 2 +- .../03-storage-backends/README.md | 4 +- doc/04-extensions/03-storage-backends/oci.md | 28 +-- ...ent-descriptor-normalization-algorithms.md | 238 +++++++++++++++++- .../04-algorithms/signing-algorithms.md | 2 +- doc/04-extensions/README.md | 2 +- doc/04-extensions/common/formatspec.md | 4 +- doc/05-guidelines/01-transport.md | 6 +- doc/05-guidelines/02-contract.md | 10 +- doc/05-guidelines/README.md | 2 +- doc/glossary.md | 6 +- 29 files changed, 537 insertions(+), 134 deletions(-) delete mode 100644 .github/.markdown-link-check.json delete mode 100644 .github/.markdownlint.yml create mode 100644 .github/config/.markdownlint-cli2.yaml create mode 100644 .github/config/linkspector.yml create mode 100644 .github/config/spellcheck.yml create mode 100644 .github/config/wordlist.txt delete mode 100644 .github/workflows/markdown-analysis.yml create mode 100644 .github/workflows/verify-markdown.yml diff --git a/.github/.markdown-link-check.json b/.github/.markdown-link-check.json deleted file mode 100644 index ff0ce58..0000000 --- a/.github/.markdown-link-check.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "replacementPatterns": [ - { - "pattern": "^/", - "replacement": "/github/workspace/" - } - ], - "ignorePatterns": [ - { - "pattern": "^http[s]*://localhost.*" - } - ] -} diff --git a/.github/.markdownlint.yml b/.github/.markdownlint.yml deleted file mode 100644 index 8f3b3a5..0000000 --- a/.github/.markdownlint.yml +++ /dev/null @@ -1,5 +0,0 @@ -default: true - -MD013: false #https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md#md013 -MD029: false #https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md#md033 -MD033: false #https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md#md033 diff --git a/.github/config/.markdownlint-cli2.yaml b/.github/config/.markdownlint-cli2.yaml new file mode 100644 index 0000000..7f1718f --- /dev/null +++ b/.github/config/.markdownlint-cli2.yaml @@ -0,0 +1,13 @@ +#yaml-language-server: $schema=https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/refs/heads/main/schema/markdownlint-cli2-config-schema.json +gitignore: true +config: + default: true + + MD013: false #Line length - https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md#md013 + MD033: false #Inline HTML - https://github.com/DavidAnson/markdownlint/blob/HEAD/doc/Rules.md#md033 + MD024: + siblings_only: true #Multiple headers with the same content + MD009: false #no-trailing-spaces Trailing spaces + MD004: false #Unordered list style + MD031: false #Fenced code blocks should be surrounded by blank lines + MD036: false #No emphasis added \ No newline at end of file diff --git a/.github/config/linkspector.yml b/.github/config/linkspector.yml new file mode 100644 index 0000000..3466022 --- /dev/null +++ b/.github/config/linkspector.yml @@ -0,0 +1,5 @@ +dirs: + - ./ +replacementPatterns: + - pattern: "^/" + replacement: "{{BASEURL}}/" diff --git a/.github/config/spellcheck.yml b/.github/config/spellcheck.yml new file mode 100644 index 0000000..8ca52de --- /dev/null +++ b/.github/config/spellcheck.yml @@ -0,0 +1,35 @@ +matrix: + - name: Markdown + aspell: + lang: en + ignore-case: true + mode: markdown + dictionary: + wordlists: + - .github/config/wordlist.txt + encoding: utf-8 + pipeline: + - pyspelling.filters.context: + context_visible_first: true + escapes: '\\[\\`~]' + delimiters: + # Ignore multiline content between fences (fences can have 3 or more back ticks) + # ```yaml + # content + # ``` + - open: '(?s)^(?P *`{3,}).*$' + close: '^(?P=open) *$' + # Ignore text between inline back ticks + - open: '(?P`+)' + close: '(?P=open)' + - pyspelling.filters.markdown: + markdown_extensions: + - pymdownx.superfences + - pyspelling.filters.html: + comments: false + ignores: + - code + - pre + sources: + - '**/*.md' + default_encoding: utf-8 \ No newline at end of file diff --git a/.github/config/wordlist.txt b/.github/config/wordlist.txt new file mode 100644 index 0000000..52cb3fd --- /dev/null +++ b/.github/config/wordlist.txt @@ -0,0 +1,137 @@ +APIs +BACKEND +Backend +Backends +CNCF +CLI +CTF +Canonicalization +CycloneDX +DNS +FileSystem +Filesystem +FluxCD +Frontend +GOARCH +GOOS +GitOps +Golang +HTTPS +JSON +Kubernetes +Lifecycle +LocalBlob +NIST +NPM +NodeJS +NormalisationAlgorithm +ORAS +OCI +OCIArtifact +OCIRegistry +OCM +PEM +PKCS +RDF +RSA +RSASSA +ReferenceHint +SBOD +SBOM +SBOMs +SHA +SPDX +SWID +Semver +Subpath +Syft +TCP +TLS +TOI +URI +UTF +Uploaders +Verifiers +YAML +amd +autoscale +backend +backends +blobstore +bool +canonicalized +codebase +componentNameMapping +config +conformant +deployer +deserialization +descriptor's +digester +digesters +directoryTree +downloader +executables +extraIdentity +fileSystem +filesystem +gitOpsTemplate +gitops +gtar +gzip +hashAlgorithm +helmChart +helmchart +hostname +http +implementers +indirections +instantiation +interpretable +json +keyring +lexicographically +lifecycle +localBlob +localblob +mariadb +md +mediatype +multiarch +namespace +namespaced +namespaces +nbsp +noredirect +npm +npmPackage +ociArtifact +ociBlob +ociImage +ociartifact +ociblob +ocm +pathToYourRepo +prepended +queryable +reimplementation +repo +sbom +schemas +semantical +sha +structs +subtree +templated +tgz +toolset +untyped +untrusted +updatable +uploader +url +verifiers +wget +whitespace +whitespaces +yaml diff --git a/.github/workflows/markdown-analysis.yml b/.github/workflows/markdown-analysis.yml deleted file mode 100644 index b2a58dc..0000000 --- a/.github/workflows/markdown-analysis.yml +++ /dev/null @@ -1,30 +0,0 @@ -name: markdown-analysis-workflow -permissions: - contents: read - -on: - push: - branches: - - main - pull_request: - branches: - - main - paths: - - '**/*.md' - -jobs: - markdown-analysis-job: - runs-on: ubuntu-latest - name: 'github actions: markdownlint' - steps: - - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 - - name: markdownlint - uses: nosborn/github-action-markdown-cli@508d6cefd8f0cc99eab5d2d4685b1d5f470042c1 # v3 - with: - files: . - config_file: ./.github/.markdownlint.yml - - name: markdown link check - uses: gaurav-nelson/github-action-markdown-link-check@5c5dfc0ac2e225883c0e5f03a85311ec2830d368 #v1 - with: - config-file: ./.github/.markdown-link-check.json diff --git a/.github/workflows/verify-markdown.yml b/.github/workflows/verify-markdown.yml new file mode 100644 index 0000000..8830156 --- /dev/null +++ b/.github/workflows/verify-markdown.yml @@ -0,0 +1,50 @@ +name: Verify Markdown + +on: + pull_request: + branches: + - main + - website/** + paths: + - '**/*.md' + +permissions: + contents: read + pull-requests: write + +jobs: + markdown-lint: + runs-on: ubuntu-latest + name: Lint Markdown + steps: + - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v4 + - uses: DavidAnson/markdownlint-cli2-action@992badcdf24e3b8eb7e87ff9287fe931bcb00c6e # v20 + with: + globs: '**/*.md' + separator: "," + config: .github/config/.markdownlint-cli2.yaml + + verify-links: + name: Verify links + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + - name: Run linkspector + uses: umbrelladocs/action-linkspector@652f85bc57bb1e7d4327260decc10aa68f7694c3 # v1 + with: + github_token: ${{ secrets.github_token }} + reporter: github-pr-check + fail_level: any + config_file: .github/config/linkspector.yaml + show_stats: true + + spellcheck: + name: Spellcheck + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v4 + - name: Spellcheck + uses: rojopolis/spellcheck-github-actions@35a02bae020e6999c5c37fabaf447f2eb8822ca7 # v0 + with: + config_path: .github/config/spellcheck.yml + task_name: Markdown diff --git a/README.md b/README.md index 5986ccf..e20ce40 100644 --- a/README.md +++ b/README.md @@ -22,17 +22,17 @@ The following chapters provide a formal description of the format to describe so * 1.1.2 [Components and Component Versions](doc/01-model/01-model.md#components-and-component-versions) * 1.1.3 [Component Repositories](doc/01-model/01-model.md#component-repositories) * 1.1.4 [Summary](doc/01-model/01-model.md#summary) - * 1.2. [Model Elements](doc/01-model/02-elements-toplevel.md#model-elements) - * 1.2.1 [Components and Component Versions](doc/01-model/02-elements-toplevel.md#components-and-component-versions) + * 1.2. [Model Elements](doc/01-model/02-elements-toplevel.md) + * 1.2.1 [Components and Component Versions](doc/01-model/02-elements-toplevel.md#component-identity) * 1.2.2 [Artifacts (Resources and Sources)](doc/01-model/02-elements-toplevel.md#artifacts-resources-and-sources) * 1.2.3 [Sources](doc/01-model/02-elements-toplevel.md#sources) * 1.2.4 [Resources](doc/01-model/02-elements-toplevel.md#resources) * 1.2.5 [References](doc/01-model/02-elements-toplevel.md#references) * 1.2.6 [Summary](doc/01-model/02-elements-toplevel.md#summary) * 1.3. [Model Elements - Fundamentals](doc/01-model/03-elements-sub.md) - * 1.3.1 [Identifiers](doc/01-model/03-elements-sub.md#identifiers) + * 1.3.1 [Identifiers](doc/01-model/03-elements-sub.md#element-identity) * 1.3.2 [Access Specification](doc/01-model/03-elements-sub.md#access-specification) - * 1.3.3 [Access Types](doc/01-model/03-elements-sub.md#access-types) + * 1.3.3 [Access Types](doc/01-model/03-elements-sub.md#access-specification) * 1.3.4 [Labels](doc/01-model/03-elements-sub.md#labels) * 1.3.5 [Repository Contexts](doc/01-model/03-elements-sub.md#repository-contexts) * 1.3.6 [Signatures](doc/01-model/03-elements-sub.md#signatures) @@ -45,27 +45,27 @@ The following chapters provide a formal description of the format to describe so * 1.6 [Extending the Open Component Model](doc/01-model/07-extensions.md#extending-the-open-component-model) * 1.6.1 [Functional extensions](doc/01-model/07-extensions.md#functional-extensions) * 1.6.2 [Semantic extensions](doc/01-model/07-extensions.md#semantic-extensions) -* 2. [Processing](doc/02-processing/README.md) +* 1. [Processing](doc/02-processing/README.md) * 2.1 [Referencing](doc/02-processing/01-references.md#referencing) * 2.1.1 [Example](doc/02-processing/01-references.md#example) * 2.2 [Signing](doc/02-processing/02-signing.md#signing) * 2.2.1 [Verification Procedure](doc/02-processing/02-signing.md#verification-procedure) * 2.3 [Normalization](doc/02-processing/03-signing-process.md#signing-process-and-normalization) - * 2.3.1 [Artifact Digest](doc/02-processing/03-signing-process.md#determing-the-artifact-digests) + * 2.3.1 [Artifact Digest](doc/02-processing/03-signing-process.md#determining-the-artifact-digests) * 2.3.2 [Normalization Types](doc/02-processing/03-signing-process.md#normalization-types) * 2.3.3 [Serialization Format](doc/02-processing/03-signing-process.md#serialization-format) * 2.3.4 [Recursive Digest Calculation](doc/02-processing/03-signing-process.md#recursive-digest-calculation) - * 2.4 [Example](doc/02-processing/04-signing-examples.md#examples-for-signing-of-component-version) + * 2.4 [Example](doc/02-processing/04-signing-examples.md#examples-for-signing-of-component-versions) * 2.4.1 [Simple Component-Version](doc/02-processing/04-signing-examples.md#simple-component-version) * 2.4.2 [Component-Version With Reference](doc/02-processing/04-signing-examples.md#component-version-with-reference) - * 2.5 [Component Descriptor Normalization](doc/02-processing/04-signing-examples.md#component-descriptor-normalization) - * 2.5.1 [Signing-relevant information in Component Descriptors](doc/02-processing/04-signing-examples.md#relevant-information-in-component-descriptors) + * 2.5 [Component Descriptor Normalization](doc/02-processing/05-component-descriptor-normalization.md#component-descriptor-normalization) + * 2.5.1 [Signing-relevant information in Component Descriptors](doc/02-processing/05-component-descriptor-normalization.md#signing-relevant-information-in-component-descriptors) * 2.5.2 [Exclude Resources from Normalization/Signing](doc/02-processing/05-component-descriptor-normalization.md#exclude-resources-from-normalizationsigning) * 2.5.3 [Generic Normalization Format](doc/02-processing/05-component-descriptor-normalization.md#generic-normalization-format) * 2.6 [Artifact Normalization](doc/02-processing/06-artifact-normalization.md#artifact-normalization) * 2.6.1 [Blob Representation Format for Resource Types](doc/02-processing/06-artifact-normalization.md#blob-representation-format-for-resource-types) * 2.6.2 [Interaction of Local Blobs, Access Methods, Uploaders and Media Types](doc/02-processing/06-artifact-normalization.md#interaction-of-local-blobs-access-methods-uploaders-and-media-types) -* 3. [Persistence](doc/03-persistence/README.md) +* 1. [Persistence](doc/03-persistence/README.md) * 3.1 [Model Operations](doc/03-persistence/01-operations.md#model-operations) * 3.2 [Abstract Operations defined by the Open Component Model](doc/03-persistence/01-operations.md#abstract-operations-defined-by-the-open-component-model) * 3.2.1 [Repository Operations](doc/03-persistence/01-operations.md#repository-operations) @@ -109,7 +109,7 @@ The following chapters provide a formal description of the format to describe so ### Guidelines and Conventions -* 5. [Guidelines](doc/05-guidelines/README.md) +* 1. [Guidelines](doc/05-guidelines/README.md) * 5.1 [Transport](doc/05-guidelines/01-transport.md#transport) * 5.1.1 [Kinds of Transports](doc/05-guidelines/01-transport.md#kinds-of-transports) * 5.2 [Model Contract](doc/05-guidelines/02-contract.md#model-contract) @@ -120,7 +120,7 @@ The following chapters provide a formal description of the format to describe so ### Glossary -* 6. [Glossary](doc/glossary.md) +* 1. [Glossary](doc/glossary.md) ## Central OCM project web page diff --git a/doc/01-model/01-model.md b/doc/01-model/01-model.md index c59dafe..377dbde 100644 --- a/doc/01-model/01-model.md +++ b/doc/01-model/01-model.md @@ -4,7 +4,7 @@ This chapter describes the elements and data formats the Open Component Model de ## Introduction -The Open Compoment Model consists of a core model plus extensions. The core model describes the key elements *Component*, *Component Version* being stored in *Component Registries*. *Component Versions* have a type and an identity, and consist of *sources*, *resources* and *references*. *Component Registries* are containers persisting component versions and may exist in various types for different storage technologies. Many parts of the Open-Component-Model can be extended to provide flexibility and adaption to different environments. Some of these extension are defined in this specification. Others may be defined customer-specific or for dedicated environments. +The Open Component Model consists of a core model plus extensions. The core model describes the key elements *Component*, *Component Version* being stored in *Component Registries*. *Component Versions* have a type and an identity, and consist of *sources*, *resources* and *references*. *Component Registries* are containers persisting component versions and may exist in various types for different storage technologies. Many parts of the Open-Component-Model can be extended to provide flexibility and adaption to different environments. Some of these extension are defined in this specification. Others may be defined customer-specific or for dedicated environments. The following chapters will provide more details about these concepts. @@ -12,7 +12,7 @@ The following chapters will provide more details about these concepts. Usually, complex software products are divided into logical units (called components in this specification). A component is typically maintained in a version control system. It has a build procedure generating binary artifacts from source code and a release process to make it available for consumers. Usually, releases are repeated from time to time, making new versions available. A component is a logical unit within a software product. It is a semantic bracket around software pieces belonging together because they fulfill a specific purpose. E.g. like, "This is the Frontend Component," "This is the Database component," and "This is the Kubernetes vertical autoscale component." -In the Open Component Model, a *Component Version* is described by a *Component Descriptor*. It describes the resources, sources, and aggregated other Component Versions belonging to a particular Component Version. A Component Descriptor is stored in a yaml file following this [schema](https://github.com/open-component-model/ocm/blob/main/resources/component-descriptor-ocm-v3-schema.yaml). +In the Open Component Model, a *Component Version* is described by a *Component Descriptor*. It describes the resources, sources, and aggregated other Component Versions belonging to a particular Component Version. A Component Descriptor is stored in a YAML file following this [schema](https://github.com/open-component-model/ocm/blob/main/resources/component-descriptor-ocm-v3-schema.yaml). A component itself is described by a globally unique identity. Each component version is described by the identity of the component plus a version number following the [semantic versioning](https://semver.org) specification. diff --git a/doc/01-model/02-elements-toplevel.md b/doc/01-model/02-elements-toplevel.md index 073e01d..469cf07 100644 --- a/doc/01-model/02-elements-toplevel.md +++ b/doc/01-model/02-elements-toplevel.md @@ -79,7 +79,7 @@ the access specification determines the concrete format given by a media type us For example, a helm chart (type `helmChart`) can be represented as OCI artifact or helm chart archive. Nevertheless, the technical meaning is the same. In both cases the artifact (resource)`type` will be `helmChart`. -The acess specification however will be different. In the first case it will refer to the helm-chart archive. +The access specification however will be different. In the first case it will refer to the helm-chart archive. In the second case the access method type will be `ociArtifact`. ```yaml @@ -162,7 +162,7 @@ There are two kinds of types: ``` [Artifact Types](../01-model/07-extensions.md#artifact-types) are an extension point within the OCM model. - All existing artifact types are listed [here](../04-extensions/01-artifact-types/README.md). + All existing artifact types are listed in the [Artifact Types extension section](../04-extensions/01-artifact-types/README.md). ## Sources @@ -242,7 +242,7 @@ Example: type: ociArtefact ``` -The full list of resource types is [here](../04-extensions/01-artifact-types/README.md). +The full list of resource types is in the [Artifact Types extension section](../04-extensions/01-artifact-types/README.md). ## References diff --git a/doc/01-model/03-elements-sub.md b/doc/01-model/03-elements-sub.md index c63222e..fecd8c3 100644 --- a/doc/01-model/03-elements-sub.md +++ b/doc/01-model/03-elements-sub.md @@ -235,7 +235,7 @@ regardless by which component provider they are generated. To assure that this information has a globally unique interpretation or meaning, labels must comply with some naming scheme and use a common structure. -Label types are covered by the OCM extension concept, so you can also find information [here](./07-extensions.md#label-types). +Label types are covered by the OCM extension concept, so you can also find information in the [Label Types extension section](./07-extensions.md#label-types). ## Repository Contexts diff --git a/doc/01-model/06-conventions.md b/doc/01-model/06-conventions.md index 46d761c..e156ef9 100644 --- a/doc/01-model/06-conventions.md +++ b/doc/01-model/06-conventions.md @@ -3,13 +3,13 @@ To ensure uniformity across tools that interact with content from the component model, certain conventions should be adhered to. -These conventiones are not covered by the [model-tool contract](../05-guidelines/02-contract.md#model-contract). -They are also not part of the specificationsbut should be obeyed +These conventions are not covered by the [model-tool contract](../05-guidelines/02-contract.md#model-contract). +They are also not part of the specifications but should be obeyed to achieve a common understanding about the meaning of content. ## Intended Environments -There are several scenarios where artifacts will be provided as content of [component versions](./02-elements-toplevel.md#components-and-component-versions), which might be bound to a dedicated runtime environment. If a component version should provide several flavors of the same artifact intended for different environments they should use the same element name and version, and the environment should be reflected by one or more [extra identity properties](./03-elements-sub.md#identifiers). +There are several scenarios where artifacts will be provided as content of [component versions](./02-elements-toplevel.md), which might be bound to a dedicated runtime environment. If a component version should provide several flavors of the same artifact intended for different environments they should use the same element name and version, and the environment should be reflected by one or more [extra identity properties](./03-elements-sub.md#element-identity). ### Operating System and CPU Architecture diff --git a/doc/01-model/07-extensions.md b/doc/01-model/07-extensions.md index 7a5ba48..835625c 100644 --- a/doc/01-model/07-extensions.md +++ b/doc/01-model/07-extensions.md @@ -42,9 +42,9 @@ There are two different kinds of extensions: functional and semantic. ## Component Descriptor Serialization The elements used to describe a component version can be represented in a serialized format, -typically as yaml document. This document MUST contain a format specification version +typically as YAML document. This document MUST contain a format specification version with the concrete representation of the model elements of a component version. -The defined formats are described [here](../04-extensions/00-component-descriptor/README.md). +The defined formats are described in the [Component Descriptor extension section](../04-extensions/00-component-descriptor/README.md). ## Storage Backends @@ -98,7 +98,7 @@ Every OCM repository can therefore be described by such a *Repository Specificat This specification can be utilized by a language binding to access the repository. The type is employed to distinguish the backend implementation, and the additional attributes are leveraged by the implementation -to faciliprovide access to the specific repository instance. +to provide access to the specific repository instance. In a concrete environment all those repositories are usable, for which an implementation of the [abstract model operations](../03-persistence/01-operations.md) exists. @@ -115,7 +115,7 @@ used to implement an OCM repository interface. The version is used to specify the attribute structure that describes the repository instance as part of the repository specification. -Regardless of the creator of a component version, an access method must be uniquely identifyable. +Regardless of the creator of a component version, an access method must be uniquely identifiable. Therefore, the names of access methods must be globally unique. There are two kinds of type name: @@ -132,8 +132,7 @@ There are two kinds of type name: [A-Z][a-zA-Z0-9]* ``` - The defined types with their meaning and formats can be found - [here](../04-extensions/03-storage-backends/README.md) + The defined types with their meaning and formats can be found in the [Storage Backends extension section](../04-extensions/03-storage-backends/README.md) - Vendor specific types @@ -252,7 +251,7 @@ The task of an access method is to provide access to the physical content of an The content is always provided as blob with a dedicated media type, either depending on the access method itself or the [artifact type](#artifact-types). To fulfill its task an access method gets an access specification. -The list of centrally defined access methods types can be found [here](../04-extensions/02-access-types/README.md) +The list of centrally defined access methods types can be found in the [Access Types extension section](../04-extensions/02-access-types/README.md) ### Access Specification @@ -282,7 +281,7 @@ The version is used to specify the attribute structure used to describe the information to identify the artifact in sme repository as part of the access specification. -Regardless of the creator of a component version, an access method must be uniquely identifyable. +Regardless of the creator of a component version, an access method must be uniquely identifiable. Therefore, the names of access methods must be globally unique. There are two kinds of type name: @@ -298,7 +297,7 @@ There are two kinds of type name: [a-z][a-zA-Z0-9]* ``` - The defined types with their meaning and formats can be found in [here](../04-extensions/02-access-types/README.md) + The defined types with their meaning and formats can be found in the [Access Types extension section](../04-extensions/02-access-types/README.md) - Vendor specific types @@ -401,7 +400,7 @@ and stream access for the denoted blob is required. ## Digest Algorithms Digest algorithms describe the way digests are calculated from a byte stream. -The defined algorithms can be found [here](../04-extensions/04-algorithms/digest-algorithms.md). +The defined algorithms can be found in the [Digest Algorithms extension section](../04-extensions/04-algorithms/digest-algorithms.md). ## Signing Algorithms @@ -472,7 +471,7 @@ the normalization is a *digest specification* with the following fields The HEX encoded digest value. -The already defined digesters can be found [here](../04-extensions/04-algorithms/artifact-normalization-types.md). +The already defined digesters can be found in the [Artifact Normalization Types extension section](../04-extensions/04-algorithms/artifact-normalization-types.md). Example: diff --git a/doc/02-processing/03-signing-process.md b/doc/02-processing/03-signing-process.md index a750719..6e3b250 100644 --- a/doc/02-processing/03-signing-process.md +++ b/doc/02-processing/03-signing-process.md @@ -10,7 +10,7 @@ A signature of a component version is based on digests of the involved elements. Therefore, there must be a defined way, how to calculate digests. This has to happen in a recursive way to handle aggregations. -## Determing the Artifact Digests +## Determining the Artifact Digests The content of every artifact is provided in a dedicated blob format by the various access methods. A digest can be calculated based on this blob. This is the default behaviour. @@ -53,7 +53,7 @@ If the digest algorithm `NO-DIGEST` is specified for an artifact, this artifact content is not included into the component version digest. This is typically configured for source artifacts, which are not deliverable. -The artifact digest normalization algorithms are listed in the [extensions](../04-extensions/04-algorithms/README.md#artifact-normalization-types) +The artifact digest normalization algorithms are listed in the [Artifact Normalization Types](../04-extensions/04-algorithms/artifact-normalization-types.md) section of the specification. ## Normalization Types diff --git a/doc/02-processing/06-artifact-normalization.md b/doc/02-processing/06-artifact-normalization.md index 2dcddbe..3a499b7 100644 --- a/doc/02-processing/06-artifact-normalization.md +++ b/doc/02-processing/06-artifact-normalization.md @@ -32,11 +32,11 @@ If multiple media types are possible for blobs, the digest of the artifact conte MUST be immutable to avoid invalidating signatures. In such a case a dedicated artifact normalization algorithm MUST be provided for such media types. -Available artifact normalization types can be found [here](./03-signing-process.md#normalization-types). +Available artifact normalization types can be found in the [Normalization Types section](./03-signing-process.md#normalization-types). ## Interaction of Local Blobs, Access Methods, Uploaders and Media Types -The Open Component Model is desiged to support transports of artifacts. +The Open Component Model is designed to support transports of artifacts. To assure the integrity of digests and signatures some rules must be obeyed by the involved model extensions. ### Access Methods diff --git a/doc/02-processing/README.md b/doc/02-processing/README.md index fa6ec66..0d3463f 100644 --- a/doc/02-processing/README.md +++ b/doc/02-processing/README.md @@ -9,15 +9,15 @@ This chapter explains how to create and use components. * 2.1.1.[Verify with RSA](02-signing.md#verify-with-rsa) * 2.1.2.[Verify with X509](02-signing.md#verify-with-x509) * 3.[Normalization](03-signing-process.md#signing-process-and-normalization) - * 3.1.[Artifact Digest](03-signing-process.md#determing-the-artifact-digests) + * 3.1.[Artifact Digest](03-signing-process.md#determining-the-artifact-digests) * 3.2.[Normalization Types](03-signing-process.md#normalization-types) * 3.3.[Serialization Format](03-signing-process.md#serialization-format) * 3.4.[Recursive Digest Calculation](03-signing-process.md#recursive-digest-calculation) * 4.[Example](04-signing-examples.md#examples-for-signing-of-component-versions) * 4.1.[Simple Component-Version](04-signing-examples.md#simple-component-version) * 4.2.[Component-Version With Reference](04-signing-examples.md#component-version-with-reference) -* 5.[Component Descriptor Normalization](04-signing-examples.md#component-descriptor-normalization) - * 5.1.[Signing-relevant information in Component Descriptors](04-signing-examples.md#relevant-information-in-component-descriptors) +* 5.[Component Descriptor Normalization](05-component-descriptor-normalization.md#component-descriptor-normalization) + * 5.1.[Signing-relevant information in Component Descriptors](05-component-descriptor-normalization.md#signing-relevant-information-in-component-descriptors) * 5.1.1.[Access Methods](05-component-descriptor-normalization.md#access-methods) * 5.1.2.[Labels](05-component-descriptor-normalization.md#labels) * 5.2.[Exclude Resources from Normalization/Signing](05-component-descriptor-normalization.md#exclude-resources-from-normalizationsigning) diff --git a/doc/04-extensions/01-artifact-types/blob.md b/doc/04-extensions/01-artifact-types/blob.md index ea15286..e6fddcd 100644 --- a/doc/04-extensions/01-artifact-types/blob.md +++ b/doc/04-extensions/01-artifact-types/blob.md @@ -9,4 +9,4 @@ A blob represents any data without a dedicated logical type. ## Format Variants Any arbitrary media type is used to define the logical and/or technical format of the byte-stream represented by the blob. -By default the media type `application/octet-stream` can be used for an anoymous byte sequence. +By default the media type `application/octet-stream` can be used for an anonymous byte sequence. diff --git a/doc/04-extensions/01-artifact-types/toipackage.md b/doc/04-extensions/01-artifact-types/toipackage.md index c7fb9e3..250d710 100644 --- a/doc/04-extensions/01-artifact-types/toipackage.md +++ b/doc/04-extensions/01-artifact-types/toipackage.md @@ -4,7 +4,7 @@ TOI is a small toolset on top of the [Open Component Model](../../01-model/01-mo It provides a possibility to run images taken from a component version with user configuration and feed them with the content of this component version. It is some basic mechanism which can be used to execute simple installation -steps based on content described by the Open Component Model (see the [TOI documenation](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi-bootstrapping.md).) +steps based on content described by the Open Component Model (see the [TOI documentation](https://github.com/open-component-model/ocm/blob/main/docs/reference/ocm_toi-bootstrapping.md).) A TOI package is YAML resource describing the installation handling for a dedicated software package based on one or more diff --git a/doc/04-extensions/03-storage-backends/README.md b/doc/04-extensions/03-storage-backends/README.md index 4072676..3708fc1 100644 --- a/doc/04-extensions/03-storage-backends/README.md +++ b/doc/04-extensions/03-storage-backends/README.md @@ -62,8 +62,8 @@ binding to achieve interoperability among those implementations.
The specification for layer 1 is described in the [model element specification section](../../01-model/README.md). -The specification of the extension points can be found [here](../../01-model/07-extensions.md). -The storage backend extension specification is [here](../../01-model/07-extensions.md#storage-backends). +The specification of the extension points can be found in the [Extensions section](../../01-model/07-extensions.md). +The storage backend extension specification is in the [Storage Backends section](../../01-model/07-extensions.md#storage-backends). This sections describes the abstract model mapping for the storage backend extensions according to layer 3. Different implementations (for different language bindings) MUST implement this mapping diff --git a/doc/04-extensions/03-storage-backends/oci.md b/doc/04-extensions/03-storage-backends/oci.md index 8d866d0..f92be3c 100644 --- a/doc/04-extensions/03-storage-backends/oci.md +++ b/doc/04-extensions/03-storage-backends/oci.md @@ -833,7 +833,7 @@ software.ocm.component.version: "" ### 12.1 Version Aliasing OCI tags such as `latest`, `stable`, or other user-defined symbolic names are not OCM versions. -To support workflows that rely on floating pointers to versions, clients **MAY** implement *version aliasing*. +To support workflows that rely on floating pointers to versions, clients **MAY** implement _version aliasing_. An alias is an OCI tag whose meaning is defined by client-side resolution logic rather than by the OCM version string. Aliases map to a concrete OCM version based on deterministic selection rules. @@ -915,7 +915,7 @@ Examples are grouped into: #### Repository Specification Examples -*(References: [4. Repository Specification Format](#4-repository-specification-format))* +_(References: [4. Repository Specification Format](#4-repository-specification-format))_ ##### A. Minimal HTTPS Example @@ -961,7 +961,7 @@ Because `subPath` is explicitly provided, **no normalization** occurs ([4.3](#43 #### Repository Grammar Validity -*(References: [4.5. Repository Reference Grammar](#45-string-reference-grammar))* +_(References: [4.5. Repository Reference Grammar](#45-string-reference-grammar))_ ##### Valid References @@ -981,7 +981,7 @@ Invalid references **MUST** be rejected ([4.5](#45-string-reference-grammar)). #### Component → Repository Mapping -*(References: [5. Component Repository Mapping](#5-component-repository-mapping))* +_(References: [5. Component Repository Mapping](#5-component-repository-mapping))_ Given: @@ -1003,7 +1003,7 @@ All versions reside under this repository. #### Manifest Representation -*(References: [6.1. Manifest Representation](#61-manifest-representation))* +_(References: [6.1. Manifest Representation](#61-manifest-representation))_ A manifest storing a component version may look like: @@ -1037,7 +1037,7 @@ Key points: #### Index Representation -*(References: [6.2. Index Representation](#62-index-representation))* +_(References: [6.2. Index Representation](#62-index-representation))_ ```json { @@ -1064,7 +1064,7 @@ Additional manifests are regular artifacts. #### Descriptor Selection Logic -*(References: [7. Descriptor Selection Logic](#7-descriptor-selection-logic))* +_(References: [7. Descriptor Selection Logic](#7-descriptor-selection-logic))_ Given an index: @@ -1085,7 +1085,7 @@ If none exist → select the **first manifest** for compatibility ([7](#7-descri #### LocalBlob Resolution -*(References: [10.3 Resolution](#103-resolution))* +_(References: [10.3 Resolution](#103-resolution))_ ```text localReference: sha256:beef1234 @@ -1099,7 +1099,7 @@ Resolution steps: #### Version Mapping -*(References: [12. Tag and Version Mapping Rules](#12-tag-and-version-mapping-rules))* +_(References: [12. Tag and Version Mapping Rules](#12-tag-and-version-mapping-rules))_ OCM → OCI: @@ -1119,7 +1119,7 @@ Round-trip **MUST** be exact. #### Publishing a Component Version -*(References: [5](#5-component-repository-mapping), [6.1](#61-manifest-representation), [7](#7-descriptor-selection-logic), [8](#8-component-index-referrer-anchor), [10](#10-localblob-processing), [12](#12-tag-and-version-mapping-rules))* +_(References: [5](#5-component-repository-mapping), [6.1](#61-manifest-representation), [7](#7-descriptor-selection-logic), [8](#8-component-index-referrer-anchor), [10](#10-localblob-processing), [12](#12-tag-and-version-mapping-rules))_ ##### Scenario @@ -1158,7 +1158,7 @@ Digest equality ensures the LocalBlob resolves exactly to one descriptor. #### Subject Handling When Registry Rejects `subject` -*(References: [8.2 Version Behavior](#82-version-behavior), [8.5.2 Publishing a Component Version](#852-publishing-a-component-version))* +_(References: [8.2 Version Behavior](#82-version-behavior), [8.5.2 Publishing a Component Version](#852-publishing-a-component-version))_ If the registry removes: @@ -1174,7 +1174,7 @@ Then: #### Full OCI Layout Reconstruction -*(References: [10.4 Retrieval](#104-retrieval))* +_(References: [10.4 Retrieval](#104-retrieval))_ Given a manifest referencing: @@ -1200,7 +1200,7 @@ Any of these **MUST** abort retrieval ([10.4](#104-retrieval)). #### Index vs Manifest Fallback -*(References: [7 Descriptor Selection Logic](#7-descriptor-selection-logic))* +_(References: [7 Descriptor Selection Logic](#7-descriptor-selection-logic))_ If: @@ -1215,7 +1215,7 @@ contains **no** descriptor annotation: #### LocalBlob → OCIArtifact/v1 Conversion -*(References: [11.3 Translation of `localBlob` to `OCIArtifact/v1`](#113-translation-of-localblob-to-ociartifactv1))* +_(References: [11.3 Translation of `localBlob` to `OCIArtifact/v1`](#113-translation-of-localblob-to-ociartifactv1))_ Input: diff --git a/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md b/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md index ca0dba6..5c773b0 100644 --- a/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md +++ b/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md @@ -1,30 +1,30 @@ # Normalization Algorithms -Currently the there are two different normalizations defined: +The following component descriptor normalization algorithms are defined: -- `jsonNormalisationV1`: This is a legacy format, which depends on the format of the - component descriptor -- `jsonNormalisationV2`: This is the new format. which is independent of the - chosen representation format of the component descriptor. +- `jsonNormalisationV1`: Legacy format that depends on the serialization format of the component descriptor. Uses the [OCM-specific generic normalization format](../../02-processing/05-component-descriptor-normalization.md#generic-normalization-format). **Deprecated.** +- `jsonNormalisationV2`: Format-independent normalization using [RFC 8785 (JCS)](https://www.rfc-editor.org/rfc/rfc8785). Includes legacy extra-identity defaulting. **Deprecated.** +- `jsonNormalisationV3`: Identical to v2 but **without** legacy extra-identity defaulting. **Deprecated** — transparently mapped to `jsonNormalisationV4alpha1`. +- `jsonNormalisationV4alpha1`: Clean reimplementation of v3. **Current default.** The normalization process is divided into two steps: -- *extraction of the signature relevant information from the component descriptor* +- *extraction of the signing-relevant information from the component descriptor* - The result is basically a JSON object, which decsribed the relevant information. + The result is a JSON object which describes the relevant information. - *normalization of the resulting JSON object* - Here, the object is serialized to a unique and reproducable byte sequence, which is finally used to determine the digest. + The object is serialized to a unique and reproducible byte sequence, which is finally used to determine the digest. - There are two such normalization methods: - - `jsonNormalisationV1` - - `jsonNormalisationV2` + The following serialization methods are used across the algorithms: + - `jsonNormalisationV1` uses the [OCM-specific generic normalization format](../../02-processing/05-component-descriptor-normalization.md#generic-normalization-format) (dictionaries serialized as sorted single-entry lists) + - All other algorithms use [RFC 8785 (JCS)](https://www.rfc-editor.org/rfc/rfc8785) ## `jsonNormalisationV1` The `JsonNormalisationV1` serialization format is based on the serialization format of the component descriptor. -It uses an appropriate JSON object containing the relevant fields as contained in the component descriptors's serialization. +It uses an appropriate JSON object containing the relevant fields as contained in the component descriptor's serialization. The format version fields are included. Therefore, the normalized form is depending on the chosen serialization format. Changing this format version would result in different digests. The resulting JSON object is serialized with the [OCM specific scheme](../../02-processing/05-component-descriptor-normalization.md#generic-normalization-format) @@ -32,7 +32,7 @@ The resulting JSON object is serialized with the [OCM specific scheme](../../02- ## `jsonNormalisationV2` `JsonNormalisationV2` strictly uses only the relevant component descriptor -information according to the field specification. It is independent of the serialization format used to store the component decsriptor in some storage backend. Therefore, the calculated digest is finally independent of the serialization format chosen for storing the component descriptor in a storage backend. It uses a standard scheme according to [RFC8785 (JCS)](https://www.rfc-editor.org/rfc/rfc8785) +information according to the field specification. It is independent of the serialization format used to store the component descriptor in some storage backend. Therefore, the calculated digest is finally independent of the serialization format chosen for storing the component descriptor in a storage backend. It uses a standard scheme according to [RFC8785 (JCS)](https://www.rfc-editor.org/rfc/rfc8785) Relevant fields and their mapping to the normalized data structure for `JsonNormalisationV2` are: @@ -43,3 +43,215 @@ Relevant fields and their mapping to the normalized data structure for `JsonNorm - Resources: mapped to `component.resources`, if no resource is present, an empty list is enforced - Sources: mapped to `component.sources`, if no source is present, an empty list is enforced - References: mapped to `component.references`, if no reference is present, an empty list is enforced + +## `jsonNormalisationV3` + +> **Status:** Deprecated — transparently mapped to `jsonNormalisationV4alpha1`. Existing signatures using `jsonNormalisationV3` remain verifiable. + +`jsonNormalisationV3` uses the same serialization ([RFC 8785 / JCS](https://www.rfc-editor.org/rfc/rfc8785)), the same field selection, and the same exclusion rules as `jsonNormalisationV2`. The **only difference** is the removal of a legacy extra-identity defaulting behaviour: + +- **`jsonNormalisationV2`** automatically inserts the `version` field into `extraIdentity` when multiple resources (or sources) share the same `name` and identical `extraIdentity`. This was an accidental coupling of defaulting logic with normalization and could silently mutate the descriptor before digest calculation. +- **`jsonNormalisationV3`** normalizes the component descriptor **as-is**, without any implicit defaulting. If resource identities are ambiguous the descriptor is taken at face value. + +Because the extra-identity defaulting only triggers when duplicate name + extraIdentity combinations exist, most component descriptors produce **identical digests** under v2 and v3. + +The algorithm operates on the **v2 serialization** of the component descriptor as its baseline and applies the following transformation rules. +These extraction and exclusion rules are shared with `jsonNormalisationV2` (and `jsonNormalisationV4alpha1`); they are documented here in full detail. + +### Extraction of Signing-Relevant Information + +The following top-level sections are **completely excluded**: + +| Excluded Section | Reason | +|---------------------|---------------------------------------------------| +| `meta` | Schema version metadata, not content-relevant | +| `signatures` | The signature itself cannot be part of the digest | +| `nestedDigests` | Digests stored for referenced component versions in the parent descriptor | + +Within the `component` section, the following rules apply: + +#### Component-Level Fields + +| Field | Treatment | +|----------------------|-----------| +| `component.name` | Included | +| `component.version` | Included | +| `component.provider` | Included — always serialized as a JSON object `{"name": ""}`, even if the original descriptor stores the provider as a plain string | +| `component.labels` | Included, subject to [Label Rules](#label-rules) | +| `component.repositoryContexts` | **Excluded** — transport-specific | +| `component.resources` | Included as a JSON array (empty `[]` if absent), subject to [Resource Rules](#resource-rules) | +| `component.sources` | Included as a JSON array (empty `[]` if absent), subject to [Source Rules](#source-rules) | +| `component.references` | Included as a JSON array (empty `[]` if absent), subject to [Reference Rules](#reference-rules) | + +All list fields (`resources`, `sources`, `references`, `repositoryContexts`) default to an empty array `[]` when absent or `null`. + +#### Resource Rules + +For each resource entry: + +| Field | Treatment | +|------------|-----------| +| `access` | **Excluded** — transport-specific | +| `srcRefs` | **Excluded** | +| `labels` | Subject to [Label Rules](#label-rules) | +| `digest` | Included, **except** for resources whose access type is `none` (or legacy `None`), where the `digest` field is removed | +| All other fields | Included (e.g. `name`, `version`, `type`, `relation`, `extraIdentity`) | + +#### Source Rules + +For each source entry: + +| Field | Treatment | +|----------|-----------| +| `access` | **Excluded** — transport-specific | +| `labels` | Subject to [Label Rules](#label-rules) | +| All other fields | Included | + +#### Reference Rules + +For each reference entry: + +| Field | Treatment | +|----------|-----------| +| `labels` | Subject to [Label Rules](#label-rules) | +| All other fields | Included | + +#### Label Rules + +Labels are treated specially across all label-bearing elements (component, resources, sources, references): + +1. **Only signing-relevant labels are included.** A label is signing-relevant if and only if its `signing` field is set to `true` (boolean or the string `"true"`).Labels without `signing: true` are excluded. +2. **For included labels, only these fields are preserved:** + +- `name` +- `version` +- `value` +- `signing` + +1. **Other label metadata** (e.g. `mergeAlgorithm`) is excluded. +2. **If the resulting label array is empty after filtering, the entire `labels` field is omitted** (not serialized as `[]`). + +### Serialization + +After extracting the signing-relevant fields according to the rules above, +the resulting JSON structure is serialized using [RFC 8785 (JCS)](https://www.rfc-editor.org/rfc/rfc8785), which defines: + +- Lexicographic ordering of object keys +- Specific number formatting (no trailing zeros, no positive sign for exponents) +- Specific string escaping rules +- No whitespace between tokens + The resulting byte sequence is the normalized form used for digest calculation. + +### Example + +Given this component descriptor (v2 serialization): + +```yaml +meta: + schemaVersion: v2 +component: + name: ocm.software/example + version: 1.0.0 + provider: acme.org + repositoryContexts: + - baseUrl: ghcr.io + type: OCIRegistry + resources: + - name: my-binary + type: executable + version: 1.0.0 + relation: local + access: + type: localBlob + localReference: sha256:abc123... + mediaType: application/octet-stream + digest: + hashAlgorithm: SHA-256 + normalisationAlgorithm: genericBlobDigest/v1 + value: abc123... + labels: + - name: downloadName + value: my-binary + - name: config-hash + value: def456... + signing: true + sources: [] + references: [] +signatures: [] +``` + +The normalized form (formatted for readability) is: + +```json +{ + "component": { + "name": "ocm.software/example", + "provider": { + "name": "acme.org" + }, + "references": [], + "resources": [ + { + "digest": { + "hashAlgorithm": "SHA-256", + "normalisationAlgorithm": "genericBlobDigest/v1", + "value": "abc123..." + }, + "labels": [ + { + "name": "config-hash", + "signing": true, + "value": "def456..." + } + ], + "name": "my-binary", + "relation": "local", + "type": "executable", + "version": "1.0.0" + } + ], + "sources": [], + "version": "1.0.0" + } +} +``` + +Note: In the actual serialized byte stream, there are no whitespaces or newlines — the formatted version above is for illustration only. The keys within each object are lexicographically ordered per RFC 8785. + +Excluded from this output: + +- `meta` (schema version) +- `signatures` +- `component.repositoryContexts` (transport-specific) +- `resources[].access` (transport-specific) +- `resources[].labels[0]` (`downloadName` — no `signing: true`) +- `provider` is serialized as `{"name":"acme.org"}` (not as the plain string `"acme.org"`) + +## `jsonNormalisationV4alpha1` + +> **Status:** Current default algorithm. + +`jsonNormalisationV4alpha1` is a clean-room reimplementation of `jsonNormalisationV3`. It uses the same field selection rules, the same RFC 8785 (JCS) serialization, the same absence of legacy extra-identity defaulting, and produces **byte-identical output** for the same input. +The algorithm exists to provide a well-tested, independently implemented normalization that is not tied to the legacy OCM v1 codebase. Conformance between v3 and v4alpha1 is verified by test suites that compare the output of both algorithms on real-world component descriptors. + +### Differences from `jsonNormalisationV3` + +There are **no behavioral differences**. The field extraction rules, label handling, provider normalization, none-access resource handling, +empty-list defaults, and JCS serialization are identical. Neither v3 nor v4alpha1 perform the legacy extra-identity defaulting that v2 applies. The `v4alpha1` name reflects that: + +1. It is part of the next-generation OCM bindings (hence the version bump). +2. The `alpha1` suffix indicates that the algorithm name may be consolidated in a future specification version (e.g. to a final `v3` or `v4`). + +### Backward Compatibility + +When a signature or digest references `jsonNormalisationV3`, implementations SHOULD transparently use the `jsonNormalisationV4alpha1` algorithm for both signing and verification. +The two algorithms are interchangeable. + +### Reference Implementation + +The reference implementation can be found in the [Open Component Model repository](https://github.com/open-component-model/open-component-model): + +- Algorithm registration and exclusion rules: `bindings/go/descriptor/normalisation/json/v4alpha1/normalisation.go` +- JCS engine (RFC 8785): `bindings/go/descriptor/normalisation/engine/jcs/` +- Legacy v3 → v4alpha1 mapping: `bindings/go/signing/digest.go` +- Conformance test data (v3 compatibility): `bindings/go/descriptor/normalisation/json/v4alpha1/testdata/conformance/legacy/jsonNormalisation/v3/` diff --git a/doc/04-extensions/04-algorithms/signing-algorithms.md b/doc/04-extensions/04-algorithms/signing-algorithms.md index 344c702..bc66774 100644 --- a/doc/04-extensions/04-algorithms/signing-algorithms.md +++ b/doc/04-extensions/04-algorithms/signing-algorithms.md @@ -5,7 +5,7 @@ which will the be signed with the selected signing algorithm. ## RSA -*Algorith Name:* `RSASSA-PKCS1-V1_5` +*Algorithm Name:* `RSASSA-PKCS1-V1_5` After the digest for the normalised component descriptor is calculated, it can be signed using RSASSA-PKCS1-V1_5 as signature.algorithm. The corresponding signature is stored hex encoded in `signature.value` with a `mediaType` of diff --git a/doc/04-extensions/README.md b/doc/04-extensions/README.md index ba7e70f..5a409f4 100644 --- a/doc/04-extensions/README.md +++ b/doc/04-extensions/README.md @@ -3,7 +3,7 @@ The core specification does not rely on a fixed set of certain fields. However, the specification defines a set of known values for certain types listed in the following sections. These sets can be extended by new specification versions, -addendums or for customer-specific environments. +addenda or for customer-specific environments. ## Table of Content diff --git a/doc/04-extensions/common/formatspec.md b/doc/04-extensions/common/formatspec.md index ce0fb36..1447e75 100644 --- a/doc/04-extensions/common/formatspec.md +++ b/doc/04-extensions/common/formatspec.md @@ -161,12 +161,12 @@ models for the OCI specification: described by this format. But language bindings basically have to support this additional type. -# *Component Archive Format* +## *Component Archive Format* This is a special filesystem based format to store the content of a single component version. It is intended to be used during a build process to incrementally compose a component version. -Once finished it can be transfered to a regular OCM repository. +Once finished it can be transferred to a regular OCM repository. It is a directory containing diff --git a/doc/05-guidelines/01-transport.md b/doc/05-guidelines/01-transport.md index 6ba705e..1b68487 100644 --- a/doc/05-guidelines/01-transport.md +++ b/doc/05-guidelines/01-transport.md @@ -11,7 +11,7 @@ The model provided by OCM can be used to create a transport tool being able to t To support this, a component version includes the access information for the described artifacts. If no applicable storage system for an artifact type according to its access method is available it can be stored as local blob along with the component descriptor. -The descriptor stored in the target repository has to be adapted accordingly to reflect the new ocal location. In this way OCM allows to provide modifiable access information for artifacts. +The descriptor stored in the target repository has to be adapted accordingly to reflect the new local location. In this way OCM allows to provide modifiable access information for artifacts. The transport target might even be an archive or filesystem. This enables the transport of OCM content into fenced environments via data storage media (e.g USB stick). @@ -34,12 +34,12 @@ A transport of a component version from one component repository into another on * directly from an OCM repository to another one: To support transport by value requires the availability of a blob state in the target environment. * indirectly using an intermediate file based format: This format must be capable to store blobs that have to be transported side-by-side with the component descriptors. In this format the component descriptor must be capable to describe the access to those locally stored blobs. -To simplify and unify the handling of those two scenarios, and generally the handling of blobs in various environments, a component repository must also include support for storing blobs under the identity of the component descriptor. A repository implementation may forward this task to a predefinied other blob store or handle this part of the API in its own way. +To simplify and unify the handling of those two scenarios, and generally the handling of blobs in various environments, a component repository must also include support for storing blobs under the identity of the component descriptor. A repository implementation may forward this task to a predefined other blob store or handle this part of the API in its own way. This enables: * a simple usage of a component repository to store any content without the need of always requiring other external stores for (possibly specific types of) resources, e.g. for storing simple configuration data along with the component descriptor. -* providing a respository implementation for file system formats that can be used transparently by component tools. +* providing a repository implementation for file system formats that can be used transparently by component tools. * the usage of a minimal repository environment on the target side of a transport by just using a dedicated component repository. Therefore, *Component Repositories* MUST provide the possibility to store technical artifacts together with the component descriptors in the component repository itself (as *local blobs*). The general access method type `localBlob` MUST be supported by all repository implementations. This allows packing all component versions with their technical artifacts in a *Component Repository* as a completely self-contained package. diff --git a/doc/05-guidelines/02-contract.md b/doc/05-guidelines/02-contract.md index 431ae09..dd6096b 100644 --- a/doc/05-guidelines/02-contract.md +++ b/doc/05-guidelines/02-contract.md @@ -15,10 +15,10 @@ This contract consists of two parts: This has various consequences especially for deployment environments, but basically for all tools working with the component model and even the component model itself: -- Deployment descriptions MUST be part of a component version. They have to be stored as additional resources with an appropriate (tool/technology specific) artifact type. There are too many deployment technologies to define them centrally. Deploment descriptions therefore use extensions. +- Deployment descriptions MUST be part of a component version. They have to be stored as additional resources with an appropriate (tool/technology specific) artifact type. There are too many deployment technologies to define them centrally. Deployment descriptions therefore use extensions. - Those descriptions MUST use descriptive elements of the component model to locate and access artifacts. It is not allowed to use explicit, absolute or global direct artifact locations. - A component version MUST include all resources, either directly contained in the component version or by referring to other component versions using references. References can contain other references resulting in a graph. To avoid the need of describing always complete closed sets of artifacts in a single component version the model offers the [component reference/aggregation feature](../02-processing/01-references.md). -- The artifacts must be resolvable in the context of the component version containing this description as artifact. See also [relative artifact references](../02-processing/01-references.md#relative-artifact-references) +- The artifacts must be resolvable in the context of the component version containing this description as artifact. See also [relative artifact references](./03-references.md#relative-artifact-references) ## Example: Helm deployment @@ -32,7 +32,7 @@ A tool used to deploy a component version with helm therefore requires several r - all the images required for the helm chart - the helm chart -- a helm specific description containig a mapping of value names to image locations of the component version. +- a helm specific description containing a mapping of value names to image locations of the component version. The OCM-compliant deploy tool (ocm-helm-adapter) must: @@ -42,7 +42,7 @@ The OCM-compliant deploy tool (ocm-helm-adapter) must: The deploy tool can then call the native helm command using the helm chart location from the component version and the generated helm values.
-OCM and Helm Deployments +OCM and Helm Deployments
### Example: Indirect Deployments @@ -50,5 +50,5 @@ The deploy tool can then call the native helm command using the helm chart locat A deployed image may contain code to deploy pods to a Kubernetes cluster (for example, a Kubernetes operator managing some service instances). These image locations must also be taken from the component version requiring an additional indirection. For an OCM-compliant deployment, the executable of the image must accept some argument or configuration to pass these locations at runtime. The necessary mapping from resources of a component version to the configuration of the deployer executable must again be described in the description resource and processed by the adapter to generate the target configuration.
-OCM and Helm Deployments with indirect Deployments +OCM and Helm Deployments with indirect Deployments
diff --git a/doc/05-guidelines/README.md b/doc/05-guidelines/README.md index beb11e6..80a4cdb 100644 --- a/doc/05-guidelines/README.md +++ b/doc/05-guidelines/README.md @@ -1,6 +1,6 @@ # Guidelines (non-normative) -This chapter contains context information to the OCM core specification. It contains common use-cases where OCM is used and conventions how to make best use of the information in ihe model. +This chapter contains context information to the OCM core specification. It contains common use-cases where OCM is used and conventions how to make best use of the information in the model. The specification itself does not rely on the information of this chapter. For interoperability it is strongly recommended to follow the conventions outlined in this chapter. diff --git a/doc/glossary.md b/doc/glossary.md index 095fafc..94a9970 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -28,7 +28,7 @@ Grouping multiple OCM component versions by referencing from a root component ve [Content](#content) described by a [component version](#component-version). -### [Artifact Digest](02-processing/03-signing-process.md#determing-the-artifact-digests) +### [Artifact Digest](02-processing/03-signing-process.md#determining-the-artifact-digests) The (logical) digest of an [artifact](#artifact). @@ -50,7 +50,7 @@ The formal type of an [artifact](#artifact) described by a [component version](# An abstract entity describing a dedicated usage context or meaning for a provided piece of software. -### [Component Constructor](https://ocm.software/docs/getting-started/create-component-version/) +### [Component Constructor](https://ocm.software/docs/getting-started/create-component-versions/) A file that acts as input for the OCM CLI to construct one or multiple component version(s). @@ -206,7 +206,7 @@ Using extra identities to express the assignment of an [artifact](#artifact) to 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) +### [Relative Resource References](05-guidelines/03-references.md#relative-artifact-references) 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). From 53643ffafc960456f51ec13e5149463904260d53 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gergely=20Br=C3=A4utigam?= Date: Fri, 20 Mar 2026 16:57:13 +0100 Subject: [PATCH 04/14] chore: update code of conduct link (#138) On-behalf-of: Gergely Brautigam #### What this PR does / why we need it #### Which issue(s) this PR is related to --------- Signed-off-by: Gergely Brautigam <182850+Skarlso@users.noreply.github.com> Signed-off-by: Fabian Burth Co-authored-by: Fabian Burth Signed-off-by: Gerald Morrison (SAP) On-behalf-of: Gerald Morrison (SAP) --- .github/config/wordlist.txt | 1 + README.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/config/wordlist.txt b/.github/config/wordlist.txt index 52cb3fd..aa7ae54 100644 --- a/.github/config/wordlist.txt +++ b/.github/config/wordlist.txt @@ -21,6 +21,7 @@ JSON Kubernetes Lifecycle LocalBlob +NeoNephos NIST NPM NodeJS diff --git a/README.md b/README.md index e20ce40..e3b3d4f 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ Check out the main project [web page](https://ocm.software) to find out more abo Code contributions, feature requests, bug reports, and help requests are very welcome. Please refer to the [Contributing Guide in the Community repository](https://github.com/open-component-model/community/blob/main/CONTRIBUTING.md) for more information on how to contribute to OCM. -OCM follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). +OCM follows the [NeoNephos Code of Conduct](https://github.com/neonephos/.github/blob/main/CODE_OF_CONDUCT.md). ## Licensing From ce7a68e02bfccf8fc8a4eae67e3d02ac0822334c Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Mon, 30 Mar 2026 17:54:42 +0200 Subject: [PATCH 05/14] chore: add jsonNormalization in version v3 and v4alpha1 (#135) On-behalf-of: Gerald Morrison (SAP) #### What this PR does / why we need it add v3 and v4alpha1 of jsonNormalization --------- Signed-off-by: Gerald Morrison (SAP) Co-authored-by: Gerald Morrison (SAP) Signed-off-by: Gerald Morrison (SAP) On-behalf-of: Gerald Morrison (SAP) --- .../component-descriptor-normalization-algorithms.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md b/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md index 5c773b0..2c8ab97 100644 --- a/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md +++ b/doc/04-extensions/04-algorithms/component-descriptor-normalization-algorithms.md @@ -123,13 +123,13 @@ Labels are treated specially across all label-bearing elements (component, resou 1. **Only signing-relevant labels are included.** A label is signing-relevant if and only if its `signing` field is set to `true` (boolean or the string `"true"`).Labels without `signing: true` are excluded. 2. **For included labels, only these fields are preserved:** -- `name` -- `version` -- `value` -- `signing` + - `name` + - `version` + - `value` + - `signing` -1. **Other label metadata** (e.g. `mergeAlgorithm`) is excluded. -2. **If the resulting label array is empty after filtering, the entire `labels` field is omitted** (not serialized as `[]`). +3. **Other label metadata** (e.g. `mergeAlgorithm`) is excluded. +4. **If the resulting label array is empty after filtering, the entire `labels` field is omitted** (not serialized as `[]`). ### Serialization From 2b562d2cf13a33d2aafdd68474814ce31c2db39d Mon Sep 17 00:00:00 2001 From: "Gerald Morrison (SAP)" Date: Fri, 10 Apr 2026 15:46:35 +0200 Subject: [PATCH 06/14] add word On-behalf-of: Gerald Morrison (SAP) Signed-off-by: Gerald Morrison (SAP) --- .github/config/wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/config/wordlist.txt b/.github/config/wordlist.txt index aa7ae54..34d274d 100644 --- a/.github/config/wordlist.txt +++ b/.github/config/wordlist.txt @@ -136,3 +136,4 @@ wget whitespace whitespaces yaml +OCIImageLayer From 12eae392fd954dc2a7bd8a896d8e0ff37dd499be Mon Sep 17 00:00:00 2001 From: "Gerald Morrison (SAP)" Date: Mon, 13 Apr 2026 15:05:01 +0200 Subject: [PATCH 07/14] docs: complete alias lists and rename localBlob to LocalBlob - OCIImage: add ociArtifact/v1, ociRegistry(/v1), ociImage(/v1) aliases - OCIImageLayer: add ociBlob/v1 alias - Helm: add helm/v1 alias - LocalBlob: rename from localBlob, add localBlob(/v1) alias - README: update table to show LocalBlob On-behalf-of: Gerald Morrison (SAP) Signed-off-by: Gerald Morrison (SAP) --- doc/04-extensions/02-access-types/README.md | 2 +- doc/04-extensions/02-access-types/helm.md | 2 +- doc/04-extensions/02-access-types/localblob.md | 6 ++++-- doc/04-extensions/02-access-types/ociartifact.md | 5 ++++- doc/04-extensions/02-access-types/ociblob.md | 2 +- 5 files changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/04-extensions/02-access-types/README.md b/doc/04-extensions/02-access-types/README.md index 9711666..6d7a66b 100644 --- a/doc/04-extensions/02-access-types/README.md +++ b/doc/04-extensions/02-access-types/README.md @@ -10,7 +10,7 @@ The following access method types are centrally defined: | TYPE NAME | DESCRIPTION | |---------------------------------|-----------------------------------------------------| -| [`localBlob`](localblob.md) | an artifact stored along with the component version | +| [`LocalBlob`](localblob.md) | an artifact stored along with the component version | | [`OCIImage`](ociartifact.md) | an artifact in a repository of an OCI registry | | [`OCIImageLayer`](ociblob.md) | a blob in a repository of an OCI registry | | [`Helm`](helm.md) | a Helm chart stored in a Helm Repository | diff --git a/doc/04-extensions/02-access-types/helm.md b/doc/04-extensions/02-access-types/helm.md index bbbe079..1ab5780 100644 --- a/doc/04-extensions/02-access-types/helm.md +++ b/doc/04-extensions/02-access-types/helm.md @@ -7,7 +7,7 @@ type: Helm[/VERSION] [ATTRIBUTES] ``` -Legacy type name `helm` is supported as a backward-compatible alias. +Legacy type name `helm` / `helm/v1` is supported as a backward-compatible alias. ## Description diff --git a/doc/04-extensions/02-access-types/localblob.md b/doc/04-extensions/02-access-types/localblob.md index dbbe625..123361b 100644 --- a/doc/04-extensions/02-access-types/localblob.md +++ b/doc/04-extensions/02-access-types/localblob.md @@ -1,12 +1,14 @@ -# localBlob — Blob Hosted in OCM Repository +# LocalBlob — Blob Hosted in OCM Repository ## Synopsis ```text -type: localBlob/[VERSION] +type: LocalBlob[/VERSION] [ATTRIBUTES] ``` +Legacy type name `localBlob` / `localBlob/v1` is supported as a backward-compatible alias. + ## Description Access to a resource blob stored along with the component descriptor. diff --git a/doc/04-extensions/02-access-types/ociartifact.md b/doc/04-extensions/02-access-types/ociartifact.md index f964e60..ec53d8b 100644 --- a/doc/04-extensions/02-access-types/ociartifact.md +++ b/doc/04-extensions/02-access-types/ociartifact.md @@ -7,7 +7,10 @@ type: OCIImage[/VERSION] [ATTRIBUTES] ``` -Legacy type name `ociArtifact` is supported as a backward-compatible alias. +The following legacy type names are supported as backward-compatible aliases: +- `ociArtifact` / `ociArtifact/v1` +- `ociRegistry` / `ociRegistry/v1` +- `ociImage` / `ociImage/v1` ## Description diff --git a/doc/04-extensions/02-access-types/ociblob.md b/doc/04-extensions/02-access-types/ociblob.md index 30f8805..140384c 100644 --- a/doc/04-extensions/02-access-types/ociblob.md +++ b/doc/04-extensions/02-access-types/ociblob.md @@ -7,7 +7,7 @@ type: OCIImageLayer[/VERSION] [ATTRIBUTES] ``` -Legacy type name `ociBlob` is supported as a backward-compatible alias. +Legacy type name `ociBlob` / `ociBlob/v1` is supported as a backward-compatible alias. ## Description From a7f8d1bf0e42e03349c43fd980dcdf0790905d23 Mon Sep 17 00:00:00 2001 From: "Gerald Morrison (SAP)" Date: Mon, 13 Apr 2026 15:12:29 +0200 Subject: [PATCH 08/14] correct markdown linter errors On-behalf-of: Gerald Morrison (SAP) Signed-off-by: Gerald Morrison (SAP) --- doc/04-extensions/02-access-types/ociartifact.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/04-extensions/02-access-types/ociartifact.md b/doc/04-extensions/02-access-types/ociartifact.md index ec53d8b..79abe5b 100644 --- a/doc/04-extensions/02-access-types/ociartifact.md +++ b/doc/04-extensions/02-access-types/ociartifact.md @@ -8,6 +8,7 @@ type: OCIImage[/VERSION] ``` The following legacy type names are supported as backward-compatible aliases: + - `ociArtifact` / `ociArtifact/v1` - `ociRegistry` / `ociRegistry/v1` - `ociImage` / `ociImage/v1` From ddc4a2b98cf2c98c9cffb2cd69f7fb489f4fdff4 Mon Sep 17 00:00:00 2001 From: Gerald Morrison Date: Tue, 14 Apr 2026 11:11:35 +0200 Subject: [PATCH 09/14] docs: align wget, s3, gitHub, npm access type notation to UpperCamelCase Registers Wget, S3, GitHub, Npm as canonical type names with legacy lowercase forms retained as backward-compatible aliases, consistent with helm/ociArtifact/ociBlob/localBlob already updated in this branch. Signed-off-by: Gerald Morrison (SAP) On-behalf-of: Gerald Morrison (SAP) --- doc/04-extensions/02-access-types/README.md | 8 ++++---- doc/04-extensions/02-access-types/github.md | 6 ++++-- doc/04-extensions/02-access-types/npm.md | 6 ++++-- doc/04-extensions/02-access-types/s3.md | 6 ++++-- doc/04-extensions/02-access-types/wget.md | 6 ++++-- 5 files changed, 20 insertions(+), 12 deletions(-) diff --git a/doc/04-extensions/02-access-types/README.md b/doc/04-extensions/02-access-types/README.md index 6d7a66b..69558fc 100644 --- a/doc/04-extensions/02-access-types/README.md +++ b/doc/04-extensions/02-access-types/README.md @@ -14,7 +14,7 @@ The following access method types are centrally defined: | [`OCIImage`](ociartifact.md) | an artifact in a repository of an OCI registry | | [`OCIImageLayer`](ociblob.md) | a blob in a repository of an OCI registry | | [`Helm`](helm.md) | a Helm chart stored in a Helm Repository | -| [`gitHub`](github.md) | a commit in a GitHub-based Git repository | -| [`s3`](s3.md) | a blob stored in an AWS S3 bucket | -| [`npm`](npm.md) | a NodeJS package stored in an NPM repository | -| [`wget`](wget.md) | a blob stored on an HTTP server | +| [`GitHub`](github.md) | a commit in a GitHub-based Git repository | +| [`S3`](s3.md) | a blob stored in an AWS S3 bucket | +| [`Npm`](npm.md) | a NodeJS package stored in an NPM repository | +| [`Wget`](wget.md) | a blob stored on an HTTP server | diff --git a/doc/04-extensions/02-access-types/github.md b/doc/04-extensions/02-access-types/github.md index 223eb79..c39b55a 100644 --- a/doc/04-extensions/02-access-types/github.md +++ b/doc/04-extensions/02-access-types/github.md @@ -1,11 +1,13 @@ -# gitHub — Git Commit hosted by GitHub +# GitHub — Git Commit hosted by GitHub ## Synopsis ```text -type: gitHub/v1 +type: GitHub[/VERSION] ``` +Legacy type name `gitHub` / `gitHub/v1` is supported as a backward-compatible alias. + ## Description Access to a commit in a Git repository. diff --git a/doc/04-extensions/02-access-types/npm.md b/doc/04-extensions/02-access-types/npm.md index c3392e7..d6aba60 100644 --- a/doc/04-extensions/02-access-types/npm.md +++ b/doc/04-extensions/02-access-types/npm.md @@ -1,12 +1,14 @@ -# npm — Node Package Manager archive +# Npm — Node Package Manager archive ## Synopsis ```text -type: npm[/VERSION] +type: Npm[/VERSION] [ATTRIBUTES] ``` +Legacy type name `npm` / `npm/v1` is supported as a backward-compatible alias. + ## Description Access to an NodeJS package in an NPM registry. diff --git a/doc/04-extensions/02-access-types/s3.md b/doc/04-extensions/02-access-types/s3.md index 7839ec3..7ed485e 100644 --- a/doc/04-extensions/02-access-types/s3.md +++ b/doc/04-extensions/02-access-types/s3.md @@ -1,12 +1,14 @@ -# s3 — Blob hosted in S3 Blob Store +# S3 — Blob hosted in S3 Blob Store ## Synopsis ```text -type: s3[/VERSION] +type: S3[/VERSION] [ATTRIBUTES] ``` +Legacy type name `s3` / `s3/v1` is supported as a backward-compatible alias. + ## Description Access to a blob stored in an S3 API compatible bucket. diff --git a/doc/04-extensions/02-access-types/wget.md b/doc/04-extensions/02-access-types/wget.md index b8c099a..8ce79d8 100644 --- a/doc/04-extensions/02-access-types/wget.md +++ b/doc/04-extensions/02-access-types/wget.md @@ -1,12 +1,14 @@ -# wget — Blob hosted on an HTTP server +# Wget — Blob hosted on an HTTP server ## Synopsis ```text -type: wget[/VERSION] +type: Wget[/VERSION] [ATTRIBUTES] ``` +Legacy type name `wget` / `wget/v1` is supported as a backward-compatible alias. + ## Description Access to a blob stored on an HTTP server. From 21d7754ef88b6d5eb26829eafa12cdc77f7f2180 Mon Sep 17 00:00:00 2001 From: Gerald Morrison Date: Tue, 14 Apr 2026 11:31:29 +0200 Subject: [PATCH 10/14] docs: list both gitHub and github as legacy aliases for GitHub access type Signed-off-by: Gerald Morrison (SAP) On-behalf-of: Gerald Morrison (SAP) --- doc/04-extensions/02-access-types/github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/04-extensions/02-access-types/github.md b/doc/04-extensions/02-access-types/github.md index c39b55a..5fcf256 100644 --- a/doc/04-extensions/02-access-types/github.md +++ b/doc/04-extensions/02-access-types/github.md @@ -6,7 +6,7 @@ type: GitHub[/VERSION] ``` -Legacy type name `gitHub` / `gitHub/v1` is supported as a backward-compatible alias. +Legacy type names `gitHub` / `gitHub/v1` and `github` / `github/v1` are supported as backward-compatible aliases. ## Description From 963f639404ef357798a8a8e8982e1107a9fb5349 Mon Sep 17 00:00:00 2001 From: "Gerald Morrison (SAP)" Date: Fri, 17 Apr 2026 12:14:13 +0200 Subject: [PATCH 11/14] docs: add S3 v2 spec, rename Npm to NPM, simplify legacy alias mentions - Add S3/v2 section documenting renamed JSON fields (bucketName, objectKey) - Rename Npm type to NPM for acronym consistency with OCIImage, UTF8 - Remove explicit version suffixes from legacy alias sentences across all access type docs (version-agnostic prefix is sufficient) On-behalf-of: Gerald Morrison (SAP) Signed-off-by: Gerald Morrison (SAP) --- doc/04-extensions/02-access-types/README.md | 2 +- doc/04-extensions/02-access-types/github.md | 2 +- doc/04-extensions/02-access-types/helm.md | 2 +- .../02-access-types/localblob.md | 2 +- doc/04-extensions/02-access-types/npm.md | 6 ++--- .../02-access-types/ociartifact.md | 6 ++--- doc/04-extensions/02-access-types/ociblob.md | 2 +- doc/04-extensions/02-access-types/s3.md | 23 ++++++++++++++++++- doc/04-extensions/02-access-types/wget.md | 2 +- 9 files changed, 34 insertions(+), 13 deletions(-) diff --git a/doc/04-extensions/02-access-types/README.md b/doc/04-extensions/02-access-types/README.md index 69558fc..9c63f20 100644 --- a/doc/04-extensions/02-access-types/README.md +++ b/doc/04-extensions/02-access-types/README.md @@ -16,5 +16,5 @@ The following access method types are centrally defined: | [`Helm`](helm.md) | a Helm chart stored in a Helm Repository | | [`GitHub`](github.md) | a commit in a GitHub-based Git repository | | [`S3`](s3.md) | a blob stored in an AWS S3 bucket | -| [`Npm`](npm.md) | a NodeJS package stored in an NPM repository | +| [`NPM`](npm.md) | a NodeJS package stored in an NPM repository | | [`Wget`](wget.md) | a blob stored on an HTTP server | diff --git a/doc/04-extensions/02-access-types/github.md b/doc/04-extensions/02-access-types/github.md index 5fcf256..7a89165 100644 --- a/doc/04-extensions/02-access-types/github.md +++ b/doc/04-extensions/02-access-types/github.md @@ -6,7 +6,7 @@ type: GitHub[/VERSION] ``` -Legacy type names `gitHub` / `gitHub/v1` and `github` / `github/v1` are supported as backward-compatible aliases. +Legacy type names `gitHub` and `github` are supported as backward-compatible aliases. ## Description diff --git a/doc/04-extensions/02-access-types/helm.md b/doc/04-extensions/02-access-types/helm.md index 1ab5780..bbbe079 100644 --- a/doc/04-extensions/02-access-types/helm.md +++ b/doc/04-extensions/02-access-types/helm.md @@ -7,7 +7,7 @@ type: Helm[/VERSION] [ATTRIBUTES] ``` -Legacy type name `helm` / `helm/v1` is supported as a backward-compatible alias. +Legacy type name `helm` is supported as a backward-compatible alias. ## Description diff --git a/doc/04-extensions/02-access-types/localblob.md b/doc/04-extensions/02-access-types/localblob.md index 123361b..cda5ff5 100644 --- a/doc/04-extensions/02-access-types/localblob.md +++ b/doc/04-extensions/02-access-types/localblob.md @@ -7,7 +7,7 @@ type: LocalBlob[/VERSION] [ATTRIBUTES] ``` -Legacy type name `localBlob` / `localBlob/v1` is supported as a backward-compatible alias. +Legacy type name `localBlob` is supported as a backward-compatible alias. ## Description diff --git a/doc/04-extensions/02-access-types/npm.md b/doc/04-extensions/02-access-types/npm.md index d6aba60..2e04986 100644 --- a/doc/04-extensions/02-access-types/npm.md +++ b/doc/04-extensions/02-access-types/npm.md @@ -1,13 +1,13 @@ -# Npm — Node Package Manager archive +# NPM — Node Package Manager archive ## Synopsis ```text -type: Npm[/VERSION] +type: NPM[/VERSION] [ATTRIBUTES] ``` -Legacy type name `npm` / `npm/v1` is supported as a backward-compatible alias. +Legacy type name `npm` is supported as a backward-compatible alias. ## Description diff --git a/doc/04-extensions/02-access-types/ociartifact.md b/doc/04-extensions/02-access-types/ociartifact.md index 79abe5b..4b886cf 100644 --- a/doc/04-extensions/02-access-types/ociartifact.md +++ b/doc/04-extensions/02-access-types/ociartifact.md @@ -9,9 +9,9 @@ type: OCIImage[/VERSION] The following legacy type names are supported as backward-compatible aliases: -- `ociArtifact` / `ociArtifact/v1` -- `ociRegistry` / `ociRegistry/v1` -- `ociImage` / `ociImage/v1` +- `ociArtifact` +- `ociRegistry` +- `ociImage` ## Description diff --git a/doc/04-extensions/02-access-types/ociblob.md b/doc/04-extensions/02-access-types/ociblob.md index 140384c..30f8805 100644 --- a/doc/04-extensions/02-access-types/ociblob.md +++ b/doc/04-extensions/02-access-types/ociblob.md @@ -7,7 +7,7 @@ type: OCIImageLayer[/VERSION] [ATTRIBUTES] ``` -Legacy type name `ociBlob` / `ociBlob/v1` is supported as a backward-compatible alias. +Legacy type name `ociBlob` is supported as a backward-compatible alias. ## Description diff --git a/doc/04-extensions/02-access-types/s3.md b/doc/04-extensions/02-access-types/s3.md index 7ed485e..0c2d9b0 100644 --- a/doc/04-extensions/02-access-types/s3.md +++ b/doc/04-extensions/02-access-types/s3.md @@ -7,7 +7,7 @@ type: S3[/VERSION] [ATTRIBUTES] ``` -Legacy type name `s3` / `s3/v1` is supported as a backward-compatible alias. +Legacy type name `s3` is supported as a backward-compatible alias. ## Description @@ -41,3 +41,24 @@ Attributes: The media type of the blob used to store the resource. It may add format information like `+tar` or `+gzip`. + +### v2 + +Attributes: + +- **`region`** (optional) *string* + + region identifier of the used store + +- **`bucketName`** *string* + + The name of the S3 bucket containing the blob + +- **`objectKey`** *string* + + The key of the desired blob + +- **`mediaType`** *string* + + The media type of the blob used to store the resource. It may add + format information like `+tar` or `+gzip`. diff --git a/doc/04-extensions/02-access-types/wget.md b/doc/04-extensions/02-access-types/wget.md index 8ce79d8..502bd65 100644 --- a/doc/04-extensions/02-access-types/wget.md +++ b/doc/04-extensions/02-access-types/wget.md @@ -7,7 +7,7 @@ type: Wget[/VERSION] [ATTRIBUTES] ``` -Legacy type name `wget` / `wget/v1` is supported as a backward-compatible alias. +Legacy type name `wget` is supported as a backward-compatible alias. ## Description From 9bcbca9bf8259f184e2e9822b6c1054973dd2e08 Mon Sep 17 00:00:00 2001 From: "Gerald Morrison (SAP)" Date: Fri, 17 Apr 2026 12:21:56 +0200 Subject: [PATCH 12/14] correct table format On-behalf-of: Gerald Morrison (SAP) Signed-off-by: Gerald Morrison (SAP) --- doc/04-extensions/02-access-types/README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/04-extensions/02-access-types/README.md b/doc/04-extensions/02-access-types/README.md index 9c63f20..12fd23e 100644 --- a/doc/04-extensions/02-access-types/README.md +++ b/doc/04-extensions/02-access-types/README.md @@ -8,13 +8,13 @@ required to identify the blob and its location. The following access method types are centrally defined: -| TYPE NAME | DESCRIPTION | -|---------------------------------|-----------------------------------------------------| -| [`LocalBlob`](localblob.md) | an artifact stored along with the component version | -| [`OCIImage`](ociartifact.md) | an artifact in a repository of an OCI registry | -| [`OCIImageLayer`](ociblob.md) | a blob in a repository of an OCI registry | -| [`Helm`](helm.md) | a Helm chart stored in a Helm Repository | -| [`GitHub`](github.md) | a commit in a GitHub-based Git repository | -| [`S3`](s3.md) | a blob stored in an AWS S3 bucket | -| [`NPM`](npm.md) | a NodeJS package stored in an NPM repository | -| [`Wget`](wget.md) | a blob stored on an HTTP server | +| TYPE NAME | DESCRIPTION | +|:---------------------------------|-----------------------------------------------------| +| [`LocalBlob`](localblob.md) | an artifact stored along with the component version | +| [`OCIImage`](ociartifact.md) | an artifact in a repository of an OCI registry | +| [`OCIImageLayer`](ociblob.md) | a blob in a repository of an OCI registry | +| [`Helm`](helm.md) | a Helm chart stored in a Helm Repository | +| [`GitHub`](github.md) | a commit in a GitHub-based Git repository | +| [`S3`](s3.md) | a blob stored in an AWS S3 bucket | +| [`NPM`](npm.md) | a NodeJS package stored in an NPM repository | +| [`Wget`](wget.md) | a blob stored on an HTTP server | From 4b220955736350afd06a87ecce03b929170aa976 Mon Sep 17 00:00:00 2001 From: Gerald Morrison <67469729+morri-son@users.noreply.github.com> Date: Fri, 17 Apr 2026 12:22:51 +0200 Subject: [PATCH 13/14] Update doc/04-extensions/02-access-types/ociartifact.md Co-authored-by: Frederic Wilhelm Signed-off-by: Gerald Morrison <67469729+morri-son@users.noreply.github.com> --- doc/04-extensions/02-access-types/ociartifact.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/04-extensions/02-access-types/ociartifact.md b/doc/04-extensions/02-access-types/ociartifact.md index 4b886cf..15b8c61 100644 --- a/doc/04-extensions/02-access-types/ociartifact.md +++ b/doc/04-extensions/02-access-types/ociartifact.md @@ -1,4 +1,4 @@ -# OCIImage — Artifact hosted in OCI Repository +# OCIImage — Image hosted in OCI Repository ## Synopsis From 2bb37e4bc6c1060d055f2c89ba7e6934f055ed7e Mon Sep 17 00:00:00 2001 From: "Gerald Morrison (SAP)" Date: Fri, 17 Apr 2026 12:25:06 +0200 Subject: [PATCH 14/14] add v2 for s3 On-behalf-of: Gerald Morrison (SAP) Signed-off-by: Gerald Morrison (SAP) --- doc/04-extensions/02-access-types/s3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/04-extensions/02-access-types/s3.md b/doc/04-extensions/02-access-types/s3.md index 0c2d9b0..c9bb61a 100644 --- a/doc/04-extensions/02-access-types/s3.md +++ b/doc/04-extensions/02-access-types/s3.md @@ -1,4 +1,4 @@ -# S3 — Blob hosted in S3 Blob Store + # S3 — Blob hosted in S3 Blob Store ## Synopsis