Semantic Versioning Support for OpenAPI

Codebelt brings SemVer to Asp.Versioning

APIs are software components. They deserve the same release discipline, traceability, and compatibility signalling that we already expect from libraries, packages, containers, and tools.

With Codebelt.Extensions.Asp.Versioning 10.1.0, Codebelt introduces Semantic Versioning support for OpenAPI-oriented REST APIs through SemanticApiVersion and its related parser, formatter, and metadata attributes. This makes it possible to describe API versions as major.minor.patch, including pre-release identifiers and build metadata, while still integrating with the existing Asp.Versioning model.

This matters because the common REST API shorthand of v1, v2, and v3 is useful, but incomplete. A major version tells consumers which compatibility family they are using. It does not always tell them which exact released API artifact they are running against.

That distinction becomes important in the real world.

An API may move from v2.0.0 to v2.0.1 without changing the public interface at all. The OpenAPI shape may be identical. The route design may be identical. The request and response contracts may be identical. The release may simply contain dependency updates, runtime fixes, documentation improvements, or infrastructure hardening.

But if one dependency update introduces an exotic edge-case bug, support teams and customers need a precise answer to a simple question:

Which API release are we actually talking about?

With Semantic Versioning support, the answer can be v2.0.1, not just v2.

Why API versioning needs more than v1 and v2

Major-only API versioning is a good compatibility signal. It keeps URLs, documentation groups, and client conversations simple:

GET /v2/orders
Accept: application/json

However, major-only versioning is not a complete release identity.

When consumers report an issue, the difference between v2.0.0 and v2.0.1 can be operationally significant even when the API contract has not changed. A patch release may still change runtime behavior through dependency updates, serialization fixes, validation corrections, caching changes, security hardening, or infrastructure-level adjustments.

That does not mean every patch release is a breaking change. It means every released API artifact should be identifiable.

Semantic Versioning gives APIs a language for that:

• 2.0.0 identifies the first stable release in the v2 compatibility line.
• 2.0.1 identifies a patch release that should remain backward compatible.
• 2.1.0 identifies a backward-compatible feature addition.
• 3.0.0 identifies a breaking API change.
• 2.1.0-preview.1 identifies a pre-release version.
• 2.1.0+revision.42 can carry build metadata without changing precedence.

The result is a better support model: consumers can report the precise version, maintainers can compare the exact release delta, and teams can reason about compatibility without losing the familiar major-version API story.

What Codebelt adds

The 10.1.0 release introduces a focused semantic API versioning model for APIs that require major.minor.patch versioning with pre-release and build metadata support.

The release adds:

• SemanticApiVersion
• SemanticApiVersionParser
• SemanticApiVersionFormatter
• SemanticApiVersionAttribute
• MapToSemanticApiVersionAttribute
• VersionConversionOptions

Together, these types provide a developer-friendly way to use Semantic Versioning with Asp.Versioning instead of hand-rolling parsing, formatting, comparison, and attribute mapping logic.

The important part is that Codebelt does not ask teams to abandon the existing ASP.NET Core versioning ecosystem. It complements Asp.Versioning by adding semantic release identity where the standard ApiVersion model is not expressive enough.

Designed for OpenAPI transparency

OpenAPI documents are often treated as the source of truth for client integration. They describe the public surface area of the API: operations, parameters, schemas, responses, security requirements, and versioned documentation groups.

That makes OpenAPI a natural place to expose precise API release identity.

When an API is documented as v2, consumers know the compatibility family. When it is also identified as 2.0.1, they know the exact release line. That extra precision gives support, platform, and integration teams a stronger basis for diagnostics.

For example:

Customer A reports an issue against v2.0.1.
Customer B is still running successfully against v2.0.0.
The public OpenAPI contract did not change.
The implementation and dependency graph did.

That is exactly the kind of scenario where semantic API versioning provides value. It does not create noise in the public contract. It improves transparency around the released component.

A small API for a precise concept

Codebelt keeps the developer experience intentionally simple.

Instead of forcing teams to model semantic versions as strings throughout their codebase, SemanticApiVersion gives the version a dedicated type:

var version = new SemanticApiVersion(2, 0, 1);

Pre-release identifiers and build metadata are supported when needed:

var preview = new SemanticApiVersion(2, 1, 0, prerelease: "preview.1");

var build = new SemanticApiVersion(2, 0, 1, buildMetadata: "revision.42");

Attribute-based usage is also available for controller and action metadata:

[ApiController]
[Route("orders")]
[SemanticApiVersion("2.0.0")]
[SemanticApiVersion("2.0.1")]
public sealed class OrdersController : ControllerBase
{
    [HttpGet]
    [MapToSemanticApiVersion("2.0.1")]
    public IActionResult Get()
    {
        return Ok();
    }
}

For teams that prefer strongly-typed constructor arguments over strings, the same intent can be expressed without parsing at the call site:

[SemanticApiVersion(2, 0, 1)]

That is the Codebelt approach: clear intent, less ceremony, and fewer custom conventions to maintain.

Correct SemVer behavior where it matters

Semantic Versioning has two related but different concerns:

1. Version identity
2. Version precedence

SemanticApiVersion handles both.

Exact identity includes the complete version, including build metadata. That means 2.0.1+revision.42 and 2.0.1+revision.43 can be treated as distinct released artifacts.

Precedence comparison follows the SemVer rule that build metadata does not affect ordering. That means build metadata can improve traceability without incorrectly changing the compatibility order of two versions.

This is an important distinction for APIs. Build metadata can help identify what was deployed, while precedence still answers which version is newer in the semantic compatibility sequence.

Mapping .NET versions to API versions

Codebelt also adds VersionConversionOptions for converting .NET Version values into semantic API versions.

The conversion model is intentionally explicit:

• Version.Major maps to semantic major.
• Version.Minor maps to semantic minor.
• Version.Build maps to semantic patch.
• Version.Revision can be included as build metadata when configured.

That gives teams a safe bridge from .NET’s four-part version model to SemVer’s major.minor.patch model.

For example, a .NET version such as:

2.0.1.42

can be represented as a semantic API version such as:

2.0.1+revision.42

That preserves the meaningful SemVer core while keeping the revision available as metadata.

Fast feedback, less code

RESTful API versioning in ASP.NET Core can require several coordinated pieces: API versioning registration, MVC registration, API Explorer integration, version readers, error behavior, and OpenAPI/Swagger generation.

Codebelt’s versioning package already focuses on making that setup more convenient through a single registration path and RESTful defaults. Semantic API versioning continues that direction.

The feature is developer-friendly because it gives teams:

• a dedicated semantic API version type,
• parser and formatter support,
• attribute-based metadata,
• API Explorer integration,
• conversion from .NET Version,
• and test coverage for parsing, formatting, comparison, and API explorer integration.

The practical result is faster feedback and less code. Developers can describe the API version they mean instead of building small, local SemVer utilities in every service.

Recommended usage

Use major API versions to communicate compatibility families:

v1
v2
v3

Use semantic API versions to communicate precise release identity:

1.0.0
2.0.0
2.0.1
2.1.0
3.0.0

Use build metadata when the deployed artifact needs additional traceability without changing version precedence:

2.0.1+revision.42

Use pre-release identifiers only when the API surface is intentionally published as preview, release candidate, or otherwise non-stable:

2.1.0-preview.1
2.1.0-rc.1

This gives API teams a balanced model:

• simple major-version language for consumers,
• precise semantic version identity for documentation and support,
• optional diagnostic metadata for operations,
• and compatibility semantics that match established software release practices.

Why this matters for customers

Good API versioning is not only for developers. It is also for consumers, support engineers, platform teams, and product owners.

When a customer reports a production issue, the conversation should not stop at:

We are using v2.

It should be possible to say:

We are using v2.0.1.

That extra precision can make the difference between guessing and diagnosing.

If v2.0.0 worked and v2.0.1 introduced an edge-case regression, teams can compare the exact release delta. If the patch only contained dependency updates, that becomes part of the investigation. If build metadata identifies the deployed revision, the path from customer report to source change becomes shorter.

That is the core value of Semantic Versioning support for OpenAPI: transparent APIs, traceable releases, and fewer ambiguous support conversations.

Summary

SemanticApiVersion brings Semantic Versioning into the API versioning model where it belongs: close to the OpenAPI documentation, close to the ASP.NET Core version metadata, and close to the developers maintaining the API.

Major versions remain useful. They still provide the simple v1 and v2 language that REST API consumers understand.

Semantic versions add the missing precision.

With Codebelt, API teams can express both.

That means more transparent APIs, better diagnostics, clearer release communication, and a more disciplined developer experience — with fast feedback and less code.