Merge pull request #280943 from mumian/0716-specific-integer-type

Bicep -  integer/string literal type and union type

Author: v-dirichards

articles/azure-resource-manager/bicep/data-types.md

@@ -3,7 +3,7 @@ title: Data types in Bicep
 description: Describes the data types that are available in Bicep
 ms.topic: reference
 ms.custom: devx-track-bicep
-ms.date: 11/03/2023
+ms.date: 07/16/2024
 ---
 
 # Data types in Bicep
@@ -39,7 +39,7 @@ var mixedArray = ['abc', 'def'
     'ghi']
 ```
 
-In an array, each item is represented by the [any type](bicep-functions-any.md). You can have an array where each item is the same data type, or an array that holds different data types.
+Each array element can be of any type. You can have an array where each item is the same data type, or an array that holds different data types.
 
 The following example shows an array of integers and an array different types.
 
@@ -58,7 +58,7 @@ var mixedArray = [
 ]
 ```
 
-Arrays in Bicep are zero-based. In the following example, the expression `exampleArray[0]` evaluates to 1 and `exampleArray[2]` evaluates to 3. The index of the indexer may itself be another expression. The expression `exampleArray[index]` evaluates to 2. Integer indexers are only allowed on expression of array types.
+Arrays in Bicep are zero-based. In the following example, the expression `exampleArray[0]` evaluates to 1 and `exampleArray[2]` evaluates to 3. The index of the indexer can be another expression. The expression `exampleArray[index]` evaluates to 2. Integer indexers are only allowed on expression of array types.
 
 ```bicep
 var index = 1
@@ -102,7 +102,30 @@ When specifying integer values, don't use quotation marks.
 param exampleInt int = 1
 ```
 
-In Bicep, integers are 64-bit integers. When passed as inline parameters, the range of values may be limited by the SDK or command-line tool you use for deployment. For example, when using PowerShell to deploy a Bicep, integer types can range from -2147483648 to 2147483647. To avoid this limitation, specify large integer values in a [parameter file](parameter-files.md). Resource types apply their own limits for integer properties.
+Bicep integers are 64-bit integers. When passed as inline parameters, the range of values can be limited by the SDK or command-line tool you use for deployment. For example, when using PowerShell to deploy a Bicep, integer types can range from -2147483648 to 2147483647. To avoid this limitation, specify large integer values in a [parameter file](parameter-files.md). Resource types apply their own limits for integer properties.
+
+Bicep supports integer literal type that refers to a specific value that is an exact integer. In the following example, _1_ is an integer literal type, _foo_ can only be assigned the value _1_ and no other value.
+
+```bicep
+output foo 1 = 1
+```
+
+An integer literal type can either be declared inline, as shown in the preceding example,  or in a [`type` statement](./user-defined-data-types.md).  
+
+```bicep
+type oneType = 1
+
+output foo oneType = 1
+output bar oneType = 2
+```
+
+In the preceding example, assigning _2_ to _bar_ results in a [BCP033](./bicep-error-bcp033.md) error - _Expected a value of type "1" but the provided value is of type "2"_.
+
+The following example shows using integer literal type with [union type](#union-types):
+
+```bicep
+output bar 1 | 2 | 3 = 3
+```
 
 Floating point, decimal or binary formats aren't currently supported.
 
@@ -132,7 +155,7 @@ var test = {
 }
 ```
 
-In the preceding example, quotes are used when the object property keys contain special characters.  For example space, '-', or '.'. The following example shows how to use interpolation in object property keys.
+In the preceding example, quotes are used when the object property keys contain special characters. For example space, '-', or '.'. The following example shows how to use interpolation in object property keys.
 
 ```bicep
 var stringVar = 'example value'
@@ -176,7 +199,7 @@ output accessorResult string = environmentSettings['dev'].name
 
 [!INCLUDE [JSON object ordering](../../../includes/resource-manager-object-ordering-bicep.md)]
 
-You will get the following error when accessing an nonexisting property of an object:
+You get the following error when accessing a nonexisting property of an object:
 
 ```error
 The language expression property 'foo' doesn't exist
@@ -196,7 +219,7 @@ output bar bool = contains(objectToTest, 'four') && objectToTest.four == 4
 
 ## Strings
 
-In Bicep, strings are marked with singled quotes, and must be declared on a single line. All Unicode characters with code points between *0* and *10FFFF* are allowed.
+In Bicep, strings are marked with singled quotes, and must be declared on a single line. All Unicode characters with code points between _0_ and _10FFFF_ are allowed.
 
 ```bicep
 param exampleString string = 'test value'
@@ -211,21 +234,47 @@ The following table lists the set of reserved characters that must be escaped by
 | `\n` | line feed (LF) ||
 | `\r` | carriage return (CR) ||
 | `\t` | tab character ||
-| `\u{x}` | Unicode code point `x` | **x** represents a hexadecimal code point value between *0* and *10FFFF* (both inclusive). Leading zeros are allowed. Code points above *FFFF* are emitted as a surrogate pair.
+| `\u{x}` | Unicode code point `x` | **x** represents a hexadecimal code point value between _0_ and _10FFFF_ (both inclusive). Leading zeros are allowed. Code points above _FFFF_ are emitted as a surrogate pair. |
 | `\$` | `$` | Only escape when followed by `{`. |
 
 ```bicep
 // evaluates to "what's up?"
 var myVar = 'what\'s up?'
 ```
 
+Bicep supports string literal type that refers to a specific string value. In the following example, _red_ is a string literal type, _redColor_ can only be assigned the value _red_ and no other value.
+
+```bicep
+output redColor 'red' = 'red'
+```
+
+A string literal type can either be declared inline, as shown in the preceding example, or in a [`type` statement](./user-defined-data-types.md).  
+
+```bicep
+type redColor = 'red'
+
+output colorRed redColor = 'red'
+output colorBlue redColor = 'blue'
+```
+
+In the preceding example, assigning _blue_ to _colorBlue_ results in a [BCP033](./bicep-error-bcp033.md) error - _Expected a value of type "'red'" but the provided value is of type "'blue'"_.
+
+The following example shows using string literal type with [union type](#union-types):
+
+```bicep
+type direction = 'north' | 'south' | 'east' | 'west'
+
+output west direction = 'west'
+output northWest direction = 'northwest'
+```
+
 All strings in Bicep support interpolation. To inject an expression, surround it by `${` and `}`. Expressions that are referenced can't span multiple lines.
 
 ```bicep
 var storageName = 'storage${uniqueString(resourceGroup().id)}'
 ```
 
-## Multi-line strings
+### Multi-line strings
 
 In Bicep, multi-line strings are defined between three single quote characters (`'''`) followed optionally by a newline (the opening sequence), and three single quote characters (`'''` - the closing sequence). Characters that are entered between the opening and closing sequence are read verbatim, and no escaping is necessary or possible.
 
@@ -268,6 +317,66 @@ var myVar6 = '''interpolation
 is ${blocked}'''
 ```
 
+## Union types
+
+In Bicep, a union type allows the creation of a combined type consisting of a set of sub-types. An assignment is valid if any of the individual sub-type assignments are permitted. The `|` character separates individual sub-types using an _or_ condition. For example, the syntax _'a' | 'b'_ means that a valid assignment could be either _'a'_ or _'b'_. Union types are translated into the [allowed-value](../templates/definitions.md#allowed-values) constraint in Bicep, so only literals are permitted as members. Unions can include any number of literal-typed expressions.
+
+```bicep
+type color = 'Red' | 'Blue' | 'White'
+type trueOrFalse = 'true' | 'false'
+type permittedIntegers = 1 | 2 | 3
+type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
+type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]
+```
+
+Any type expression can be used as a sub-type in a union type declaration (between `|` characters). For example, the following examples are all valid:
+
+```bicep
+type foo = 1 | 2
+type bar = foo | 3
+type baz = bar | (4 | 5) | 6
+```
+
+### Custom-tagged union data type
+
+Bicep supports custom tagged union data type, which is used to represent a value that can be one of several different types. To declare a custom tagged union data type, you can use a `@discriminator()` decorator. [Bicep CLI version 0.21.X or higher](./install.md) is required to use this decorator. The syntax is:
+
+```bicep
+@discriminator('<property-name>')
+```
+
+The discriminator decorator takes a single parameter, which represents a shared property name among all union members. This property name must be a required string literal on all members and is case-sensitive. The values of the discriminated property on the union members must be unique in a case-insensitive manner.
+
+```bicep
+type FooConfig = {
+  type: 'foo'
+  value: int
+}
+
+type BarConfig = {
+  type: 'bar'
+  value: bool
+}
+
+@discriminator('type')
+param ServiceConfig  FooConfig | BarConfig | { type: 'baz', *: string } = { type: 'bar', value: true }
+```
+
+The parameter value is validated based on the discriminated property value. For instance, in the preceding example, if the _serviceConfig_ parameter is of type _foo_, it's validated using the _FooConfig_ type. Similarly, if the parameter is of type _bar_, it's validated using the _BarConfig_ type. This pattern applies to other types as well.
+
+There are some limitations with union type.
+
+* Union types must be reducible to a single Azure Resource Manager (ARM) type.  The following definition is invalid:
+
+  ```bicep
+  type foo = 'a' | 1
+  ```
+
+* Only literals are permitted as members.
+* All literals must be of the same primitive data type (e.g., all strings or all integers).
+
+The union type syntax can be used in [user-defined data types](./user-defined-data-types.md).
+
 ## Secure strings and objects
 
 Secure string uses the same format as string, and secure object uses the same format as object. With Bicep, you add the `@secure()` [decorator](./parameters.md#decorators) to a string or object.

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

@@ -14,7 +14,7 @@ Resource Manager resolves parameter values before starting the deployment operat
 
 Each parameter must be set to one of the [data types](data-types.md).
 
-You're limited to 256 parameters in a Bicep file. For more information, see [Template limits](../templates/best-practices.md#template-limits).
+Bicep allows a maximum of 256 parameters. For more information, see [Template limits](../templates/best-practices.md#template-limits).
 
 For parameter best practices, see [Parameters](./best-practices.md#parameters).
 
@@ -59,7 +59,7 @@ param storageAccountConfig {
 }
 ```
 
-For more information, see [User-defined data types](./user-defined-data-types.md#user-defined-data-type-syntax).
+For more information, see [User-defined data types](./user-defined-data-types.md#syntax).
 
 ## Default value
 
@@ -105,7 +105,7 @@ The following table describes the available decorators and how to use them.
 
 | Decorator | Apply to | Argument | Description |
 | --------- | ---- | ----------- | ------- |
-| [allowed](#allowed-values) | all | array | Allowed values for the parameter. Use this decorator to make sure the user provides correct values. |
+| [allowed](#allowed-values) | all | array | Use this decorator to make sure the user provides correct values. This decorator is only permitted on `param` statements. To declare that a property must be one of a set of predefined values in a [`type`](./user-defined-data-types.md) or [`output`](./outputs.md) statement, use [union type syntax](./data-types.md#union-types). Union type syntax can also be used in `param` statements.|
 | [description](#description) | all | string | Text that explains how to use the parameter. The description is displayed to users through the portal. |
 | [maxLength](#length-constraints) | array, string | int | The maximum length for string and array parameters. The value is inclusive. |
 | [maxValue](#integer-constraints) | int | int | The maximum value for the integer parameter. This value is inclusive. |
@@ -203,7 +203,7 @@ When you hover your cursor over **storageAccountName** in VS Code, you see the f
 
 :::image type="content" source="./media/parameters/vscode-bicep-extension-description-decorator-markdown.png" alt-text="Use Markdown-formatted text in VSCode":::
 
-Make sure the text follows proper Markdown formatting; otherwise, it may not display correctly when rendered
+Make sure the text follows proper Markdown formatting; otherwise, it may not display correctly when rendered.
 
 ### Metadata
 
@@ -220,7 +220,7 @@ You might use this decorator to track information about the parameter that doesn
 param settings object
 ```
 
-When you provide a `@metadata()` decorator with a property that conflicts with another decorator, that decorator always takes precedence over anything in the `@metadata()` decorator. So, the conflicting property within the @metadata() value is redundant and will be replaced. For more information, see [No conflicting metadata](./linter-rule-no-conflicting-metadata.md).
+When you provide a `@metadata()` decorator with a property that conflicts with another decorator, that decorator always takes precedence over anything in the `@metadata()` decorator. So, the conflicting property within the `@metadata()` value is redundant and will be replaced. For more information, see [No conflicting metadata](./linter-rule-no-conflicting-metadata.md).
 
 ## Use parameter
 

articles/azure-resource-manager/bicep/user-defined-data-types.md

@@ -12,16 +12,15 @@ Learn how to use user-defined data types in Bicep. For system-defined data types
 
 [Bicep CLI version 0.12.X or higher](./install.md) is required to use this feature.
 
-## User-defined data type syntax
+## Syntax
 
 You can use the `type` statement to define user-defined data types. In addition, you can also use type expressions in some places to define custom types.
 
 ```bicep
 type <user-defined-data-type-name> = <type-expression>
 ```
 
-> [!NOTE]
-> The [`@allowed` decorator](./parameters.md#decorators) is only permitted on [`param` statements](./parameters.md). To declare that a property must be one of a set of predefined values in a `type` or [`output`](./outputs.md) statement, use union type syntax. Union type syntax may also be used in [`param` statements](./parameters.md).
+The [`@allowed`](./parameters.md#decorators) decorator is only permitted on [`param` statements](./parameters.md). To declare that a property with a set of predefined values in a `type`, use [union type syntax](./data-types.md#union-types). 
 
 The valid type expressions include:
 
@@ -95,13 +94,16 @@ The valid type expressions include:
     }
     ```
 
-    The following sample shows how to use the union type syntax to list a set of predefined values:
+    The following sample shows how to use the [union type syntax](./data-types.md#union-types) to list a set of predefined values:
 
     ```bicep
+    type directions = 'east' | 'south' | 'west' | 'north'
+
     type obj = {
       level: 'bronze' | 'silver' | 'gold'
     }
     ```
+
     **Recursion**
 
     Object types may use direct or indirect recursion so long as at least leg of the path to the recursion point is optional. For example, the `myObjectType` definition in the following example is valid because the directly recursive `recursiveProp` property is optional:
@@ -225,17 +227,9 @@ resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
 }
 ```
 
-## Declare tagged union type
-
-To declare a custom tagged union data type within a Bicep file, you can place a discriminator decorator above a user-defined type declaration. [Bicep CLI version 0.21.X or higher](./install.md) is required to use this decorator. The syntax is:
-
-```bicep
-@discriminator('<propertyName>')
-```
-
-The discriminator decorator takes a single parameter, which represents a shared property name among all union members. This property name must be a required string literal on all members and is case-sensitive. The values of the discriminated property on the union members must be unique in a case-insensitive manner.
+## Tagged union data type
 
-The following example shows how to declare a tagged union type:
+To declare a custom tagged union data type within a Bicep file, you can place a discriminator decorator above a user-defined type declaration. [Bicep CLI version 0.21.X or higher](./install.md) is required to use this decorator. The following example shows how to declare a tagged union data type:
 
 ```bicep
 type FooConfig = {
@@ -256,7 +250,7 @@ param serviceConfig ServiceConfig = { type: 'bar', value: true }
 output config object = serviceConfig
 ```
 
-The parameter value is validated based on the discriminated property value.  In the preceding example, if the *serviceConfig* parameter value is of type *foo*, it undergoes validation using the *FooConfig*type. Likewise, if the parameter value is of type *bar*, validation is performed using the *BarConfig* type, and this pattern continues for other types as well.
+For more information, see [Custom tagged union data type](./data-types.md#custom-tagged-union-data-type).
 
 ## Import types between Bicep files