Consolidate the information on union type

Author: mumian

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

@@ -319,12 +319,14 @@ 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'`.
+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 constraint in Bicep, so only literals are permitted as members. Unions may 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:
@@ -335,15 +337,42 @@ 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 is validated using the _FooConfig_ type. Similarly, if the parameter is of type _bar_, it is validated using the _BarConfig_ type. This pattern applies to other types as well.
+
 There are some limitations with union type.
 
-* Union types must be reduceable to a single ARM type.  The following definition is in valid:
+* Union types must be reduceable to a single ARM type.  The following definition is invalid:
 
   ```bicep
   type foo = 'a' | 1
   ```
 
-The union type syntax can also be used in [user-defined data types](./user-defined-data-types.md).
+The union type syntax can be used in [user-defined data types](./user-defined-data-types.md).
 
 ## Secure strings and objects
 

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

@@ -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 may 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. |

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
+## The 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