Course contentsShow
← Cloud and Infrastructure
Lesson 896 of 2,98917. Azure ARM Templates and BicepFree lesson

API Versions and Resource Schemas

Understand how apiVersion determines available properties and features for each resource type.

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 apiVersion values
  • 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.