Bicep Modules

Workflow

Always follow this order for every module task:

1. Identify resource type — determine the Azure resource being authored or modified
2. Read security baselines — open references/security-baselines.md and locate the section for this resource type; apply all defaults
3. Read cost guidelines — if SKU or tier selection is needed, open references/cost-guidelines.md and apply the appropriate default with upgrade path documented in the parameter description
4. Read conventions — open references/conventions.md for role assignments, private endpoints, network rule construction, App Config key-values, or any complex structural pattern
5. Produce the module — write the complete Bicep file
6. Self-check — verify against the checklist at the bottom of this file before returning output

---

File and Naming Rules

Rule	Convention
File names	camelCase: keyVault.bicep, containerApp.bicep, blobStorage.bicep
Role assignment files	<resource>RoleAssignment.bicep (e.g., keyVaultRoleAssignment.bicep)
All identifiers	camelCase — resources, variables, parameters, outputs
API versions	Pinned to a specific date (e.g., @2023-07-01); stable preferred; preview acceptable when no stable alternative exists (add a comment explaining why)
Target scope	No targetScope declaration — all modules use implicit resource group scope

---

Parameter Block Rules

Ordering

name (or primary identifier)
location
[required resource-specific params]
[optional resource-specific params]
tags object = {}

• name is first unless the primary identifier has a resource-specific name (e.g., appName, storeName, keyVaultName) — use that instead
• location string = resourceGroup().location — always included, placed immediately after the name/identifier group
• tags object = {} — always last, no exceptions

Decorator Order

Apply decorators in this order (omit those that don’t apply):

1. @description('...') — always present, every parameter
2. @metadata({ example: ... }) — for complex array/object parameters only, placed after @description()
3. @allowed([...])
4. @minLength() / @maxLength()
5. @minValue() / @maxValue()
6. @secure() — last decorator, applies only to string parameters (never object)

Examples

@description('Name of the storage account (3–24 lowercase alphanumeric characters only)')
@minLength(3)
@maxLength(24)
param name string

@description('Administrator password')
@secure()
param administratorPassword string

@description('SKU tier for the search service')
@allowed([
  'basic'
  'standard'
  'standard2'
])
param sku string = 'basic'

@description('Database names to create')
@metadata({ example: ['app', 'analytics'] })
param databaseNames array = ['app']

---

Code Pattern Quick Reference

Pattern	Form
Conditional resource	resource x '...' = if (condition) { ... }
Private endpoint flag	var usePrivateEndpoint = !empty(privateEndpointSubnetId)
Extract name from ID	last(split(resourceId, '/'))!
Null-safe field access	obj.?field ?? defaultValue
Parent-child resource	parent: parentResource — never string concatenation
Existing resource reference	resource x '...' existing = { name: name }
Loop output	[for (item, i) in items: resources[i].property]
Purge protection (never false)	enablePurgeProtection: param ? true : null
Network rules from arrays	[for subnetId in allowedSubnetIds: { id: subnetId, ignoreMissingVnetServiceEndpoint: false }]

Full pattern implementations with context: see references/conventions.md.

---

Output Block Rules

• Every output has @description() — no exceptions
• Order: id → name → resource-specific outputs (endpoint, fqdn, principalId, etc.)
• Child resources (e.g., keyVaultSecret, appConfigKeyValue): no independent .id — start with name
• Role assignment modules: NO outputs at all

@description('The resource ID of the Key Vault')
output id string = keyVault.id

@description('The name of the Key Vault')
output name string = keyVault.name

@description('The URI of the Key Vault')
output vaultUri string = keyVault.properties.vaultUri

---

Common Issues and Troubleshooting

Issue	Resolution
enablePurgeProtection: false rejected by ARM	Use param ? true : null — ARM rejects false after the feature is enabled; omit the property to leave it unchanged
Conditional resource compile error	Both the conditional resource and any parent: child resources must share the same if (condition) guard
last(split(...)) type error	Append ! non-null assertion: last(split(resourceId, '/'))!
Role assignment fails with duplicate name	The guid() call must include roleName as a third argument — omitting it causes collisions when assigning multiple roles to the same principal
Private DNS zone group depends-on error	DNS zone group must use parent: privateEndpoint (not name: concat) and be guarded by the same if (usePrivateEndpoint) condition
Preview API version with no stable alternative	Add an inline comment: // No stable API version available as of <date>

---

Self-Check Checklist

Before returning any module, verify:

• @description() on every parameter and every output
• name / primary identifier is first parameter; tags is last
• Decorator order: @description → @metadata → @allowed → @minLength/@maxLength → @minValue/@maxValue → @secure
• Security defaults applied per references/security-baselines.md for this resource type
• SKU/tier defaults are cost-appropriate per references/cost-guidelines.md; upgrade path documented in parameter description
• API version is pinned to a specific date; stable preferred; preview has explanatory comment
• No targetScope declaration
• First output is id, second is name — unless child resource (start with name) or role assignment (no outputs)
• enablePurgeProtection uses param ? true : null pattern — never false
• Conditional resources use = if (condition) pattern
• Private endpoint uses var usePrivateEndpoint = !empty(...) flag
• Parent-child resources use parent: — never name string concatenation
• @secure() only on string parameters, never object
• Role assignment modules: principalType: 'ServicePrincipal' hardcoded; no outputs
• App Config key-values: key format App:Component:Setting (PascalCase); secrets via KV reference