Proposal: More semantically correct alias for `apiVersion` in configuration document

[michaeltlombardi]

Summary of the new feature / enhancement

As a configuration document author and reader,
I want the field that defines a version requirement for a resource to make immediate sense,
so that I don't have to double check documentation to understand what it does.

Currently, in a configuration document, I might define the following snippets to pin the usage of a resource to specific versions or version ranges:

# This snippet elides unrelated fields, like `$schema` and `properties`
resources
  - name: pinned to specific semver
    type: Versioned.Semantically/Resource
    apiVersion: =1.2.3 # exactly `1.2.3`

  - name: implicitly pinned to semver range
    type: Versioned.Semantically/Resource
    apiVersion: 1.2.3  # expands to `>=1.2.3, <2.0.0`

  - name: pinned to exact string match for non-semver
    type: Versioned.ByReleaseDate/Resource
    apiVersion: 2026-02-01

In an ARM context, apiVersion makes sense because it maps to the API that the resource is interacting with. In a DSC context, the api prefix doesn't make immediate sense. Moreover, for DSC, the string maps to a version requirement, not exclusively to an exact version - and apiVersion: 1.2.3 is not identical to apiVersion: =1.2.3.

I think the more semantically correct name for this field is versionRequirement or requiredVersion.

Proposed technical implementation details (optional)

Given that this field was added in 3.2.0-preview.4, I think we should consider renaming this field before making the stable release and keeping apiVersion as an alias.

We probably need specific handling when exporting for ARM, but I think that transformation is tractable.

Proposed canonical field names with JSON representation:

Rust field name	JSON field name	JSON alias
required_version	requiredVersion	apiVersion
version_requirement	versionRequirement	apiVersion

Note

As an aside, as part of the schema canonicalization work, I'm defining a newtype for this value so we would be passing a ResourceVersionReq instead of a string, but that's not directly related to the renaming for this field in a configuration document.

[SteveL-MSFT]

I think requireVersion makes the most sense and consistent with other naming like requireAdapter

[theJasonHelmick]

The apiVersion will still be an alias.