ARM consistent API version behavior

[Bpoe]

Summary of the new feature / enhancement

We need ARM consistent API version handling. This includes:

• ARM compatible version formats - i.e. "2025-07-04-preview"
• The ability to pass the API version to the module when called - or - the ability to call a different module based on API version
• The exact API version should be called without automatically using a higher version

Proposed technical implementation details (optional)

No response

[SteveL-MSFT]

@Bpoe and I discussed this and came up with couple of options:

1. we can have both version (semver) and apiVersion (date) supported, but this can cause confusion to users if some resources support one vs the other
2. we can have version (aliased to apiVersion) accept both semver and date and if date, it has to be an exact match. This means in the resource manifest, it can be either a semver or date (we would still recommend semver), but this means resource authors have to decide which "world" they participate in

[ThomasNieto]

How does a date version communicate any breaking changes? If it can't do that it shouldn't be a valid option. Users of resources have to know when there are breaking changes to the resource that require updates to the configuration document.

[SteveL-MSFT]

@ThomasNieto agreed, but we have some specific partner scenarios that require support for date format. My expectation is that general DSC resources should use semver.

[ThomasNieto]

Since it sounds like DSC needs to support date type versions. DSC should still have single version property with strict checking of the format. In the issue about having ambiguous output from a resource there was an argument about tools calling resources need a strong contract. This is very similar if version or apiVersion and one of them being populated or apiVersion supporting both semver or date creates issues on the caller side with what data type will be returned from the manifest.

To alleviate those issues I propose a single version property that has a child property of semantic or date (example names) which adhere to strict JSON schema validation of the data type formats. In this model only one version type is allowed preventing confusion on the caller side. Then it also allows for supporting additional version schemes in the future.

{
  "type": "object",
  "properties": {
    "version": {
      "type": "object",
      "properties": {
        "semantic": {
          "type": "string",
          "pattern": "^\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z-.]+)?(\\+[0-9A-Za-z-.]+)?$"
        },
        "date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}(-preview)?$"
        }
      },
      "oneOf": [
        { "required": ["semantic"] },
        { "required": ["date"] }
      ]
    }
  },
  "required": ["version"]
}

[SteveL-MSFT]

We don't want to deviate from ARM template syntax unless we must. In this particular case, I think we simply keep version as alias to apiVersion and recommend semver. The need for supporting date style versioning is a specific partner scenario, so I think we simply allow that to pass-through the currently strict semver validation. I think if semver validation fails, we fall-through to a regex that validates YYYY-MM-DD-text otherwise we reject it. For semver, we would (once that feature is implemented) allow partial versions such that 3.1 would match 3.1.2, but date format MUST be exact.