Review ARM template revisions separately from resource API versions

Source facts

ARM’s contentVersion records the template’s version and can document significant template changes. A resource’s apiVersion selects the REST API used to create that resource. Microsoft recommends retaining a working resource API version and considering an update when a later version provides a needed feature. These are different versioning decisions. Microsoft Learn.

Applicability

Apply this distinction during template maintenance and release review. Identify whether a proposed edit labels a new template revision or changes the resource API contract. Keep the template language version and resource API choice visible as separate fields rather than treating every version string as interchangeable.

DSE recommendation

DSE recommends describing the purpose of each version-field change in the review. For a template revision, retain the actual content diff with its revision label. For a resource API update, inspect the intended feature and relevant resource schema, then plan a controlled deployment check. Avoid combining an unexplained API change with an otherwise administrative release-number update.

Verification

Compare the previous and proposed templates field by field. Verify which resources, if any, have a changed apiVersion and assess those changes against their intended configuration. Use approved validation and test deployment evidence for the affected resources before production release. Preserve both the template revision and the specific resource API versions in the acceptance record; a higher template version alone should not be described as an API upgrade.

Official references

Microsoft Learn. Source retrieved September 9, 2026.