Merge pull request #185 from michaeltlombardi/maint/main/document-dependsOn-update

Document `dependsOn` update

Author: SteveL-MSFT

docs/reference/cli/dsc.md

@@ -73,13 +73,10 @@ To set the output format for a command or subcommand, specify this option before
 `dsc --format pretty-json resource list`.
 
 ```yaml
-Type:          String
-Mandatory:     false
-Default Value: yaml
-Valid Values:
-  - json
-  - pretty-json
-  - yaml
+Type:         String
+Mandatory:    false
+DefaultValue: yaml
+ValidValues:  [json, pretty-json, yaml]
 ```
 
 ### -h, --help

docs/reference/cli/schema/command.md

@@ -73,18 +73,19 @@ schema the application returns:
   `dsc config test` command.
 
 ```yaml
-Type:      String
-Mandatory: true
-Valid Values:
-  - dsc-resource
-  - resource-manifest
-  - get-result
-  - set-result
-  - test-result
-  - configuration
-  - configuration-get-result
-  - configuration-set-result
-  - configuration-test-result
+Type:        String
+Mandatory:   true
+ValidValues: [
+               dsc-resource,
+               resource-manifest,
+               get-result,
+               set-result,
+               test-result,
+               configuration,
+               configuration-get-result,
+               configuration-set-result,
+               configuration-test-result
+             ]
 ```
 
 ### -h, --help

docs/reference/schemas/config/document.md

@@ -14,9 +14,9 @@ The YAML or JSON file that defines a DSC Configuration.
 ## Metadata
 
 ```yaml
-Schema Dialect : https://json-schema.org/draft/2020-12/schema
-Schema ID      : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
-Type           : object
+SchemaDialect: https://json-schema.org/draft/2020-12/schema
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
+Type:          object
 ```
 
 ## Description
@@ -55,11 +55,12 @@ adheres to. DSC uses this property when validating the configuration document be
 configuration operations.
 
 ```yaml
-Type:     string
-Required: true
-Format:   URI
-Valid Values:
-  - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
+Type:        string
+Required:    true
+Format:      URI
+ValidValues: [
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
+             ]
 ```
 
 ### metadata
@@ -90,9 +91,9 @@ For more information about defining parameters in a configuration, see
 [DSC Configuration parameters][03] -->
 
 ```yaml
-Type:                  object
-Required:              false
-Valid Property Schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json
+Type:                object
+Required:            false
+ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json
 ```
 
 ### variables
@@ -125,10 +126,10 @@ For more information about defining a valid resource instance in a configuration
 [DSC Configuration resources][06] and [DSC Configuration resource groups][07]. -->
 
 ```yaml
-Type:               array
-Required:           true
-Minimum Item Count: 1
-Valid Item Schema:  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json
+Type:             array
+Required:         true
+MinimumItemCount: 1
+ValidItemSchema:  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json
 ```
 
 <!-- [01]: ../../../configurations/overview.md -->

docs/reference/schemas/config/parameter.md

@@ -14,9 +14,9 @@ Defines runtime options for a configuration.
 ## Metadata
 
 ```yaml
-Schema Dialect : https://json-schema.org/draft/2020-12/schema
-Schema ID      : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json
-Type           : object
+SchemaDialect: https://json-schema.org/draft/2020-12/schema
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json
+Type:          object
 ```
 
 ## Description
@@ -75,16 +75,9 @@ For more information about data types, see
 [DSC configuration parameter data type schema reference][02].
 
 ```yaml
-Type:     string
-Required: true
-Valid Values:
-  - string
-  - securestring
-  - int
-  - bool
-  - object
-  - secureobject
-  - array
+Type:        string
+Required:    true
+ValidValues: [string, securestring, int, bool, object, secureobject, array]
 ```
 
 ### defaultValue
@@ -95,13 +88,8 @@ runtime and no default value is defined, DSC raises an error. The value must be
 parameter's `type`.
 
 ```yaml
-Required: false
-Valid JSON Types:
-  - string
-  - integer
-  - object
-  - array
-  - boolean
+Required:       false
+ValidJSONTypes: [string, integer, object, array, boolean]
 ```
 
 ### allowedValues
@@ -114,14 +102,9 @@ This property is always an array. If this property is defined, it must include a
 the list of values.
 
 ```yaml
-Type:     array
-Required: false
-Valid Item JSON Types:
-  - string
-  - integer
-  - object
-  - array
-  - boolean
+Type:               array
+Required:           false
+ValidItemJSONTypes: [string, integer, object, array, boolean]
 ```
 
 ### minLength
@@ -137,9 +120,9 @@ If this property is defined with the `maxLength` property, this property must be
 `maxLength`. If it isn't, DSC raises an error.
 
 ```yaml
-Type:          int
-Required:      false
-Minimum Value: 0
+Type:         int
+Required:     false
+MinimumValue: 0
 ```
 
 ### maxLength
@@ -155,9 +138,9 @@ If this property is defined with the `minLength` property, this property must be
 `minLength`. If it isn't, DSC raises an error.
 
 ```yaml
-Type:          int
-Required:      false
-Minimum Value: 0
+Type:         int
+Required:     false
+MinimumValue: 0
 ```
 
 ### minValue

docs/reference/schemas/config/resource.md

@@ -14,9 +14,9 @@ Defines a DSC Resource instance in a configuration document.
 ## Metadata
 
 ```yaml
-Schema Dialect : https://json-schema.org/draft/2020-12/schema
-Schema ID      : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json
-Type           : object
+SchemaDialect: https://json-schema.org/draft/2020-12/schema
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json
+Type:          object
 ```
 
 ## Description
@@ -45,9 +45,13 @@ The `name` property of a resource instance defines the short, human-readable nam
 Resource instance. This property must be unique within a DSC Configuration document. If any
 resource instances share the same name, DSC raises an error.
 
+The instance name must be a non-empty string containing only letters, numbers, and spaces.
+
 ```yaml
-Type:     string
-Required: true
+Type:          string
+Required:      true
+MinimumLength: 1
+Pattern:       ^[a-zA-Z0-9 ]+$
 ```
 
 ### type
@@ -80,30 +84,62 @@ Required: true
 To declare that a resource instance is dependent on another instance in the configuration, define
 the `dependsOn` property.
 
-This property must be an array of dependency declarations. Each dependency must use this
-syntax:
+This property defines a list of DSC Resource instances that DSC must successfully process before
+processing this instance. Each value for this property must be the `resourceID()` lookup for
+another instance in the configuration. Multiple instances can depend on the same instance, but
+every dependency for an instance must be unique in that instance's `dependsOn` property.
+
+The `resourceID()` function uses this syntax:
 
 ```yaml
-"[<resource-type-name>]<instance-name>"
+"[resourceId('<resource-type-name>', '<instance-name>']"
 ```
 
-In the dependency syntax, `<resource-type-name>` is the `type` property of the dependent resource
-and `<instance-name>` is the dependency's `name` property.
+The `<resource-type-name>` value is the `type` property of the dependent resource and
+`<instance-name>` is the dependency's `name` property. When adding a dependency in a YAML-format
+configuration document, always wrap the `resourceID()` lookup in double quotes (`"`).
+
+For example, this instance depends on an instance of the `Microsoft.Windows/Registry`
+resource named `Tailspin Key`:
+
+```yaml
+- name: Tailspin Key
+  type: Microsoft.Windows/Registry
+  properties:
+    keyPath: HKCU\tailspin
+    _ensure: Present
+- name: Update Tailspin Automatically
+  type: Microsoft.Windows/Registry
+  properties:
+    keyPath:   HKCU\tailspin\updates
+    valueName: automatic
+    valueData:
+      String: enable
+  dependsOn:
+    - "[resourceId('Microsoft.Windows/Registry', 'Tailspin Key')]"
+```
 
-Multiple instances can depend on the same instance, but every dependency for an instance must be
-unique in that instance's `dependsOn` property.
+> [!NOTE]
+> When defining dependencies for [nested resource instances][02], instances can only reference
+> dependencies in the same resource provider or group instance. They can't use the `resourceId()`
+> function to lookup instances at the top-level of the configuration document or inside another
+> provider or group instance.
+>
+> If a top-level instance depends on a nested instance, use the `resourceId()` function to lookup
+> the instance of the provider or group containing the dependency instance instead.
 
 <!-- For more information, see [Configuration resource dependencies][04]. -->
 
 ```yaml
-Type:                 array
-Required:             false
-Items Must be Unique: true
-Valid Items Type:     string
-Valid Items Pattern:  ^\[\w+(\.\w+){0,2}\/\w+\].+$
+Type:              array
+Required:          false
+ItemsMustBeUnique: true
+ItemsType:         string
+ItemsPattern:      ^\[resourceId\(\s*'\w+(\.\w+){0,2}\/\w+'\s*,\s*'[a-zA-Z0-9 ]+'\s*\)\]$
 ```
 
 [01]: ../definitions/resourceType.md
+[02]: /powershell/dsc/glossary#nested-resource-instance
 <!-- [02]: ../../../resources/concepts/assertion-resources.md -->
 <!-- [03]: ../../../resources/concepts/schemas.md -->
 <!-- [04]: ../../../configurations/concepts/dependencies.md -->

docs/reference/schemas/definitions/message.md

@@ -14,9 +14,9 @@ A message emitted by a DSC Resource with associated metadata.
 ## Metadata
 
 ```yaml
-Schema Dialect : https://json-schema.org/draft/2020-12/schema
-Schema ID      : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json
-Type           : object
+SchemaDialect: https://json-schema.org/draft/2020-12/schema
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json
+Type:          object
 ```
 
 ## Description
@@ -67,12 +67,9 @@ Required: true
 Indicates the severity of the message.
 
 ```yaml
-Type:     string
-Required: true
-Valid Values:
-  - Error
-  - Warning
-  - Information
+Type:         string
+Required:     true
+Valid Values: [Error, Warning, Information]
 ```
 
 [01]: resourceType.md

docs/reference/schemas/definitions/parameters/dataTypes.md

@@ -14,17 +14,10 @@ Defines valid data types for a DSC configuration parameter
 ## Metadata
 
 ```yaml
-Schema Dialect : https://json-schema.org/draft/2020-12/schema
-Schema ID      : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json
-Type           : string
-Valid Values:
-  - array
-  - bool
-  - int
-  - object
-  - string
-  - secureobject
-  - securestring
+SchemaDialect: https://json-schema.org/draft/2020-12/schema
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json
+Type:          string
+ValidValues:   [array, bool, int, object, string, secureobject, securestring]
 ```
 
 ## Description

docs/reference/schemas/definitions/resourceType.md

@@ -14,10 +14,10 @@ Identifies a DSC Resource.
 ## Metadata
 
 ```yaml
-Schema Dialect : https://json-schema.org/draft/2020-12/schema
-Schema ID      : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json
-Type           : string
-Pattern        : ^\w+(\.\w+){0,2}\/\w+$
+SchemaDialect: https://json-schema.org/draft/2020-12/schema
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json
+Type:          string
+Pattern:       ^\w+(\.\w+){0,2}\/\w+$
 ```
 
 ## Description

docs/reference/schemas/outputs/config/get.md

@@ -14,9 +14,9 @@ The result output from the `dsc config get` command.
 ## Metadata
 
 ```yaml
-Schema Dialect : https://json-schema.org/draft/2020-12/schema
-Schema ID      : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/get.json
-Type           : object
+SchemaDialect: https://json-schema.org/draft/2020-12/schema
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/get.json
+Type:          object
 ```
 
 ## Description
@@ -41,9 +41,9 @@ configuration document. Every entry in the list includes the resource's type nam
 and the result data for an instance.
 
 ```yaml
-Type:     array
-Required: true
-Items Type: object
+Type:      array
+Required:  true
+ItemsType: object
 ```
 
 #### type