Configure a Versioning Scheme

By default OCM assumes semantic versioning. This tutorial shows how to configure a calendar versioning (CalVer) scheme so OCM accepts versions like 2024.03.15 and orders them newest-first.

What You’ll Learn#

By the end of this tutorial, you will:

• Write a versioning.config.ocm.software/v1alpha1 entry in your .ocmconfig
• Add and list CalVer component versions with the OCM CLI
• Confirm the active versioning scheme with ocm get config

Estimated time: ~5 minutes

Prerequisites#

• OCM CLI installed
• A working directory you can write to (example: /tmp/ocm-versioning)

Scenario#

• Component: acme.org/service
• Versions: 2024.03.15 and 2024.10.01 (CalVer YYYY.MM.DD)
• Repository: a local CTF archive ./ctf
• Config file: versioning.ocmconfig

Tutorial Steps#

1. Write the versioning configuration#

   Create versioning.ocmconfig with a CalVer scheme. Here we use the built-in calver-full scheme (see the catalog); it is equivalent to writing the CalVer pattern by hand. Once you configure schemes, the built-in loose-semver scheme is no longer added automatically, so add an explicit builtin: loose-semver entry to keep semver versions working.

   type: generic.config.ocm.software/v1
   configurations:
     - type: versioning.config.ocm.software/v1alpha1
       schemes:
         - builtin: calver-full
         - builtin: loose-semver

2. Create a component constructor#

   Save this as component-constructor.yaml:

   components:
     - name: acme.org/service
       version: "2024.03.15"
       provider:
         name: acme.org

3. Add the first CalVer version#

   Without the versioning config this fails version validation. With --config versioning.ocmconfig, the CalVer scheme accepts it:

   ocm --config versioning.ocmconfig add cv --repository ./ctf --constructor component-constructor.yaml

   Expected output

    COMPONENT         │ VERSION    │ PROVIDER
   ───────────────────┼────────────┼──────────
    acme.org/service  │ 2024.03.15 │ acme.org

4. Add a newer CalVer version#

   Change version in component-constructor.yaml to "2024.10.01" and add it to the same archive:

   ocm --config versioning.ocmconfig add cv --repository ./ctf --constructor component-constructor.yaml

5. List versions and observe the ordering#

   ocm --config versioning.ocmconfig get cv ./ctf//acme.org/service -o yaml

   Both versions are accepted and listed newest-first: 2024.10.01 appears before 2024.03.15. The CalVer scheme compares the year, month, and day capture groups numerically — not lexically.

6. Confirm the active scheme#

   Print the effective merged configuration to verify the CalVer scheme is loaded:

   ocm --config versioning.ocmconfig get config

   The effective configuration includes your versioning.config.ocm.software/v1alpha1 entry with its schemes, confirming the CalVer scheme is active.

What you’ve learned#

• You configured a regex-based CalVer scheme with named comparison groups.
• You added and listed non-semver component versions that OCM would otherwise reject.
• You confirmed correct newest-first ordering and inspected the active configuration.

Troubleshooting#

Problem: add cv fails with an invalid version error#

Cause: The version does not match any configured scheme (or you forgot --config versioning.ocmconfig).

Fix: Ensure the pattern matches your version string and that you pass the config file.

Problem: The version is rejected as an invalid OCI tag#

Cause: OCI tags allow only ^[\w][\w.-]{0,127}$. A version containing :, /, ~, or spaces cannot be a tag and is rejected at publish time. A + (semver build metadata) is the exception: it is rewritten to .build- for the tag, but that rewrite is not reversed on read, so the version you list differs from the one you added — avoid + too.

Fix: Choose a scheme whose versions are valid OCI tags. See OCI Tag Constraints.

Related documentation#

• Versioning Configuration — Full schema, scheme catalog, and OCI tag constraints.
• Resolver Configuration — How versionConstraint interacts with versioning schemes.