Merge pull request #307308 from mumian/1023-onlyifnotexist

Document the onlyIfNotExist decorator

Author: Stacyrch140

articles/azure-resource-manager/bicep/resource-declaration.md

@@ -3,7 +3,7 @@ title: Declare resources in Bicep
 description: Describes how to declare resources to deploy in Bicep.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 04/28/2025
+ms.date: 10/24/2025
 ---
 
 # Resource declaration in Bicep
@@ -68,6 +68,7 @@ Decorators are written in the format `@expression` and are placed above resource
 | --------- | ----------- | ------- |
 | [batchSize](./bicep-import.md#export-variables-types-and-functions) | none | Set up instances to deploy sequentially. |
 | [description](#description) | string | Provide descriptions for the resource. |
+| [onlyIfNotExists](#onlyifnotexists) | none | Deploy the resource only if it doesn't already exist in the target scope. |
 
 Decorators are in the [sys namespace](bicep-functions.md#namespaces-for-functions). If you need to differentiate a decorator from another item with the same name, preface the decorator with `sys`. For example, if your Bicep file includes a parameter named `description`, you must add the sys namespace when using the **description** decorator.
 
@@ -99,6 +100,24 @@ resource storageAccountResources 'Microsoft.Storage/storageAccounts@2024-01-01'
 
 Markdown-formatted text can be used for the description text.
 
+### onlyIfNotExists
+
+By default, when a Bicep deployment runs, Azure Resource Manager (ARM) creates the resource if it doesn’t exist or updates it if it does. If an existing resource has properties that differ from your template, ARM might attempt to update it—or fail if updates aren’t permitted.
+
+Starting with Bicep version v0.38.3, the `@onlyIfNotExists()` decorator instructs ARM to create the resource only if it does not already exist. If a resource with the resource ID is found, ARM skips creation and leaves the existing resource unchanged.
+
+```bicep
+@onlyIfNotExists()
+resource example 'Microsoft.Storage/storageAccounts@2025-01-01' = {
+  name: 'mystorageacct'
+  location: resourceGroup().location
+  kind: 'StorageV2'
+  sku: {
+    name: 'Standard_LRS'
+  }
+}
+```
+
 ## Resource name
 
 Each resource has a name. When setting the resource name, pay attention to the [rules and restrictions for resource names](../management/resource-name-rules.md).

articles/azure-resource-manager/bicep/toc.yml

@@ -267,6 +267,7 @@ items:
         href: variables.md
         displayName: configuration
       - name: Resources (resource)
+        displayName: batchsize,onlyifnotexists,description,decorators
         href: resource-declaration.md
       - name: Outputs (output)
         href: outputs.md