From a6ad18c270f0e98996dc4870b461bcf817ba2e46 Mon Sep 17 00:00:00 2001 From: Piotr Janik Date: Mon, 27 Jul 2026 09:44:19 +0200 Subject: [PATCH 1/4] docs(oci): relax component version identification rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #### What this PR does / why we need it Requiring the deprecated `software.ocm.componentversion` annotation on every tagged manifest is too strict: it forces writers to keep emitting a deprecated form and gives readers no sanctioned fallback when it is absent. This relaxes the OCI storage-backend spec so that annotation becomes optional (`MUST` → `MAY`), promotes the component-key annotations to the recommended verification form (`MAY` → `SHOULD`), and defines a deterministic fallback: when no annotation is present, clients identify a component version by the manifest config media type (current or legacy Gardener/cnudie) and derive the version from the tag. The compatibility section documents the two legacy config media types readers SHOULD accept and writers MUST NOT produce. #### Which issue(s) this PR fixes Fixes: https://github.com/open-component-model/ocm-spec/issues/2889 Signed-off-by: Piotr Janik --- doc/04-extensions/03-storage-backends/oci.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/doc/04-extensions/03-storage-backends/oci.md b/doc/04-extensions/03-storage-backends/oci.md index 6625989..0d903fd 100644 --- a/doc/04-extensions/03-storage-backends/oci.md +++ b/doc/04-extensions/03-storage-backends/oci.md @@ -779,20 +779,25 @@ Examples: | `1.2.3.build-ci.42` | `1.2.3+ci.42` | Tags **SHOULD** reference a manifest or index (see [6](#6-component-version-storage-models)), -whose descriptor **MUST** include the (deprecated) annotation: +whose descriptor **MAY** include the (deprecated) annotation: ```text software.ocm.componentversion: ":" ``` The descriptor **MAY** also be identified by component key annotations from [6.3 Asset Annotations](#63-asset-annotations) -as an alternative to the above annotation. Clients **MAY** use one of or both forms for verification: +as an alternative to the above annotation. Clients **SHOULD** use one of or both forms for verification: ```text software.ocm.component.name: "" software.ocm.component.version: "" ``` +When neither annotation form is present, clients **SHOULD** identify a component version +by the manifest's config media type: the media type defined in +[6.1 Manifest Representation](#61-manifest-representation), or one of the legacy media +types listed in [13. Compatibility Requirements](#13-compatibility-requirements). + ### 12.1 Version Aliasing OCI tags such as `latest`, `stable`, or other user-defined symbolic names are not OCM versions. @@ -899,6 +904,12 @@ callers to handle the capability gap gracefully. * Descriptor formats (YAML, JSON, TAR) **SHOULD** be read; at least one **MUST** be written. * Index-based representation **MUST NOT** deprecate manifest-based. * Component Index semantics **MAY** rely on registry referrer support but MUST NOT require it. +* Readers **SHOULD** accept the legacy (pre-OCM Gardener/cnudie) config media types + `application/vnd.gardener.cloud.cnudie.component.config.v1+json` and + `application/vnd.oci.gardener.cloud.cnudie.component-descriptor-metadata.config.v2+json` + as identifying a component version manifest (see + [12. Tag and Version Mapping Rules](#12-tag-and-version-mapping-rules)); writers + **MUST NOT** produce them. ## Examples (Informative) From 51885fcf35226a1be11e7e91ffb7eee61e67bc75 Mon Sep 17 00:00:00 2001 From: Piotr Janik Date: Tue, 28 Jul 2026 11:55:27 +0200 Subject: [PATCH 2/4] docs(oci): prefer componentversion over legacy config media type Signed-off-by: Piotr Janik --- doc/04-extensions/03-storage-backends/oci.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/04-extensions/03-storage-backends/oci.md b/doc/04-extensions/03-storage-backends/oci.md index 0d903fd..6ddd025 100644 --- a/doc/04-extensions/03-storage-backends/oci.md +++ b/doc/04-extensions/03-storage-backends/oci.md @@ -907,9 +907,12 @@ callers to handle the capability gap gracefully. * Readers **SHOULD** accept the legacy (pre-OCM Gardener/cnudie) config media types `application/vnd.gardener.cloud.cnudie.component.config.v1+json` and `application/vnd.oci.gardener.cloud.cnudie.component-descriptor-metadata.config.v2+json` - as identifying a component version manifest (see - [12. Tag and Version Mapping Rules](#12-tag-and-version-mapping-rules)); writers - **MUST NOT** produce them. + as identifying a component version manifest; writers **MUST NOT** produce them. +* When a manifest carries both a legacy config media type and the + `software.ocm.componentversion` annotation, the annotation **MUST** take precedence: + readers **MUST** identify the component version from `software.ocm.componentversion` + (see [12. Tag and Version Mapping Rules](#12-tag-and-version-mapping-rules)) and + **MUST NOT** derive it from the legacy config media type. ## Examples (Informative) From 8afee57e86a42ed4df6baa05f7376864028da00c Mon Sep 17 00:00:00 2001 From: Piotr Janik Date: Mon, 3 Aug 2026 15:31:12 +0200 Subject: [PATCH 3/4] chore: empty commit Signed-off-by: Piotr Janik From 4b236a19a9d7457dabd364b1e49e7bb2f979dccc Mon Sep 17 00:00:00 2001 From: Piotr Janik Date: Mon, 3 Aug 2026 16:04:50 +0200 Subject: [PATCH 4/4] I am empty Signed-off-by: Piotr Janik