docs: Update output schemas, schema URIs, and dsc function CLI reference (#1709)

Author: Gijsreyn

docs/reference/cli/function/list.md

@@ -1,6 +1,6 @@
 ---
 description: Command line reference for the 'dsc function list' command
-ms.date:     07/20/2025
+ms.date:     09/01/2026
 ms.topic:    reference
 title:       dsc function list
 ---
@@ -49,16 +49,16 @@ dsc function list
 ```
 
 ```output
-Category               Function              MinArgs  MaxArgs  ReturnTypes  Description            
----------------------------------------------------------------------------------------------------
-Array                  array                 1        1        a-----       Convert the value to a…
-Array                  createArray           0        maxInt   a-----       Creates an array from …
-Array                  range                 2        2        a-----       Creates an array of in…
-Array                  tryIndexFromEnd       2        2        ab-nso       Retrieves a value from 
-Array, Lambda          filter                2        2        a-----       Filters an array with …
-Array, Lambda          map                   2        2        a-----       Transforms an array by 
-Array, Object          intersection          2        maxInt   a----o       Returns a single array 
-Array, Object          tryGet                2        2        ab-nso       Attempts to retrieve a 
+Category       Function         Syntax                               Description
+-----------------------------------------------------------------------------------------
+Array          array            array( <string | number | object …  Convert the value to…
+Array          createArray      createArray( [value], ... )          Creates an array fro…
+Array          range            range( <startIndex>, <count> )       Creates an array of …
+Array          tryIndexFromEnd  tryIndexFromEnd( <array>, <index> )  Retrieves a value fr…
+Array, Lambda  filter           filter( <array>, <lambda> )          Filters an array wit…
+Array, Lambda  map              map( <array>, <lambda> )             Transforms an array …
+Array, Object  intersection     intersection( <array | object>, <…   Returns a single arr…
+Array, Object  tryGet           tryGet( <array | object>, <key | …   Attempts to retrieve…
 // truncated
 ```
 
@@ -73,9 +73,9 @@ dsc function list resource*
 ```
 
 ```output
-Category Name       MinArgs MaxArgs ArgTypes Description
--------- ----       ------- ------- -------- -----------
-Resource resourceId 2       2       ---s-    Constructs a resource ID from the given type and name
+Category  Function    Syntax                        Description
+----------------------------------------------------------------------------------------
+Resource  resourceId  resourceId( <type>, <name> )  Constructs a resource ID from the gi…
 ```
 
 ### Example 3 - Get details for a specific function
@@ -90,23 +90,63 @@ dsc function list concat --output-format yaml
 
 ```yaml
 category:
-- Array
-- String
+- array
+- string
 name: concat
 description: Concatenates two or more strings or arrays
+syntax: concat( <string | array>, <string | array>, ... )
+constraints: All arguments must be of the same type (all strings or all arrays)
 minArgs: 2
 maxArgs: 18446744073709551615
 acceptedArgOrderedTypes:
-- - String
-  - Array
-- - String
-  - Array
+- - string
+  - array
+- - string
+  - array
 remainingArgAcceptedTypes:
-- String
-- Array
+- string
+- array
 returnTypes:
-- String
-- Array
+- string
+- array
+```
+
+### Example 4 - Filter functions by category
+
+<a id="example-4"></a>
+
+This command uses the `--category` option to list only the functions in the `lambda` category.
+
+```sh
+dsc function list --category lambda
+```
+
+```output
+Category       Function         Syntax                                     Description
+----------------------------------------------------------------------------------------
+Array, Lambda  filter           filter( <array>, <lambda> )                Filters an ar…
+Array, Lambda  map              map( <array>, <lambda> )                   Transforms an…
+Lambda         lambda           lambda( <param1>, [param2], ..., <body> )  Creates a lam…
+Lambda         lambdaVariables  lambdaVariables( <name> )                  Retrieves the…
+```
+
+### Example 5 - Filter functions by description
+
+<a id="example-5"></a>
+
+This command uses the `--description` option to list only the functions whose description
+matches a wildcard pattern.
+
+```sh
+dsc function list --description *CIDR*
+```
+
+```output
+Category  Function    Syntax                                          Description
+-----------------------------------------------------------------------------------------
+CIDR      cidrHost    cidrHost( <cidr>, <hostIndex> )                 Calculates the usab…
+CIDR      cidrSubnet  cidrSubnet( <cidr>, <newCidr>, <subnetIndex> )  Splits the specifie…
+CIDR      parseCidr   parseCidr( <cidr> )                             Parses an IP addres…
 ```
 
 ## Parameters
@@ -125,6 +165,39 @@ Position:  0
 
 ## Options
 
+### -c, --category
+
+<a id="-c"></a>
+<a id="--category"></a>
+
+The `--category` option filters the results by function category. You can specify the option more
+than once to filter for multiple categories. When you specify more than one category, DSC returns
+only the functions that belong to every specified category.
+
+```yaml
+Type:         string
+Mandatory:    false
+ValidValues:  [array, cidr, comparison, date, deployment, lambda, logical,
+               numeric, object, resource, string, system]
+LongSyntax:   --category <CATEGORY>
+ShortSyntax:  -c <CATEGORY>
+```
+
+### -d, --description
+
+<a id="-d"></a>
+<a id="--description"></a>
+
+The `--description` option filters the results by function description. You can use wildcard
+patterns in the value. DSC returns only the functions whose description matches the pattern.
+
+```yaml
+Type:         string
+Mandatory:    false
+LongSyntax:   --description <PATTERN>
+ShortSyntax:  -d <PATTERN>
+```
+
 ### -o, --output-format
 
 <a id="-o"></a>
@@ -183,29 +256,18 @@ ShortSyntax : -h
 
 ## Output
 
-This command returns a formatted array containing an object for each function that includes the
-function's type, version, manifest settings, and other metadata. For more information, see
-[dsc function list result schema reference][03].
+This command returns an object for each function that includes the function's name, categories,
+syntax, argument metadata, and return types. For more information, see
+[dsc function list result schema reference][03]. For more information about the [data types][04]
+used in the argument and return type metadata, see the linked schema reference.
 
 If the output of the command isn't captured or redirected, it displays in the console by default as
 a summary table for the returned functions. The summary table includes the following columns,
 displayed in the listed order:
 
-- **Category** - The category the function belongs to.
+- **Category** - The categories the function belongs to.
 - **Function** - The name of the function.
-- **MinArgs** - The minimum number of arguments the function accepts.
-- **MaxArgs** - The maximum number of arguments the function accepts.
-- **ReturnTypes** - The [data types][04] the function emits as flags. The valid return types are
-  displayed in the following order, using a `-` instead of the appropriate letter if the function
-  doesn't return that data type:
-
-  - `a` indicates that the function returns an array value.
-  - `b` indicates that the function returns a boolean value.
-  - `l` indicates that the function returns a lambda value.
-  - `n` indicates that the function returns a number value.
-  - `s` indicates that the function returns a string value.
-  - `o` indicates that the function returns an object value.
-
+- **Syntax** - The syntax for calling the function, showing its expected arguments.
 - **Description** - A synopsis of what the function does.
 
 For more information about the formatting of the output data, see the

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

@@ -1,6 +1,6 @@
 ---
 description: JSON schema reference for the data returned by the 'dsc config get' command.
-ms.date:     07/03/2025
+ms.date:     09/01/2026
 ms.topic:    reference
 title:       dsc config get result schema reference
 ---
@@ -28,34 +28,24 @@ in the configuration document.
 
 The output always includes these properties:
 
-- [metadata](#metadata-1)
 - [results](#results)
 - [messages](#messages)
 - [hadErrors](#haderrors)
 
 ## Properties
 
-### metadata
+### executionInformation
 
-Defines metadata DSC returns for a configuration operation. The properties under the
-`Microsoft.DSC` property describe the context of the operation.
-
-```yaml
-Type:     object
-Required: true
-```
-
-#### Microsoft.DSC
-
-The metadata under this property describes the context of the overall operation:
+Describes the context of the overall operation. DSC adds this property to the output of every
+configuration operation. The value is an object with the following properties:
 
 - [version][01] defines the version of DSC that ran the command. This value is always the semantic
   version of the DSC command, like `3.0.0-preview.7`.
-- [operation][02] defines the operation that DSC applied to the configuration document: `Get`,
-  `Set`, `Test`, or `Export`.
+- [operation][02] defines the operation that DSC applied to the configuration document: `get`,
+  `set`, `test`, or `export`.
 - [executionType][03] defines whether DSC actually applied an operation to the configuration or was
-  run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export`
-  operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--what-if`
+  run in what-if mode. This property is always `actual` for `get`, `test`, and `export`
+  operations. For `set` operations, this value is `whatIf` when DSC is invoked with the `--what-if`
   argument.
 - [startDatetime][04] defines the start date and time for the DSC operation as a timestamp
   following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like
@@ -67,32 +57,87 @@ The metadata under this property describes the context of the overall operation:
   resource instance as a string following the format defined in [ISO8601 ABNF for `duration`][08].
   For example, `PT0.611216S` represents a duration of about `0.61` seconds.
 - [securityContext][09] defines the security context that DSC was run under. If the value for this
-  metadata property is `Elevated`, DSC was run as `root` (non-Windows) or an elevated session with
-  Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user
+  metadata property is `elevated`, DSC was run as `root` (non-Windows) or an elevated session with
+  Administrator privileges (on Windows). If the value is `restricted`, DSC was run as a normal user
   or account in a non-elevated session.
+- [restartRequired][10] defines the list of restarts that resource instances reported as required
+  during the operation. DSC only includes this property when at least one instance reported a
+  required restart.
+
+```yaml
+Type:     object
+Required: false
+```
+
+### metadata
+
+Defines metadata DSC returns for a configuration operation. The properties under the
+`Microsoft.DSC` property describe the context of the operation. DSC includes this property for
+backwards compatibility with tools and scripts that process DSC output. In DSC version 4.0.0, the
+output will no longer include this property. Prefer [executionInformation](#executioninformation)
+instead.
+
+```yaml
+Type:     object
+Required: false
+```
+
+#### Microsoft.DSC
+
+The metadata under this property describes the context of the overall operation. It includes the
+same properties as [executionInformation](#executioninformation). For more information, see
+[Microsoft.DSC metadata property schema reference][11].
 
 ### results
 
 Defines the list of results for the `get` operation invoked against every instance in the
 configuration document. Every entry in the list includes the resource's type name, instance name,
-and the result data for an instance.
+and the result data for an instance. DSC doesn't include an entry for an instance it skipped
+because the instance's `condition` didn't evaluate to `true`.
 
 ```yaml
 Type:      array
 Required:  true
 ItemsType: object
 ```
 
+#### executionInformation
+
+An item's `executionInformation` property describes the context of the operation for the instance.
+The value is an object with the following properties:
+
+- [duration][07] defines the duration of the DSC operation against the resource instance as a
+  string following the format defined in [ISO8601 ABNF for `duration`][08].
+- [restartRequired][10] defines the list of restarts the resource reported as required. DSC only
+  includes this property when the resource reported a required restart.
+
+```yaml
+Type:     object
+Required: false
+```
+
+#### metadata
+
+An item's `metadata` property defines the metadata DSC returns for the resource instance operation.
+The `Microsoft.DSC` property under this property includes the [duration][07] of the operation. DSC
+includes this property for backwards compatibility. In DSC version 4.0.0, the output will no longer
+include this property.
+
+```yaml
+Type:     object
+Required: false
+```
+
 #### type
 
 An item's `type` property identifies the instance's DSC Resource by its fully qualified type name.
 For more information about type names, see
-[DSC Resource fully qualified type name schema reference][10].
+[DSC Resource fully qualified type name schema reference][12].
 
 ```yaml
 Type:     string
 Required: true
-Pattern:  ^\w+(\.\w+){0,2}\/\w+$
+Pattern:  ^\w+(\.\w+)*\/\w+$
 ```
 
 #### name
@@ -108,12 +153,12 @@ Required: true
 
 An item's `result` property includes the actual state for the resource instance. The value for this
 property adheres to the same schema as the output for the `dsc resource get` command. For more
-information, see [dsc resource get result schema reference][11].
+information, see [dsc resource get result schema reference][13].
 
 ### messages
 
 Defines the list of structured messages emitted by resources during the get operation. For more
-information, see [Structured message schema reference][12].
+information, see [Structured message schema reference][14].
 
 ```yaml
 Type:     array
@@ -130,6 +175,18 @@ Type:     boolean
 Required: true
 ```
 
+### outputs
+
+Defines the values for the outputs that the configuration document defines. Each key is the name of
+an output and the value is the evaluated value for that output. DSC only includes this property
+when the document defines at least one output that DSC evaluated. For more information about
+defining outputs, see the [outputs][15] property in the configuration document schema.
+
+```yaml
+Type:     object
+Required: false
+```
+
 <!-- Link reference definitions -->
 [01]: ../../metadata/Microsoft.DSC/properties.md#version
 [02]: ../../metadata/Microsoft.DSC/properties.md#operation
@@ -140,6 +197,9 @@ Required: true
 [07]: ../../metadata/Microsoft.DSC/properties.md#duration
 [08]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A
 [09]: ../../metadata/Microsoft.DSC/properties.md#securitycontext
-[10]: ../../definitions/resourceType.md
-[11]: ../resource/get.md
-[12]: ../../definitions/message.md
+[10]: ../../metadata/Microsoft.DSC/properties.md#restartrequired
+[11]: ../../metadata/Microsoft.DSC/properties.md
+[12]: ../../definitions/resourceType.md
+[13]: ../resource/get.md
+[14]: ../../definitions/message.md
+[15]: ../../config/document.md#outputs