Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Gijs Reijn (Gijsreyn) wants to merge 1 commit into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 103 additions & 41 deletions docs/reference/cli/function/list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---
Expand Down Expand Up @@ -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
```

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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>
Expand Down Expand Up @@ -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
Expand Down
116 changes: 88 additions & 28 deletions docs/reference/schemas/outputs/config/get.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Loading