Merge branch '0501-metadata-object' of https://github.com/mumian/azure-docs-pr into 0523-metadata-object

Author: mumian

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

@@ -3,7 +3,7 @@ title: Bicep file structure and syntax
 description: Describes the structure and properties of a Bicep file using declarative syntax.
 ms.topic: conceptual
 ms.custom: devx-track-bicep
-ms.date: 07/06/2022
+ms.date: 05/01/2023
 ---
 
 # Understand the structure and syntax of Bicep files
@@ -19,6 +19,8 @@ Bicep is a declarative language, which means the elements can appear in any orde
 A Bicep file has the following elements.
 
 ```bicep
+metadata <metadata-name> = {}
+
 targetScope = '<scope>'
 
 @<decorator>(<argument>)
@@ -43,6 +45,11 @@ output <output-name> <output-data-type> = <output-value>
 The following example shows an implementation of these elements.
 
 ```bicep
+metadata bicepDescription = {
+  description: 'Creates a storage account and a web app'
+}
+
+@description('The prefix to use for the storage account name.')
 @minLength(3)
 @maxLength(11)
 param storagePrefix string
@@ -52,7 +59,7 @@ param location string = resourceGroup().location
 
 var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'
 
-resource stg 'Microsoft.Storage/storageAccounts@2019-04-01' = {
+resource stg 'Microsoft.Storage/storageAccounts@2022-09-01' = {
   name: uniqueStorageName
   location: location
   sku: {
@@ -71,10 +78,14 @@ module webModule './webApp.bicep' = {
     location: location
   }
 }
-
-output storageEndpoint object = stg.properties.primaryEndpoints
 ```
 
+## Metadata
+
+Metadata in Bicep is an untyped object that can be included in Bicep files. It allows you to provide supplementary information about your Bicep files, including details like its name, description, author, creation date, and more.
+
+When assigning identifiers for metadata, [`param`](#parameters), [`var`](#variables), [`resource`](#resources), [`module`](#modules), and [`output`](#outputs), it's important to note that they share the same namespace as [decorators](./parameters.md#decorators) and [Bicep functions](./bicep-functions.md). Therefore, using the same identifier for metadata and a decorator (or a Bicep function) can cause confusion. It's advisable to choose a unique identifier that doesn't conflict with a decorator or a function. For instance, instead of using **description** as the metadata identifier, you could use **bicepDescription** to differentiate it from the **@description** decorator in the preceding example.
+
 ## Target scope
 
 By default, the target scope is set to `resourceGroup`. If you're deploying at the resource group level, you don't need to set the target scope in your Bicep file.
@@ -143,7 +154,7 @@ For more information, see [Variables in Bicep](./variables.md).
 
 ## Resources
 
-Use the `resource` keyword to define a resource to deploy. Your resource declaration includes a symbolic name for the resource. You'll use this symbolic name in other parts of the Bicep file to get a value from the resource.
+Use the `resource` keyword to define a resource to deploy. Your resource declaration includes a symbolic name for the resource. You use this symbolic name in other parts of the Bicep file to get a value from the resource.
 
 The resource declaration includes the resource type and API version. Within the body of the resource declaration, include properties that are specific to the resource type.
 

articles/azure-resource-manager/templates/syntax.md

@@ -3,7 +3,7 @@ title: Template structure and syntax
 description: Describes the structure and properties of Azure Resource Manager templates (ARM templates) using declarative JSON syntax.
 ms.topic: conceptual
 ms.custom: ignite-2022, devx-track-arm-template
-ms.date: 09/28/2022
+ms.date: 05/01/2023
 ---
 
 # Understand the structure and syntax of ARM templates