{ "api_version": "1", "kind": "dse_post", "self": "https://update.dsesecurity.com/api/v1/posts/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/", "item": { "id": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/", "slug": "dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions", "url": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/", "alternate_urls": { "markdown": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions.md", "json": "https://update.dsesecurity.com/api/v1/posts/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/" }, "title": "Review ARM template revisions separately from resource API versions", "summary": "Does incrementing contentVersion change the API used to deploy an ARM resource?", "format": { "slug": "guide", "name": "Guide" }, "priority": { "slug": "info", "name": "Information" }, "featured": false, "image": { "theme": "network-infrastructure", "label": "Networks & infrastructure", "alt": "Resilient network core with engineered blue and gold data paths.", "card_url": "https://update.dsesecurity.com/assets/editorial/network-infrastructure-card.webp?v=1.8.20", "hero_url": "https://update.dsesecurity.com/assets/editorial/network-infrastructure-hero.webp?v=1.8.20", "social_url": "https://update.dsesecurity.com/assets/editorial/network-infrastructure-social-v2.jpg?v=1.8.20", "width": 2400, "height": 1350 }, "topics": [ { "slug": "it", "name": "IT", "url": "https://update.dsesecurity.com/topic/it/" }, { "slug": "networks-infrastructure", "name": "Networks & Infrastructure", "url": "https://update.dsesecurity.com/topic/networks-infrastructure/" } ], "author": { "name": "DSE Security Editorial Team", "url": "https://update.dsesecurity.com/#editorial-team", "type": "Organization" }, "publisher": { "name": "Detection Systems & Engineering", "url": "https://dsesecurity.com/" }, "published_at": "2026-09-10T00:29:48+00:00", "modified_at": "2026-09-10T00:52:38+00:00", "reviewed_on": "2026-09-09", "reading_minutes": 2, "word_count": 234, "potentially_affected": "Azure Resource Manager JSON templates with contentVersion and resource apiVersion fields.", "dse_recommendation": "DSE recommends describing the purpose of each version-field change in the review.", "primary_source": { "name": "Template structure and syntax - Azure Resource Manager | Microsoft Learn", "url": "https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/syntax", "published_on": null, "authority": "Microsoft Learn" }, "publishing_principles": "https://update.dsesecurity.com/updates/dse-updates-editorial-methodology/", "usage_info": "https://update.dsesecurity.com/usage/", "copyright_notice": "Copyright © 2026 Detection Systems & Engineering. All rights reserved.", "content_html": "

Source facts

\n

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.

\n

Applicability

\n

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.

\n

DSE recommendation

\n

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.

\n

Verification

\n

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.

\n

Official references

\n

Microsoft Learn. Source retrieved September 9, 2026.

", "content_text": "Source facts\nARM’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.\nApplicability\nApply 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.\nDSE recommendation\nDSE 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.\nVerification\nCompare 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.\nOfficial references\nMicrosoft Learn. Source retrieved September 9, 2026.", "content_markdown": "## Source facts\n\nARM’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](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/syntax).\n\n## Applicability\n\nApply 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.\n\n## DSE recommendation\n\nDSE 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.\n\n## Verification\n\nCompare 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.\n\n## Official references\n\n[Microsoft Learn](https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/syntax). Source retrieved September 9, 2026." }, "json_ld": { "@context": "https://schema.org", "@graph": [ { "@type": "Organization", "@id": "https://dsesecurity.com/#organization", "name": "Detection Systems & Engineering", "alternateName": "DSE Security", "url": "https://dsesecurity.com/", "logo": { "@type": "ImageObject", "url": "https://update.dsesecurity.com/assets/dse-logo-20260812.png?v=1.8.20" } }, { "@type": "Organization", "@id": "https://update.dsesecurity.com/#editorial-team", "name": "DSE Security Editorial Team", "url": "https://update.dsesecurity.com/", "parentOrganization": { "@id": "https://dsesecurity.com/#organization" } }, { "@type": "WebSite", "@id": "https://update.dsesecurity.com/#website", "name": "DSE Updates", "alternateName": "DSE Security Knowledge Hub", "url": "https://update.dsesecurity.com/", "inLanguage": "en-US", "publisher": { "@id": "https://dsesecurity.com/#organization" }, "potentialAction": { "@type": "SearchAction", "target": { "@type": "EntryPoint", "urlTemplate": "https://update.dsesecurity.com/?q={search_term_string}" }, "query-input": "required name=search_term_string" } }, { "@type": "WebPage", "@id": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/", "url": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/", "isPartOf": { "@id": "https://update.dsesecurity.com/#website" }, "lastReviewed": "2026-09-09" }, { "@type": "BreadcrumbList", "@id": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/#breadcrumbs", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "DSE Updates", "item": "https://update.dsesecurity.com/" }, { "@type": "ListItem", "position": 2, "name": "Review ARM template revisions separately from resource API versions", "item": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/" } ] }, { "@type": [ "Article", "TechArticle" ], "@id": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/#article", "identifier": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/", "url": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/", "headline": "Review ARM template revisions separately from resource API versions", "description": "Does incrementing contentVersion change the API used to deploy an ARM resource?", "abstract": "Does incrementing contentVersion change the API used to deploy an ARM resource?", "articleBody": "Source facts\nARM’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.\nApplicability\nApply 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.\nDSE recommendation\nDSE 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.\nVerification\nCompare 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.\nOfficial references\nMicrosoft Learn. Source retrieved September 9, 2026.", "datePublished": "2026-09-10T00:29:48+00:00", "dateModified": "2026-09-10T00:52:38+00:00", "mainEntityOfPage": { "@id": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/" }, "inLanguage": "en-US", "isAccessibleForFree": true, "author": { "@type": "Organization", "name": "DSE Security Editorial Team", "url": "https://update.dsesecurity.com/#editorial-team" }, "publisher": { "@id": "https://dsesecurity.com/#organization" }, "image": { "@type": "ImageObject", "@id": "https://update.dsesecurity.com/updates/dse-20260909-128-review-arm-template-revisions-separately-from-resource-api-versions/#primaryimage", "url": "https://update.dsesecurity.com/assets/editorial/network-infrastructure-social-v2.jpg?v=1.8.20", "contentUrl": "https://update.dsesecurity.com/assets/editorial/network-infrastructure-social-v2.jpg?v=1.8.20", "width": 1200, "height": 630, "caption": "Review ARM template revisions separately from resource API versions" }, "articleSection": [ "IT", "Networks & Infrastructure" ], "keywords": [ "IT", "Networks & Infrastructure", "Guide", "Information priority" ], "genre": "Guide", "about": [ { "@type": "Thing", "name": "IT", "url": "https://update.dsesecurity.com/topic/it/" }, { "@type": "Thing", "name": "Networks & Infrastructure", "url": "https://update.dsesecurity.com/topic/networks-infrastructure/" } ], "wordCount": 234, "timeRequired": "PT2M", "publishingPrinciples": "https://update.dsesecurity.com/updates/dse-updates-editorial-methodology/", "usageInfo": "https://update.dsesecurity.com/usage/", "copyrightHolder": { "@id": "https://dsesecurity.com/#organization" }, "copyrightNotice": "Copyright © 2026 Detection Systems & Engineering. All rights reserved.", "citation": { "@type": "CreativeWork", "name": "Template structure and syntax - Azure Resource Manager | Microsoft Learn", "url": "https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/syntax" } } ] } }