API Versions and Resource Schemas
What You'll Learn
You'll learn why every ARM template resource must declare an apiVersion, and how that single value determines what properties and features are available for that resource.
The Role of apiVersion
In ARM templates, the apiVersion property isn't optional decoration—it's the contract between your template and Azure's REST API. Each Azure resource type evolves over time: new properties get added, behaviors change, and features expand. The apiVersion acts like a snapshot, locking your resource declaration to a specific "version" of that resource's schema.
Think of it like ordering from a restaurant menu. The apiVersion is the menu date—a 2020 menu might not include dishes added in 2023. Similarly, "Microsoft.Storage/storageAccounts" with apiVersion "2019-06-01" supports different properties than "2023-01-01".
How API Versions Control Schemas
When you specify:
{
"type": "Microsoft.Compute/virtualMachines",
"apiVersion": "2021-07-01",
"name": "myVM"
}
Azure validates your template against the 2021-07-01 schema for virtual machines. Properties introduced in later versions (like new security features in 2023) won't be recognized. Conversely, deprecated properties from older versions might no longer work in newer apiVersion values.
Finding the Right Version
Always check Azure's documentation for each resource type to see:
- Available
apiVersionvalues - What properties each version supports
- Whether versions are stable, preview, or deprecated
Using outdated versions works but locks you out of new features. Using the latest stable version is generally recommended for production templates.
Key Takeaway: The apiVersion determines the exact schema, properties, and behaviors available for each resource—choose it deliberately based on the features you need and Azure's stability guarantees.