From b626073a6dc3b25aeb4efb422551d7f2a6b15d7b Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Wed, 2 Sep 2026 04:20:12 +0200 Subject: [PATCH 1/3] Sync reference schema for released v3.2.0 --- .openpublishing.redirection.json | 5 + .../dsc-3.0/reference/cli/function/index.md | 64 + .../dsc-3.0/reference/cli/function/list.md | 280 ++++ .../dsc-3.0/reference/cli/toc.yml | 6 + .../reference/schemas/config/document.md | 322 ++++- .../reference/schemas/config/functions/add.md | 4 +- .../reference/schemas/config/functions/and.md | 148 ++ .../schemas/config/functions/array.md | 184 +++ .../schemas/config/functions/base64.md | 2 +- .../config/functions/base64ToString.md | 208 +++ .../schemas/config/functions/bool.md | 137 ++ .../schemas/config/functions/cidrHost.md | 274 ++++ .../schemas/config/functions/cidrSubnet.md | 317 +++++ .../schemas/config/functions/coalesce.md | 129 ++ .../schemas/config/functions/concat.md | 5 +- .../schemas/config/functions/contains.md | 199 +++ .../schemas/config/functions/context.md | 204 +++ .../schemas/config/functions/copy.md | 294 ++++ .../schemas/config/functions/copyIndex.md | 240 ++++ .../schemas/config/functions/createArray.md | 6 +- .../schemas/config/functions/createObject.md | 255 ++++ .../schemas/config/functions/dataUri.md | 191 +++ .../config/functions/dataUriToString.md | 224 +++ .../reference/schemas/config/functions/div.md | 8 +- .../schemas/config/functions/empty.md | 217 +++ .../schemas/config/functions/endsWith.md | 183 +++ .../schemas/config/functions/envvar.md | 4 +- .../schemas/config/functions/equals.md | 20 +- .../schemas/config/functions/false.md | 76 ++ .../schemas/config/functions/filter.md | 303 +++++ .../schemas/config/functions/first.md | 175 +++ .../schemas/config/functions/format.md | 2 +- .../schemas/config/functions/greater.md | 157 +++ .../config/functions/greaterOrEquals.md | 159 +++ .../reference/schemas/config/functions/if.md | 28 +- .../schemas/config/functions/indexOf.md | 193 +++ .../reference/schemas/config/functions/int.md | 2 +- .../schemas/config/functions/intersection.md | 253 ++++ .../schemas/config/functions/items.md | 205 +++ .../schemas/config/functions/join.md | 160 +++ .../schemas/config/functions/json.md | 239 ++++ .../schemas/config/functions/lambda.md | 280 ++++ .../config/functions/lambdaVariables.md | 240 ++++ .../schemas/config/functions/last.md | 194 +++ .../schemas/config/functions/lastIndexOf.md | 158 +++ .../schemas/config/functions/length.md | 195 +++ .../schemas/config/functions/less.md | 157 +++ .../schemas/config/functions/lessOrEquals.md | 160 +++ .../reference/schemas/config/functions/map.md | 313 +++++ .../reference/schemas/config/functions/max.md | 2 +- .../reference/schemas/config/functions/min.md | 2 +- .../reference/schemas/config/functions/mod.md | 2 +- .../reference/schemas/config/functions/mul.md | 16 +- .../reference/schemas/config/functions/not.md | 83 ++ .../schemas/config/functions/null.md | 150 +++ .../schemas/config/functions/objectKeys.md | 305 +++++ .../reference/schemas/config/functions/or.md | 148 ++ .../schemas/config/functions/overview.md | 348 ++++- .../schemas/config/functions/parameters.md | 11 +- .../schemas/config/functions/parseCidr.md | 265 ++++ .../schemas/config/functions/path.md | 190 +++ .../schemas/config/functions/range.md | 249 ++++ .../schemas/config/functions/reference.md | 18 +- .../schemas/config/functions/resourceId.md | 18 +- .../config/functions/restartRequired.md | 119 ++ .../schemas/config/functions/secret.md | 233 ++++ .../schemas/config/functions/shallowMerge.md | 498 +++++++ .../schemas/config/functions/skip.md | 149 ++ .../schemas/config/functions/startsWith.md | 183 +++ .../schemas/config/functions/stateChanged.md | 109 ++ .../schemas/config/functions/stdout.md | 179 +++ .../schemas/config/functions/string.md | 262 ++++ .../reference/schemas/config/functions/sub.md | 6 +- .../schemas/config/functions/substring.md | 267 ++++ .../schemas/config/functions/systemRoot.md | 98 ++ .../schemas/config/functions/take.md | 327 +++++ .../schemas/config/functions/toLower.md | 222 +++ .../schemas/config/functions/toUpper.md | 221 +++ .../schemas/config/functions/trim.md | 257 ++++ .../schemas/config/functions/true.md | 76 ++ .../schemas/config/functions/tryGet.md | 336 +++++ .../config/functions/tryIndexFromEnd.md | 316 +++++ .../schemas/config/functions/tryWhich.md | 228 ++++ .../schemas/config/functions/union.md | 320 +++++ .../schemas/config/functions/uniqueString.md | 199 +++ .../reference/schemas/config/functions/uri.md | 345 +++++ .../schemas/config/functions/uriComponent.md | 273 ++++ .../config/functions/uriComponentToString.md | 209 +++ .../schemas/config/functions/utcNow.md | 173 +++ .../schemas/config/functions/variables.md | 2 +- .../reference/schemas/config/metadata.md | 37 +- .../reference/schemas/config/parameter.md | 8 +- .../reference/schemas/config/resource.md | 270 +++- .../functions/builtin/dataTypes.md | 49 + .../reference/schemas/definitions/message.md | 9 +- .../definitions/parameters/dataTypes.md | 15 +- .../definitions/resourceCapabilities.md | 73 +- .../schemas/definitions/resourceKind.md | 19 +- .../schemas/definitions/resourceType.md | 49 +- .../schemas/extension/manifest/discover.md | 98 +- .../schemas/extension/manifest/root.md | 241 +++- .../schemas/extension/stdout/discover.md | 69 +- .../metadata/Microsoft.DSC/properties.md | 95 +- .../reference/schemas/outputs/config/get.md | 116 +- .../reference/schemas/outputs/config/set.md | 120 +- .../reference/schemas/outputs/config/test.md | 122 +- .../schemas/outputs/extension/list.md | 73 +- .../schemas/outputs/function/list.md | 243 ++++ .../reference/schemas/outputs/resource/get.md | 43 +- .../schemas/outputs/resource/list.md | 173 ++- .../reference/schemas/outputs/resource/set.md | 53 +- .../schemas/outputs/resource/test.md | 50 +- .../dsc-3.0/reference/schemas/overview.md | 169 ++- .../schemas/resource/manifest/adapter.md | 113 +- .../schemas/resource/manifest/delete.md | 204 ++- .../schemas/resource/manifest/export.md | 224 ++- .../schemas/resource/manifest/get.md | 197 ++- .../schemas/resource/manifest/resolve.md | 119 +- .../schemas/resource/manifest/root.md | 351 +++-- .../resource/manifest/schema/embedded.md | 31 +- .../resource/manifest/schema/property.md | 106 +- .../schemas/resource/manifest/set.md | 277 +++- .../schemas/resource/manifest/test.md | 174 ++- .../schemas/resource/manifest/validate.md | 170 ++- .../schemas/resource/manifest/whatif.md | 282 +++- .../schemas/resource/properties/ensure.md | 8 +- .../schemas/resource/properties/exist.md | 2 +- .../resource/properties/inDesiredState.md | 3 +- .../schemas/resource/properties/overview.md | 26 +- .../schemas/resource/properties/purge.md | 2 +- .../resource/properties/rebootRequested.md | 48 - .../schemas/resource/stdout/delete.md | 80 +- .../schemas/resource/stdout/export.md | 2 +- .../reference/schemas/resource/stdout/get.md | 2 +- .../schemas/resource/stdout/index.md | 31 +- .../reference/schemas/resource/stdout/list.md | 179 ++- .../schemas/resource/stdout/resolve.md | 2 +- .../schemas/resource/stdout/schema.md | 2 +- .../reference/schemas/resource/stdout/set.md | 12 +- .../reference/schemas/resource/stdout/test.md | 18 +- .../schemas/resource/stdout/validate.md | 2 +- .../schemas/resource/stdout/whatIf.md | 79 +- .../dsc-3.0/reference/schemas/schema-uris.md | 1200 ++++++++++++++--- .../dsc-3.0/reference/schemas/toc.yml | 144 +- 144 files changed, 20069 insertions(+), 1408 deletions(-) create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/cli/function/index.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/cli/function/list.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/and.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/array.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64ToString.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/bool.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/cidrHost.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/cidrSubnet.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/coalesce.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/contains.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/context.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/copy.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/copyIndex.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/createObject.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUri.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUriToString.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/empty.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/endsWith.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/false.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/filter.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/first.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/greater.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/greaterOrEquals.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/indexOf.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/intersection.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/items.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/join.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/json.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lambda.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lambdaVariables.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/last.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lastIndexOf.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/length.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/less.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lessOrEquals.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/map.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/not.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/null.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/objectKeys.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/or.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parseCidr.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/path.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/range.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/restartRequired.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/secret.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/shallowMerge.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/skip.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/startsWith.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/stateChanged.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/stdout.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/string.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/substring.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/systemRoot.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/take.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/toLower.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/toUpper.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/trim.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/true.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryGet.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryIndexFromEnd.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryWhich.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/union.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uniqueString.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uri.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uriComponent.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uriComponentToString.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/utcNow.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/functions/builtin/dataTypes.md create mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/function/list.md delete mode 100644 dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/rebootRequested.md diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 15ce8e33..854adf25 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -105,6 +105,11 @@ "redirect_url": "/powershell/dsc/reference/schemas/resource/manifest/adapter", "redirect_document_id": true }, + { + "source_path": "dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/rebootRequested.md", + "redirect_url": "/powershell/dsc/reference/schemas/resource/properties/overview", + "redirect_document_id": false + }, { "source_path": "dsc/docs-conceptual/dsc-3.0/resources/concepts/anatomy.md", "redirect_url": "/powershell/dsc/concepts/resources/anatomy", diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/function/index.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/function/index.md new file mode 100644 index 00000000..b0323c62 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/function/index.md @@ -0,0 +1,64 @@ +--- +description: Command line reference for the 'dsc function' command +ms.date: 09/01/2026 +ms.topic: reference +title: dsc function +--- + +# dsc function + +## Synopsis + +Operations on DSC functions. + +## Syntax + +```sh +dsc function [Options] +``` + +## Description + +The `dsc function` command contains a subcommand for listing DSC functions. + +## Commands + +### list + +The `list` command returns the list of available DSC functions with an optional filter. For more +information, see [dsc function list][01]. + +### help + +The `help` command returns help information for this command or a subcommand. + +To get the help for a command or subcommand, use the syntax: + +```sh +dsc function help [] +``` + +For example, `dsc function help` gets the help for this command. `dsc function help list` +gets the help for the `list` subcommand. + +You can also use the [--help](#--help) option on the command or subcommand to display the help +information. For example, `dsc function --help` or `dsc function list --help`. + +## Options + +### -h, --help + + + + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all other options and arguments. + +```yaml +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h +``` + +[01]: ./list.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/function/list.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/function/list.md new file mode 100644 index 00000000..16ff5ba3 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/function/list.md @@ -0,0 +1,280 @@ +--- +description: Command line reference for the 'dsc function list' command +ms.date: 09/01/2026 +ms.topic: reference +title: dsc function list +--- + +# dsc function list + +## Synopsis + +List or find DSC functions. + +## Syntax + +```sh +dsc function list [Options] [] +``` + +## Description + +The `dsc function list` command returns information about the available DSC functions. By default, +it returns all available functions. You can filter the results by specifying a function name or +pattern. + +DSC functions are built-in functions that can be used in configuration documents to perform various +operations including: + +- String manipulation and formatting +- Mathematical calculations +- Logical operations +- Type conversions +- Parameter and variable access +- Resource references + +For more information about the available builtin functions, see +[DSC Configuration document functions reference][01] + +## Examples + +### Example 1 - List all functions + + + +This command returns information about all available DSC functions. + +```sh +dsc function list +``` + +```output +Category Function Syntax Description +----------------------------------------------------------------------------------------- +Array array array( , ) Creates an array of … +Array tryIndexFromEnd tryIndexFromEnd( , ) Retrieves a value fr… +Array, Lambda filter filter( , ) Filters an array wit… +Array, Lambda map map( , ) Transforms an array … +Array, Object intersection intersection( , <… Returns a single arr… +Array, Object tryGet tryGet( , + +This command filters functions by name using a wildcard pattern. + +```sh +dsc function list resource* +``` + +```output +Category Function Syntax Description +---------------------------------------------------------------------------------------- +Resource resourceId resourceId( , ) Constructs a resource ID from the gi… +``` + +### Example 3 - Get details for a specific function + + + +This command returns detailed information about a specific function, displaying it in YAML format. + +```sh +dsc function list concat --output-format yaml +``` + +```yaml +category: +- array +- string +name: concat +description: Concatenates two or more strings or arrays +syntax: concat( , , ... ) +constraints: All arguments must be of the same type (all strings or all arrays) +minArgs: 2 +maxArgs: 18446744073709551615 +acceptedArgOrderedTypes: +- - string + - array +- - string + - array +remainingArgAcceptedTypes: +- string +- array +returnTypes: +- string +- array +``` + +### Example 4 - Filter functions by category + + + +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( , ) Filters an ar… +Array, Lambda map map( , ) Transforms an… +Lambda lambda lambda( , [param2], ..., ) Creates a lam… +Lambda lambdaVariables lambdaVariables( ) Retrieves the… +``` + +### Example 5 - Filter functions by description + + + +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( , ) Calculates the usab… +CIDR cidrSubnet cidrSubnet( , , ) Splits the specifie… +CIDR parseCidr parseCidr( ) Parses an IP addres… +``` + +## Parameters + +### FUNCTION_NAME + +The name of the function to retrieve information about. You can use wildcard patterns to filter +functions. When you specify this parameter, DSC only returns information about functions that match +the pattern. + +```yaml +Type: string +Required: false +Position: 0 +``` + +## Options + +### -c, --category + + + + +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 +ShortSyntax: -c +``` + +### -d, --description + + + + +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 +ShortSyntax: -d +``` + +### -o, --output-format + + + + +The `--output-format` option controls which format DSC uses for the data the command returns. The +available formats are: + +- `json` to emit the data as a [JSON Line][02]. +- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability. +- `yaml` to emit the data as YAML. +- `table-no-truncate` to emit the data as a summary table without truncating each line to the + current console width. + +> [!NOTE] +> In the current release of DSC, the `table-no-truncate` option has a bug that causes the data to +> emit as a series of YAML documents instead. This bug will be fixed in a future version of DSC. + +The default output format depends on whether DSC detects that the output is being redirected or +captured as a variable: + +- If the command isn't being redirected or captured, DSC displays the output as a summary table + described in the [Output](#output) section of this document. +- If the command output is redirected or captured, DSC emits the data as the `json` format to + stdout. + +When you use this option, DSC uses the specified format regardless of whether the command is being +redirected or captured. + +When the command isn't redirected or captured, the output in the console is formatted for improved +readability. When the command isn't redirected or captured, the output includes terminal sequences +for formatting. + +```yaml +Type: string +Mandatory: false +ValidValues: [json, pretty-json, yaml, table-no-truncate] +LongSyntax: --output-format <> +ShortSyntax: -o <> +``` + +### -h, --help + + + + +Displays the help for the current command. When you specify this option, the application ignores +all other options and arguments. + +```yaml +Type : boolean +Mandatory : false +LongSyntax : --help +ShortSyntax : -h +``` + +## Output + +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 categories the function belongs to. +- **Function** - The name of the function. +- **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 +[--output-format option](#--output-format). + + +[01]: ../../schemas/config/functions/overview.md +[02]: https://jsonlines.org/ +[03]: ../../schemas/outputs/function/list.md +[04]: ../../schemas/definitions/functions/builtin/dataTypes.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/toc.yml b/dsc/docs-conceptual/dsc-3.0/reference/cli/toc.yml index 9bf1fb97..52e487aa 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/toc.yml +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/toc.yml @@ -21,6 +21,12 @@ items: href: extension/index.md - name: dsc extension list href: extension/list.md + - name: dsc function subcommands + items: + - name: dsc function + href: function/index.md + - name: dsc function list + href: function/list.md - name: dsc resource subcommands items: - name: dsc resource diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md index c41774aa..4ceb997b 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a Desired State Configuration document. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Configuration document schema reference --- @@ -71,7 +71,7 @@ semantic version, the latest schema for a minor version, or the latest schema fo of DSC. For more information about schema URIs and versioning, see [DSC JSON Schema URIs](../schema-uris.md). -For every version of the schema, there are three valid urls: +For every version of the schema, there are three valid URLs: - `.../config/document.json` @@ -104,9 +104,33 @@ ValidValues: [ https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/config/document.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/config/document.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/config/document.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/config/document.vscode.json @@ -125,9 +149,33 @@ ValidValues: [ https://aka.ms/dsc/schemas/v3/config/document.json https://aka.ms/dsc/schemas/v3/bundled/config/document.json https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.2/config/document.json + https://aka.ms/dsc/schemas/v3.2/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.2/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.2.3/config/document.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.2.2/config/document.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.2.1/config/document.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.2.0/config/document.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/config/document.vscode.json https://aka.ms/dsc/schemas/v3.1/config/document.json https://aka.ms/dsc/schemas/v3.1/bundled/config/document.json https://aka.ms/dsc/schemas/v3.1/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.1.3/config/document.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.1.2/config/document.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/config/document.vscode.json + https://aka.ms/dsc/schemas/v3.1.1/config/document.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/config/document.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/config/document.vscode.json https://aka.ms/dsc/schemas/v3.1.0/config/document.json https://aka.ms/dsc/schemas/v3.1.0/bundled/config/document.json https://aka.ms/dsc/schemas/v3.1.0/bundled/config/document.vscode.json @@ -146,11 +194,208 @@ ValidValues: [ ] ``` +### contentVersion + +The `contentVersion` property defines a version string for the configuration document. You can use +this property to track revisions of the document. DSC doesn't validate or use this value when +processing a configuration document. The document that the `dsc config export` command returns +always defines this property as `1.0.0`. + +```yaml +Type: string +Required: false +``` + +### directives + +The `directives` property defines how DSC processes the configuration document as a whole. Every +directive is optional. + +```yaml +Type: object +Required: false +``` + +You can define the following directives for a configuration document: + +#### resourceDiscovery + +The `resourceDiscovery` directive controls when DSC raises an error for a resource that it can't +find. When you don't define this directive or set it to `preDeployment`, DSC discovers resources +and extensions before invoking any resource instance and raises an error if any instance in the +document uses a resource that DSC didn't discover. + +Set this directive to `duringDeployment` to defer this check until DSC processes each instance. +This is useful when the configuration document itself installs a resource that a later instance +depends on. With this setting, DSC performs discovery again when it processes an instance whose +resource wasn't initially discovered and only raises an error if the resource isn't available at +that time. + +```yaml +Type: string +Required: false +Default: preDeployment +ValidValues: [preDeployment, duringDeployment] +``` + +#### securityContext + +The `securityContext` directive defines the security context the configuration document requires. +Before invoking any resource instances, DSC validates that it's running in the required security +context and raises an error if it isn't: + +- `current` - DSC can process the document in any security context. This is the default. +- `elevated` - DSC must be running as `root` (non-Windows) or in an elevated session with + Administrator privileges (Windows). +- `restricted` - DSC must be running as a normal user or account in a non-elevated session. + +This directive replaces the deprecated `Microsoft.DSC.securityContext` property in the document's +[metadata][02]. If you define both, the values must match or DSC raises an error. A resource +instance can override this directive with its own `directives.securityContext` setting. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + +#### version + +The `version` directive defines a semantic version requirement for DSC itself. When you define this +directive, DSC compares its own version to the requirement before invoking any resource instances +and raises an error if its version doesn't satisfy the requirement. This enables you to prevent a +configuration document from being processed by an incompatible version of DSC. + +The value must be one or more comparators separated by commas. Each comparator is an operator +(`=`, `>`, `>=`, `<`, `<=`, `^`, or `~`) followed by a version, like `>=3.2.0, <4.0.0`. Build +metadata isn't allowed in the version. The syntax is the same as for the `requireVersion` property +of a resource instance. For more information, see [requireVersion][03]. + +```yaml +Type: string +Required: false +``` + +### executionInformation + +The `executionInformation` property describes the DSC operation that produced a configuration +document. DSC adds this property to the document returned by the `dsc config export` command. The +schema accepts this property in any configuration document, but DSC ignores it when it processes +the document. + +The value is an object with the same properties as the [Microsoft.DSC metadata][04] object that DSC +returns in command output, plus an optional `whatIf` property that describes any what-if +operations DSC performed. + +```yaml +Type: object +Required: false +``` + +### functions + +The `functions` property defines user-defined functions that you can call in configuration +expressions anywhere in the document. Each item in the list defines a namespace and the functions +that belong to it: + +- `namespace` - Required. The name that groups the functions. You call a user-defined function as + `.()`. +- `members` - Required. An object that maps each function name to its definition. Each definition + is an object with the following properties: + + - `parameters` - Optional. A list of parameters for the function. Each parameter is an object + that defines the `name` and `type` of the parameter. The `type` must be one of the + [parameter data types][05]. When you call the function, DSC raises an error if the number of + arguments or their types don't match the parameters. + - `output` - Required. An object that defines the `type` of the value the function returns and + the `value` as a string. DSC evaluates the `value` as a configuration expression and raises an + error if the result doesn't match the declared `type`. + +In the `value` expression, use the [parameters()][06] function to access the function's own +parameters. User-defined functions can't access the document's parameters or variables, can't use +the `reference()` function, and can't call other user-defined functions. + +For example, this document defines the `contoso.greet()` function and calls it in a resource +instance: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +functions: + - namespace: contoso + members: + greet: + parameters: + - name: name + type: string + output: + type: string + value: "[format('Hello, {0}!', parameters('name'))]" +resources: + - name: Greeting + type: Microsoft.DSC.Debug/Echo + properties: + output: "[contoso.greet('World')]" +``` + +```yaml +Type: array +Required: false +ItemsType: object +``` + ### metadata -The `metadata` property defines a set of key-value pairs as annotations for the configuration. DSC -doesn't validate the metadata. A configuration can include any arbitrary information in this -property. +The `metadata` property defines a set of key-value pairs as annotations for the configuration. +Except for the `Microsoft.DSC` property, DSC doesn't validate the metadata. A configuration can +include any arbitrary information in this property. + +The `Microsoft.DSC` property is reserved for DSC. For more information, see +[DSC Configuration document metadata schema][02]. + +```yaml +Type: object +Required: false +``` + +### outputs + +The `outputs` property defines values that DSC evaluates after it processes every resource instance +in the document and returns in the `outputs` property of the command output. Each output is defined +as a key-value pair. The key is the name of the output. The value is an object with the following +properties: + +- `type` - Required. The [data type][05] of the output value. DSC raises an error if the evaluated + value doesn't match this type. DSC doesn't return outputs with the `secureString` or + `secureObject` types. Instead, it raises a warning and skips them. +- `value` - Required. A string that DSC evaluates as a configuration expression. Use this property + to return data from resource results, parameters, variables, and functions, like + `"[reference(resourceId('Microsoft.DSC.Debug/Echo', 'echo')).output]"`. +- `condition` - Optional. A string that DSC evaluates as a configuration expression. DSC only + returns the output when the condition evaluates to `true`. When it evaluates to any other value, + DSC skips the output. + +The schema also accepts a `copy` object in place of `value`, with the same shape as the `copy` +property of a resource instance. DSC doesn't currently support copy loops for outputs. When an +output defines `copy` instead of `value`, DSC raises a warning and skips the output. + +DSC doesn't evaluate outputs when you invoke the `dsc config set` command with the `--what-if` +option. + +For example, this document returns the value that the `echo` instance reported: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: echo + type: Microsoft.DSC.Debug/Echo + properties: + output: Hello World +outputs: + echoOutput: + type: string + value: "[reference(resourceId('Microsoft.DSC.Debug/Echo', 'echo')).output]" +``` ```yaml Type: object @@ -164,19 +409,37 @@ defined as key-value pair. The key for each pair defines the name of the paramet each pair must be an object that defines the `type` keyword to indicate how DSC should process the parameter. -Parameters may be overridden at run-time, enabling re-use of the same configuration document for +Parameters may be overridden at runtime, enabling re-use of the same configuration document for different contexts. For more information about defining parameters in a configuration, see -[DSC Configuration document parameter schema][02]. +[DSC Configuration document parameter schema][07]. +[DSC Configuration parameters][08] --> ```yaml Type: object Required: false -ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.parameter.json +ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/config/document.parameter.json +``` + +### resources + +The `resources` property defines a list of DSC Resource instances that the configuration manages. +Instances may share the same DSC Resource type, but every instance must have a unique combination +of `type` and `name`. If two instances share the same type and name, DSC raises an error. + +For more information about defining a valid resource instance in a configuration, see +[DSC Configuration document resource schema][09]. + + + +```yaml +Type: array +Required: true +ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/config/document.resource.json ``` ### variables @@ -187,40 +450,27 @@ the variable by name can access the variable's value. This can help reduce the amount of copied values and options for resources in the configuration, which makes the document easier to read and maintain. Unlike parameters, variables can only be -defined in the configuration and can't be overridden at run-time. +defined in the configuration and can't be overridden at runtime. +[DSC Configuration variables][12]. --> ```yaml Type: object Required: false ``` -### resources - -The `resources` property defines a list of DSC Resource instances that the configuration manages. -Every instance in the list must be unique, but instances may share the same DSC Resource type. - -For more information about defining a valid resource instance in a configuration, see -[DSC Configuration document resource schema][05]. - - - -```yaml -Type: array -Required: true -MinimumItemCount: 1 -ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.resource.json -``` - -[01]: functions/resourceId.md +[01]: functions/overview.md -[02]: parameter.md - - -[05]: resource.md - - +[02]: metadata.md +[03]: resource.md#requireversion +[04]: ../metadata/Microsoft.DSC/properties.md +[05]: ../definitions/parameters/dataTypes.md +[06]: functions/parameters.md +[07]: parameter.md + +[09]: resource.md + + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/add.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/add.md index 0c65e7d3..ee08f2c2 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/add.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/add.md @@ -1,6 +1,6 @@ --- description: Reference for the 'add' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: add --- @@ -39,7 +39,7 @@ resources: ``` ```bash -dsc config get --file add.example.1.dsc.config.yaml +dsc config get --file add.example.1.dsc.config.yaml ``` ```yaml diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/and.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/and.md new file mode 100644 index 00000000..25b08396 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/and.md @@ -0,0 +1,148 @@ +--- +description: Reference for the 'and' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: and +--- + +# and + +## Synopsis + +Returns true if all arguments are true. + +## Syntax + +```Syntax +and(, , ...) +``` + +## Description + +The `and()` function evaluates if all arguments are true. It takes two or more boolean arguments +and returns `true` only if every argument is `true`. If any argument is `false`, the function +returns `false`. + +This function uses short-circuit evaluation, meaning it returns `false` as soon as it encounters +the first `false` argument without evaluating the remaining arguments. + +## Examples + +### Example 1 - Basic and operation + +This configuration demonstrates basic usage of the `and()` function. + +```yaml +# and.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo and result + type: Microsoft.DSC.Debug/Echo + properties: + output: "[and(true, true)]" +``` + +```bash +dsc config get --file and.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.1291763S + name: Echo and result + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +### Example 2 - And operation with false value + +This example shows the `and()` function returning false when one argument is false. + +```yaml +# and.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo and result with false + type: Microsoft.DSC.Debug/Echo + properties: + output: "[and(true, false, true)]" +``` + +```bash +dsc config get --file and.example.2.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0329292S + name: Echo and result with false + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: false +messages: [] +hadErrors: false +``` + +### Example 3 - And operation with multiple conditions + +This configuration uses the `and()` function with multiple boolean expressions. + +```yaml +# and.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo complex and operation + type: Microsoft.DSC.Debug/Echo + properties: + output: "[and(equals(5, 5), equals('hello', 'hello'), true)]" +``` + +```bash +dsc config get --file and.example.3.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0514415S + name: Echo complex and operation + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +### arguments + +The `and()` function requires two or more boolean arguments. + +```yaml +Type: boolean +Required: true +MinimumCount: 2 +MaximumCount: 18446744073709551615 +``` + +## Output + +The `and()` function returns `true` if all arguments are `true`, otherwise it returns `false`. + +```yaml +Type: boolean +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/array.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/array.md new file mode 100644 index 00000000..7150eaf6 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/array.md @@ -0,0 +1,184 @@ +--- +description: Reference for the 'array' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: array +--- + +# array + +## Synopsis + +Wraps a single value (string, number, array, or object) in an array. + +## Syntax + +```Syntax +array() +``` + +## Description + +The `array()` function returns a new array containing the single input value. +The value can be a string, number, array, or object. Use +`createArray()` to construct arrays with multiple elements of the same type. + +This function is useful when a schema expects an array, but you only have a +single value, or when you need to nest an existing array or object inside an +outer array. + +## Examples + +### Example 1 - Wrap an existing array as a single element + +This example demonstrates wrapping an existing server list into a single array +element, producing a nested array. This can be useful when a downstream schema +expects an array of arrays. + +```yaml +# array.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + webServers: + type: array + defaultValue: + - web01 + - web02 + batchSize: + type: int + defaultValue: 2 +resources: +- name: Deployment Plan + type: Microsoft.DSC.Debug/Echo + properties: + output: "[array(parameters('webServers'))]" +``` + +```bash +dsc config get --file array.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Deployment Plan + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - - web01 + - web02 +messages: [] +hadErrors: false +``` + +### Example 2 - Wrap a single object for payloads + +This example shows how to wrap a structured metadata object into an array for +logging or monitoring systems that expect arrays. + +```yaml +# array.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + correlationId: + type: string + defaultValue: ABC123 +resources: +- name: Telemetry Payload + type: Microsoft.DSC.Debug/Echo + properties: + output: + payload: "[array(createObject('severity', 'info'))]" +``` + +```bash +dsc config get --file array.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Telemetry Payload + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + payload: + - severity: info +messages: [] +hadErrors: false +``` + +### Example 3 - Wrap generated collections + +This example demonstrates wrapping a generated collection (like one from +`createArray()` or `createObject()`) into an outer array. + +```yaml +# array.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Combined Collections + type: Microsoft.DSC.Debug/Echo + properties: + output: + combinedArray: "[array(createArray('a','b'))]" + combinedObject: "[array(createObject('k','v'))]" +``` + +```bash +dsc config get --file array.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Combined Collections + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + combinedArray: + - - a + - b + combinedObject: + - k: v +messages: [] +hadErrors: false +``` + +## Parameters + +### value + +The single value to wrap in the array. + +```yaml +Type: string, number, array, or object +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +The provided value will be wrapped into the resulting array. The value must be +one of the four accepted types: string, number (integer), array, or object. +Boolean and null values are not supported. + +## Output + +Returns a new array containing the provided elements in order. + +```yaml +Type: array +``` + +## Related functions + +- [`createArray()`][00] - Creates a homogeneous array (all elements same type) +- [`createObject()`][01] - Builds an object from key-value pairs +- [`first()`][02] - Gets the first element from an array +- [`indexOf()`][03] - Finds the index of an item in an array + + +[00]: ./createArray.md +[01]: ./createObject.md +[02]: ./first.md +[03]: ./indexOf.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64.md index 3d51e71b..ef125866 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64.md @@ -1,6 +1,6 @@ --- description: Reference for the 'base64' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: base64 --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64ToString.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64ToString.md new file mode 100644 index 00000000..002b6991 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64ToString.md @@ -0,0 +1,208 @@ +--- +description: Reference for the 'base64ToString' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: base64ToString +--- + +# base64ToString + +## Synopsis + +Converts a base64 representation to a string. + +## Syntax + +```Syntax +base64ToString() +``` + +## Description + +The `base64ToString()` function converts a [base64][01] encoded string back to +its original string representation. This function is the inverse of the +[`base64()`][02] function and is useful for decoding base64-encoded +configuration data, secrets, or content that was previously encoded for safe +transmission or storage.## Examples + +### Example 1 - Decode a base64 string + +The configuration decodes a base64-encoded string back to its original value. + +```yaml +# base64ToString.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Decode base64 string + type: Microsoft.DSC.Debug/Echo + properties: + output: "[base64ToString('aGVsbG8gd29ybGQ=')]" +``` + +```bash +dsc config get --file base64ToString.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Decode base64 string + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: hello world +messages: [] +hadErrors: false +``` + +### Example 2 - Round-trip encoding and decoding + +The configuration demonstrates encoding a string to base64 and then decoding it +back using the [`base64()`][02] function inside the `base64ToString()` function. + +```yaml +# base64ToString.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Round-trip base64 conversion + type: Microsoft.DSC.Debug/Echo + properties: + output: "[base64ToString(base64('Configuration Data'))]" +``` + +```bash +dsc config get --file base64ToString.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Round-trip base64 conversion + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Configuration Data +messages: [] +hadErrors: false +``` + +### Example 3 - Decode configuration from parameters + +This example shows decoding base64-encoded configuration data passed through +parameters, which is common when passing complex data through deployment +systems that require base64 encoding. + +```yaml +# base64ToString.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + encodedConfig: + type: string + defaultValue: eyJzZXJ2ZXJOYW1lIjoid2ViLXNlcnZlci0wMSIsInBvcnQiOjgwODB9 +resources: + - name: Decode server configuration + type: Microsoft.DSC.Debug/Echo + properties: + output: "[base64ToString(parameters('encodedConfig'))]" +``` + +```bash +dsc config get --file base64ToString.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Decode server configuration + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: '{"serverName":"web-server-01","port":8080}' +messages: [] +hadErrors: false +``` + +### Example 4 - Decode with error handling + +This example demonstrates how the function handles invalid base64 input by +using the [`if()`][03] function to provide fallback behavior. + +```yaml +# base64ToString.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + possiblyEncodedData: + type: string + defaultValue: validBase64String= + fallbackData: + type: string + defaultValue: default configuration +resources: + - name: Safe decode with fallback + type: Microsoft.DSC.Debug/Echo + properties: + output: + decodedValue: "[base64ToString(parameters('possiblyEncodedData'))]" + fallback: "[parameters('fallbackData')]" +``` + +```bash +dsc --file base64ToString.example.4.dsc.config.yaml config get +``` + +```yaml +results: +- name: Safe decode with fallback + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + decodedValue: waEb(KidString + fallback: default configuration +messages: [] +hadErrors: false +``` + +## Parameters + +### base64Value + +The `base64ToString()` function expects a single string containing valid +base64-encoded data. The function decodes the base64 representation back to +the original string. If the value isn't a valid base64 string, DSC raises an +error. If the decoded bytes don't form valid UTF-8, DSC also raises an error. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `base64ToString()` function returns the decoded string representation of +the **base64Value** parameter. + +```yaml +Type: string +``` + +## Exceptions + +The `base64ToString()` function raises errors for the following conditions: + +- **Invalid base64 encoding**: When the input string contains characters or + patterns that are not valid base64 +- **Invalid UTF-8**: When the decoded bytes do not form valid UTF-8 text + +## Related functions + +- [`base64()`][02] - Encodes a string to base64 format +- [`string()`][04] - Converts values to strings +- [`parameters()`][05] - Retrieves parameter values +- [`if()`][03] - Returns values based on a condition + + +[01]: https://en.wikipedia.org/wiki/Base64 +[02]: ./base64.md +[03]: ./if.md +[04]: ./string.md +[05]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/bool.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/bool.md new file mode 100644 index 00000000..67b89259 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/bool.md @@ -0,0 +1,137 @@ +--- +description: Reference for the 'bool' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: bool +--- + +# bool + +## Synopsis + +Converts a string or number to a boolean value. + +## Syntax + +```Syntax +bool() +``` + +## Description + +The `bool()` function converts a string or number to a boolean value. For string arguments, +it accepts "true" (case-insensitive) which converts to `true`, and "false" (case-insensitive) +which converts to `false`. For numeric arguments, zero converts to `false` and any non-zero +value converts to `true`. + +> [!NOTE] +> Any string argument other than `true` or `false` (case-insensitive) will raise a DSC error. + +## Examples + +### Example 1 - Convert string to boolean + +This configuration demonstrates converting string values to boolean. + +```yaml +# bool.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo bool from string + type: Microsoft.DSC.Debug/Echo + properties: + output: + trueValue: "[bool('true')]" + falseValue: "[bool('FALSE')]" +``` + +```bash +dsc config get --file bool.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0334711S + name: Echo bool from string + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + trueValue: true + falseValue: false +messages: [] +hadErrors: false +``` + +### Example 2 - Convert number to boolean + +This example shows the `bool()` function converting numeric values to boolean. + +```yaml +# bool.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo bool from numbers + type: Microsoft.DSC.Debug/Echo + properties: + output: + zeroIsFalse: "[bool(0)]" + oneIsTrue: "[bool(1)]" + negativeIsTrue: "[bool(-5)]" + positiveIsTrue: "[bool(42)]" +``` + +```bash +dsc config get --file bool.example.2.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0323199S + name: Echo bool from numbers + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + zeroIsFalse: false + oneIsTrue: true + negativeIsTrue: true + positiveIsTrue: true +messages: [] +hadErrors: false +``` + +## Parameters + +### value + +The `bool()` function requires a single argument that is either a string or number. + +For strings, valid values are: + +- "true" (case-insensitive) - converts to `true` +- "false" (case-insensitive) - converts to `false` + +For numbers: + +- 0 - converts to `false` +- Any non-zero value - converts to `true` + +```yaml +Type: [string, integer] +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `bool()` function returns a boolean value based on the input argument. + +```yaml +Type: boolean +``` diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/cidrHost.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/cidrHost.md new file mode 100644 index 00000000..e74ae4e7 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/cidrHost.md @@ -0,0 +1,274 @@ +--- +description: Reference for the 'cidrHost' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: cidrHost +--- + +# cidrHost + +## Synopsis + +Calculates a host IP address within a CIDR network block. + +## Syntax + +```Syntax +cidrHost(, ) +``` + +## Description + +The `cidrHost()` function calculates a specific host IP address within a given +[CIDR][01] network block by adding a host number offset to the network address. +This function is particularly useful for systematically assigning IP addresses +to hosts, generating gateway addresses, or allocating IP addresses for network +resources in infrastructure-as-code scenarios. + +The host number is zero-indexed, where `0` represents the network address +itself. For typical host assignments, start with `1` to get the first usable +IP address in the network. + +## Examples + +### Example 1 - Calculate gateway address + +Network configurations commonly use the first usable IP address as the gateway. +This example calculates that address using host number `1`. + +```yaml +# cidrHost.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Gateway address + type: Microsoft.DSC.Debug/Echo + properties: + output: "[cidrHost('10.0.1.0/24', 1)]" +``` + +```bash +dsc config get --file cidrHost.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Gateway address + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: 10.0.1.1 +messages: [] +hadErrors: false +``` + +### Example 2 - Assign multiple host addresses + +This configuration demonstrates calculating host addresses for a subnet created +with [`cidrSubnet()`][02], useful for assigning IP addresses to multiple servers +or network devices. + +```yaml +# cidrHost.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + baseNetwork: + type: string + defaultValue: 172.16.0.0/16 + subnetIndex: + type: int + defaultValue: 10 +resources: + - name: Web server IPs + type: Microsoft.DSC.Debug/Echo + properties: + output: + subnet: "[cidrSubnet(parameters('baseNetwork'), 24, parameters('subnetIndex'))]" + webServer1: >- + [cidrHost(cidrSubnet(parameters('baseNetwork'), 24, + parameters('subnetIndex')), 10)] + webServer2: >- + [cidrHost(cidrSubnet(parameters('baseNetwork'), 24, + parameters('subnetIndex')), 11)] + webServer3: >- + [cidrHost(cidrSubnet(parameters('baseNetwork'), 24, + parameters('subnetIndex')), 12)] +``` + +```bash +dsc config get --file cidrHost.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Web server IPs + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + subnet: 172.16.10.0/24 + webServer1: 172.16.10.11 + webServer2: 172.16.10.12 + webServer3: 172.16.10.13 +messages: [] +hadErrors: false +``` + +### Example 3 - Allocate IPs for network infrastructure + +This configuration shows allocating specific IP addresses for various network +infrastructure components within a subnet, demonstrating practical host number +offsets for different device types. + +```yaml +# cidrHost.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + networkCidr: + type: string + defaultValue: 192.168.100.0/24 +resources: + - name: Network infrastructure IPs + type: Microsoft.DSC.Debug/Echo + properties: + output: + network: "[parameters('networkCidr')]" + gateway: "[cidrHost(parameters('networkCidr'), 1)]" + primaryDNS: "[cidrHost(parameters('networkCidr'), 2)]" + secondaryDNS: "[cidrHost(parameters('networkCidr'), 3)]" + loadBalancer: "[cidrHost(parameters('networkCidr'), 10)]" + webServer1: "[cidrHost(parameters('networkCidr'), 20)]" + webServer2: "[cidrHost(parameters('networkCidr'), 21)]" + dbServer: "[cidrHost(parameters('networkCidr'), 50)]" +``` + +```bash +dsc config get --file cidrHost.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Network infrastructure IPs + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + network: 192.168.100.0/24 + gateway: 192.168.100.1 + primaryDNS: 192.168.100.2 + secondaryDNS: 192.168.100.3 + loadBalancer: 192.168.100.10 + webServer1: 192.168.100.20 + webServer2: 192.168.100.21 + dbServer: 192.168.100.50 +messages: [] +hadErrors: false +``` + +### Example 4 - IPv6 host address allocation + +This configuration demonstrates calculating host addresses within an IPv6 +network, showing that the function supports both IPv4 and IPv6 address families. + +```yaml +# cidrHost.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + ipv6Network: + type: string + defaultValue: 2001:db8::/64 +resources: + - name: IPv6 host addresses + type: Microsoft.DSC.Debug/Echo + properties: + output: + network: "[parameters('ipv6Network')]" + router: "[cidrHost(parameters('ipv6Network'), 1)]" + server1: "[cidrHost(parameters('ipv6Network'), 10)]" + server2: "[cidrHost(parameters('ipv6Network'), 11)]" +``` + +```bash +dsc config get --file cidrHost.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: IPv6 host addresses + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + network: 2001:db8::/64 + router: 2001:db8::1 + server1: 2001:db8::a + server2: 2001:db8::b +messages: [] +hadErrors: false +``` + +## Parameters + +### cidrNotation + +The `cidrHost()` function expects the first parameter to be a string in valid +CIDR notation format, including both an IP address and prefix length (e.g., +`10.0.0.0/16`). + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +### hostNumber + +The second parameter specifies the host number offset from the network address. +The value must be a non-negative integer within the valid range of the network. + +- For a `/24` network (254 usable hosts), valid values are `0` to `255` +- For a `/16` network (65,534 usable hosts), valid values are `0` to `65535` +- Value `0` returns the network address itself +- Value `1` typically returns the first usable host (often used for gateways) + +The function raises an error if the host number exceeds the network capacity. + +```yaml +Type: integer +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `cidrHost()` function returns a string containing the calculated IP address +in standard notation (e.g., `10.0.1.15` for IPv4 or `2001:db8::a` for IPv6). + +```yaml +Type: string +``` + +## Exceptions + +The `cidrHost()` function raises errors for the following conditions: + +- **Invalid CIDR notation**: When the CIDR string is malformed or missing the + prefix length +- **Host number out of range**: When the host number exceeds the maximum number + of addresses in the network +- **Invalid host number**: When the host number is negative + +## Related functions + +- [`cidrSubnet()`][02] - Creates a subnet from a larger CIDR block +- [`parseCidr()`][03] - Parses CIDR notation and returns network details +- [`add()`][04] - Adds two numbers together +- [`parameters()`][05] - Retrieves parameter values + + +[01]: https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing +[02]: ./cidrSubnet.md +[03]: ./parseCidr.md +[04]: ./add.md +[05]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/cidrSubnet.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/cidrSubnet.md new file mode 100644 index 00000000..82da1fd7 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/cidrSubnet.md @@ -0,0 +1,317 @@ +--- +description: Reference for the 'cidrSubnet' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: cidrSubnet +--- + +# cidrSubnet + +## Synopsis + +Creates a subnet CIDR block from a larger network block. + +## Syntax + +```Syntax +cidrSubnet(, , ) +``` + +## Description + +The `cidrSubnet()` function calculates a subnet [CIDR][01] block from a larger +network block by subdividing it based on a new prefix length and subnet index. +This function is essential for network segmentation, allowing you to +systematically divide a large address space into smaller, manageable subnets +for different purposes like DMZs, application tiers, or regional deployments. + +The subnet number is zero-indexed, meaning the first subnet is `0`, the second +is `1`, and so on. The new prefix length must be greater than or equal to the +original prefix to create a valid subnet. + +## Examples + +### Example 1 - Create multiple subnets from a network block + +This configuration divides a `/16` network into multiple `/24` subnets, +demonstrating how to create separate network segments for different purposes. + +```yaml +# cidrSubnet.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Network segmentation + type: Microsoft.DSC.Debug/Echo + properties: + output: + baseNetwork: 10.0.0.0/16 + webTierSubnet: "[cidrSubnet('10.0.0.0/16', 24, 0)]" + appTierSubnet: "[cidrSubnet('10.0.0.0/16', 24, 1)]" + dataTierSubnet: "[cidrSubnet('10.0.0.0/16', 24, 2)]" + managementSubnet: "[cidrSubnet('10.0.0.0/16', 24, 3)]" +``` + +```bash +dsc config get --file cidrSubnet.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Network segmentation + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + baseNetwork: 10.0.0.0/16 + webTierSubnet: 10.0.0.0/24 + appTierSubnet: 10.0.1.0/24 + dataTierSubnet: 10.0.2.0/24 + managementSubnet: 10.0.3.0/24 +messages: [] +hadErrors: false +``` + +### Example 2 - Create subnets for multiple regions + +This configuration demonstrates creating dedicated subnets for different regions +or environments, showing how to systematically allocate non-overlapping network +segments from a larger address space. + +```yaml +# cidrSubnet.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + baseNetwork: + type: string + defaultValue: 10.144.0.0/20 + newPrefix: + type: int + defaultValue: 24 +resources: + - name: Regional subnets + type: Microsoft.DSC.Debug/Echo + properties: + output: + eastus: "[cidrSubnet(parameters('baseNetwork'), parameters('newPrefix'), 0)]" + westus: "[cidrSubnet(parameters('baseNetwork'), parameters('newPrefix'), 1)]" + northeurope: "[cidrSubnet(parameters('baseNetwork'), parameters('newPrefix'), 2)]" + westeurope: "[cidrSubnet(parameters('baseNetwork'), parameters('newPrefix'), 3)]" + southeastasia: >- + [cidrSubnet(parameters('baseNetwork'), parameters('newPrefix'), 4)] +``` + +```bash +dsc config get --file cidrSubnet.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Regional subnets + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + eastus: 10.144.0.0/24 + westus: 10.144.1.0/24 + northeurope: 10.144.2.0/24 + westeurope: 10.144.3.0/24 + southeastasia: 10.144.4.0/24 +messages: [] +hadErrors: false +``` + +### Example 3 - Nested subnetting with host allocation + +This example demonstrates combining `cidrSubnet()` with [`cidrHost()`][03] +and [`parseCidr()`][04] to create a complete network configuration including +subnets and host IP assignments. + +```yaml +# cidrSubnet.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + vnetCidr: + type: string + defaultValue: 172.16.0.0/12 + subnetIndex: + type: int + defaultValue: 42 +resources: + - name: Complete network configuration + type: Microsoft.DSC.Debug/Echo + properties: + output: + vnetAddressSpace: "[parameters('vnetCidr')]" + subnetCidr: "[cidrSubnet(parameters('vnetCidr'), 24, parameters('subnetIndex'))]" + subnetDetails: >- + [parseCidr(cidrSubnet(parameters('vnetCidr'), 24, + parameters('subnetIndex')))] + gatewayIP: >- + [cidrHost(cidrSubnet(parameters('vnetCidr'), 24, + parameters('subnetIndex')), 1)] + loadBalancerIP: >- + [cidrHost(cidrSubnet(parameters('vnetCidr'), 24, + parameters('subnetIndex')), 4)] +``` + +```bash +dsc config get --file cidrSubnet.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Complete network configuration + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + vnetAddressSpace: 172.16.0.0/12 + subnetCidr: 172.16.42.0/24 + subnetDetails: + network: 172.16.42.0 + netmask: 255.255.255.0 + broadcast: 172.16.42.255 + firstUsable: 172.16.42.1 + lastUsable: 172.16.42.254 + cidr: 24 + gatewayIP: 172.16.42.2 + loadBalancerIP: 172.16.42.5 +messages: [] +hadErrors: false +``` + +### Example 4 - IPv6 subnet allocation + +This configuration demonstrates creating IPv6 subnets from a larger IPv6 address +block, showing support for both IPv4 and IPv6 address families. + +```yaml +# cidrSubnet.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + ipv6BaseNetwork: + type: string + defaultValue: 2001:db8::/32 + subnetPrefix: + type: int + defaultValue: 48 +resources: + - name: IPv6 subnets + type: Microsoft.DSC.Debug/Echo + properties: + output: + baseNetwork: "[parameters('ipv6BaseNetwork')]" + subnet0: >- + [cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 0)] + subnet1: >- + [cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 1)] + subnet10: >- + [cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 10)] +``` + +```bash +dsc config get --file cidrSubnet.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: IPv6 subnets + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + baseNetwork: 2001:db8::/32 + subnet0: 2001:db8::/48 + subnet1: 2001:db8:1::/48 + subnet10: 2001:db8:a::/48 +messages: [] +hadErrors: false +``` + +## Parameters + +### cidrNotation + +The first parameter specifies the base network in CIDR notation from which +subnets will be created. This must be a valid CIDR string including both an +IP address and prefix length (e.g., `10.0.0.0/16`). + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +### newPrefixLength + +The second parameter specifies the prefix length for the new subnet. This value +must be greater than or equal to the base network's prefix length. + +For example: + +- To divide a `/16` into `/24` subnets, use `24` (creates 256 subnets) +- To divide a `/20` into `/24` subnets, use `24` (creates 16 subnets) +- To divide a `/8` into `/16` subnets, use `16` (creates 256 subnets) + +The function raises an error if the new prefix length is smaller than the +original, as this would create a larger network rather than a subnet. + +```yaml +Type: integer +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +### subnetNumber + +The third parameter specifies which subnet to calculate, using zero-based +indexing. The valid range depends on how many subnets the prefix length +difference allows. + +For example, dividing a `/16` into `/24` subnets allows subnet numbers from +`0` to `255` (2^(24-16) = 256 subnets). + +The function raises an error if the subnet number exceeds the maximum number +of subnets available in the base network. + +```yaml +Type: integer +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `cidrSubnet()` function returns a string containing the calculated subnet +in CIDR notation (e.g., `10.0.5.0/24`). + +```yaml +Type: string +``` + +## Exceptions + +The `cidrSubnet()` function raises errors for the following conditions: + +- **Invalid CIDR notation**: When the base CIDR string is malformed or missing + the prefix length +- **Invalid prefix length**: When the new prefix is smaller than the base + network's prefix +- **Subnet number out of range**: When the subnet number exceeds the maximum + number of subnets possible with the given prefix lengths +- **Invalid subnet number**: When the subnet number is negative + +## Related functions + +- [`cidrHost()`][02] - Calculates a host IP address within a CIDR block +- [`parseCidr()`][03] - Parses CIDR notation and returns network details +- [`parameters()`][04] - Retrieves parameter values + + +[01]: https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing +[02]: ./cidrHost.md +[03]: ./parseCidr.md +[04]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/coalesce.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/coalesce.md new file mode 100644 index 00000000..d3dae838 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/coalesce.md @@ -0,0 +1,129 @@ +--- +description: Reference for the 'coalesce' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: coalesce +--- + +# coalesce + +## Synopsis + +Returns the first non-null value from a list of arguments. + +## Syntax + +```Syntax +coalesce(, , ...) +``` + +## Description + +The `coalesce()` function evaluates arguments from left to right and returns the first argument that +isn't null. This function is useful for providing fallback values when dealing with potentially +null data. + +If all arguments are null, the function returns null. + +## Examples + +### Example 1 - Basic coalesce with strings + +The following example shows how to use the function with string values. + +```yaml +# coalesce.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Coalesce strings + type: Microsoft.DSC.Debug/Echo + properties: + output: + firstNonNull: "[coalesce(null(), 'DSC', 'landscape')]" + allNull: "[coalesce(null(), null(), null())]" + noneNull: "[coalesce('first', 'second', 'third')]" +``` + +```bash +dsc config get --file coalesce.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Coalesce strings + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + firstNonNull: DSC + allNull: null + noneNull: first +messages: [] +hadErrors: false +``` + +### Example 2 - Mixed data types + +The following example shows how the function works with different data types. + +```yaml +# coalesce.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Coalesce mixed types + type: Microsoft.DSC.Debug/Echo + properties: + output: + numberFallback: "[coalesce(null(), 42)]" + booleanFallback: "[coalesce(null(), null(), true)]" + stringToNumber: "[coalesce(null(), 123, 'fallback')]" +``` + +```bash +dsc config get --file coalesce.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Coalesce mixed types + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + numberFallback: 42 + booleanFallback: true + stringToNumber: 123 +messages: [] +hadErrors: false +``` + +## Parameters + +### value1, value2 + +The `coalesce()` function accepts one or more arguments of any type. +Arguments are evaluated from left to right, and the function returns the first non-null +value encountered. + +```yaml +Type: [any] +Required: true +MinimumCount: 1 +MaximumCount: unlimited +``` + +## Output + +The `coalesce()` function returns the first non-null argument, or null if all arguments are null. +The return type matches the type of the first non-null argument. + +```yaml +Type: [any] +``` + +## Related functions + +- [`null()`][00] - Returns a simple JSON null value. + + +[00]: ./null.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md index 409edc0f..cd934797 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md @@ -1,6 +1,6 @@ --- description: Reference for the 'concat' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: concat --- @@ -60,7 +60,8 @@ hadErrors: false ### Example 2 - Concatenate arrays of strings -The configuration uses the `concat()` function to return a combined array of strings from two arrays of strings. It uses YAML's folded multiline syntax to make the function more readable. +The configuration uses the `concat()` function to return a combined array of strings from two +arrays of strings. It uses YAML's folded multiline syntax to make the function more readable. ```yaml # concat.example.2.dsc.config.yaml diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/contains.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/contains.md new file mode 100644 index 00000000..50332a31 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/contains.md @@ -0,0 +1,199 @@ +--- +description: Reference for the 'contains' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: contains +--- + +# contains + +## Synopsis + +Checks whether a collection contains a specific value or whether a string +contains a substring. + +## Syntax + +```Syntax +contains(, ) +``` + +## Description + +The `contains()` function checks whether a collection (array, object, or +string) contains a specific value, returning `true` if it does and `false` +otherwise. For arrays, it checks if the value exists as an element. For +objects, it checks if the value exists as a property key or value. For +strings, it checks if the value exists as a substring. + +The function accepts string and number values for the search parameter when +used with arrays, objects, or strings. + +## Examples + +### Example 1 - Check array for values + +The following example shows how to check if an array contains specific values. + +```yaml +# contains.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + myArray: + type: array + defaultValue: + - apple + - banana + - 42 + - true +resources: +- name: Check array contents + type: Microsoft.DSC.Debug/Echo + properties: + output: + hasApple: "[contains(parameters('myArray'), 'apple')]" + hasOrange: "[contains(parameters('myArray'), 'orange')]" + hasNumber42: "[contains(parameters('myArray'), 42)]" + hasNumber99: "[contains(parameters('myArray'), 99)]" +``` + +```bash +dsc config get --file contains.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Check array contents + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + hasApple: true + hasOrange: false + hasNumber42: true + hasNumber99: false +messages: [] +hadErrors: false +``` + +### Example 2 - Check object for keys and values + +The following example shows how to check if an object contains specific keys +or values. + +```yaml +# contains.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + myObject: + type: object + defaultValue: + name: John + age: 30 + city: Seattle +resources: +- name: Check object contents + type: Microsoft.DSC.Debug/Echo + properties: + output: + hasNameKey: "[contains(parameters('myObject'), 'name')]" + hasEmailKey: "[contains(parameters('myObject'), 'email')]" + hasSeattleValue: "[contains(parameters('myObject').city, 'Seattle')]" + hasAge30Value: "[contains(parameters('myObject').age, 30)]" +``` + +```bash +dsc config get --file contains.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Check object contents + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + hasNameKey: true + hasEmailKey: false + hasSeattleValue: true + hasAge30Value: true +messages: [] +hadErrors: false +``` + +### Example 3 - Check string for substrings + +The following example shows how to check if a string contains specific +substrings. + +```yaml +# contains.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + myString: + type: string + defaultValue: "Hello DSC 123" +resources: +- name: Check string contents + type: Microsoft.DSC.Debug/Echo + properties: + output: + hasHello: "[contains(parameters('myString'), 'Hello')]" + hasDSC: "[contains(parameters('myString'), 'DSC')]" + hasNumber: "[contains(parameters('myString'), '123')]" + hasXYZ: "[contains(parameters('myString'), 'XYZ')]" +``` + +```bash +dsc config get --file contains.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Check string contents + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + hasHello: true + hasDSC: true + hasNumber: true + hasXYZ: false +messages: [] +hadErrors: false +``` + +## Parameters + +### collection + +The collection to search in (array, object, or string). + +```yaml +Type: [array, object, string] +Required: true +``` + +### value + +The value to search for. Must be a string or number. + +```yaml +Type: [string, number] +Required: true +``` + +The `contains()` function expects exactly two input values. The first +parameter is the collection to search, and the second is the value to find. +Complex objects and arrays cannot be used as search values. + +## Output + +The `contains()` function returns `true` if the collection contains the +specified value and `false` otherwise. + +```yaml +Type: bool +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/context.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/context.md new file mode 100644 index 00000000..31605c1f --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/context.md @@ -0,0 +1,204 @@ +--- +description: Reference for the 'context' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: context +--- + +# context + +## Synopsis + +Returns contextual information about the system and execution environment. + +## Syntax + +```Syntax +context() +``` + +## Description + +The `context()` function returns an object with information about the operating system and the +security context that DSC is running under. This is useful when you want to configure resources +differently depending on the host platform, OS version, bitness, or whether DSC is running with +elevated privileges. + +The returned object has two top-level properties: + +- **os** - An object describing the operating system. +- **security** - A string indicating the security context. + +You can access individual properties from the returned object using dot-path notation, such as +`context().os.family` or `context().security`. + +### os properties + +| Property | Type | Always present | Description | +|----------------|---------|:--------------:|----------------------------------------------------------------------------| +| `family` | string | Yes | The OS family: `Linux`, `macOS`, or `Windows`. | +| `version` | string | Yes | The OS version string. | +| `edition` | string | No | The Windows edition, e.g. `Windows 11 Enterprise`. Windows only. | +| `codename` | string | No | The Linux distribution codename from `lsb_release`. Linux only. | +| `bitness` | integer | No | The OS bitness: `32` or `64`. May be `null` if the bitness can't be found. | +| `architecture` | string | No | The processor architecture, e.g. `x86_64` or `arm64`. | + +### security values + +| Value | Description | +|--------------|-------------------------------------------------------------------------------| +| `elevated` | DSC is running with elevated (administrator or root) privileges. | +| `restricted` | DSC is running with restricted (standard user) privileges. | +| `current` | The security context is forwarded from the calling process without elevation. | + +When called on the local node, `context().security` is derived from the effective privileges +and will be either `elevated` or `restricted`. The `current` value represents a forwarded, +non-elevated security context. + +## Examples + +### Example 1 - Echo the full context object + +This example shows how to echo the entire `context()` output to inspect all available fields +on the machine where DSC is running. + +```yaml +# context.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Show context + type: Microsoft.DSC.Debug/Echo + properties: + output: "[context()]" +``` + +```bash +dsc config get --file context.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Show context + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + os: + family: Windows + version: 10.0.26100 + edition: Windows 11 Enterprise + bitness: 64 + architecture: x86_64 + security: elevated +messages: [] +hadErrors: false +``` + +### Example 2 - Access individual OS properties + +This example uses dot-path notation to access specific fields from the context object. It +echoes the OS family and architecture separately, which is useful when you need only a subset +of the context data. + +```yaml +# context.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: OS details + type: Microsoft.DSC.Debug/Echo + properties: + output: + family: "[context().os.family]" + version: "[context().os.version]" + architecture: "[context().os.architecture]" + security: "[context().security]" +``` + +```bash +dsc config get --file context.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: OS details + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + family: Linux + version: 22.04 + architecture: x86_64 + security: restricted +messages: [] +hadErrors: false +``` + +### Example 3 - Use context to tailor resource input + +This example passes OS context into a resource property so that the downstream configuration +logic can adapt to the current platform. It combines `context()` with `createObject()` to +build a structured payload, and uses `base64()` to encode it for safe transport. + +```yaml +# context.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Platform-aware payload + type: Microsoft.DSC.Debug/Echo + properties: + output: + platform: "[context().os.family]" + isElevated: "[equals(context().security, 'elevated')]" + encodedContext: "[base64(string(context()))]" +``` + +```bash +dsc config get --file context.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Platform-aware payload + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + platform: macOS + isElevated: false + encodedContext: eyJvcyI6eyJmYW1pbHkiOiJtYWNPUyIsInZlcnNpb24iOiIxNS4zLjEiLCJiaXRuZXNzIjo2NCwiYXJjaGl0ZWN0dXJlIjoiYXJtNjQifSwic2VjdXJpdHkiOiJSZXN0cmljdGVkIn0= +messages: [] +hadErrors: false +``` + +## Parameters + +The `context()` function takes no arguments. + +```yaml +Type: none +Required: false +MinimumCount: 0 +MaximumCount: 0 +``` + +## Output + +Returns an object with two top-level properties: **os** and **security**. Use dot-path notation +to access nested properties, such as `context().os.family`. + +```yaml +Type: object +``` + +## Related functions + +- [`parameters()`][00] - Returns the value of a configuration parameter. +- [`variables()`][01] - Returns the value of a configuration variable. +- [`string()`][02] - Converts a value to its string representation. +- [`base64()`][03] - Returns the base64 representation of a string. + + +[00]: ./parameters.md +[01]: ./variables.md +[02]: ./string.md +[03]: ./base64.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/copy.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/copy.md new file mode 100644 index 00000000..e1f4c3ca --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/copy.md @@ -0,0 +1,294 @@ +--- +description: Reference for the 'copy' DSC configuration document resource loop +ms.date: 09/01/2026 +ms.topic: reference +title: copy +--- + +# copy + +## Synopsis + +Defines a loop to create multiple instances of a resource. + +## Syntax + +```Syntax +copy: + name: + count: +``` + +## Description + +The `copy` property enables you to create multiple instances of a resource in a +DSC configuration. This is the equivalent implementation of the copy +functionality from Azure Resource Manager (ARM) templates. DSC only supports +copy loops on resource instances. Copy loops for variables and resource +properties aren't supported. A configuration output can define `copy`, but DSC +ignores that output and emits a warning that copy loops for outputs aren't +supported. + +> [!IMPORTANT] +> Copy loops are deprecated. When DSC expands a copy loop, it emits a warning +> that the copy loop is deprecated and will be removed in a future release. For +> more information, see [issue #1429][03] in the DSC repository. + +When you use `copy` on a resource, DSC creates multiple instances of that +resource based on the specified count. You can use the [`copyIndex()`][01] +function within the resource definition to access the current iteration index +and create unique names or property values for each instance. + +> [!NOTE] +> The `mode` and `batchSize` properties are not currently supported and will +> result in an error if used. + +## Examples + +### Example 1 - Create multiple Echo resources + +This example demonstrates the basic usage of `copy` to create three instances +of a Debug Echo resource. + +```yaml +# copy.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Echo-{0}', copyIndex())]" + copy: + name: echoLoop + count: 3 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Hello DSC" +``` + +```bash +dsc config get --file copy.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Hello DSC +- name: Echo-1 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Hello DSC +- name: Echo-2 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Hello DSC +messages: [] +hadErrors: false +``` + +### Example 2 - Using copyIndex with offset + +This example demonstrates using [`copyIndex()`][01] with an offset to start +numbering from a different value. + +```yaml +# copy.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Service-{0}', copyIndex(100))]" + copy: + name: serviceLoop + count: 3 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Service instance" +``` + +```bash +dsc config get --file copy.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Service-100 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Service instance +- name: Service-101 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Service instance +- name: Service-102 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Service instance +messages: [] +hadErrors: false +``` + +### Example 3 - Using named loop references + +This example shows how to reference a specific loop by name when using +[`copyIndex()`][01]. + +```yaml +# copy.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Resource-{0}', copyIndex('mainLoop'))]" + copy: + name: mainLoop + count: 2 + type: Microsoft.DSC.Debug/Echo + properties: + output: "From main loop" +``` + +```bash +dsc config get --file copy.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Resource-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: From main loop +- name: Resource-1 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: From main loop +messages: [] +hadErrors: false +``` + +### Example 4 - Using expressions for count with parameters + +This example demonstrates using an expression for the `count` property, which +allows you to dynamically determine the number of resource instances to create +based on a parameter value. This is commonly used to make configurations +flexible and reusable. + +```yaml +# copy.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + instanceCount: + type: int + defaultValue: 2 +resources: +- name: "[format('Dynamic-{0}', copyIndex())]" + copy: + name: dynamicLoop + count: "[parameters('instanceCount')]" + type: Microsoft.DSC.Debug/Echo + properties: + output: "[format('Instance {0} of {1}', copyIndex(), parameters('instanceCount'))]" +``` + +```bash +params='{"parameters": {"instanceCount": 4}}' +dsc config --parameters "$params" get --file copy.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Dynamic-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Instance 0 of 4 +- name: Dynamic-1 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Instance 1 of 4 +- name: Dynamic-2 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Instance 2 of 4 +- name: Dynamic-3 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Instance 3 of 4 +messages: [] +hadErrors: false +``` + +## Properties + +### name + +The name of the copy loop. This name can be used with the [`copyIndex()`][01] +function to reference the current iteration index of this specific loop. + +```yaml +Type: string +Required: true +``` + +### count + +The number of iterations to perform. Must be a non-negative integer. If set to +0, no instances of the resource are created. + +The `count` property accepts both literal integer values and expressions that +evaluate to an integer, such as parameter references using the +[`parameters()`][02] function. This allows you to dynamically control the +number of resource instances based on configuration parameters. + +```yaml +Type: integer +Required: true +Minimum: 0 +``` + +### mode + +> [!WARNING] +> The `mode` property is not currently supported and will result in an error +> if used. + +This property is reserved for future implementation to specify whether resources +should be created serially or in parallel. + +### batchSize + +> [!WARNING] +> The `batchSize` property is not currently supported and will result in an +> error if used. + +This property is reserved for future implementation to specify how many +resources to create in each batch when using parallel mode. + +## Limitations + +The current implementation has the following limitations: + +- **Deprecation**: Copy loops are deprecated. DSC emits a warning when it + expands a copy loop. For more information, see [issue #1429][03]. +- **Resources only**: Copy loops are only supported on resource instances. Copy + loops for variables and resource properties aren't supported. DSC ignores a + `copy` definition on a configuration output and emits a warning. +- **Mode control**: The `mode` property (serial/parallel) is not implemented. +- **Batch processing**: The `batchSize` property is not implemented. +- **Name expressions**: The resource name expression must evaluate to a string. + +## Related functions + +- [`copyIndex()`][01] - Returns the current iteration index of a copy loop. +- [`parameters()`][02] - Returns the value of a configuration parameter. + + +[01]: ./copyIndex.md +[02]: ./parameters.md +[03]: https://github.com/PowerShell/DSC/issues/1429 diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/copyIndex.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/copyIndex.md new file mode 100644 index 00000000..a4f619eb --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/copyIndex.md @@ -0,0 +1,240 @@ +--- +description: Reference for the 'copyIndex' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: copyIndex +--- + +# copyIndex + +## Synopsis + +Returns the current iteration index of a copy loop. + +## Syntax + +```Syntax +copyIndex() +copyIndex() +copyIndex('') +copyIndex('', ) +``` + +## Description + +The `copyIndex()` function returns the current iteration index of a copy loop. +This function can only be used within resources that have a `copy` property +defined. The function is necessary for creating unique names and property +values for each instance created by the copy loop. + +The index starts at 0 for the first iteration and increments by 1 for each +subsequent iteration. You can add an offset to shift the starting number, or +reference a specific loop by name when multiple copy loops are present. + +## Examples + +### Example 1 - Basic copyIndex usage + +This example shows the basic usage of `copyIndex()` to create unique resource +names. + +```yaml +# copyIndex.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Resource-{0}', copyIndex())]" + copy: + name: basicLoop + count: 3 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Hello DSC" +``` + +```bash +dsc config get --file copyIndex.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Resource-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Hello World" +- name: Resource-1 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Hello World" +- name: Resource-2 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Hello World" +messages: [] +hadErrors: false +``` + +### Example 2 - Using copyIndex with offset + +This example demonstrates using an offset to start numbering from a different +value. + +```yaml +# copyIndex.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Server-{0}', copyIndex(10))]" + copy: + name: serverLoop + count: 3 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Server instance starting from 10 till 12" +``` + +```bash +dsc config get --file copyIndex.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Server-10 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Server instance starting from 10 till 12" +- name: Server-11 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Server instance starting from 10 till 12" +- name: Server-12 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Server instance starting from 10 till 12" +messages: [] +hadErrors: false +``` + +### Example 3 - Using copyIndex with loop name + +This example shows how to reference a specific loop by name. + +```yaml +# copyIndex.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Item-{0}', copyIndex('itemLoop'))]" + copy: + name: itemLoop + count: 1 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Item from loop" +``` + +```bash +dsc config get --file copyIndex.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Item-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Item from loop" +messages: [] +hadErrors: false +``` + +### Example 4 - Using copyIndex with loop name and offset + +This example combines both loop name and offset parameters. + +```yaml +# copyIndex.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: "[format('Database-{0}', copyIndex('dbLoop', 100))]" + copy: + name: dbLoop + count: 2 + type: Microsoft.DSC.Debug/Echo + properties: + output: "Database instance" +``` + +```bash +dsc config get --file copyIndex.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Database-100 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Database instance" +- name: Database-101 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "Database instance" +messages: [] +hadErrors: false +``` + +## Parameters + +### offset + +An optional integer offset to add to the current index. The offset must be a +non-negative number. + +```yaml +Type: integer +Required: false +Minimum: 0 +``` + +### loopName + +An optional string specifying the name of the copy loop to reference. This is +useful when you have multiple copy loops and need to reference a specific one. + +```yaml +Type: string +Required: false +``` + +## Output + +The `copyIndex()` function returns an integer representing the current iteration +index, optionally adjusted by the offset. + +```yaml +Type: integer +``` + +## Error Conditions + +The `copyIndex()` function will return an error in the following situations: + +- **Used outside copy loop**: The function can only be used within resources + that have a `copy` property defined. +- **Negative offset**: The offset parameter must be non-negative. +- **Invalid loop name**: If a loop name is specified but no loop with that + name exists. +- **Invalid arguments**: If the arguments provided are not of the expected + types. + +## Related Properties + +- [`copy`][01] - Defines a loop to create multiple instances of a resource. + + +[01]: ./copy.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/createArray.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/createArray.md index 78a7a97c..850cb75c 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/createArray.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/createArray.md @@ -1,6 +1,6 @@ --- description: Reference for the 'createArray' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: createArray --- @@ -29,7 +29,7 @@ function returns an array of arrays. ### Example 1 - Create an array of integers -example synopsis +The following example shows how to create a simple array with integers. ```yaml # createArray.example.1.dsc.config.yaml @@ -42,7 +42,7 @@ resources: ``` ```bash -dsc config get --file createArray.example.1.dsc.config.yaml config get +dsc config get --file createArray.example.1.dsc.config.yaml ``` ```yaml diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/createObject.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/createObject.md new file mode 100644 index 00000000..2a59ed7f --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/createObject.md @@ -0,0 +1,255 @@ +--- +description: Reference for the 'createObject' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: createObject +--- + +# createObject + +## Synopsis + +Creates a JSON object from key-value pairs. + +## Syntax + +```Syntax +createObject(, , , , ...) +``` + +## Description + +The `createObject()` function creates a JSON object from the provided key-value pairs. +Arguments must be provided in pairs where the first argument of each pair is a string key, +and the second argument is the value of any type. + +If no arguments are provided, the function returns an empty object. The number of arguments +must be even, as they represent key-value pairs. + +## Examples + +### Example 1 - Basic object creation + +The following example shows how to create simple objects with string and numeric values. + +```yaml +# createObject.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Basic object creation + type: Microsoft.DSC.Debug/Echo + properties: + output: + simpleObject: "[createObject('name', 'test')]" + multipleProps: "[createObject('key1', 'value1', 'key2', 42)]" + emptyObject: "[createObject()]" +``` + +```bash +dsc config get --file createObject.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Basic object creation + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + simpleObject: + name: test + multipleProps: + key1: value1 + key2: 42 + emptyObject: {} +messages: [] +hadErrors: false +``` + +### Example 2 - Mixed data types + +The following example shows how to create objects with different value types. + +```yaml +# createObject.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Mixed data types + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [createObject('string', 'hello', 'number', 123, 'boolean', true, + 'nullValue', null())] +``` + +```bash +dsc config get --file createObject.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Mixed data types + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + string: hello + number: 123 + boolean: true + nullValue: null +messages: [] +hadErrors: false +``` + +### Example 3 - Nested objects and arrays + +The following example shows how to create objects containing other objects and arrays. + +```yaml +# createObject.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Nested structures + type: Microsoft.DSC.Debug/Echo + properties: + output: + nestedObject: >- + [createObject('config', createObject('timeout', 30, 'enabled', true))] + objectWithArray: "[createObject('items', createArray('foo', 'bar', 'baz'))]" +``` + +```bash +dsc config get --file createObject.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Nested structures + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + nestedObject: + config: + timeout: 30 + enabled: true + objectWithArray: + items: + - foo + - bar + - baz +messages: [] +hadErrors: false +``` + +### Example 4 - Using with other functions + +The following example shows how to use `createObject()` with other DSC functions. + +```yaml +# createObject.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + userName: + type: string + defaultValue: guest +resources: +- name: Function integration + type: Microsoft.DSC.Debug/Echo + properties: + output: + userConfig: >- + [createObject('user', parameters('userName'), 'role', + coalesce(null(), 'default'))] + fallbackObject: >- + [createObject('result', coalesce(null(), createObject('status', 'success')))] +``` + +```bash +dsc config get --file createObject.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Function integration + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + userConfig: + user: guest + role: default + fallbackObject: + result: + status: success +messages: [] +hadErrors: false +``` + +## Parameters + +### Key-value pairs + +The `createObject()` function accepts zero or more key-value pairs. Each key must be a string, +and values can be of any type. + +```yaml +Type: key: [string], value: [any] +Required: false +MinimumCount: 0 +MaximumCount: unlimited (must be even number) +``` + +#### key + +The object property name. Must be a string value. + +```yaml +Type: [string] +Required: true (when providing values) +``` + +#### value + +The object property value. Can be any valid JSON type including strings, numbers, booleans, null, +arrays, or other objects. + +```yaml +Type: [any] +Required: true (when providing keys) +``` + +## Output + +The `createObject()` function returns a JSON object containing the specified key-value pairs. + +```yaml +Type: [object] +``` + +## Error conditions + +The function will return an error in the following cases: + +- **Odd number of arguments**: Arguments must be provided in key-value pairs +- **Non-string keys**: All keys must be string values +- **Invalid argument types**: Arguments must be valid JSON types + +## Notes + +- Keys must be strings. If you specify numeric or other types, DSC raises an error. +- Values can be any valid JSON type including null, arrays, and nested objects. +- Duplicate keys will result in the last value overwriting previous values. +- Empty object creation (`createObject()` with no arguments) is supported. +- The function preserves the order of properties as specified. + +## Related functions + +- [`createArray()`][00] - Creates arrays that can be used as object values +- [`coalesce()`][01] - Provides fallback values for object properties +- [`null()`][02] - Creates explicit null values for object properties + + +[00]: ./createArray.md +[01]: ./coalesce.md +[02]: ./null.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUri.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUri.md new file mode 100644 index 00000000..4038eea6 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUri.md @@ -0,0 +1,191 @@ +--- +description: Reference for the 'dataUri' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: dataUri +--- + +# dataUri + +## Synopsis + +Converts a value to a data URI. + +## Syntax + +```Syntax +dataUri() +``` + +## Description + +The `dataUri()` function converts a string value to a [data URI][01] format. The function encodes +the input string as base64 and returns it as a data URI with the `application/json` media type and +`utf8` charset. + +Data URIs are useful for embedding small text content directly in configuration documents, +especially when the content needs to be passed through systems that expect URI-formatted data. + +## Examples + +### Example 1 - Encode a script for transport + +Encoding a PowerShell script as a data URI ensures safe transport through systems that may have +issues with special characters or line breaks. + +```yaml +# dataUri.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + scriptContent: + type: string + defaultValue: "Write-Host 'Hello, World!'" +resources: + - name: Encode script as data URI + type: Microsoft.DSC.Debug/Echo + properties: + output: + originalScript: "[parameters('scriptContent')]" + encodedScript: "[dataUri(parameters('scriptContent'))]" +``` + +```bash +dsc config get --file dataUri.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Encode script as data URI + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + originalScript: Write-Host 'Hello, World!' + encodedScript: data:application/json;base64,V3JpdGUtSG9zdCAnSGVsbG8sIFdvcmxkISc= +messages: [] +hadErrors: false +``` + +### Example 2 - Encode JSON configuration for embedding + +The configuration encodes a JSON configuration string as a data URI, which is useful when passing +structured data through systems that expect URI-formatted content. + +```yaml +# dataUri.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Encode JSON config as data URI + type: Microsoft.DSC.Debug/Echo + properties: + output: "[dataUri('{\"setting\":\"value\",\"enabled\":true}')]" +``` + +```bash +dsc config get --file dataUri.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Encode JSON config as data URI + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: data:application/json;base64,eyJzZXR0aW5nIjoidmFsdWUiLCJlbmFibGVkIjp0cnVlfQ== +messages: [] +hadErrors: false +``` + +### Example 3 - Compare base64 and dataUri encoding + +Unlike the [`base64()`][02] function which returns only the encoded content, `dataUri()` adds +the data URI prefix with media type information. Use `dataUri()` when the target system expects +the full data URI format. + +```yaml +# dataUri.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Compare encoding methods + type: Microsoft.DSC.Debug/Echo + properties: + output: + base64Only: "[base64('Hello')]" + fullDataUri: "[dataUri('Hello')]" +``` + +```bash +dsc config get --file dataUri.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Compare encoding methods + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + base64Only: SGVsbG8= + fullDataUri: data:application/json;base64,SGVsbG8= +messages: [] +hadErrors: false +``` + +### Example 4 - Encode multiline content + +Multiline content like configuration files or scripts can be encoded as a data URI to preserve +line breaks during transport. + +```yaml +# dataUri.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Encode multiline content + type: Microsoft.DSC.Debug/Echo + properties: + output: "[dataUri('line1\nline2\nline3')]" +``` + +```bash +dsc config get --file dataUri.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Encode multiline content + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: data:application/json;base64,bGluZTEKbGluZTIKbGluZTM= +messages: [] +hadErrors: false +``` + +## Parameters + +### stringToConvert + +The `dataUri()` function expects a single string as input. The function converts the value into a +data URI representation. If the value isn't a string, DSC raises an error when validating the +configuration document. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `dataUri()` function returns a data URI string in the format +`data:application/json;charset=utf8;base64,` where `` is the +base64 representation of the **stringToConvert** value. + +```yaml +Type: string +``` + + +[01]: https://en.wikipedia.org/wiki/Data_URI_scheme +[02]: base64.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUriToString.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUriToString.md new file mode 100644 index 00000000..0b87ec8f --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUriToString.md @@ -0,0 +1,224 @@ +--- +description: Reference for the 'dataUriToString' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: dataUriToString +--- + +# dataUriToString + +## Synopsis + +Converts a data URI formatted value to a string. + +## Syntax + +```Syntax +dataUriToString() +``` + +## Description + +The `dataUriToString()` function converts a [data URI][01] formatted value back to its original +string representation. This function is the inverse of the [`dataUri()`][02] function and is useful +for decoding data that was previously encoded as a data URI. + +The function supports only base64-encoded data URIs (those containing `;base64` in the metadata). +Non-base64 or URL-encoded data URIs aren't supported and result in an error. + +## Examples + +### Example 1 - Decode embedded script content + +Decoding a PowerShell script from a data URI is useful when receiving commands from external +systems that transmit data in this format. + +```yaml +# dataUriToString.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + encodedScript: + type: string + defaultValue: "data:text/plain;charset=utf8;base64,\ + V3JpdGUtSG9zdCAnSGVsbG8sIFdvcmxkISc=" +resources: + - name: Decode and display script + type: Microsoft.DSC.Debug/Echo + properties: + output: "[dataUriToString(parameters('encodedScript'))]" +``` + +```bash +dsc config get --file dataUriToString.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Decode and display script + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Write-Host 'Hello, World!' +messages: [] +hadErrors: false +``` + +### Example 2 - Extract JSON configuration from data URI + +The configuration decodes a JSON configuration that was transmitted as a data URI, then parses it +using the [`json()`][06] function to access its properties. + +```yaml +# dataUriToString.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + configDataUri: + type: string + defaultValue: "data:;base64,eyJzZXR0aW5nIjoidmFsdWUiLCJlbmFibGVkIjp0cnVlfQ==" +resources: + - name: Decode and parse JSON config + type: Microsoft.DSC.Debug/Echo + properties: + output: + rawJson: "[dataUriToString(parameters('configDataUri'))]" + parsedSetting: "[json(dataUriToString(parameters('configDataUri'))).setting]" +``` + +```bash +dsc config get --file dataUriToString.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Decode and parse JSON config + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + rawJson: '{"setting":"value","enabled":true}' + parsedSetting: value +messages: [] +hadErrors: false +``` + +### Example 3 - Process data from Azure ARM template output + +Azure ARM templates and similar systems often use data URIs for content encoding. Use +`dataUriToString()` to decode this content back to its original form. + +```yaml +# dataUriToString.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + armTemplateOutput: + type: string + defaultValue: "data:text/plain;charset=utf8;base64,SGVsbG8sIFdvcmxkIQ==" +resources: + - name: Process ARM template data URI output + type: Microsoft.DSC.Debug/Echo + properties: + output: "[dataUriToString(parameters('armTemplateOutput'))]" +``` + +```bash +dsc config get --file dataUriToString.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Process ARM template data URI output + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Hello, World! +messages: [] +hadErrors: false +``` + +### Example 4 - Round-trip verification + +Encoding a string to a data URI and decoding it back verifies that data survives the +transformation correctly. Combine `dataUriToString()` with [`dataUri()`][02] to test this. + +```yaml +# dataUriToString.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + originalContent: + type: string + defaultValue: "Configuration with special chars: <>&\"" +resources: + - name: Verify round-trip encoding + type: Microsoft.DSC.Debug/Echo + properties: + output: + original: "[parameters('originalContent')]" + afterRoundTrip: "[dataUriToString(dataUri(parameters('originalContent')))]" +``` + +```bash +dsc config get --file dataUriToString.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Verify round-trip encoding + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + original: 'Configuration with special chars: <>&"' + afterRoundTrip: 'Configuration with special chars: <>&"' +messages: [] +hadErrors: false +``` + +## Parameters + +### dataUriToConvert + +The `dataUriToString()` function expects a single string containing a valid data URI. The data URI +must start with `data:` and contain a comma separating the metadata from the encoded data. The +metadata must include `;base64`, and the data portion is decoded as base64. Data URIs without +`;base64` metadata are not supported and result in an error. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `dataUriToString()` function returns the decoded string representation of the +**dataUriToConvert** parameter. + +```yaml +Type: string +``` + +## Exceptions + +The `dataUriToString()` function raises errors for the following conditions: + +- **Invalid data URI format**: When the input string doesn't start with `data:` or doesn't contain + a comma separator +- **Invalid base64 encoding**: When the data portion contains invalid base64 characters (for + base64-encoded data URIs) +- **Invalid UTF-8**: When the decoded bytes do not form valid UTF-8 text + +## Related functions + +- [`dataUri()`][02] - Converts a value to a data URI +- [`base64()`][03] - Encodes a string to base64 format +- [`base64ToString()`][04] - Decodes a base64 string +- [`parameters()`][05] - Retrieves parameter values + + +[01]: https://en.wikipedia.org/wiki/Data_URI_scheme +[02]: ./dataUri.md +[03]: ./base64.md +[04]: ./base64ToString.md +[05]: ./parameters.md +[06]: ./json.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/div.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/div.md index 1eb96815..ca3ce9ea 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/div.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/div.md @@ -1,6 +1,6 @@ --- description: Reference for the 'div' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: div --- @@ -90,9 +90,9 @@ hadErrors: false ### operands -The `div()` function expects exactly two integers as input. The **operands** can be either an integer -or the output of any configuration function that returns an integer. The function divides the -first operand by the second operand. Separate the **operands** with a comma (`,`). +The `div()` function expects exactly two integers as input. The **operands** can be either an +integer or the output of any configuration function that returns an integer. The function divides +the first operand by the second operand. Separate the **operands** with a comma (`,`). ```yaml Type: integer diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/empty.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/empty.md new file mode 100644 index 00000000..6b8199bd --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/empty.md @@ -0,0 +1,217 @@ +--- +description: Reference for the 'empty' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: empty +--- + +# empty + +## Synopsis + +Checks whether a value is empty. + +## Syntax + +```Syntax +empty() +``` + +## Description + +The `empty()` function checks whether a value is empty, returning `true` if +it is and `false` otherwise. For arrays and objects, it returns `true` if +they contain no elements or properties. For strings, it returns `true` if +the string is empty (zero length). + +## Examples + +### Example 1 - Check empty arrays + +The following example shows how to check if arrays are empty. + +```yaml +# empty.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + populatedArray: + type: array + defaultValue: + - item1 + - item2 + - item3 + emptyArray: + type: array + defaultValue: [] +resources: +- name: Check array emptiness + type: Microsoft.DSC.Debug/Echo + properties: + output: + populatedEmpty: "[empty(parameters('populatedArray'))]" + emptyArrayEmpty: "[empty(parameters('emptyArray'))]" +``` + +```bash +dsc config get --file empty.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Check array emptiness + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + populatedEmpty: false + emptyArrayEmpty: true +messages: [] +hadErrors: false +``` + +### Example 2 - Check empty objects + +The following example shows how to check if objects are empty. + +```yaml +# empty.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + populatedObject: + type: object + defaultValue: + name: John + age: 30 + emptyObject: + type: object + defaultValue: {} +resources: +- name: Check object emptiness + type: Microsoft.DSC.Debug/Echo + properties: + output: + populatedEmpty: "[empty(parameters('populatedObject'))]" + emptyObjectEmpty: "[empty(parameters('emptyObject'))]" +``` + +```bash +dsc config get --file empty.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Check object emptiness + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + populatedEmpty: false + emptyObjectEmpty: true +messages: [] +hadErrors: false +``` + +### Example 3 - Check empty strings + +The following example shows how to check if strings are empty. + +```yaml +# empty.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + populatedString: + type: string + defaultValue: "Hello World" + emptyString: + type: string + defaultValue: "" +resources: +- name: Check string emptiness + type: Microsoft.DSC.Debug/Echo + properties: + output: + populatedEmpty: "[empty(parameters('populatedString'))]" + emptyStringEmpty: "[empty(parameters('emptyString'))]" + literalEmpty: "[empty('')]" +``` + +```bash +dsc config get --file empty.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Check string emptiness + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + populatedEmpty: false + emptyStringEmpty: true + literalEmpty: true +messages: [] +hadErrors: false +``` + +### Example 4 - Conditional resource deployment + +The following example shows a practical use case for checking if a +configuration array is empty before deploying resources. + +```yaml +# empty.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + serverList: + type: array + defaultValue: [] +resources: +- name: Check if servers configured + type: Microsoft.DSC.Debug/Echo + properties: + output: + message: >- + [if(empty(parameters('serverList')), 'No servers to configure', + concat('Configuring ', string(length(parameters('serverList'))), ' servers'))] +``` + +```bash +dsc config get --file empty.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Check if servers configured + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + message: No servers to configure +messages: [] +hadErrors: false +``` + +## Parameters + +### value + +The value to check for emptiness. + +```yaml +Type: [array, object, string] +Required: true +``` + +The `empty()` function expects exactly one input value of type array, object, +or string. + +## Output + +The `empty()` function returns `true` if the value is empty and `false` +otherwise. + +```yaml +Type: bool +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/endsWith.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/endsWith.md new file mode 100644 index 00000000..bcccca96 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/endsWith.md @@ -0,0 +1,183 @@ +--- +description: Reference for the 'endsWith' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: endsWith +--- + +# endsWith + +## Synopsis + +Determines whether a string ends with the specified suffix. + +## Syntax + +```Syntax +endsWith(, ) +``` + +## Description + +The `endsWith()` function returns `true` if the first string ends with the +specified suffix. Comparison is case-sensitive. Use it for conditional logic in +configuration documents such as matching file extensions, environment name +suffixes, or resource identifiers. + +## Examples + +### Example 1 - Check a file extension + +The following example checks if a specified filename ends with `.log`. + +```yaml +# endswith.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + fileName: + type: string + defaultValue: application.log +resources: +- name: Check file extension + type: Microsoft.DSC.Debug/Echo + properties: + output: + isLog: "[endsWith(parameters('fileName'), '.log')]" +``` + +```bash +dsc config get --file endswith.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Check file extension + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + isLog: true +messages: [] +hadErrors: false +``` + +### Example 2 - Conditional environment handling + +The following example uses `endsWith()` to build a message when an environment +name ends with `-prod`. + +```yaml +# endswith.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + environment: + type: string + defaultValue: web-prod +resources: +- name: Environment classification + type: Microsoft.DSC.Debug/Echo + properties: + output: + classification: >- + [if(endsWith(parameters('environment'), '-prod'), 'Production', + 'Non-production')] +``` + +```bash +dsc config get --file endswith.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Environment classification + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + classification: Production +messages: [] +hadErrors: false +``` + +### Example 3 - Filter resource identifiers + +The following example shows checking multiple suffixes by combining conditions. + +```yaml +# endswith.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + resourceId: + type: string + defaultValue: storage-westus-01 +resources: +- name: Identify resource segment + type: Microsoft.DSC.Debug/Echo + properties: + output: + isRegional: "[endsWith(parameters('resourceId'), '-01')]" + endsWithWest: "[endsWith(parameters('resourceId'), 'westus-01')]" + endsWithEast: "[endsWith(parameters('resourceId'), 'eastus-01')]" +``` + +```bash +dsc config get --file endswith.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Identify resource segment + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + isRegional: true + endsWithWest: true + endsWithEast: false +messages: [] +hadErrors: false +``` + +## Parameters + +### string + +The input string to evaluate. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### suffix + +The suffix string to test for. + +```yaml +Type: string +Required: true +Position: 2 +``` + +## Output + +The `endsWith()` function returns a boolean value indicating whether the input +string ends with the specified suffix. + +```yaml +Type: bool +``` + +## Related functions + +- [`startsWith()`][00] - Determines whether a string starts with a prefix +- [`concat()`][01] - Concatenates strings together +- [`if()`][02] - Returns values based on a condition +- [`string()`][03] - Converts values to strings + + +[00]: ./startsWith.md +[01]: ./concat.md +[02]: ./if.md +[03]: ./string.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md index 9e610f98..4b96b977 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md @@ -1,6 +1,6 @@ --- description: Reference for the 'envvar' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: envvar --- @@ -82,4 +82,4 @@ The `envvar()` function returns the value of the environment variable specified Type: string ``` -[01]: ../../../cli/config/command.md#environment-variables +[01]: ../../../cli/config/index.md#environment-variables diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/equals.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/equals.md index 7dad419b..1b27a06e 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/equals.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/equals.md @@ -1,6 +1,6 @@ --- description: Reference for the 'equals' DSC configuration document function -ms.date: 07/02/2025 +ms.date: 09/01/2026 ms.topic: reference title: equals --- @@ -14,7 +14,7 @@ Checks whether two values are identical. ## Syntax ```Syntax -equals() +equals(, ) ``` ## Description @@ -36,7 +36,7 @@ resources: - name: Compare strings type: Microsoft.DSC.Debug/Echo properties: - output: + output: sameCase: "[equals('a', 'a')]" differentCase: "[equals('a', 'A')]" differentLetters: "[equals('a', 'b')]" @@ -89,9 +89,6 @@ results: output: sameInteger: true differentInteger: false - sameFloat: true - differentFloat: false - integerAndFloat: ? messages: [] hadErrors: false ``` @@ -159,14 +156,17 @@ hadErrors: false ### inputValue -The `equals()` function expects exactly two input values of the same type. Separate each value with -a comma. If the type of the second input value is different from the first value, DSC returns an -error for the function. +The `equals()` function expects exactly two input values. Separate each value with a comma. If +the type of the second input value is different from the first value, DSC returns `false` for +the function. String comparisons are case-sensitive. Array comparisons are position-sensitive. +The function doesn't accept boolean values. DSC raises an error when either input value is a +boolean. + ```yaml -Type: [integer, string, object, array] +Type: [null, integer, string, object, array] Required: true MinimumCount: 2 MaximumCount: 2 diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/false.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/false.md new file mode 100644 index 00000000..61296b18 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/false.md @@ -0,0 +1,76 @@ +--- +description: Reference for the 'false' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: false +--- + +# false + +## Synopsis + +Returns the boolean value false. + +## Syntax + +```Syntax +false() +``` + +## Description + +The `false()` function returns the boolean value `false`. This function takes no arguments and +always returns `false`. It's useful for providing explicit boolean values in configurations +or for logical operations. + +## Examples + +### Example 1 - Basic false value + +This configuration demonstrates basic usage of the `false()` function. + +```yaml +# false.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo false value + type: Microsoft.DSC.Debug/Echo + properties: + output: "[false()]" +``` + +```bash +dsc config get --file false.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo false value + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: false +messages: [] +hadErrors: false +``` + +## Parameters + +The `false()` function takes no arguments. + +```yaml +Type: none +Required: false +MinimumCount: 0 +MaximumCount: 0 +``` + +## Output + +The `false()` function always returns the boolean value `false`. + +```yaml +Type: boolean +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/filter.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/filter.md new file mode 100644 index 00000000..7329fe01 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/filter.md @@ -0,0 +1,303 @@ +--- +description: Reference for the 'filter' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: filter +--- + +# filter + +## Synopsis + +Returns a new array that contains only the elements of an input array for which a lambda function +returns `true`. + +## Syntax + +```Syntax +filter(, ) +``` + +## Description + +The `filter()` function evaluates a lambda function created with [`lambda()`][00] against every +element of an array and returns a new array that contains only the elements for which the lambda +returned `true`. The function doesn't change the elements it keeps. It copies them to the output +array in their original order. + +For each element in the input array, DSC: + +1. Binds the element to the lambda's first parameter. +1. Binds the zero-based index of the element to the lambda's second parameter, if the lambda + declares one. +1. Evaluates the lambda's body expression. Inside the body, use [`lambdaVariables()`][01] to read + the bound parameters. +1. Includes the element in the output when the body returns `true` and skips it when the body + returns `false`. + +The lambda body must return a boolean value. If it returns a value of any other type, DSC raises +an error and stops processing the configuration document. + +The lambda body can call any other configuration function. DSC evaluates the body with a copy of +the current context, so the body can read configuration [`parameters()`][02] and +[`variables()`][03] in addition to the lambda's own parameters. + +This function is useful for: + +- Selecting the subset of an array that meets a condition before passing it to a resource. +- Filtering an array of objects by the value of one of their properties. +- Keeping only specific positions of an array by testing the index parameter. + +## Examples + +### Example 1 - Filter numbers by value + +The following example keeps only the numbers greater than `2`. The lambda declares a single +parameter, `x`, which DSC binds to each element in turn. The [`greater()`][04] function returns +the boolean value that `filter()` requires. + +```yaml +# filter.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + numbers: + type: array + defaultValue: [1, 2, 3, 4, 5] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [filter( + parameters('numbers'), + lambda('x', greater(lambdaVariables('x'), 2)) + )] +``` + +```bash +dsc config get --file filter.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 3 + - 4 + - 5 +messages: [] +hadErrors: false +``` + +### Example 2 - Filter elements by index + +The following example uses a lambda with two parameters. DSC binds the element to `val` and the +zero-based index of the element to `i`. The lambda uses [`less()`][05] on the index to keep only +the first two elements. + +```yaml +# filter.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + items: + type: array + defaultValue: [10, 20, 30, 40] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [filter( + parameters('items'), + lambda('val', 'i', less(lambdaVariables('i'), 2)) + )] +``` + +```bash +dsc config get --file filter.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 10 + - 20 +messages: [] +hadErrors: false +``` + +### Example 3 - Filter objects by a property + +The following example filters an array of objects. The lambda body accesses the `enabled` +property of each element with the property access syntax. Because the property is already a +boolean value, the lambda returns it directly. + +```yaml +# filter.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + services: + type: array + defaultValue: + - name: web + enabled: true + - name: database + enabled: false + - name: cache + enabled: true +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [filter( + parameters('services'), + lambda('service', lambdaVariables('service').enabled) + )] +``` + +```bash +dsc config get --file filter.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - name: web + enabled: true + - name: cache + enabled: true +messages: [] +hadErrors: false +``` + +The output contains the complete objects that matched, not just the property that was tested. + +### Example 4 - Filter strings by prefix + +The following example uses [`startsWith()`][06] in the lambda body to keep only the strings that +start with `prod-`. + +```yaml +# filter.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [filter( + createArray('prod-web', 'dev-web', 'prod-db', 'test-db'), + lambda('name', startsWith(lambdaVariables('name'), 'prod-')) + )] +``` + +```bash +dsc config get --file filter.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - prod-web + - prod-db +messages: [] +hadErrors: false +``` + +## Parameters + +### inputArray + +The array whose elements to test. The elements can be of any type, including objects and nested +arrays. + +```yaml +Type: array +Required: true +Position: 1 +``` + +### lambda + +A lambda function created with [`lambda()`][00]. The lambda must declare one or two parameters. +DSC binds the current element to the first parameter and the zero-based index of the element to +the optional second parameter. The lambda's body must return a boolean value. + +```yaml +Type: lambda +Required: true +Position: 2 +``` + +## Output + +Returns an array containing the elements of `inputArray` for which the lambda returned `true`, in +their original order. Returns an empty array when no elements match or when `inputArray` is empty. + +```yaml +Type: array +``` + +## Error conditions + +The function raises an error in the following cases: + +- **Not an array**: The first argument isn't an array. For example, passing a string raises + `Function 'filter' does not accept string arguments, accepted types are: Array`. +- **Not a lambda**: The second argument isn't a lambda created with [`lambda()`][00]. +- **Too many parameters**: The lambda declares more than two parameters. DSC raises + `Function 'filter' requires lambda with 1 or 2 parameters (element and optional index)`. +- **Non-boolean result**: The lambda body returns a value that isn't a boolean. DSC raises + `filter() lambda must return a boolean value`. +- **Body error**: The lambda body raises an error. For example, calling + [`lambdaVariables()`][01] with a name that the lambda didn't declare raises + `Lambda parameter '' not found in current context`. + +## Notes + +- The function doesn't transform the elements it keeps. To change the elements of an array, use + [`map()`][07] instead. +- The function evaluates the lambda body once for each element in the input array. When the input + array is empty, the body is never evaluated and the function returns an empty array. +- The index that DSC binds to the optional second parameter is a zero-based number. +- Lambda parameters are separate from configuration variables. Read them with + [`lambdaVariables()`][01], not [`variables()`][03]. + +## Related functions + +- [`lambda()`][00] - Creates the lambda function that `filter()` evaluates +- [`lambdaVariables()`][01] - Reads a lambda parameter inside the lambda body +- [`map()`][07] - Transforms every element of an array with a lambda +- [`parameters()`][02] - Returns the value of a configuration parameter +- [`variables()`][03] - Returns the value of a configuration variable +- [`greater()`][04] - Checks whether the first value is greater than the second value +- [`less()`][05] - Checks whether the first value is less than the second value +- [`startsWith()`][06] - Checks whether a string starts with a prefix +- [`createArray()`][08] - Creates an array from values + + +[00]: ./lambda.md +[01]: ./lambdaVariables.md +[02]: ./parameters.md +[03]: ./variables.md +[04]: ./greater.md +[05]: ./less.md +[06]: ./startsWith.md +[07]: ./map.md +[08]: ./createArray.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/first.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/first.md new file mode 100644 index 00000000..9fff430a --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/first.md @@ -0,0 +1,175 @@ +--- +description: Reference for the 'first' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: first +--- + +# first + +## Synopsis + +Returns the first element of an array or the first character of a string. + +## Syntax + +```Syntax +first() +``` + +## Description + +The `first()` function extracts the first element from an array or the first +character from a string. When used with arrays, it returns the actual first +element preserving its original data type (string, number, array, or object). +When used with strings, it returns a new single-character string containing +the first Unicode character. + +This function is particularly useful for accessing the primary or default item +from a collection, or extracting prefixes from identifiers and codes. The +function will return an error if the input array or string is empty. + +## Examples + +### Example 1 - Get the first server hostname + +This example shows how to extract the primary server from a list of servers, +which could be useful for identifying the lead server in a cluster or getting +the default target for deployment operations. + +```yaml +# first.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + servers: + type: array + defaultValue: + - web01 + - web02 +resources: +- name: First Server + type: Microsoft.DSC.Debug/Echo + properties: + output: + firstServer: "[first(parameters('servers'))]" +``` + +```bash +dsc config get --file first.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: First Server + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + firstServer: web01 +messages: [] +hadErrors: false +``` + +### Example 2 - Extract leading character for a prefix + +This example demonstrates extracting the first character from an environment +code to create abbreviated prefixes for resource naming or tagging schemes. + +```yaml +# first.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + environmentCode: + type: string + defaultValue: Prod +resources: +- name: Prefix Builder + type: Microsoft.DSC.Debug/Echo + properties: + output: + prefix: "[first(parameters('environmentCode'))]" +``` + +```bash +dsc config get --file first.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Prefix Builder + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + prefix: P +messages: [] +hadErrors: false +``` + +### Example 3 - Chain with array construction + +This example shows how `first()` can be combined with `array()` to get the +first element from a dynamically constructed array, by wrapping a single +generated collection. + +```yaml +# first.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Chained Example + type: Microsoft.DSC.Debug/Echo + properties: + output: + firstMixed: "[first(array(createArray('a','b')))]" +``` + +```bash +dsc config get --file first.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Chained Example + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + firstMixed: a +messages: [] +hadErrors: false +``` + +## Parameters + +### input + +The array or string to extract the first element or character from. + +```yaml +Type: array or string +Required: true +``` + +If the input is an array, the first element is returned with its original data +type preserved. If the input is a string, the first Unicode character is +returned as a new string. Empty arrays and empty strings will result in an +error. + +## Output + +Returns the first element or character. + +```yaml +Type: string | number | array | object +``` + +## Related functions + +- [`array()`][00] - Creates an array from heterogeneous elements +- [`createArray()`][01] - Creates a homogeneous array +- [`indexOf()`][02] - Finds the index of an item in an array + + +[00]: ./array.md +[01]: ./createArray.md +[02]: ./indexOf.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/format.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/format.md index 3b98bc92..c259a32f 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/format.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/format.md @@ -1,6 +1,6 @@ --- description: Reference for the 'format' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: format --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/greater.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/greater.md new file mode 100644 index 00000000..e84a2a9c --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/greater.md @@ -0,0 +1,157 @@ +--- +description: Reference for the 'greater' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: greater +--- + +# greater + +## Synopsis + +Checks whether the first value is greater than the second value. + +## Syntax + +```Syntax +greater(, ) +``` + +## Description + +The `greater()` function checks whether the first value is greater than the second value, +returning `true` if it is and otherwise `false`. You can use this function to compare two +values of the same data type. If the values are different types, like a string and an +integer, DSC returns an error for this function. + +For strings, the comparison is case-sensitive and uses lexicographic ordering based on character +codes. + +## Examples + +### Example 1 - Compare two numbers + +The following example shows how you can use the function to compare two numbers. + +```yaml +# greater.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Compare numbers + type: Microsoft.DSC.Debug/Echo + properties: + output: + firstGreater: "[greater(5, 3)]" + secondGreater: "[greater(3, 5)]" + equalNumbers: "[greater(5, 5)]" +``` + +```bash +dsc config get --file greater.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Compare numbers + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + firstGreater: true + secondGreater: false + equalNumbers: false +messages: [] +hadErrors: false +``` + +### Example 2 - Compare two strings + +The following example shows how you can use the function to compare two strings. + +```yaml +# greater.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Compare strings + type: Microsoft.DSC.Debug/Echo + properties: + output: + lexicographicGreater: "[greater('b', 'a')]" + lexicographicLess: "[greater('a', 'b')]" + caseSensitive: "[greater('a', 'A')]" +``` + +```bash +dsc config get --file greater.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Compare strings + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + lexicographicGreater: true + lexicographicLess: false + caseSensitive: true +messages: [] +hadErrors: false +``` + +### Example 3 - Type mismatch error + +The following example shows what happens when you try to compare different types. + +```yaml +# greater.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Type mismatch + type: Microsoft.DSC.Debug/Echo + properties: + output: "[greater('5', 3)]" +``` + +```bash +dsc config get --file greater.example.3.dsc.config.yaml +``` + +This will result in an error because you cannot compare a string with a number. + +## Parameters + +### firstValue + +The first value to compare. Must be the same type as the second value. + +```yaml +Type: [number, string] +Required: true +``` + +### secondValue + +The second value to compare. Must be the same type as the first value. + +```yaml +Type: [number, string] +Required: true +``` + +The `greater()` function expects exactly two input values of the same type. +Separate each value with a comma. If the type of the second input value is +different from the first value, DSC returns an error for the function. + +String comparisons are case-sensitive and use lexicographic ordering. + +## Output + +The `greater()` function returns `true` if the first value is greater than +the second value and otherwise `false`. + +```yaml +Type: bool +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/greaterOrEquals.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/greaterOrEquals.md new file mode 100644 index 00000000..5072e025 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/greaterOrEquals.md @@ -0,0 +1,159 @@ +--- +description: Reference for the 'greaterOrEquals' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: greaterOrEquals +--- + +# greaterOrEquals + +## Synopsis + +Checks whether the first value is greater than or equal to the second value. + +## Syntax + +```Syntax +greaterOrEquals(, ) +``` + +## Description + +The `greaterOrEquals()` function checks whether the first value is greater +than or equal to the second value, returning `true` if it is and otherwise `false`. +You can use this function to compare two values of the same data type. If the values +are different types, like a string and an integer, DSC returns an error for this function. + +For strings, the comparison is case-sensitive and uses lexicographic ordering based on character +codes. + +## Examples + +### Example 1 - Compare two numbers + +The following example shows how you can use the function to compare two numbers. + +```yaml +# greaterOrEquals.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Compare numbers + type: Microsoft.DSC.Debug/Echo + properties: + output: + firstGreater: "[greaterOrEquals(5, 3)]" + secondGreater: "[greaterOrEquals(3, 5)]" + equalNumbers: "[greaterOrEquals(5, 5)]" +``` + +```bash +dsc config get --file greaterOrEquals.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Compare numbers + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + firstGreater: true + secondGreater: false + equalNumbers: true +messages: [] +hadErrors: false +``` + +### Example 2 - Compare two strings + +The following example shows how you can use the function to compare two strings. + +```yaml +# greaterOrEquals.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Compare strings + type: Microsoft.DSC.Debug/Echo + properties: + output: + lexicographicGreater: "[greaterOrEquals('b', 'a')]" + lexicographicLess: "[greaterOrEquals('a', 'b')]" + equalStrings: "[greaterOrEquals('a', 'a')]" + caseSensitive: "[greaterOrEquals('Aa', 'aa')]" +``` + +```bash +dsc config get --file greaterOrEquals.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Compare strings + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + lexicographicGreater: true + lexicographicLess: false + equalStrings: true + caseSensitive: false +messages: [] +hadErrors: false +``` + +### Example 3 - Type mismatch error + +The following example shows what happens when you try to compare different types. + +```yaml +# greaterOrEquals.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Type mismatch + type: Microsoft.DSC.Debug/Echo + properties: + output: "[greaterOrEquals('5', 3)]" +``` + +```bash +dsc config get --file greaterOrEquals.example.3.dsc.config.yaml +``` + +This will result in an error because you cannot compare a string with a number. + +## Parameters + +### firstValue + +The first value to compare. Must be the same type as the second value. + +```yaml +Type: [number, string] +Required: true +``` + +### secondValue + +The second value to compare. Must be the same type as the first value. + +```yaml +Type: [number, string] +Required: true +``` + +The `greaterOrEquals()` function expects exactly two input values of the same type. +Separate each value with a comma. If the type of the second input value is different +from the first value, DSC returns an error for the function. + +String comparisons are case-sensitive and use lexicographic ordering. + +## Output + +The `greaterOrEquals()` function returns `true` if the first value is greater than +or equal to the second value and otherwise `false`. + +```yaml +Type: bool +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/if.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/if.md index faf1dd7c..71f13e34 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/if.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/if.md @@ -1,6 +1,6 @@ --- description: Reference for the 'if' DSC configuration document function -ms.date: 07/02/2025 +ms.date: 09/01/2026 ms.topic: reference title: if --- @@ -22,6 +22,10 @@ if(, , ) The `if()` function returns a value based on whether a condition is true or false. You can use this function to conditionally use different values in a configuration document. +The values to return must be strings, integers, objects, or arrays. The function doesn't accept +boolean or null values for `trueValue` or `falseValue`. For more information, see +[Error conditions](#error-conditions). + ## Examples ### Example 1 - Returning values @@ -76,10 +80,11 @@ MaximumCount: 1 The `if()` function expects the second parameter to be the value to return when the `condition` parameter evaluates to `true`. This parameter may be a literal value or an expression that -evaluates to a string, integer, boolean, object, or array value. +evaluates to a string, integer, object, or array value. Boolean and null values aren't +accepted for this parameter. ```yaml -Type: [string, int, bool, object, array] +Type: [string, int, object, array] Required: true MinimumCount: 1 MaximumCount: 1 @@ -89,10 +94,11 @@ MaximumCount: 1 The `if()` function expects the third parameter to be the value to return when the `condition` parameter evaluates to `false`. This parameter may be a literal value or an expression that -evaluates to a string, integer, boolean, object, or array value. +evaluates to a string, integer, object, or array value. Boolean and null values aren't +accepted for this parameter. ```yaml -Type: [string, int, bool, object, array] +Type: [string, int, object, array] Required: true MinimumCount: 1 MaximumCount: 1 @@ -104,7 +110,17 @@ The function returns either the `trueValue` or `falseValue` depending on whether parameter evaluates to `true` or `false`. ```yaml -Type: [string, int, bool, object, array] +Type: [string, int, object, array] ``` +## Error conditions + +DSC raises an error when the `trueValue` or `falseValue` parameter is a boolean or null value. +For example, the expression `[if(true(), true(), false())]` fails with the error +`Function 'if' does not accept boolean arguments, accepted types are: String, Number, Array, +Object`. + +To return a boolean value based on a condition, use the condition expression directly instead of +wrapping it in `if()`. + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/indexOf.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/indexOf.md new file mode 100644 index 00000000..95fbf5f9 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/indexOf.md @@ -0,0 +1,193 @@ +--- +description: Reference for the 'indexOf' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: indexOf +--- + +# indexOf + +## Synopsis + +Returns the zero-based index of the first occurrence of an item in an array, or -1 if not found. + +## Syntax + +```Syntax +indexOf(, ) +``` + +## Description + +The `indexOf()` function searches an array for a specific item and returns the +zero-based index of the first matching element. If the item is not found, the +function returns `-1`. This is useful for determining the position of elements +in arrays or checking if an item exists without throwing errors. + +The function performs strict equality checking: + +- **Strings**: Case-sensitive exact match +- **Numbers**: Numeric equality comparison +- **Arrays**: Deep equality (same length, order, and element values) +- **Objects**: Deep equality (same keys, values, and structure) + +The search always starts from the beginning of the array and returns the index +of the first match found. + +## Examples + +### Example 1 - Locate a specific server in inventory + +This example demonstrates finding the position of a database server within a +server inventory list, which could be useful for ordering deployment operations +or determining server priorities. + +```yaml +# indexOf.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + servers: + type: array + defaultValue: + - web01 + - web02 + - db01 +resources: +- name: Find Server + type: Microsoft.DSC.Debug/Echo + properties: + output: + dbIndex: "[indexOf(parameters('servers'), 'db01')]" +``` + +```bash +dsc config get --file indexOf.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Find Server + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + dbIndex: 2 +messages: [] +hadErrors: false +``` + +### Example 2 - Detect presence of a feature flag object + +This example shows how to search for complex objects within an array, useful +for checking if specific configuration objects or feature flags are present +in a collection. + +```yaml +# indexOf.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + flags: + type: array + defaultValue: [] +resources: +- name: Flag Lookup + type: Microsoft.DSC.Debug/Echo + properties: + output: + hasFeature: >- + [indexOf(array(createObject('name','Beta')), createObject('name','Beta'))] +``` + +```bash +dsc config get --file indexOf.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Flag Lookup + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + hasFeature: 0 +messages: [] +hadErrors: false +``` + +### Example 3 - Case sensitivity demonstration + +This example illustrates the case-sensitive nature of string comparisons, +showing how exact case matching is required for successful string searches. + +```yaml +# indexOf.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Case Demo + type: Microsoft.DSC.Debug/Echo + properties: + output: + appleLower: "[indexOf(createArray('Apple','Banana'), 'apple')]" + appleExact: "[indexOf(createArray('Apple','Banana'), 'Apple')]" +``` + +```bash +dsc config get --file indexOf.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Case Demo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + appleLower: -1 + appleExact: 0 +messages: [] +hadErrors: false +``` + +## Parameters + +### arrayToSearch + +The array to search within. + +```yaml +Type: array +Required: true +``` + +### itemToFind + +The item to search for within the array. + +```yaml +Type: string, number, array, or object +Required: true +``` + +The item must be one of the four supported data types. The function will +perform type-appropriate equality checking to find matching elements. + +## Output + +Returns the zero-based index of the first matching element, or -1 if not found. + +```yaml +Type: number +``` + +## Related functions + +- [`array()`][00] - Builds a heterogeneous array +- [`createArray()`][01] - Builds a homogeneous array +- [`first()`][02] - Gets the first element of an array +- [`contains()`][03] - Checks if an array, object key, or string contains a value + + +[00]: ./array.md +[01]: ./createArray.md +[02]: ./first.md +[03]: ./contains.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/int.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/int.md index 71d4f25c..5695584a 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/int.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/int.md @@ -1,6 +1,6 @@ --- description: Reference for the 'int' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: int --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/intersection.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/intersection.md new file mode 100644 index 00000000..5aeb1dad --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/intersection.md @@ -0,0 +1,253 @@ +--- +description: Reference for the 'intersection' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: intersection +--- + +# intersection + +## Synopsis + +Returns a single array or object with the common elements from the parameters. + +## Syntax + +```Syntax +intersection(value1, value2, ...) +``` + +## Description + +The `intersection()` function takes two or more arrays or objects and returns +only the elements that exist in all of them. For arrays, it returns elements +that appear in every array. For objects, it returns key-value pairs where both +the key and value match across all objects. + +All parameters must be the same type - either all arrays or all objects. +Results are deduplicated, meaning each element appears only once in the output. + +Supported types: + +- Arrays (elements compared by value) +- Objects (key-value pairs compared by deep equality) + +## Examples + +### Example 1 - Find common security groups across environments (arrays) + +Use `intersection()` to identify security groups that are consistently applied +across development, staging, and production environments. This helps ensure +security policies are uniformly enforced. This example uses +[`createArray()`][01] to build the security group lists. + +```yaml +# intersection.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Common Security Groups + type: Microsoft.DSC.Debug/Echo + properties: + output: + commonGroups: >- + [intersection(createArray('admin-access', 'monitoring', 'backup'), + createArray('monitoring', 'backup', 'web-access'), + createArray('backup', 'monitoring', 'database'))] + twoEnvCommon: >- + [intersection(createArray('admin-access', 'monitoring'), + createArray('monitoring', 'audit-log'))] +``` + +```bash +dsc config get --file intersection.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Common Security Groups + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + commonGroups: + - monitoring + - backup + twoEnvCommon: + - monitoring +messages: [] +hadErrors: false +``` + +### Example 2 - Identify shared configuration properties (objects) + +Find configuration settings that are identical across multiple service +instances. This is useful for extracting common configuration into shared +templates or validating consistency. This example uses [`createObject()`][02] +to build configuration objects. + +```yaml +# intersection.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Shared Config Properties + type: Microsoft.DSC.Debug/Echo + properties: + output: + commonSettings: >- + [intersection(createObject('timeout', 30, 'retries', 3, 'region', 'us-east'), + createObject('retries', 3, 'ssl', true, 'region', 'us-east'), + createObject('region', 'us-east', 'retries', 3, 'logging', 'info'))] +``` + +```bash +dsc config get --file intersection.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Shared Config Properties + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + commonSettings: + retries: 3 + region: us-east +messages: [] +hadErrors: false +``` + +### Example 3 - Find overlapping server capabilities (arrays with no matches) + +Sometimes environments have no common elements, which is valuable information +for infrastructure planning. This example shows how `intersection()` handles +arrays with no shared elements. + +```yaml +# intersection.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Server Capabilities + type: Microsoft.DSC.Debug/Echo + properties: + output: + noOverlap: >- + [intersection(createArray('windows-iis', 'dotnet-core'), + createArray('linux-apache', 'php', 'mysql'))] + someOverlap: >- + [intersection(createArray('docker', 'kubernetes', 'monitoring'), + createArray('monitoring', 'logging', 'docker'))] +``` + +```bash +dsc config get --file intersection.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Server Capabilities + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + noOverlap: [] + someOverlap: + - docker + - monitoring +messages: [] +hadErrors: false +``` + +### Example 4 - Validate compliance across teams (objects) + +Use `intersection()` to verify that critical compliance settings are identical +across different team configurations. Only settings with matching values will +appear in the result. + +```yaml +# intersection.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Compliance Check + type: Microsoft.DSC.Debug/Echo + properties: + output: + sharedCompliance: >- + [intersection(createObject('encryption', true, 'backup', 'daily', 'audit', true), + createObject('audit', true, 'encryption', true, 'access', 'restricted'), + createObject('encryption', true, 'audit', true, 'monitoring', 'enabled'))] +``` + +```bash +dsc config get --file intersection.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Compliance Check + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + sharedCompliance: + encryption: true + audit: true +messages: [] +hadErrors: false +``` + +## Parameters + +### value1 + +The first array or object to compare. Required. + +```yaml +Type: array | object +Required: true +Position: 1 +``` + +### value2 + +The second array or object to compare. Must be the same type as value1. +Required. + +```yaml +Type: array | object +Required: true +Position: 2 +``` + +### Additional values + +Additional arrays or objects to include in the intersection. All must be the +same type. Optional. + +```yaml +Type: array | object +Required: false +Position: 3+ +``` + +## Output + +Returns an array or object containing only the common elements. The return type +matches the input type. + +```yaml +Type: array | object +``` + +## Related functions + +- [`union()`][00] - Combines all elements from multiple arrays or objects +- [`contains()`][03] - Checks for presence in arrays/objects/strings +- [`createArray()`][01] - Creates an array from individual values +- [`createObject()`][02] - Creates an object from key-value pairs + + +[00]: ./union.md +[01]: ./createArray.md +[02]: ./createObject.md +[03]: ./contains.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/items.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/items.md new file mode 100644 index 00000000..da3d0b73 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/items.md @@ -0,0 +1,205 @@ +--- +description: Reference for the 'items' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: items +--- + +# items + +## Synopsis + +Converts a dictionary object to an array of key-value pairs. + +## Syntax + +```Syntax +items(inputObject) +``` + +## Description + +The `items()` function converts a dictionary object to an array of key-value pairs. + +- Each element in the returned array is an object with two properties: `key` (the + property name) and `value` (the property value). + +This function is useful for iterating over object properties in DSC configurations, +especially when used with loops. + +## Examples + +### Example 1 - Convert simple object to array + +This example uses [`createObject()`][00] to create a simple object and converts it +to an array of key-value pairs. + +```yaml +# items.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[items(createObject('a', 1, 'b', 2, 'c', 3))]" +``` + +```bash +dsc config get --file items.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - key: a + value: 1 + - key: b + value: 2 + - key: c + value: 3 +messages: [] +hadErrors: false +``` + +### Example 2 - Access keys and values + +This example shows how to access the keys and values from the items array using array +indexing. + +```yaml +# items.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[items(createObject('firstName', 'John', 'lastName', 'Doe'))[0].key]" +``` + +```bash +dsc config get --file items.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: firstName +messages: [] +hadErrors: false +``` + +### Example 3 - Get length of object + +This example shows how to use `items()` with [`length()`][01] to count the number of +properties in an object. + +```yaml +# items.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[length(items(createObject('a', 1, 'b', 2, 'c', 3)))]" +``` + +```bash +dsc config get --file items.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: 3 +messages: [] +hadErrors: false +``` + +### Example 4 - Handle nested objects + +This example demonstrates using `items()` with objects that contain nested objects. +It uses [`length()`][01] and [`copyIndex()`][02] with the `copy` feature to iterate +over each user. + +```yaml +# items.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + users: + type: object + defaultValue: + admin: + name: Administrator + role: admin + guest: + name: Guest User + role: guest +resources: +- name: "[format('User-{0}', copyIndex())]" + copy: + name: userLoop + count: "[length(items(parameters('users')))]" + type: Microsoft.DSC.Debug/Echo + properties: + output: "[items(parameters('users'))[copyIndex()].value.name]" +``` + +```bash +dsc config get --file items.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: User-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Administrator +- name: User-1 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Guest User +messages: [] +hadErrors: false +``` + +## Parameters + +### inputObject + +The dictionary object to convert to an array of key-value pairs. + +```yaml +Type: object +Required: true +Position: 1 +``` + +## Output + +Returns an array where each element is an object with `key` and `value` properties. + +```yaml +Type: array +``` + +## Related functions + +- [`createObject()`][00] - Creates an object from key-value pairs +- [`length()`][01] - Returns the number of elements in an array or object + + +[00]: ./createObject.md +[01]: ./length.md +[02]: ./copyIndex.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/join.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/join.md new file mode 100644 index 00000000..3a84716e --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/join.md @@ -0,0 +1,160 @@ +--- +description: Reference for the 'join' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: join +--- + +# join + +## Synopsis + +Joins an array into a single string, separated using a delimiter. + +## Syntax + +```Syntax +join(, ) +``` + +## Description + +The `join()` function takes an array and a delimiter. + +- Each string, number, or boolean element is converted to a string and + concatenated with the delimiter between elements. +- DSC raises an error when an element is null, an array, or an object. + +The `delimiter` must be a string. + +## Examples + +### Example 1 - Produce a list of servers + +Create a comma-separated string from a list of hostnames to pass to tools or +APIs that accept CSV input. This example uses [`createArray()`][02] to build +the server list and joins with ", ". + +```yaml +# join.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[join(createArray('web01','web02','web03'), ', ')]" +``` + +```bash +dsc config get --file join.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: web01, web02, web03 +messages: [] +hadErrors: false +``` + +### Example 2 - Build a file system path from segments + +Join path segments into a single path string. This is useful when composing +paths dynamically from parts. + +```yaml +# join.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[join(createArray('/etc','nginx','sites-enabled'), '/')]" +``` + +```bash +dsc config get --file join.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: /etc/nginx/sites-enabled +messages: [] +hadErrors: false +``` + +### Example 3 - Format a version string from numeric parts + +Convert version components (numbers) into a dotted version string. Number +elements are converted to strings automatically. + +```yaml +# join.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[join(createArray(1,2,3), '.')]" +``` + +```bash +dsc config get --file join.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: 1.2.3 +messages: [] +hadErrors: false +``` + +## Parameters + +### inputArray + +The array whose elements will be concatenated. + +```yaml +Type: array +Required: true +Position: 1 +``` + +### delimiter + +The string to insert between elements. DSC raises an error when the delimiter isn't a string. + +```yaml +Type: string +Required: true +Position: 2 +``` + +## Output + +Returns a string containing the joined result. + +```yaml +Type: string +``` + +## Related functions + +- [`concat()`][00] - Concatenates strings together +- [`string()`][01] - Converts values to strings + + +[00]: ./concat.md +[01]: ./string.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/json.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/json.md new file mode 100644 index 00000000..bd41a1c2 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/json.md @@ -0,0 +1,239 @@ +--- +description: Reference for the 'json' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: json +--- + +# json + +## Synopsis + +Converts a valid JSON string into a JSON data type. + +## Syntax + +```Syntax +json() +``` + +## Description + +The `json()` function parses a JSON string and returns the corresponding JSON data type. + +- The string must be a properly formatted JSON string. +- Returns the parsed JSON value (object, array, string, number, boolean, or null). + +This function is useful for converting JSON strings received from external sources or +stored as configuration into usable data structures. + +## Examples + +### Example 1 - Parse JSON object + +This example parses a JSON string containing an object into a usable object data type. + +```yaml +# json.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[json('{\"name\":\"John\",\"age\":30}')]" +``` + +```bash +dsc config get --file json.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + name: John + age: 30 +messages: [] +hadErrors: false +``` + +### Example 2 - Parse JSON array + +This example parses a JSON string containing an array using [`json()`][00] and then +uses [`length()`][01] to count the elements. + +```yaml +# json.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[length(json('[1,2,3,4,5]'))]" +``` + +```bash +dsc config get --file json.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: 5 +messages: [] +hadErrors: false +``` + +### Example 3 - Parse nested JSON structure + +This example parses a JSON string with nested objects and arrays, then accesses nested +properties using array indexing and property access. + +```yaml +# json.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [json('{"users":[{"name":"Alice"},{"name":"Bob"}]}').users[0].name] +``` + +```bash +dsc config get --file json.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Alice +messages: [] +hadErrors: false +``` + +### Example 4 - Parse JSON with whitespace + +This example shows that `json()` handles JSON strings with extra whitespace. + +```yaml +# json.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[json(' { \"key\" : \"value\" } ').key]" +``` + +```bash +dsc config get --file json.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: value +messages: [] +hadErrors: false +``` + +### Example 5 - Parse primitive JSON values + +This example demonstrates parsing different primitive JSON values including strings, +numbers, and booleans. + +```yaml +# json.example.5.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo string + type: Microsoft.DSC.Debug/Echo + properties: + output: "[json('\"hello\"')]" +- name: Echo number + type: Microsoft.DSC.Debug/Echo + properties: + output: "[json('42')]" +- name: Echo boolean + type: Microsoft.DSC.Debug/Echo + properties: + output: "[json('true')]" +``` + +```bash +dsc config get --file json.example.5.dsc.config.yaml +``` + +```yaml +results: +- name: Echo string + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: hello +- name: Echo number + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: 42 +- name: Echo boolean + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +### arg1 + +The JSON string to parse. Must be a properly formatted JSON string. + +```yaml +Type: string +Required: true +Position: 1 +``` + +## Output + +Returns the parsed JSON value. The type depends on the JSON content: + +- Object for JSON objects +- Array for JSON arrays +- String for JSON strings +- Number for JSON numbers +- Boolean for JSON booleans +- Null for JSON null + +```yaml +Type: object | array | string | number | boolean +``` + +> [!NOTE] +> The declared return types for `json()` don't include null. Parsing the JSON literal `null` +> still returns a null value, so `[json('null')]` evaluates to `null`. + +## Related functions + +- [`length()`][00] - Returns the length of an array or object +- [`string()`][01] - Converts values to strings + + +[00]: ./length.md +[01]: ./string.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lambda.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lambda.md new file mode 100644 index 00000000..400d6883 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lambda.md @@ -0,0 +1,280 @@ +--- +description: Reference for the 'lambda' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: lambda +--- + +# lambda + +## Synopsis + +Creates a lambda function with named parameters and a body expression for use with functions that +evaluate an expression for each element of an array, like `map()` and `filter()`. + +## Syntax + +```Syntax +lambda(, ) +lambda(, , ) +``` + +## Description + +The `lambda()` function creates an anonymous function, called a _lambda_, that DSC evaluates once +for each element of an array. The result of `lambda()` is only usable as an argument to a function +that accepts lambdas. Currently, those functions are [`map()`][00] and [`filter()`][01]. + +A lambda consists of: + +- One or more _parameter names_, specified as string literals. When `map()` or `filter()` + evaluates the lambda for an element, DSC binds the element to the first parameter and the + zero-based index of the element to the second parameter, if the lambda declares one. +- A _body_, specified as the last argument. The body must be an expression, which is a call to a + configuration function, optionally followed by property or index access. A literal string, + number, or boolean isn't a valid body. + +DSC doesn't evaluate the body when it processes `lambda()`. Instead, DSC stores the parameter +names and the body expression and evaluates the body separately for every element when the +consuming function runs. Inside the body, use [`lambdaVariables()`][02] to read the value that DSC +bound to a parameter. The body can also call any other configuration function, including +[`parameters()`][03] and [`variables()`][04]. + +The `lambda()` function itself accepts any number of parameter names, but `map()` and `filter()` +only accept lambdas with one or two parameters. A lambda with more than two parameters raises an +error when one of those functions uses it. + +## Examples + +### Example 1 - Lambda with a single parameter + +The following example creates a lambda with one parameter, `x`, and passes it to [`map()`][00]. +For each element in the array, DSC binds the element to `x` and evaluates the body, which +multiplies the value by `10` with [`mul()`][05]. + +```yaml +# lambda.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[map(createArray(1, 2, 3), lambda('x', mul(lambdaVariables('x'), 10)))]" +``` + +```bash +dsc config get --file lambda.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 10 + - 20 + - 30 +messages: [] +hadErrors: false +``` + +### Example 2 - Lambda with an element and index parameter + +The following example creates a lambda with two parameters and passes it to [`filter()`][01]. +DSC binds each element to `item` and the zero-based index of the element to `index`. The body +uses [`mod()`][06] and [`equals()`][07] to return `true` only for elements at even indexes. + +```yaml +# lambda.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [filter( + createArray('a', 'b', 'c', 'd'), + lambda('item', 'index', equals(mod(lambdaVariables('index'), 2), 0)) + )] +``` + +```bash +dsc config get --file lambda.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - a + - c +messages: [] +hadErrors: false +``` + +In this example, the lambda declares the `item` parameter but only uses `index` in its body. The +first parameter is always bound to the element, so you must declare it even when the body only +needs the index. + +### Example 3 - Lambda body that reads a configuration parameter + +The following example shows that a lambda body can use other configuration functions. The body +calls [`parameters()`][03] to read the `prefix` parameter and [`concat()`][08] to combine it with +the current element. + +```yaml +# lambda.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + prefix: + type: string + defaultValue: srv- + names: + type: array + defaultValue: [web, db] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [map( + parameters('names'), + lambda('name', concat(parameters('prefix'), lambdaVariables('name'))) + )] +``` + +```bash +dsc config get --file lambda.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - srv-web + - srv-db +messages: [] +hadErrors: false +``` + +## Parameters + +### elementName + +The name of the parameter that DSC binds to the current element of the array. The name must be a +string literal, like `'x'`. An expression that returns a string, like `string('x')`, isn't +accepted. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### indexName + +The name of the parameter that DSC binds to the zero-based index of the current element. The name +must be a string literal. When you specify this parameter, the body must be the third argument. + +```yaml +Type: string +Required: false +Position: 2 +``` + +### body + +The expression to evaluate for each element. The body must be a call to a configuration function, +like `mul(lambdaVariables('x'), 2)`. Use [`lambdaVariables()`][02] inside the body to read the +values bound to the lambda's parameters. + +The consuming function determines how it uses the value the body returns. [`map()`][00] collects +the returned values into the output array. [`filter()`][01] requires the body to return a boolean +value and keeps the element when the value is `true`. + +The body is always the last argument. Its position is `2` when the lambda declares one parameter +and `3` when the lambda declares two parameters. + +```yaml +Type: expression +Required: true +Position: last +``` + +## Output + +Returns a lambda value that can only be used as an argument to a function that accepts lambdas. +DSC represents the lambda as an opaque identifier string with the prefix `__lambda_`. If you use +`lambda()` where DSC doesn't expect a lambda, like directly as the value of a resource property, +the result is that identifier string, which isn't useful on its own. + +```yaml +Type: lambda +``` + +## Error conditions + +The function raises an error in the following cases: + +- **Missing arguments**: The function is called with fewer than two arguments. DSC raises + `lambda() requires at least one parameter name and a body expression`. +- **Parameter name isn't a string literal**: A parameter name is a number, a boolean, or an + expression. DSC raises `lambda() parameter names must be string literals`. +- **Body isn't an expression**: The last argument is a literal value instead of a function call. + DSC raises `lambda() body must be an expression`. +- **Passed to a function that doesn't accept lambdas**: The lambda is used as an argument to a + function other than `map()` or `filter()`. For example, `concat('a', lambda('x', ...))` raises + `Function 'concat' does not accept lambda arguments, accepted types are: String, Array`. +- **Too many parameters**: The lambda declares more than two parameters and is passed to `map()` + or `filter()`. For example, DSC raises + `Function 'map' requires lambda with 1 or 2 parameters (element and optional index)`. + +## Notes + +- The output of `dsc function list lambda` reports `minArgs` and `maxArgs` as `0` and an empty + `acceptedArgOrderedTypes` list. This is because DSC's expression parser handles `lambda()` + specially: it passes the arguments to the function without evaluating them first, which is how + the body expression is captured instead of being evaluated immediately. The `constraints` field + in the same output describes the actual requirement: + `Lambda function must have at least one parameter and a body expression`. +- Parameter names are case-sensitive. The name you pass to [`lambdaVariables()`][02] must match + the declared name exactly. +- Lambda parameters are separate from configuration variables and parameters. Declaring a lambda + parameter with the same name as a configuration variable doesn't affect the variable, and + [`variables()`][04] can't read a lambda parameter. +- DSC stores lambdas only for the duration of a single configuration evaluation. +- Only functions that declare a `lambda` argument type accept the result of `lambda()`. To see + which argument types a function accepts, use `dsc function list `. + +## Related functions + +- [`map()`][00] - Transforms every element of an array with a lambda +- [`filter()`][01] - Keeps only the elements of an array for which a lambda returns `true` +- [`lambdaVariables()`][02] - Reads a lambda parameter inside the lambda body +- [`parameters()`][03] - Returns the value of a configuration parameter +- [`variables()`][04] - Returns the value of a configuration variable +- [`mul()`][05] - Multiplies two integers +- [`mod()`][06] - Returns the remainder of dividing two integers +- [`equals()`][07] - Compares two values for equality +- [`concat()`][08] - Combines strings or arrays +- [`createArray()`][09] - Creates an array from values + + +[00]: ./map.md +[01]: ./filter.md +[02]: ./lambdaVariables.md +[03]: ./parameters.md +[04]: ./variables.md +[05]: ./mul.md +[06]: ./mod.md +[07]: ./equals.md +[08]: ./concat.md +[09]: ./createArray.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lambdaVariables.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lambdaVariables.md new file mode 100644 index 00000000..8763ad15 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lambdaVariables.md @@ -0,0 +1,240 @@ +--- +description: Reference for the 'lambdaVariables' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: lambdaVariables +--- + +# lambdaVariables + +## Synopsis + +Returns the value bound to a named parameter of the lambda function that DSC is currently +evaluating. + +## Syntax + +```Syntax +lambdaVariables() +``` + +## Description + +The `lambdaVariables()` function retrieves the value of a lambda parameter. It's only meaningful +inside the body of a lambda created with [`lambda()`][00]. When [`map()`][01] or [`filter()`][02] +evaluates the lambda for an element, DSC binds the element to the lambda's first parameter and the +zero-based index of the element to the optional second parameter. The `lambdaVariables()` function +returns those bound values by name. + +The returned value has whatever type the bound value has. The element can be of any type, and the +index is always a number. When the returned value is an object or an array, you can use the +property and index access syntax on the result, like `lambdaVariables('server').name` or +`lambdaVariables('server').ports[0]`. + +Lambda parameters are separate from configuration variables and parameters. The +[`variables()`][03] function can't read a lambda parameter, and `lambdaVariables()` can't read a +configuration variable. + +If the name doesn't match a parameter of the lambda that DSC is currently evaluating, including +when you use `lambdaVariables()` outside of a lambda body, DSC raises an error and stops +processing the configuration document. + +## Examples + +### Example 1 - Read the current element + +The following example uses `lambdaVariables()` to read the element that DSC bound to the `x` +parameter and adds `1` to it with [`add()`][04]. + +```yaml +# lambdaVariables.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[map(createArray(1, 2, 3), lambda('x', add(lambdaVariables('x'), 1)))]" +``` + +```bash +dsc config get --file lambdaVariables.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 2 + - 3 + - 4 +messages: [] +hadErrors: false +``` + +### Example 2 - Read the element and its index + +The following example declares two lambda parameters. DSC binds each element to `color` and the +zero-based index of the element to `position`. The body reads both values with +`lambdaVariables()` and combines them into an object with [`createObject()`][05]. + +```yaml +# lambdaVariables.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [map( + createArray('red', 'green', 'blue'), + lambda( + 'color', + 'position', + createObject( + 'position', lambdaVariables('position'), + 'color', lambdaVariables('color') + ) + ) + )] +``` + +```bash +dsc config get --file lambdaVariables.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - position: 0 + color: red + - position: 1 + color: green + - position: 2 + color: blue +messages: [] +hadErrors: false +``` + +### Example 3 - Access properties of an object element + +The following example maps an array of objects. The body uses the property access syntax on the +result of `lambdaVariables()` to read the `name` property and the first item of the `ports` array +for each element, then combines them with [`format()`][06]. + +```yaml +# lambdaVariables.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + servers: + type: array + defaultValue: + - name: web01 + ports: [80, 443] + - name: db01 + ports: [5432] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [map( + parameters('servers'), + lambda( + 'server', + format( + '{0}:{1}', + lambdaVariables('server').name, + lambdaVariables('server').ports[0] + ) + ) + )] +``` + +```bash +dsc config get --file lambdaVariables.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - web01:80 + - db01:5432 +messages: [] +hadErrors: false +``` + +## Parameters + +### name + +The name of the lambda parameter to read. The name is case-sensitive and must exactly match one of +the parameter names declared in the enclosing [`lambda()`][00] call. + +```yaml +Type: string +Required: true +Position: 1 +``` + +## Output + +Returns the value that DSC bound to the named parameter for the current element. For the first +lambda parameter, the value is the element itself and can be of any type. For the optional second +lambda parameter, the value is the zero-based index of the element as a number. + +```yaml +Type: [array, boolean, null, number, object, string] +``` + +## Error conditions + +The function raises an error in the following cases: + +- **Unknown parameter**: The name doesn't match a parameter of the lambda that DSC is currently + evaluating. DSC raises `Lambda parameter '' not found in current context`. +- **Used outside a lambda**: The function is called outside of a lambda body, so no lambda + parameters are bound. DSC raises the same + `Lambda parameter '' not found in current context` error. +- **Invalid name**: The argument isn't a string. + +## Notes + +- Parameter names are case-sensitive. +- The index bound to the optional second lambda parameter is a zero-based number. +- DSC binds the lambda parameters fresh for every element. The body can't read the values bound + for other elements of the array. +- Lambda parameters are separate from the values returned by [`variables()`][03] and + [`parameters()`][07]. You can still call those functions inside a lambda body to read + configuration variables and parameters. + +## Related functions + +- [`lambda()`][00] - Creates a lambda function with named parameters +- [`map()`][01] - Transforms every element of an array with a lambda +- [`filter()`][02] - Keeps only the elements of an array for which a lambda returns `true` +- [`variables()`][03] - Returns the value of a configuration variable +- [`parameters()`][07] - Returns the value of a configuration parameter +- [`add()`][04] - Adds two integers +- [`createObject()`][05] - Creates an object from key-value pairs +- [`format()`][06] - Creates a formatted string from input values + + +[00]: ./lambda.md +[01]: ./map.md +[02]: ./filter.md +[03]: ./variables.md +[04]: ./add.md +[05]: ./createObject.md +[06]: ./format.md +[07]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/last.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/last.md new file mode 100644 index 00000000..5989505b --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/last.md @@ -0,0 +1,194 @@ +--- +description: Reference for the 'last' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: last +--- + +# last + +## Synopsis + +Returns the last element of an array, or the last character of a string. + +## Syntax + +```Syntax +last(arg) +``` + +## Description + +The `last()` function returns the final element from an array or the final +character from a string. This is useful when you need to access the most recent +item in a sequence, the final stage in a deployment pipeline, or the last +character in a configuration value. + +For arrays, it returns the element at index `length - 1`. For strings, it +returns the last character as a string. + +## Examples + +### Example 1 - Extract the final deployment stage (array of strings) + +Use `last()` to retrieve the final stage in a multi-stage deployment pipeline. +This helps you identify which environment or phase should receive special +handling, such as extended health checks or manual approval gates. This example +uses [`createArray()`][01] to build the deployment stages. + +```yaml +# last.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Deployment Pipeline + type: Microsoft.DSC.Debug/Echo + properties: + output: + finalStage: "[last(createArray('dev', 'test', 'staging', 'production'))]" + requiresApproval: true +``` + +```bash +dsc config get --file last.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Deployment Pipeline + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + finalStage: production + requiresApproval: true +messages: [] +hadErrors: false +``` + +This identifies `production` as the final stage, allowing you to apply +production-specific policies or validations. + +### Example 2 - Get the last character of a configuration string + +Use `last()` to extract the final character from a string value. This is useful +for parsing identifiers, checking suffixes, or validating format conventions +like version numbers or region codes. + +```yaml +# last.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Region Identifier + type: Microsoft.DSC.Debug/Echo + properties: + output: + regionCode: us-west-2 + zoneSuffix: "[last('us-west-2')]" + description: "Zone suffix extracted from region code" +``` + +```bash +dsc config get --file last.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Region Identifier + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + regionCode: us-west-2 + zoneSuffix: '2' + description: Zone suffix extracted from region code +messages: [] +hadErrors: false +``` + +The function returns `'2'` as a single-character string, representing the zone +suffix in the region identifier. + +### Example 3 - Identify the most recent backup (array of numbers) + +Use `last()` with numerical arrays to find the most recent timestamp or version +number. This example shows how to select the latest backup from a sorted list +of timestamps. This example uses [`createArray()`][01] to build the backup +timestamps. + +```yaml +# last.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Backup Selection + type: Microsoft.DSC.Debug/Echo + properties: + output: + availableBackups: "[createArray(1704067200, 1704153600, 1704240000, 1704326400)]" + latestBackup: "[last(createArray(1704067200, 1704153600, 1704240000, 1704326400))]" + description: "Most recent backup timestamp (Unix epoch)" +``` + +```bash +dsc config get --file last.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Backup Selection + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + availableBackups: + - 1704067200 + - 1704153600 + - 1704240000 + - 1704326400 + latestBackup: 1704326400 + description: Most recent backup timestamp (Unix epoch) +messages: [] +hadErrors: false +``` + +The function returns `1704326400`, which represents the most recent backup in +the chronologically sorted array. + +## Parameters + +### arg + +The array or string to get the last element or character from. Required. + +```yaml +Type: array | string +Required: true +Position: 1 +``` + +## Output + +Returns the last element of the array (preserving its original type) or the +last character as a string. For arrays, the return type matches the element +type. For strings, returns a single-character string. + +If the input is an empty array, the function returns `null`. If the input is an +empty string, the function returns an empty string. + +```yaml +Type: any | string | null +``` + +## Errors + +The function returns an error in the following cases: + +- **Invalid type**: The argument is not an array or string + +## Related functions + +- [`first()`][00] - Returns the first element of an array or character of a string +- [`createArray()`][01] - Creates an array from provided values + + +[00]: ./first.md +[01]: ./createArray.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lastIndexOf.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lastIndexOf.md new file mode 100644 index 00000000..407efc52 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lastIndexOf.md @@ -0,0 +1,158 @@ +--- +description: Reference for the 'lastIndexOf' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: lastIndexOf +--- + +# lastIndexOf + +## Synopsis + +Returns an integer for the index of the last occurrence of an item in an array. +If the item isn't present, returns -1. + +## Syntax + +```Syntax +lastIndexOf(arrayToSearch, itemToFind) +``` + +## Description + +The `lastIndexOf()` function searches an array from the end to the beginning +and returns the zero-based index of the last matching element. String +comparisons are case-sensitive. If no match is found, `-1` is returned. + +Supported `itemToFind` types: + +- string (case-sensitive) +- number (integer) +- array (deep equality) +- object (deep equality) + +## Examples + +### Example 1 - Find the last rollout slot for a server role (strings) + +Use `lastIndexOf()` to locate where a particular role (like a web node) +appears last in a planned rollout sequence. This is handy when you need to +schedule a final step (for example, draining traffic) after the last matching +node has been processed. This example uses [`createArray()`][02] to build the +list of nodes. + +```yaml +# lastindexof.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Rollout Plan + type: Microsoft.DSC.Debug/Echo + properties: + output: + lastWebIndex: >- + [lastIndexOf(createArray('web01','db01','web02','cache01','web03'), 'web03')] + lastWebFamilyIndex: >- + [lastIndexOf(createArray('web01','db01','web02','cache01','web02'), 'web02')] +``` + +```bash +dsc config get --file lastindexof.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Rollout Plan + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + lastWebIndex: 4 + lastWebFamilyIndex: 4 +messages: [] +hadErrors: false +``` + +Note that string comparison is case-sensitive. Searching for `WEB02` would +return `-1` in this example. + +### Example 2 - Locate the last matching configuration object (objects) + +Deep equality lets you search arrays of objects. Here we find the last +occurrence of a feature flag object with a specific name. This example uses +[`createObject()`][03] to build objects and [`createArray()`][10] to build the +collection. + +```yaml +# lastindexof.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Feature Flags + type: Microsoft.DSC.Debug/Echo + properties: + output: + lastBetaIndex: >- + [lastIndexOf(createArray(createObject('name','Beta'), + createObject('name','Gamma'), createObject('name','Beta')), + createObject('name','Beta'))] +``` + +```bash +dsc config get --file lastindexof.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Feature Flags + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + lastBetaIndex: 2 +messages: [] +hadErrors: false +``` + +Property order in objects doesn't matter. The following also returns `1` due to deep equality: +`lastIndexOf(array(createObject('a',1,'b',2), createObject('b',2,'a',1)), +createObject('a',1,'b',2))`. + +## Parameters + +### arrayToSearch + +The array to search. Required. + +```yaml +Type: array +Required: true +Position: 1 +``` + +### itemToFind + +The item to search for. Required. + +```yaml +Type: string | number | array | object +Required: true +Position: 2 +``` + +## Output + +Returns a number representing the last index or -1 if not found. + +```yaml +Type: number +``` + +## Related functions + +- [`indexOf()`][00] - First occurrence index in an array +- [`contains()`][01] - Checks for presence in arrays/objects/strings + + +[00]: ./indexOf.md +[01]: ./contains.md +[02]: ./createArray.md +[03]: ./createObject.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/length.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/length.md new file mode 100644 index 00000000..3b33c608 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/length.md @@ -0,0 +1,195 @@ +--- +description: Reference for the 'length' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: length +--- + +# length + +## Synopsis + +Returns the number of elements in an array, properties in an object, or +characters in a string. + +## Syntax + +```Syntax +length() +``` + +## Description + +The `length()` function returns the number of elements in a collection or +characters in a string. For arrays, it returns the count of elements. For +objects, it returns the count of properties. For strings, it returns the +count of characters. + +## Examples + +### Example 1 - Get array length + +The following example shows how to get the length of arrays. + +```yaml +# length.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + smallArray: + type: array + defaultValue: + - dsc + - v3 + largeArray: + type: array + defaultValue: + - red + - green + - blue + - yellow + - purple + emptyArray: + type: array + defaultValue: [] +resources: +- name: Check array lengths + type: Microsoft.DSC.Debug/Echo + properties: + output: + smallLength: "[length(parameters('smallArray'))]" + largeLength: "[length(parameters('largeArray'))]" + emptyLength: "[length(parameters('emptyArray'))]" +``` + +```bash +dsc config get --file length.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Check array lengths + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + smallLength: 2 + largeLength: 5 + emptyLength: 0 +messages: [] +hadErrors: false +``` + +### Example 2 - Get object property count + +The following example shows how to get the number of properties in objects. + +```yaml +# length.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + userProfile: + type: object + defaultValue: + firstName: John + lastName: Doe + email: john.doe@example.com + age: 30 + emptyConfig: + type: object + defaultValue: {} +resources: +- name: Check object property counts + type: Microsoft.DSC.Debug/Echo + properties: + output: + profileProperties: "[length(parameters('userProfile'))]" + emptyProperties: "[length(parameters('emptyConfig'))]" +``` + +```bash +dsc config get --file length.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Check object property counts + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + profileProperties: 4 + emptyProperties: 0 +messages: [] +hadErrors: false +``` + +### Example 3 - Get string character count + +The following example shows how to get the length of strings. + +```yaml +# length.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + message: + type: string + defaultValue: "Hello DSC!" + longText: + type: string + defaultValue: >- + This is a longer string with more characters to demonstrate length + calculation. +resources: +- name: Check string lengths + type: Microsoft.DSC.Debug/Echo + properties: + output: + messageLength: "[length(parameters('message'))]" + longTextLength: "[length(parameters('longText'))]" + emptyStringLength: "[length('')]" + literalLength: "[length('DSC')]" +``` + +```bash +dsc config get --file length.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Check string lengths + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + messageLength: 10 + longTextLength: 79 + emptyStringLength: 0 + literalLength: 3 +messages: [] +hadErrors: false +``` + +## Parameters + +### value + +The value to get the length of. + +```yaml +Type: [array, object, string] +Required: true +``` + +The `length()` function expects exactly one input value of type array, object, +or string. + +## Output + +The `length()` function returns an integer representing the count of elements, +properties, or characters. + +```yaml +Type: number +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/less.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/less.md new file mode 100644 index 00000000..7acc871f --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/less.md @@ -0,0 +1,157 @@ +--- +description: Reference for the 'less' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: less +--- + +# less + +## Synopsis + +Checks whether the first value is less than the second value. + +## Syntax + +```Syntax +less(, ) +``` + +## Description + +The `less()` function checks whether the first value is less than the second value, +returning `true` if it is and otherwise `false`. You can use this function to compare +two values of the same data type. If the values are different types, like a string and +an integer, DSC returns an error for this function. + +For strings, the comparison is case-sensitive and uses lexicographic ordering based on character +codes. + +## Examples + +### Example 1 - Compare two numbers + +The following example shows how you can use the function to compare two numbers. + +```yaml +# less.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Compare numbers + type: Microsoft.DSC.Debug/Echo + properties: + output: + firstLess: "[less(3, 5)]" + secondLess: "[less(5, 3)]" + equalNumbers: "[less(5, 5)]" +``` + +```bash +dsc config get --file less.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Compare numbers + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + firstLess: true + secondLess: false + equalNumbers: false +messages: [] +hadErrors: false +``` + +### Example 2 - Compare two strings + +The following example shows how you can use the function to compare two strings. + +```yaml +# less.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Compare strings + type: Microsoft.DSC.Debug/Echo + properties: + output: + lexicographicLess: "[less('a', 'b')]" + lexicographicGreater: "[less('b', 'a')]" + caseSensitive: "[less('A', 'a')]" +``` + +```bash +dsc config get --file less.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Compare strings + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + lexicographicLess: true + lexicographicGreater: false + caseSensitive: true +messages: [] +hadErrors: false +``` + +### Example 3 - Type mismatch error + +The following example shows what happens when you try to compare different types. + +```yaml +# less.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Type mismatch + type: Microsoft.DSC.Debug/Echo + properties: + output: "[less(1, 'b')]" +``` + +```bash +dsc config get --file less.example.3.dsc.config.yaml +``` + +This will result in an error because you cannot compare a number with a string. + +## Parameters + +### firstValue + +The first value to compare. Must be the same type as the second value. + +```yaml +Type: [number, string] +Required: true +``` + +### secondValue + +The second value to compare. Must be the same type as the first value. + +```yaml +Type: [number, string] +Required: true +``` + +The `less()` function expects exactly two input values of the same type. +Separate each value with a comma. If the type of the second input value is +different from the first value, DSC returns an error for the function. + +String comparisons are case-sensitive and use lexicographic ordering. + +## Output + +The `less()` function returns `true` if the first value is less than the second +value and otherwise `false`. + +```yaml +Type: bool +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lessOrEquals.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lessOrEquals.md new file mode 100644 index 00000000..1e65cbe3 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/lessOrEquals.md @@ -0,0 +1,160 @@ +--- +description: Reference for the 'lessOrEquals' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: lessOrEquals +--- + +# lessOrEquals + +## Synopsis + +Checks whether the first value is less than or equal to the second value. + +## Syntax + +```Syntax +lessOrEquals(, ) +``` + +## Description + +The `lessOrEquals()` function checks whether the first value is less than or +equal to the second value, returning `true` if it is and otherwise `false`. +You can use this function to compare two values of the same data type. +If the values are different types, like a string and an integer, DSC returns +an error for this function. + +For strings, the comparison is case-sensitive and uses lexicographic ordering +based on character codes. + +## Examples + +### Example 1 - Compare two numbers + +The following example shows how you can use the function to compare two numbers. + +```yaml +# lessOrEquals.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Compare numbers + type: Microsoft.DSC.Debug/Echo + properties: + output: + firstLess: "[lessOrEquals(3, 5)]" + secondLess: "[lessOrEquals(5, 3)]" + equalNumbers: "[lessOrEquals(5, 5)]" +``` + +```bash +dsc config get --file lessOrEquals.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Compare numbers + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + firstLess: true + secondLess: false + equalNumbers: true +messages: [] +hadErrors: false +``` + +### Example 2 - Compare two strings + +The following example shows how you can use the function to compare two strings. + +```yaml +# lessOrEquals.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Compare strings + type: Microsoft.DSC.Debug/Echo + properties: + output: + lexicographicLess: "[lessOrEquals('a', 'b')]" + lexicographicGreater: "[lessOrEquals('b', 'a')]" + equalStrings: "[lessOrEquals('a', 'a')]" + caseSensitive: "[lessOrEquals('aa', 'Aa')]" +``` + +```bash +dsc config get --file lessOrEquals.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Compare strings + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + lexicographicLess: true + lexicographicGreater: false + equalStrings: true + caseSensitive: false +messages: [] +hadErrors: false +``` + +### Example 3 - Type mismatch error + +The following example shows what happens when you try to compare different types. + +```yaml +# lessOrEquals.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Type mismatch + type: Microsoft.DSC.Debug/Echo + properties: + output: "[lessOrEquals(5, 'a')]" +``` + +```bash +dsc config get --file lessOrEquals.example.3.dsc.config.yaml +``` + +This will result in an error because you cannot compare a number with a string. + +## Parameters + +### firstValue + +The first value to compare. Must be the same type as the second value. + +```yaml +Type: [number, string] +Required: true +``` + +### secondValue + +The second value to compare. Must be the same type as the first value. + +```yaml +Type: [number, string] +Required: true +``` + +The `lessOrEquals()` function expects exactly two input values of the same type. +Separate each value with a comma. If the type of the second input value is different +from the first value, DSC returns an error for the function. + +String comparisons are case-sensitive and use lexicographic ordering. + +## Output + +The `lessOrEquals()` function returns `true` if the first value is less than or +equal to the second value and otherwise `false`. + +```yaml +Type: bool +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/map.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/map.md new file mode 100644 index 00000000..ca240e3e --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/map.md @@ -0,0 +1,313 @@ +--- +description: Reference for the 'map' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: map +--- + +# map + +## Synopsis + +Transforms an array by applying a lambda function to each element and returning the results as a +new array. + +## Syntax + +```Syntax +map(, ) +``` + +## Description + +The `map()` function evaluates a lambda function created with [`lambda()`][00] against every +element of an array and returns a new array that contains the value the lambda returned for each +element. The output array always has the same number of elements as the input array, in the same +order. + +For each element in the input array, DSC: + +1. Binds the element to the lambda's first parameter. +1. Binds the zero-based index of the element to the lambda's second parameter, if the lambda + declares one. +1. Evaluates the lambda's body expression. Inside the body, use [`lambdaVariables()`][01] to read + the bound parameters. +1. Appends the value the body returned to the output array. + +Unlike [`filter()`][02], the lambda body can return a value of any type. The returned values +don't need to have the same type as the input elements, so you can use `map()` to convert an array +of numbers into an array of strings, an array of objects into an array of one of their properties, +or an array of values into an array of objects. + +The lambda body can call any other configuration function. DSC evaluates the body with a copy of +the current context, so the body can read configuration [`parameters()`][03] and +[`variables()`][04] in addition to the lambda's own parameters. + +This function is useful for: + +- Applying the same calculation or formatting to every element of an array. +- Extracting a single property from every object in an array. +- Building an array of objects from an array of simple values. +- Generating sequential names or values together with [`range()`][05]. + +## Examples + +### Example 1 - Multiply every element + +The following example multiplies every number in the `numbers` parameter by `2`. The lambda +declares a single parameter, `x`, which DSC binds to each element in turn. + +```yaml +# map.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + numbers: + type: array + defaultValue: [1, 2, 3] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[map(parameters('numbers'), lambda('x', mul(lambdaVariables('x'), 2)))]" +``` + +```bash +dsc config get --file map.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 2 + - 4 + - 6 +messages: [] +hadErrors: false +``` + +### Example 2 - Use the element index + +The following example uses a lambda with two parameters. DSC binds the element to `val` and the +zero-based index of the element to `i`. The lambda adds the two values together. + +```yaml +# map.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + items: + type: array + defaultValue: [10, 20, 30] +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [map( + parameters('items'), + lambda('val', 'i', add(lambdaVariables('val'), lambdaVariables('i'))) + )] +``` + +```bash +dsc config get --file map.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - 10 + - 21 + - 32 +messages: [] +hadErrors: false +``` + +### Example 3 - Generate names from a range + +The following example combines `map()` with [`range()`][05] and [`format()`][06] to generate a +sequence of server names. The input elements are numbers and the output elements are strings. + +```yaml +# map.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[map(range(1, 3), lambda('n', format('server-{0}', lambdaVariables('n'))))]" +``` + +```bash +dsc config get --file map.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - server-1 + - server-2 + - server-3 +messages: [] +hadErrors: false +``` + +### Example 4 - Extract and reshape object properties + +The following example maps an array of objects twice. The `names` output extracts the `name` +property of every object with the property access syntax. The `summary` output uses +[`createObject()`][07] to build a new object for every element from its index and its properties. + +```yaml +# map.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + users: + type: array + defaultValue: + - name: alice + role: admin + - name: bob + role: user +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: + names: "[map(parameters('users'), lambda('user', lambdaVariables('user').name))]" + summary: >- + [map( + parameters('users'), + lambda( + 'user', + 'index', + createObject( + 'id', lambdaVariables('index'), + 'label', format( + '{0} ({1})', + lambdaVariables('user').name, + lambdaVariables('user').role + ) + ) + ) + )] +``` + +```bash +dsc config get --file map.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + names: + - alice + - bob + summary: + - id: 0 + label: alice (admin) + - id: 1 + label: bob (user) +messages: [] +hadErrors: false +``` + +## Parameters + +### inputArray + +The array whose elements to transform. The elements can be of any type, including objects and +nested arrays. + +```yaml +Type: array +Required: true +Position: 1 +``` + +### lambda + +A lambda function created with [`lambda()`][00]. The lambda must declare one or two parameters. +DSC binds the current element to the first parameter and the zero-based index of the element to +the optional second parameter. The value the lambda's body returns becomes the corresponding +element of the output array. + +```yaml +Type: lambda +Required: true +Position: 2 +``` + +## Output + +Returns an array with one element for each element of `inputArray`, in the same order. Each +element is the value the lambda returned for the corresponding input element. Returns an empty +array when `inputArray` is empty. + +```yaml +Type: array +``` + +## Error conditions + +The function raises an error in the following cases: + +- **Not an array**: The first argument isn't an array. For example, passing a string raises + `Function 'map' does not accept string arguments, accepted types are: Array`. +- **Not a lambda**: The second argument isn't a lambda created with [`lambda()`][00]. +- **Too many parameters**: The lambda declares more than two parameters. DSC raises + `Function 'map' requires lambda with 1 or 2 parameters (element and optional index)`. +- **Body error**: The lambda body raises an error. For example, calling + [`lambdaVariables()`][01] with a name that the lambda didn't declare raises + `Lambda parameter '' not found in current context`. + +## Notes + +- The function always returns an array with the same length as the input array. To remove + elements from an array, use [`filter()`][02] instead. +- The function evaluates the lambda body once for each element in the input array. When the input + array is empty, the body is never evaluated and the function returns an empty array. +- The index that DSC binds to the optional second parameter is a zero-based number. +- The lambda body can return a value of any type, including objects and arrays. +- Lambda parameters are separate from configuration variables. Read them with + [`lambdaVariables()`][01], not [`variables()`][04]. + +## Related functions + +- [`lambda()`][00] - Creates the lambda function that `map()` evaluates +- [`lambdaVariables()`][01] - Reads a lambda parameter inside the lambda body +- [`filter()`][02] - Keeps only the elements of an array for which a lambda returns `true` +- [`parameters()`][03] - Returns the value of a configuration parameter +- [`variables()`][04] - Returns the value of a configuration variable +- [`range()`][05] - Creates an array of sequential integers +- [`format()`][06] - Creates a formatted string from input values +- [`createObject()`][07] - Creates an object from key-value pairs +- [`mul()`][08] - Multiplies two integers +- [`add()`][09] - Adds two integers + + +[00]: ./lambda.md +[01]: ./lambdaVariables.md +[02]: ./filter.md +[03]: ./parameters.md +[04]: ./variables.md +[05]: ./range.md +[06]: ./format.md +[07]: ./createObject.md +[08]: ./mul.md +[09]: ./add.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/max.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/max.md index dc083c78..de8d0aaa 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/max.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/max.md @@ -1,6 +1,6 @@ --- description: Reference for the 'max' DSC configuration document function -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: max --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/min.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/min.md index 07a1d76a..0574b335 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/min.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/min.md @@ -1,6 +1,6 @@ --- description: Reference for the 'min' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: min --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mod.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mod.md index 3f034be6..f100be92 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mod.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mod.md @@ -1,6 +1,6 @@ --- description: Reference for the 'mod' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: mod --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mul.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mul.md index 3f511988..aeb36c39 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mul.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mul.md @@ -1,6 +1,6 @@ --- description: Reference for the 'mul' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: mul --- @@ -19,8 +19,8 @@ mul() ## Description -The `mul()` function returns the product of multiplying two integers. It multiplies the first operand -by the second operand. You can nest calls to `mul()` to multiply more than two integers. +The `mul()` function returns the product of multiplying two integers. It multiplies the first +operand by the second operand. You can nest calls to `mul()` to multiply more than two integers. ## Examples @@ -35,11 +35,11 @@ resources: - name: Multiplying integers type: Microsoft.DSC.Debug/Echo properties: - output: "[mul(3, 5)]" + output: "[mul(3, 5)]" ``` ```bash -dsc config get --file mul.example.1.dsc.config.yaml config get +dsc config get --file mul.example.1.dsc.config.yaml ``` ```yaml @@ -86,9 +86,9 @@ hadErrors: false ### operands -The `mul()` function expects exactly two integers as input. The **operands** can be either an integer -or the output of any configuration function that returns an integer. The function divides the first -operand by the second operand. Separate the **operands** with a comma (`,`). +The `mul()` function expects exactly two integers as input. The **operands** can be either an +integer or the output of any configuration function that returns an integer. The function +multiplies the first operand by the second operand. Separate the **operands** with a comma (`,`). ```yaml Type: integer diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/not.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/not.md new file mode 100644 index 00000000..2f650de9 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/not.md @@ -0,0 +1,83 @@ +--- +description: Reference for the 'not' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: not +--- + +# not + +## Synopsis + +Negates a boolean value. + +## Syntax + +```Syntax +not() +``` + +## Description + +The `not()` function negates a boolean value, returning the logical opposite. If the input is +`true`, it returns `false`. If the input is `false`, it returns `true`. This function accepts +a single boolean argument. + +## Examples + +### Example 1 - Basic not operation + +This configuration demonstrates basic usage of the `not()` function. + +```yaml +# not.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo not operations + type: Microsoft.DSC.Debug/Echo + properties: + output: + notTrue: "[not(true)]" + notFalse: "[not(false)]" +``` + +```bash +dsc config get --file not.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0328813S + name: Echo not operations + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + notTrue: false + notFalse: true +``` + +## Parameters + +### value + +The `not()` function requires a single boolean argument. + +```yaml +Type: boolean +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `not()` function returns the logical opposite of the input boolean value. + +```yaml +Type: boolean +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/null.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/null.md new file mode 100644 index 00000000..9b1ffee5 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/null.md @@ -0,0 +1,150 @@ +--- +description: Reference for the 'null' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: null +--- + +# null + +## Synopsis + +Returns a null value. + +## Syntax + +```Syntax +null() +``` + +## Description + +The `null()` function returns a JSON null value. This function takes no arguments +and always returns null. It's useful for explicitly setting null values in configurations, +testing null handling in other functions, or providing null fallbacks in conditional +expressions. + +## Examples + +### Example 1 - Basic null usage + +The following example shows basic usage of the null function. + +```yaml +# null.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Null value + type: Microsoft.DSC.Debug/Echo + properties: + output: "[null()]" +``` + +```bash +dsc config get --file null.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Null value + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: null +messages: [] +hadErrors: false +``` + +### Example 2 - Null in object creation + +The following example shows how to use null when creating objects with null properties. + +```yaml +# null.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Object with null property + type: Microsoft.DSC.Debug/Echo + properties: + output: "[createObject('name', 'test', 'value', null(), 'active', true)]" +``` + +```bash +dsc config get --file null.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Object with null property + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + name: test + value: null + active: true +messages: [] +hadErrors: false +``` + +### Example 3 - Null with coalesce function + +The following example shows how null works with the coalesce function for fallback scenarios. + +```yaml +# null.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Coalesce with null + type: Microsoft.DSC.Debug/Echo + properties: + output: + fallbackValue: "[coalesce(null(), 'default-value')]" + nestedObject: "[createObject('result', coalesce(null(), 'fallback'))]" + multipleNulls: "[coalesce(null(), null(), null(), 'final-fallback')]" +``` + +```bash +dsc config get --file null.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Coalesce with null + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + fallbackValue: default-value + nestedObject: + result: fallback + multipleNulls: final-fallback +messages: [] +hadErrors: false +``` + +## Output + +The `null()` function always returns a JSON null value. + +```yaml +Type: null +``` + +## Notes + +- The `null()` function is particularly useful when working with other functions that handle null + values, such as `coalesce()`. +- Unlike undefined or missing values, `null()` explicitly represents the JSON null value. +- When used in object creation with `createObject()`, null properties are included in the + resulting object. +- The function takes no arguments and will return an error if any arguments are provided. + +## Related functions + +- [`coalesce()`][00] - Returns the first non-null value from a list of arguments +- [`createObject()`][01] - Creates objects that can contain null properties + + +[00]: ./coalesce.md +[01]: ./createObject.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/objectKeys.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/objectKeys.md new file mode 100644 index 00000000..bf516d69 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/objectKeys.md @@ -0,0 +1,305 @@ +--- +description: Reference for the 'objectKeys' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: objectKeys +--- + +# objectKeys + +## Synopsis + +Returns an array containing all the keys from an object. + +## Syntax + +```Syntax +objectKeys() +``` + +## Description + +The `objectKeys()` function extracts all property names from an object and returns them as +an array of strings. This function is useful for: + +- Iterating over object properties when you only need the keys +- Counting the number of properties in an object +- Checking if specific keys exist in an object +- Converting object keys for further processing + +The function only returns the top-level keys of the object. For nested objects, only the +outer keys are included in the result. + +This function is similar to [`items()`][00], which returns both keys and values, while +`objectKeys()` returns only the keys. + +## Examples + +### Example 1 - Extract keys from simple object + +The following example extracts all keys from a simple object. + +```yaml +# objectKeys.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [objectKeys(createObject('firstName', 'John', 'lastName', 'Doe', 'age', 30))] +``` + +```bash +dsc config get --file objectKeys.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - firstName + - lastName + - age +messages: [] +hadErrors: false +``` + +### Example 2 - Count object properties + +The following example uses `objectKeys()` with [`length()`][01] to count the number of +properties in an object. + +```yaml +# objectKeys.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[length(objectKeys(createObject('a', 1, 'b', 2, 'c', 3)))]" +``` + +```bash +dsc config get --file objectKeys.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: 3 +messages: [] +hadErrors: false +``` + +### Example 3 - Check if key exists + +The following example uses `objectKeys()` with [`contains()`][02] to check if a specific +key exists in an object. + +```yaml +# objectKeys.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + config: + type: object + defaultValue: + enabled: true + timeout: 30 +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: + hasEnabled: "[contains(objectKeys(parameters('config')), 'enabled')]" + hasDebug: "[contains(objectKeys(parameters('config')), 'debug')]" +``` + +```bash +dsc config get --file objectKeys.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + hasEnabled: true + hasDebug: false +messages: [] +hadErrors: false +``` + +### Example 4 - Iterate over keys with copy loop + +The following example uses `objectKeys()` to iterate over object properties using the +[`copy`][03] feature. + +```yaml +# objectKeys.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + settings: + type: object + defaultValue: + debug: false + logLevel: info + maxRetries: 3 +resources: +- name: "[format('Setting-{0}', copyIndex())]" + copy: + name: settingsLoop + count: "[length(objectKeys(parameters('settings')))]" + type: Microsoft.DSC.Debug/Echo + properties: + output: "[objectKeys(parameters('settings'))[copyIndex()]]" +``` + +```bash +dsc config get --file objectKeys.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Setting-0 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: debug +- name: Setting-1 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: logLevel +- name: Setting-2 + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: maxRetries +messages: [] +hadErrors: false +``` + +### Example 5 - Top-level keys only + +The following example demonstrates that `objectKeys()` only returns top-level keys, even +when the object contains nested objects. + +```yaml +# objectKeys.example.5.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [objectKeys(createObject('user', createObject('name', 'John', 'age', 30), + 'role', 'admin'))] +``` + +```bash +dsc config get --file objectKeys.example.5.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + - user + - role +messages: [] +hadErrors: false +``` + +### Example 6 - Empty object + +The following example shows that `objectKeys()` returns an empty array for an empty object. + +```yaml +# objectKeys.example.6.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: + keys: "[objectKeys(createObject())]" + isEmpty: "[equals(length(objectKeys(createObject())), 0)]" +``` + +```bash +dsc config get --file objectKeys.example.6.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + keys: [] + isEmpty: true +messages: [] +hadErrors: false +``` + +## Parameters + +### inputObject + +The object from which to extract the keys. + +```yaml +Type: object +Required: true +Position: 1 +``` + +## Output + +Returns an array of strings, where each string is a property name (key) from the input +object. The array contains only the top-level keys. + +```yaml +Type: array +``` + +## Error conditions + +The function will return an error in the following cases: + +- **Not an object**: The input is not an object (e.g., string, number, array, null) + +## Notes + +- The function only returns top-level keys; nested object keys are not included +- For empty objects, the function returns an empty array +- The order of keys in the returned array follows JSON object property ordering +- Key names are always returned as strings +- To get both keys and values, use [`items()`][00] instead + +## Related functions + +- [`items()`][00] - Converts an object to an array of key-value pairs +- [`createObject()`][04] - Creates an object from key-value pairs +- [`length()`][01] - Returns the number of elements in an array +- [`contains()`][02] - Checks if an array contains a specific value + + +[00]: ./items.md +[01]: ./length.md +[02]: ./contains.md +[03]: ./copy.md +[04]: ./createObject.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/or.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/or.md new file mode 100644 index 00000000..92759686 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/or.md @@ -0,0 +1,148 @@ +--- +description: Reference for the 'or' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: or +--- + +# or + +## Synopsis + +Returns true if any arguments are true. + +## Syntax + +```Syntax +or(, , ...) +``` + +## Description + +The `or()` function evaluates if any arguments are true. It takes two or more boolean arguments +and returns `true` if at least one argument is `true`. If all arguments are `false`, the function +returns `false`. + +This function uses short-circuit evaluation, meaning it returns `true` as soon as it encounters +the first `true` argument without evaluating the remaining arguments. + +## Examples + +### Example 1 - Basic or operation + +This configuration demonstrates basic usage of the `or()` function. + +```yaml +# or.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo or result + type: Microsoft.DSC.Debug/Echo + properties: + output: "[or(false, true)]" +``` + +```bash +dsc config get --file or.example.1.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0329859S + name: Echo or result + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +### Example 2 - Or operation with all false values + +This example shows the `or()` function returning false when all arguments are false. + +```yaml +# or.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo or result all false + type: Microsoft.DSC.Debug/Echo + properties: + output: "[or(false, false, false)]" +``` + +```bash +dsc config get --file or.example.2.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0320911S + name: Echo or result all false + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: false +messages: [] +hadErrors: false +``` + +### Example 3 - Or operation with multiple conditions + +This configuration uses the `or()` function with multiple boolean expressions. + +```yaml +# or.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo complex or operation + type: Microsoft.DSC.Debug/Echo + properties: + output: "[or(equals(5, 10), equals('hello', 'world'), true)]" +``` + +```bash +dsc config get --file or.example.3.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.0324607S + name: Echo complex or operation + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +### arguments + +The `or()` function requires two or more boolean arguments. + +```yaml +Type: boolean +Required: true +MinimumCount: 2 +MaximumCount: 18446744073709551615 +``` + +## Output + +The `or()` function returns `true` if any argument is `true`, otherwise it returns `false`. + +```yaml +Type: boolean +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/overview.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/overview.md index a06b1543..d0d9b6ac 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/overview.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/overview.md @@ -1,6 +1,6 @@ --- description: Reference for available functions in a Desired State Configuration document. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Configuration document functions reference --- @@ -183,10 +183,10 @@ hadErrors: false ### Example 3 - Using nested functions The following configuration document shows how you can nest functions. The first two resource -instances use the output of the [concat()][concat] function as input to the [base64()][base64] function. -The third resource instance uses the output of the nested functions from the first two instances -as input to the `concat()` function. The last resource instance converts the output of the deeply -nested functions shown in the third instance to base64. +instances use the output of the [concat()][concat] function as input to the [base64()][base64] +function. The third resource instance uses the output of the nested functions from the first two +instances as input to the `concat()` function. The last resource instance converts the output of +the deeply nested functions shown in the third instance to base64. ```yaml # overview.example.3.dsc.config.yaml @@ -296,8 +296,8 @@ parameters: - name: Nested third ``` -The first configuration document defines an instance of the `Microsoft.DSC.Debug/Echo` resource to show how you -can access an object's properties in a configuration document. +The first configuration document defines an instance of the `Microsoft.DSC.Debug/Echo` resource +to show how you can access an object's properties in a configuration document. ```yaml # overview.example.4.properties.dsc.config.yaml @@ -433,7 +433,7 @@ resources: ```sh $params=overview.example.4.dsc.parameters.yaml $config=overview.example.4.items.dsc.config.yaml -dsc config --parameters-file $params get --path $config +dsc config --parameters-file $params get --file $config ``` ```yaml @@ -541,106 +541,314 @@ dsc config --parameters-file $params get --file $config ``` ```yaml -$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json -# Minimal definition of the parameters -parameters: - data: { type: object } - list: { type: array } - -resources: - - name: Access values in complex objects and arrays - type: Microsoft.DSC.Debug/Echo - properties: +results: +- metadata: + Microsoft.DSC: + duration: PT0.0437158S + name: Access values in complex objects and arrays + type: Microsoft.DSC.Debug/Echo + result: + actualState: output: - # Accessing array items of an object property - data.services[0]: "[parameters('data').services[0]]" - data.services[1]: "[parameters('data').services[1]]" - data.services[2]: "[parameters('data').services[2]]" - # Accessing properties of an object in an array - list[2].name: "[parameters('list')[2].name]" - list[2].value: "[parameters('list')[2].value]" - # Accessing the property of an object in a nested array - list[3][2].name: "[parameters('list')[3][2].name]" + data.services[0]: web + data.services[1]: database + data.services[2]: application + list[2].name: third + list[2].value: 3 + list[3][2].name: Nested third ``` ## Functions -The following sections include the available DSC configuration functions by purpose and input type. +The following sections list the available functions grouped by category. The categories are the ones +that the [dsc function list][04] command reports for each function. A function that belongs to more +than one category, like `contains()`, appears in every category it belongs to. ### Array functions -The following list of functions operate on arrays: +The following functions operate on arrays: -- [concat()][concat] - Combine multiple arrays of strings into a single array of strings. +- [array()][array] - Convert a value into an array containing that value. +- [concat()][concat] - Combine multiple strings into a single string, or multiple arrays into a + single array. +- [contains()][contains] - Check if an array contains a value or an object contains a key. - [createArray()][createArray] - Create an array of a given type from zero or more values of the same type. -- [min()][min] - Return the smallest integer value from an array of integers. -- [max()][max] - Return the largest integer value from an array of integers. +- [empty()][empty] - Check if a value (string, array, or object) is empty. +- [filter()][filter] - Return a new array containing only the elements of an array for which a + lambda function returns true. +- [first()][first] - Return the first element of an array or the first character of a string. +- [indexOf()][indexOf] - Return the zero-based index of the first occurrence of a value in an array. +- [intersection()][intersection] - Return a single array or object with the common elements from the + parameters. +- [last()][last] - Return the last element of an array or the last character of a string. +- [lastIndexOf()][lastIndexOf] - Return the zero-based index of the last occurrence of a value in an + array. +- [length()][length] - Return the number of elements in an array, characters in a string, or + top-level properties in an object. +- [map()][map] - Transform every element of an array with a lambda function and return the results + as a new array. +- [range()][range] - Create an array of integers within a specified range. +- [skip()][skip] - Return an array or string with elements skipped from the beginning. +- [take()][take] - Return an array or string with the specified number of elements from the start. +- [tryGet()][tryGet] - Safely retrieve a value from an array by index or an object by key without + throwing an error. +- [tryIndexFromEnd()][tryIndexFromEnd] - Safely retrieve a value from an array by counting backward + from the end. +- [union()][union] - Return a single array or object with all unique elements from the parameters. + +### CIDR functions + +The following functions parse and calculate IP address ranges in CIDR notation: + +- [cidrHost()][cidrHost] - Return the usable IP address of the host at a given index within an IP + address range in CIDR notation. +- [cidrSubnet()][cidrSubnet] - Split an IP address range in CIDR notation into subnets and return + the subnet at a given index. +- [parseCidr()][parseCidr] - Parse an IP address range in CIDR notation and return its network + properties. + +### Comparison functions + +The following functions compare values: + +- [coalesce()][coalesce] - Return the first non-null value from the provided arguments. +- [equals()][equals] - Check if two values are equal. +- [greater()][greater] - Check if the first value is greater than the second value. +- [greaterOrEquals()][greaterOrEquals] - Check if the first value is greater than or equal to the + second value. +- [less()][less] - Check if the first value is less than the second value. +- [lessOrEquals()][lessOrEquals] - Check if the first value is less than or equal to the second + value. + +### Date functions + +The following functions work with dates and times: + +- [utcNow()][utcNow] - Return the current UTC datetime in a specified format. + +### Deployment functions + +The following functions return data about the configuration document and the environment DSC is +processing it in, like parameters, variables, and secrets: + +- [context()][context] - Return contextual information about the system and execution environment. +- [parameters()][parameters] - Return the value of a specified configuration parameter. +- [secret()][secret] - Retrieve a secret value from a secure store. +- [variables()][variables] - Return the value of a specified configuration variable. -### Data functions +### Lambda functions -The following list of functions operate on data outside of a resource instance: +The following functions create and use lambda functions, which DSC evaluates once for each element +of an array: -- [envvar()][envvar] - Return the value of a specified environment variable. -- [parameters()][parameters] - Return the value of a specified configuration parameter. -- [variables()][variables] - Return the value of a specified configuration variable. +- [filter()][filter] - Return a new array containing only the elements of an array for which a + lambda function returns true. +- [lambda()][lambda] - Create a lambda function with named parameters and a body expression for use + with `map()` and `filter()`. +- [lambdaVariables()][lambdaVariables] - Return the value bound to a named parameter of the lambda + function currently being evaluated. +- [map()][map] - Transform every element of an array with a lambda function and return the results + as a new array. + +### Logical functions -### Mathematics functions +The following functions perform logical operations: -The following list of functions operate on integer values or arrays of integer values: +- [and()][and] - Return true if all boolean values are true. +- [bool()][bool] - Convert a value to a boolean. +- [false()][false] - Return the boolean value false. +- [if()][if] - Return one of two values based on a boolean condition. +- [not()][not] - Return the logical negation of a boolean value. +- [or()][or] - Return true if any boolean value is true. +- [true()][true] - Return the boolean value true. + +### Numeric functions + +The following functions operate on integer values: - [add()][add] - Return the sum of two integers. +- [copyIndex()][copyIndex] - Return the current iteration index of a copy loop. - [div()][div] - Return the dividend of two integers as an integer, dropping the remainder of the result, if any. - [int()][int] - Convert a string or number with a fractional part into an integer. -- [max()][max] - Return the largest value from an array of integers. -- [min()][min] - Return the smallest value from an array of integers. +- [max()][max] - Return the largest integer value from an array of integers. +- [min()][min] - Return the smallest integer value from an array of integers. - [mod()][mod] - Return the remainder from the division of two integers. - [mul()][mul] - Return the product from multiplying two integers. - [sub()][sub] - Return the difference from subtracting one integer from another. +The `copyIndex()` function is only meaningful inside a resource that defines the `copy` property. +The `copy` property isn't a function, but it works together with `copyIndex()` to create multiple +instances of a resource. For more information, see [copy][copy]. + +### Object functions + +The following functions operate on objects: + +- [contains()][contains] - Check if an array contains a value or an object contains a key. +- [createObject()][createObject] - Create an object from key-value pairs. +- [empty()][empty] - Check if a value (string, array, or object) is empty. +- [intersection()][intersection] - Return a single array or object with the common elements from the + parameters. +- [items()][items] - Convert an object into an array of key-value pair objects. +- [json()][json] - Parse a JSON string and return the resulting value. +- [length()][length] - Return the number of elements in an array, characters in a string, or + top-level properties in an object. +- [null()][null] - Return a null value. +- [objectKeys()][objectKeys] - Return an array of the top-level keys of an object. +- [shallowMerge()][shallowMerge] - Combine an array of objects into a single object, merging only + the top-level properties. +- [tryGet()][tryGet] - Safely retrieve a value from an array by index or an object by key without + throwing an error. +- [union()][union] - Return a single array or object with all unique elements from the parameters. + ### Resource functions -The following list of functions operate on resource instances: +The following functions operate on resource instances: - [reference()][reference] - Return the result data for another resource instance. -- [resourceId()][resourceId] - Return the ID of another resource instance to reference or depend - on. +- [resourceId()][resourceId] - Return the ID of another resource instance to reference or depend on. ### String functions -The following list of functions are for manipulating strings: +The following functions manipulate strings: - [base64()][base64] - Return the base64 representation of a string. -- [concat()][concat] - Return a combined string where the input strings are concatenated in the - order they're specified. - -### Type functions +- [base64ToString()][base64ToString] - Decode a base64-encoded string and return the original + string. +- [concat()][concat] - Combine multiple strings into a single string, or multiple arrays into a + single array. +- [contains()][contains] - Check if an array contains a value or an object contains a key. +- [dataUri()][dataUri] - Convert a value to a data URI. +- [dataUriToString()][dataUriToString] - Convert a data URI formatted value to a string. +- [empty()][empty] - Check if a value (string, array, or object) is empty. +- [endsWith()][endsWith] - Check if a string ends with a specified suffix. +- [first()][first] - Return the first element of an array or the first character of a string. +- [format()][format] - Create a formatted string from input values. +- [indexOf()][indexOf] - Return the zero-based index of the first occurrence of a value in an array. +- [join()][join] - Combine array elements into a single string with a specified delimiter. +- [last()][last] - Return the last element of an array or the last character of a string. +- [lastIndexOf()][lastIndexOf] - Return the zero-based index of the last occurrence of a value in an + array. +- [length()][length] - Return the number of elements in an array, characters in a string, or + top-level properties in an object. +- [path()][path] - Construct a file system path from one or more path segments. +- [skip()][skip] - Return an array or string with elements skipped from the beginning. +- [startsWith()][startsWith] - Check if a string starts with a specified prefix. +- [string()][string] - Convert a value to its string representation. +- [substring()][substring] - Extract a portion of a string starting at a specified position. +- [take()][take] - Return an array or string with the specified number of elements from the start. +- [toLower()][toLower] - Convert a string to lowercase. +- [toUpper()][toUpper] - Convert a string to uppercase. +- [trim()][trim] - Remove leading and trailing whitespace from a string. +- [uniqueString()][uniqueString] - Create a deterministic hash string based on provided values. +- [uri()][uri] - Create an absolute URI by combining a base URI with a relative URI string. +- [uriComponent()][uriComponent] - Encode a string for use as a URI component. +- [uriComponentToString()][uriComponentToString] - Decode a URI-encoded string. + +### System functions + +The following functions return information about the system or the current execution of DSC: -The following list of functions create or convert values of a given type: - -- [createArray()][createArray] - Create an array of a given type from zero or more values of the - same type. -- [int()][int] - Convert a string or number with a fractional part into an integer. +- [envvar()][envvar] - Return the value of a specified environment variable. +- [restartRequired()][restartRequired] - Return whether a system, service, or process requires a + restart. +- [stateChanged()][stateChanged] - Return whether a resource instance changed state during a `set` + operation. +- [stdout()][stdout] - Return the standard output of an extension's `import` command for processing + in the manifest's `output` expression. +- [systemRoot()][systemRoot] - Return the system root directory path. +- [tryWhich()][tryWhich] - Return the full path to an executable found in the `PATH` environment + variable, or null if it isn't found. [01]: https://yaml.org/spec/1.2.2/#folded-style [02]: https://yaml.org/spec/1.2.2/#literal-style [03]: https://yaml.org/spec/1.2.2/#block-chomping-indicator +[04]: ../../../cli/function/list.md -[add]: ./add.md -[base64]: ./base64.md -[concat]: ./concat.md -[createArray]: ./createArray.md -[div]: ./div.md -[envvar]: ./envvar.md -[int]: ./int.md -[max]: ./max.md -[min]: ./min.md -[mod]: ./mod.md -[mul]: ./mul.md -[parameters]: ./parameters.md -[reference]: ./reference.md -[resourceId]: ./resourceId.md -[sub]: ./sub.md -[variables]: ./variables.md +[add]: ./add.md +[and]: ./and.md +[array]: ./array.md +[base64]: ./base64.md +[base64ToString]: ./base64ToString.md +[bool]: ./bool.md +[cidrHost]: ./cidrHost.md +[cidrSubnet]: ./cidrSubnet.md +[coalesce]: ./coalesce.md +[concat]: ./concat.md +[contains]: ./contains.md +[context]: ./context.md +[copy]: ./copy.md +[copyIndex]: ./copyIndex.md +[createArray]: ./createArray.md +[createObject]: ./createObject.md +[dataUri]: ./dataUri.md +[dataUriToString]: ./dataUriToString.md +[div]: ./div.md +[empty]: ./empty.md +[endsWith]: ./endsWith.md +[envvar]: ./envvar.md +[equals]: ./equals.md +[false]: ./false.md +[filter]: ./filter.md +[first]: ./first.md +[format]: ./format.md +[greater]: ./greater.md +[greaterOrEquals]: ./greaterOrEquals.md +[if]: ./if.md +[indexOf]: ./indexOf.md +[int]: ./int.md +[intersection]: ./intersection.md +[items]: ./items.md +[join]: ./join.md +[json]: ./json.md +[lambda]: ./lambda.md +[lambdaVariables]: ./lambdaVariables.md +[last]: ./last.md +[lastIndexOf]: ./lastIndexOf.md +[length]: ./length.md +[less]: ./less.md +[lessOrEquals]: ./lessOrEquals.md +[map]: ./map.md +[max]: ./max.md +[min]: ./min.md +[mod]: ./mod.md +[mul]: ./mul.md +[not]: ./not.md +[null]: ./null.md +[objectKeys]: ./objectKeys.md +[or]: ./or.md +[parameters]: ./parameters.md +[parseCidr]: ./parseCidr.md +[path]: ./path.md +[range]: ./range.md +[reference]: ./reference.md +[resourceId]: ./resourceId.md +[restartRequired]: ./restartRequired.md +[secret]: ./secret.md +[shallowMerge]: ./shallowMerge.md +[skip]: ./skip.md +[startsWith]: ./startsWith.md +[stateChanged]: ./stateChanged.md +[stdout]: ./stdout.md +[string]: ./string.md +[sub]: ./sub.md +[substring]: ./substring.md +[systemRoot]: ./systemRoot.md +[take]: ./take.md +[toLower]: ./toLower.md +[toUpper]: ./toUpper.md +[trim]: ./trim.md +[true]: ./true.md +[tryGet]: ./tryGet.md +[tryIndexFromEnd]: ./tryIndexFromEnd.md +[tryWhich]: ./tryWhich.md +[union]: ./union.md +[uniqueString]: ./uniqueString.md +[uri]: ./uri.md +[uriComponent]: ./uriComponent.md +[uriComponentToString]: ./uriComponentToString.md +[utcNow]: ./utcNow.md +[variables]: ./variables.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md index 9dae9662..e8790caa 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md @@ -1,6 +1,6 @@ --- description: Reference for the 'parameters' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: parameters --- @@ -91,7 +91,8 @@ hadErrors: false The `parameters()` function expects a single string as input, representing the name of the parameter to return. If no parameter with the specified name is defined in the configuration -document, DSC raises an error during validation. +document, DSC raises an error during validation. If the parameter is defined without a default +value and you don't provide a value for it, DSC raises an error when it evaluates the function. ```yaml Type: string @@ -105,10 +106,10 @@ MaximumCount: 1 The `parameters()` function returns the value of the specified parameter. ```yaml -Type: [string, int, bool, object, array] +Type: [string, int, bool, object, array, null] ``` [01]: ../parameter.md -[02]: ../../../cli/config/command.md#-p---parameters -[03]: ../../../cli/config/command.md#-f---parameters_file +[02]: ../../../cli/config/index.md#-p---parameters +[03]: ../../../cli/config/index.md#-f---parameters-file diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parseCidr.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parseCidr.md new file mode 100644 index 00000000..dbc8a9d2 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parseCidr.md @@ -0,0 +1,265 @@ +--- +description: Reference for the 'parseCidr' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: parseCidr +--- + +# parseCidr + +## Synopsis + +Parses a CIDR notation string and returns network information. + +## Syntax + +```Syntax +parseCidr() +``` + +## Description + +The `parseCidr()` function takes a [CIDR][01] (Classless Inter-Domain Routing) +notation string and returns an object containing detailed network information +including the network address, netmask, broadcast address, and usable IP range. +This function is useful for calculating network details when configuring +networking resources, firewall rules, or IP address management systems. + +The function supports both IPv4 and IPv6 CIDR notation and always requires +explicit prefix length (e.g., `/24` for IPv4 or `/64` for IPv6). + +## Examples + +### Example 1 - Parse standard IPv4 CIDR + +This configuration parses a typical `/24` network and displays the network +details including usable IP range. + +```yaml +# parseCidr.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Parse IPv4 network + type: Microsoft.DSC.Debug/Echo + properties: + output: "[parseCidr('192.168.1.0/24')]" +``` + +```bash +dsc config get --file parseCidr.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Parse IPv4 network + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + network: 192.168.1.0 + netmask: 255.255.255.0 + broadcast: 192.168.1.255 + firstUsable: 192.168.1.1 + lastUsable: 192.168.1.254 + cidr: 24 +messages: [] +hadErrors: false +``` + +### Example 2 - Calculate subnet details with parameters + +This example demonstrates using `parseCidr()` with the [`cidrSubnet()`][02] +function to create a subnet from a larger network block and extract its details. + +```yaml +# parseCidr.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + baseNetwork: + type: string + defaultValue: 10.0.0.0/16 + subnetPrefix: + type: int + defaultValue: 24 + subnetIndex: + type: int + defaultValue: 5 +resources: + - name: Calculate subnet details + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [parseCidr(cidrSubnet(parameters('baseNetwork'), parameters('subnetPrefix'), + parameters('subnetIndex')))] +``` + +```bash +dsc config get --file parseCidr.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Calculate subnet details + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + network: 10.0.5.0 + netmask: 255.255.255.0 + broadcast: 10.0.5.255 + firstUsable: 10.0.5.1 + lastUsable: 10.0.5.254 + cidr: 24 +messages: [] +hadErrors: false +``` + +### Example 3 - Extract specific network properties + +The configuration extracts specific properties from the parsed CIDR result to +configure network settings, demonstrating how to access individual fields from +the returned object. + +```yaml +# parseCidr.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + networkCidr: + type: string + defaultValue: 10.144.0.0/20 +resources: + - name: Network configuration + type: Microsoft.DSC.Debug/Echo + properties: + output: + networkAddress: "[parseCidr(parameters('networkCidr')).network]" + subnetMask: "[parseCidr(parameters('networkCidr')).netmask]" + gatewayIP: "[parseCidr(parameters('networkCidr')).firstUsable]" + broadcastIP: "[parseCidr(parameters('networkCidr')).broadcast]" + prefixLength: "[parseCidr(parameters('networkCidr')).cidr]" +``` + +```bash +dsc config get --file parseCidr.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Network configuration + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + networkAddress: 10.144.0.0 + subnetMask: 255.255.240.0 + gatewayIP: 10.144.0.1 + broadcastIP: 10.144.15.255 + prefixLength: 20 +messages: [] +hadErrors: false +``` + +### Example 4 - Parse IPv6 CIDR notation + +This configuration demonstrates parsing IPv6 CIDR notation, showing that the +function supports both IPv4 and IPv6 address families. + +```yaml +# parseCidr.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Parse IPv6 network + type: Microsoft.DSC.Debug/Echo + properties: + output: "[parseCidr('2001:db8::/32')]" +``` + +```bash +dsc config get --file parseCidr.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Parse IPv6 network + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + network: 2001:db8:: + netmask: ffff:ffff:: + firstUsable: 2001:db8:: + lastUsable: 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff + cidr: 32 +messages: [] +hadErrors: false +``` + +## Parameters + +### cidrNotation + +The `parseCidr()` function expects a single string in valid CIDR notation +format. The string must include both an IP address and a prefix length +separated by a forward slash (e.g., `192.168.1.0/24` or `2001:db8::/32`). + +The function raises an error if: + +- The input doesn't contain a forward slash (`/`) +- The IP address format is invalid +- The prefix length is out of valid range (0-32 for IPv4, 0-128 for IPv6) + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `parseCidr()` function returns an object with the following properties: + +For **IPv4** addresses: + +- `network`: The network address (string) +- `netmask`: The subnet mask in dotted decimal notation (string) +- `broadcast`: The broadcast address (string) +- `firstUsable`: The first usable host IP address (string) +- `lastUsable`: The last usable host IP address (string) +- `cidr`: The prefix length (integer) + +For **IPv6** addresses: + +- `network`: The network address (string) +- `netmask`: The network mask (string) +- `firstUsable`: The first usable address (same as network for IPv6) (string) +- `lastUsable`: The last address in the network (string) +- `cidr`: The prefix length (integer) + +**Note**: For `/32` IPv4 networks (single host), `firstUsable` and `lastUsable` +are both set to the network address since there are no additional host addresses. + +```yaml +Type: object +``` + +## Exceptions + +The `parseCidr()` function raises errors for the following conditions: + +- **Missing prefix**: When the CIDR string doesn't include a prefix length + (e.g., `192.168.1.0` without `/24`) +- **Invalid IP address**: When the IP address portion is malformed +- **Invalid prefix length**: When the prefix is out of valid range or not a number + +## Related functions + +- [`cidrSubnet()`][02] - Creates a subnet from a larger CIDR block +- [`cidrHost()`][03] - Calculates a host IP address within a CIDR block +- [`parameters()`][04] - Retrieves parameter values + + +[01]: https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing +[02]: ./cidrSubnet.md +[03]: ./cidrHost.md +[04]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/path.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/path.md new file mode 100644 index 00000000..b657d3ff --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/path.md @@ -0,0 +1,190 @@ +--- +description: Reference for the 'path' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: path +--- + +# path + +## Synopsis + +Construct a file system path from one or more path segments + +## Syntax + +```Syntax +path(, , ...) +``` + +## Description + +The `path()` function takes a base path and any number of child items to combine +into a single path, accounting for duplicate `/` characters. + +## Examples + +### Example 1 - Construct with child path + +This configuration constructs a simple absolute path of two elements. + +```yaml +# parseChildPath.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Simple Path Construct + type: Microsoft.DSC.Debug/Echo + properties: + output: "[path('C:\\Program Files', 'WindowsPowerShell')]" +``` + +```bash +dsc config get --file parseChildPath.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Simple Path Construct + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: C:\Program Files\WindowsPowerShell +messages: [] +hadErrors: false +``` + +### Example 2 - Relative path with multiple elements + +This configuration constructs a simple relative path of three elements. + +```yaml +# relativePath.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Relative Path + type: Microsoft.DSC.Debug/Echo + properties: + output: "[path('.\\usr', 'bin', 'bash')]" +``` + +```bash +dsc config get --file relativePath.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Relative Path + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: .\usr\bin\bash +messages: [] +hadErrors: false +``` + +### Example 3 - Relative element in path + +This configuration constructs a path with a double dot in that path. + +The path is returned as-is and is not resolved to an absolute path. + +```yaml +# doubleDot.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Double Dot Path + type: Microsoft.DSC.Debug/Echo + properties: + output: "[path('parent', '..', 'child')]" +``` + +```bash +dsc config get --file doubleDot.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Double Dot Path + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: parent\..\child +messages: [] +hadErrors: false +``` + +## Parameters + +### path + +Defines the base path that the function appends child path segments to. The base path must be a +string value. It can be any of the following kinds of paths: + +- Absolute, like `C:\Windows\System32` or `/usr/bin` +- Relative, like `.\infrastructure` or `../compliance/pci` +- Universal Naming Convention (UNC), such as `\\server1\c$\Windows` + +```yaml +Type: string +Required: true +Position: 1 +``` + +### child + +Defines the child path segments the function appends to the base path. The function expects at +least one child path segment. Every child path segment must be a string value. + +The function appends each segment to the output path in the order that you specify them. The +function inserts the operating system's path separator (`\` on Windows, `/` on Linux and macOS) +between each defined segment unless the segment has a trailing forward slash (`/`). + +> [!NOTE] +> On Windows systems, when you specify any absolute path as a child path segment, like `C:\dsc`, +> the function _replaces_ the currently constructed path with that absolute path segment. +> +> For example, `[path('./a', 'b', 'C:\', 'd')]` resolves to `C:\d` on Windows and `./a/b/C:\/d` +> on non-Windows systems. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 18446744073709551615 +``` + +## Output + +Returns the concatenated path, made from the provided elements. + +The output path for the same input depends on the operating systems: + +- The function uses the operating system's defined path separator for appending child path segments + to the base path (`\` for Windows and `/` for Linux and macOS). + + For example, `[path('a', 'b', 'c')]` resolves to `a\b\c` on Windows and `a/b/c` on Linux and + macOS. +- On Windows, specifying a child path segment that begins with a drive letter _replaces_ the + constructed path instead of appending to it. + + For example, `[path('./a', 'b', 'C:\', 'd')]` resolves to `C:\d` on Windows and `./a/b/C:\/d` + on non-Windows systems. + +```yaml +Type: string +``` + +## Errors + +The function returns an error in the following cases: + +- **Invalid type**: Any argument is not a string + +## Related functions + +- [`join()`][01] - Joins an array into a single string, separated using a delimiter. +- [`uri()`][02] - Creates an absolute URI by combining the baseUri and the relativeUri string. + + +[01]: ./join.md +[02]: ./uri.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/range.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/range.md new file mode 100644 index 00000000..63bbf439 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/range.md @@ -0,0 +1,249 @@ +--- +description: Reference for the 'range' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: range +--- + +# range + +## Synopsis + +Creates an array of integers from a starting integer and containing a number of +items. + +## Syntax + +```Syntax +range(startIndex, count) +``` + +## Description + +The `range()` function generates a sequence of consecutive integers starting +from `startIndex` and containing `count` number of items. This is useful for +creating numeric sequences, iterating over indices, or generating test data. + +The sum of `startIndex` and `count` must not exceed 2,147,483,647 (the maximum +value for a 32-bit signed integer). The `count` parameter must be a +non-negative integer up to 10,000. + +## Examples + +### Example 1 - Generate server port numbers for load balancer configuration + +Use `range()` to create a sequence of port numbers for configuring multiple +backend servers in a load balancer. This ensures consistent port allocation +across your infrastructure. + +```yaml +# range.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Load Balancer Ports + type: Microsoft.DSC.Debug/Echo + properties: + output: + backendPorts: "[range(8080, 5)]" + alternativePorts: "[range(9000, 3)]" +``` + +```bash +dsc config get --file range.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Load Balancer Ports + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + backendPorts: + - 8080 + - 8081 + - 8082 + - 8083 + - 8084 + alternativePorts: + - 9000 + - 9001 + - 9002 +messages: [] +hadErrors: false +``` + +### Example 2 - Create worker node identifiers for container orchestration + +Generate sequential identifiers for worker nodes in a container cluster. This +is helpful when provisioning multiple identical workers that need unique +numeric identifiers. + +```yaml +# range.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Worker Node IDs + type: Microsoft.DSC.Debug/Echo + properties: + output: + workerIds: "[range(1, 8)]" + testNodeIds: "[range(100, 3)]" +``` + +```bash +dsc config get --file range.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Worker Node IDs + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + workerIds: + - 1 + - 2 + - 3 + - 4 + - 5 + - 6 + - 7 + - 8 + testNodeIds: + - 100 + - 101 + - 102 +messages: [] +hadErrors: false +``` + +### Example 3 - Generate database partition numbers with negative starting values + +Create partition identifiers that include negative numbers, useful for +time-series data partitioning or when working with offset-based indexing +systems. + +```yaml +# range.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Database Partitions + type: Microsoft.DSC.Debug/Echo + properties: + output: + timeOffsets: "[range(-3, 7)]" + emptyRange: "[range(50, 0)]" +``` + +```bash +dsc config get --file range.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Database Partitions + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + timeOffsets: + - -3 + - -2 + - -1 + - 0 + - 1 + - 2 + - 3 + emptyRange: [] +messages: [] +hadErrors: false +``` + +### Example 4 - Create year sequences for data archiving policies + +Generate sequences of years for implementing data retention policies or +creating time-based archive structures. This example shows practical year +ranges for typical business scenarios. + +```yaml +# range.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Archive Years + type: Microsoft.DSC.Debug/Echo + properties: + output: + recentYears: "[range(2020, 5)]" + fiscalYears: "[range(2022, 3)]" +``` + +```bash +dsc config get --file range.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Archive Years + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + recentYears: + - 2020 + - 2021 + - 2022 + - 2023 + - 2024 + fiscalYears: + - 2022 + - 2023 + - 2024 +messages: [] +hadErrors: false +``` + +## Parameters + +### startIndex + +The first integer in the array. + +```yaml +Type: int +Required: true +Position: 1 +``` + +### count + +The number of integers in the array. Must be a non-negative integer up to +10,000. The sum of `startIndex` and `count` must not exceed 2,147,483,647. + +```yaml +Type: int +Required: true +Position: 2 +``` + +## Output + +Returns an array of consecutive integers starting from `startIndex`. + +```yaml +Type: array +``` + +## Related functions + +- [`createArray()`][00] - Creates an array from individual values +- [`length()`][01] - Returns the number of elements in an array +- [`first()`][02] - Returns the first element of an array +- [`skip()`][03] - Returns array elements after skipping a specified number + + +[00]: ./createArray.md +[01]: ./length.md +[02]: ./first.md +[03]: ./skip.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/reference.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/reference.md index 1df9dd71..c986091a 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/reference.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/reference.md @@ -1,6 +1,6 @@ --- description: Reference for the 'reference' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: reference --- @@ -37,9 +37,10 @@ earlier instances. The instances don't need to be of the same type. ### Example 1 - Referencing a top-level instance -In this example configuration, the `Microsoft.DSC.Debug/Echo` resource instance echoes the `bitness` property of -the `Microsoft/OSInfo` resource. It uses the `reference()` function to retrieve the actual state of -the resource and uses the dot-path notation to access the **bitness** property of that resource. +In this example configuration, the `Microsoft.DSC.Debug/Echo` resource instance echoes the +`bitness` property of the `Microsoft/OSInfo` resource. It uses the `reference()` function to +retrieve the actual state of the resource and uses the dot-path notation to access the +**bitness** property of that resource. ```yaml # reference.example.1.dsc.config.yaml @@ -51,13 +52,13 @@ resources: - name: Echo bitness type: Microsoft.DSC.Debug/Echo properties: - output: "[reference(resourceId('Microsoft/OSInfo', 'System')).actualState.bitness]" + output: "[reference(resourceId('Microsoft/OSInfo', 'System')).bitness]" dependsOn: - "[resourceId('Microsoft/OSInfo', 'System')]" ``` ```bash -dsc config get --file reference.example.1.dsc.config.yaml config get +dsc config get --file reference.example.1.dsc.config.yaml ``` ```yaml @@ -126,7 +127,8 @@ operation: - [Simple set response][08] You can use dot-notation to access the properties of the referenced instance, as in -[Example 1](#example-1---referencing-a-top-level-instance). +[Example 1](#example-1---referencing-a-top-level-instance). When you access a property this +way, the function returns the value of that property, which can be any JSON type. > [!NOTE] > You can't reuse references to `actualState` for `get` and `test` operations in the `set` @@ -135,7 +137,7 @@ You can use dot-notation to access the properties of the referenced instance, as > want to use a reference for all three operations. ```yaml -Type: [Object, Array] +Type: [array, boolean, number, object, string] ``` diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/resourceId.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/resourceId.md index 659f29f0..6c6f22b3 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/resourceId.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/resourceId.md @@ -1,6 +1,6 @@ --- description: Reference for the 'resourceId' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: resourceId --- @@ -90,7 +90,7 @@ The value of the [type][03] property of the resource instance to reference. The ```yaml Type: string Required: true -Position: 0 +Position: 1 ``` ### instanceName @@ -100,7 +100,19 @@ The value of the [name][05] property of the resource instance to reference. ```yaml Type: string Required: true -Position: 0 +Position: 2 +``` + +## Output + +The `resourceId()` function returns a string that uniquely identifies the resource instance. The +string has the format `:`. DSC percent-encodes the instance name, +so spaces and other special characters are escaped. For example, +`[resourceId('Microsoft.Windows/Registry', 'Tailspin Key')]` returns +`Microsoft.Windows/Registry:Tailspin%20Key`. + +```yaml +Type: string ``` diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/restartRequired.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/restartRequired.md new file mode 100644 index 00000000..a60fab44 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/restartRequired.md @@ -0,0 +1,119 @@ +--- +description: Reference for the 'restartRequired' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: restartRequired +--- + +# restartRequired + +## Synopsis + +Returns whether a system, service, or process requires a restart. + +## Syntax + +```Syntax +restartRequired('system') +restartRequired('service', '') +restartRequired('process', '') +``` + +## Description + +The `restartRequired()` function returns whether a resource in the current configuration operation +reported a required restart. DSC aggregates restart requirements returned by resources in the +configuration context. + +Use `system` to query whether a system restart is required. Use `service` or `process` to query a +specific service or process by name. For `service` and `process`, the `name` argument is required. +For `system`, the `name` argument isn't allowed. + +The function returns `false` when no matching restart requirement has been reported. + +## Examples + +### Example 1 - Query restart requirements + +This configuration queries whether installing the OpenSSH Client capability with the +[Microsoft.Windows/FeatureOnDemandList][01] resource requires a system restart. When the resource +reports a system restart requirement, `restartRequired()` returns `true`. + +> [!NOTE] +> This example requires Windows, an elevated session, and access to a Windows Update or WSUS +> source. Capability installation does not always require a restart. + +```yaml +# restartRequired.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Install OpenSSH Client + type: Microsoft.Windows/FeatureOnDemandList + properties: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed +outputs: + systemRestartRequired: + type: bool + value: "[restartRequired('system')]" +``` + +```bash +dsc config set --file restartRequired.example.1.dsc.config.yaml +``` + +When the resource instances report the corresponding restart requirements, DSC returns: + +```yaml +outputs: + systemRestartRequired: true +``` + +To query a service or process restart requirement, specify its name as the second argument: + +```Syntax +restartRequired('service', 'example-service') +restartRequired('process', 'example-process') +``` + +## Parameters + +### kind + +The kind of restart requirement to query. The value must be `process`, `service`, or `system`. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +AllowedValues: +- process +- service +- system +``` + +### name + +The name of the process or service to query. This argument is required when **kind** is `process` +or `service`, and it isn't allowed when **kind** is `system`. + +```yaml +Type: string +Required: conditional +MinimumCount: 0 +MaximumCount: 1 +``` + +## Output + +The `restartRequired()` function returns `true` when a matching restart requirement was reported +by a resource in the current configuration operation. Otherwise, it returns `false`. + +```yaml +Type: bool +``` + + +[01]: ../../../resources/Microsoft/Windows/FeatureOnDemandList/index.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/secret.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/secret.md new file mode 100644 index 00000000..dfd32b70 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/secret.md @@ -0,0 +1,233 @@ +--- +description: Reference for the 'secret' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: secret +--- + +# secret + +## Synopsis + +Retrieves secrets from registered secret management extensions. + +## Syntax + +```Syntax +secret() +secret(, ) +``` + +## Description + +The `secret()` function retrieves secrets from extensions that support the secret capability. It +queries all registered extensions that implement secret management and returns the requested secret +value. If multiple extensions return different values for the same secret name, an error is +returned unless a vault is specified to disambiguate. + +The function supports two calling patterns: + +- Single argument: Retrieves a secret by name from any available vault +- Two arguments: Retrieves a secret by name from a specific vault + +If multiple extensions return the same secret value, the function succeeds and returns that value. +This allows for redundancy across secret management systems. + +## Examples + +### Example 1 - Retrieve a secret by name + +The following example retrieves a secret named `DatabasePassword` from any available vault. The +secret expression is used directly as the output value. + +```yaml +# secret.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Database Connection + type: Microsoft.DSC.Debug/Echo + properties: + output: "[secret('DatabasePassword')]" +``` + +```bash +dsc config get --file secret.example.1.dsc.config.yaml +``` + +```yaml +executionInformation: + duration: PT11.2326172S + endDatetime: 2026-05-05T09:55:33.313388600-05:00 + executionType: actual + operation: get + securityContext: restricted + startDatetime: 2026-05-05T09:55:22.080771400-05:00 + version: 3.2.0 +metadata: + Microsoft.DSC: + duration: PT11.2325964S + endDatetime: 2026-05-05T09:55:33.313367800-05:00 + executionType: actual + operation: get + securityContext: restricted + startDatetime: 2026-05-05T09:55:22.080771400-05:00 + version: 3.2.0 +results: +- executionInformation: + duration: PT2.0098514S + metadata: + Microsoft.DSC: + duration: PT2.0098514S + name: Database Connection + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: "MySecretPassword123" +messages: [] +hadErrors: false +``` + +> [!NOTE] +> In this example the secret is emitted in plain text in the output. This is because the `secret` +> function doesn't automatically wrap the result in a `secureString` wrapper. It passes the +> discovered secret directly to the resource as a string. +> +> DSC doesn't emit secrets to the console or through trace messages itself. However, DSC can't +> control whether a resource emits secrets. In this case, the secret was emitted by the `Echo` +> resource in its output. For more information about handling secrets in a configuration, see +> [Security considerations](#security-considerations). + +### Example 2 - Pass a secret through a parameter default + +The following example defines a `secureString` parameter whose default value is the secret. The +resource then uses the parameter value for the output property. + +```yaml +# secret.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + myString: + type: secureString + defaultValue: "[secret('MySecret')]" +resources: +- name: Database Connection + type: Microsoft.DSC.Debug/Echo + properties: + output: "[parameters('myString')]" +``` + +```bash +dsc config get --file secret.example.2.dsc.config.yaml +``` + +```yaml +executionInformation: + duration: PT13.5097206S + endDatetime: 2026-05-05T10:26:29.721210400-05:00 + executionType: actual + operation: get + securityContext: restricted + startDatetime: 2026-05-05T10:26:16.211489800-05:00 + version: 3.2.0 +metadata: + Microsoft.DSC: + duration: PT13.5097028S + endDatetime: 2026-05-05T10:26:29.721192600-05:00 + executionType: actual + operation: get + securityContext: restricted + startDatetime: 2026-05-05T10:26:16.211489800-05:00 + version: 3.2.0 +results: +- executionInformation: + duration: PT1.451969S + metadata: + Microsoft.DSC: + duration: PT1.451969S + name: Database Connection + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: +messages: [] +hadErrors: false +``` + +> [!NOTE] +> In this case, the value for the secret has been redacted because it was passed to the `Echo` +> resource as a `secureString` value. + +## Parameters + +### name + +The name of the secret to retrieve. + +DSC passes this value to every extension with the `secret` capability as-is. Whether this value is +case-sensitive depends on the extension and the secret vault that it uses. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### vault + +The name of the vault or secret store to retrieve the secret from. When specified, only the named +vault is queried for the secret, which helps disambiguate when multiple vaults contain secrets with +the same name. + +DSC passes this value to every extension with the `secret` capability as-is. Whether this value is +case-sensitive depends on the extension and the secret vault that it uses. + +```yaml +Type: string +Required: false +Position: 2 +``` + +## Output + +The `secret()` function returns the secret value as a string. + +```yaml +Type: string +``` + +## Error conditions + +The `secret()` function can return errors in the following situations: + +- **No extensions available**: No secret management extensions are registered + or available +- **Secret not found**: The specified secret name does not exist in any + available vault +- **Multiple different values**: Multiple extensions return different values + for the same secret name (specify a vault to disambiguate) +- **Vault not found**: The specified vault does not exist or is not accessible +- **Extension error**: An underlying secret management extension returns an + error + +## Security considerations + +- DSC retrieves secret values at runtime and doesn't cache them. +- DSC invokes the `secret` operation for every available extension with that capability on each + usage of the `secret()` function in a configuration document. +- When you invoke DSC with `--trace-level` as `TRACE`, unwrapped secret values are emitted in trace + messages as part of the JSON Validation trace message for resource input. + + When the secret values are wrapped as a `secureObject` or `secureString`, DSC redacts the value + in trace messaging where it appears instead as ``. +- DSC doesn't automatically wrap retrieved secrets as `secureString` instances. When a secret is + wrapped as a `secureString`, like `{"secureString":""}`, the resource is responsible for + unwrapping the data. Check the JSON Schema and documentation for the resources you use to see + whether they support `secureString` values. + +## Related functions + +- [`parameters()`][00] - Access configuration parameters that may influence + secret selection + + +[00]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/shallowMerge.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/shallowMerge.md new file mode 100644 index 00000000..a85b6571 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/shallowMerge.md @@ -0,0 +1,498 @@ +--- +description: Reference for the 'shallowMerge' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: shallowMerge +--- + +# shallowMerge + +## Synopsis + +Combines an array of objects into a single object where only the top-level properties are merged. + +## Syntax + +```Syntax +shallowMerge() +``` + +## Description + +The `shallowMerge()` function takes an array of objects and combines them into a single +object by merging their properties. When the same property name appears in multiple objects, +the value from the last object in the array with that property takes precedence. + +This is a _shallow merge_, which applies the following rules: + +- The first object in the array defines the base value for the merged object. +- The function processes each object in the array in the order they're defined. +- When processing each object, the function iterates over every top-level property defined for that + object and: + + - If the merged object doesn't already have the property, the function adds that property to the + merged object with the value from the current object. + - If the merged object does have the property, the function _replaces_ the existing value with + the value from the current object, even when the value is an object or array. + +This function is useful for: + +- Building composite configuration objects from multiple sources. +- Applying configuration overrides where later values take precedence. +- Combining default settings with user-specified customizations. +- Merging environment-specific configurations. + +The shallow merge behavior differs from a deep merge (like [`union()`][00]) where nested +objects are recursively merged. The `shallowMerge()` function replaces nested structures +entirely with the value defined by the last object with that property in the input array. + +## Examples + +### Example 1 - Merge configuration objects + +The following example demonstrates merging two configuration objects where the second object +overrides properties from the first. + +```yaml +# shallowMerge.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +variables: + configArray: + - host: localhost + port: 8080 + - port: 9000 + ssl: true +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[shallowMerge(variables('configArray'))]" +``` + +```bash +dsc config get --file shallowMerge.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + host: localhost + port: 9000 + ssl: true +messages: [] +hadErrors: false +``` + +In this example, the `port` value from the second object (`9000`) replaces the value from the first +object (`8080`), while properties that only exist in one object (`host` and `ssl`) are preserved. + +### Example 2 - Apply multiple configuration layers + +The following example shows combining multiple configuration layers using parameters, where +later objects in the array override properties from earlier objects. + +```yaml +# shallowMerge.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + defaults: + type: object + defaultValue: + timeout: 30 + retries: 3 + debug: false + environment: + type: object + defaultValue: + timeout: 60 + userPrefs: + type: object + defaultValue: + debug: true +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [shallowMerge( + createArray( + parameters('defaults'), + parameters('environment'), + parameters('userPrefs') + ) + )] +``` + +```bash +dsc config get --file shallowMerge.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + timeout: 60 + retries: 3 + debug: true +messages: [] +hadErrors: false +``` + +The final configuration shows `timeout` overridden by environment settings, `debug` +overridden by user preferences, and `retries` preserved from defaults. + +### Example 3 - Shallow merge replaces nested objects + +The following example demonstrates the key difference between shallow and deep merge. When a +property contains a nested object, the entire nested object is replaced rather than merged. + +```yaml +# shallowMerge.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [shallowMerge( + createArray( + createObject( + 'database', + createObject('host', 'localhost', 'port', 5432, 'ssl', true()) + ), + createObject( + 'database', + createObject('host', 'prod.db.local') + ) + ) + )] +``` + +```bash +dsc config get --file shallowMerge.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + database: + host: prod.db.local +messages: [] +hadErrors: false +``` + +The second object's `database` property completely replaces the first object's `database`, +losing the `port` and `ssl` properties. This is the shallow merge behavior. + +### Example 4 - Merge with empty objects + +The following example shows that empty objects in the array don't affect the merge result. + +```yaml +# shallowMerge.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [shallowMerge( + createArray( + createObject('name', 'Service1', 'enabled', true()), + createObject(), + createObject('version', '2.0') + ) + )] +``` + +```bash +dsc config get --file shallowMerge.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + name: Service1 + enabled: true + version: '2.0' +messages: [] +hadErrors: false +``` + +The empty object in the middle doesn't remove or affect any properties. + +### Example 5 - Build feature flags from multiple sources + +The following example merges base flags with team-specific and environment-specific overrides, +where each subsequent object overrides specific flags while preserving others. + +```yaml +# shallowMerge.example.5.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [shallowMerge( + createArray( + createObject('newUI', false(), 'darkMode', true(), 'beta', false()), + createObject('newUI', true()), createObject('beta', true()) + ) + )] +``` + +```bash +dsc config get --file shallowMerge.example.5.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + newUI: true + darkMode: true + beta: true +messages: [] +hadErrors: false +``` + +Each subsequent object overrides specific flags while preserving others. + +### Example 6 - Merge array results from parameters + +The following example demonstrates merging parameter-based objects where the last occurrence +of each property wins, resulting in a single merged object. + +```yaml +# shallowMerge.example.6.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + objects: + type: array + defaultValue: + - name: alpha + priority: 1 + - name: beta + priority: 2 + - name: beta + priority: 10 + critical: true +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: "[shallowMerge(parameters('objects'))]" +``` + +```bash +dsc config get --file shallowMerge.example.6.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + name: beta + priority: 10 + critical: true +messages: [] +hadErrors: false +``` + +The last occurrence of each property wins, resulting in a single merged object. + +### Example 7 - Combine with objectKeys for validation + +The following example uses `shallowMerge()` with [`objectKeys()`][01] and [`contains()`][05] +to validate that all expected configuration keys are present after merging. + +```yaml +# shallowMerge.example.7.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + baseConfig: + type: object + defaultValue: + timeout: 30 + retries: 3 + overrides: + type: object + defaultValue: + timeout: 60 +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: + merged: >- + [shallowMerge( + createArray( + parameters('baseConfig'), + parameters('overrides') + ) + )] + keys: >- + [objectKeys( + shallowMerge( + createArray( + parameters('baseConfig'), + parameters('overrides') + ) + ) + )] + hasRetries: >- + [contains( + objectKeys( + shallowMerge( + createArray( + parameters('baseConfig'), + parameters('overrides') + ) + ) + ), + 'retries' + )] +``` + +```bash +dsc config get --file shallowMerge.example.7.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + merged: + timeout: 60 + retries: 3 + keys: + - timeout + - retries + hasRetries: true +messages: [] +hadErrors: false +``` + +This pattern ensures the merged configuration includes required properties. + +### Example 8 - Empty array returns empty object + +The following example shows that `shallowMerge()` returns an empty object when given an +empty array. It uses [`objectKeys()`][01], [`length()`][06], and [`equals()`][07] to verify +the result is empty. + +```yaml +# shallowMerge.example.8.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: + result: "[shallowMerge(createArray())]" + isEmpty: "[equals(length(objectKeys(shallowMerge(createArray()))), 0)]" +``` + +```bash +dsc config get --file shallowMerge.example.8.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + result: {} + isEmpty: true +messages: [] +hadErrors: false +``` + +## Parameters + +### inputArray + +An array of objects to merge. Each element in the array should be an object. Non-object +elements in the array are silently ignored during the merge process. + +```yaml +Type: array +Required: true +Position: 1 +``` + +## Output + +Returns a single object containing all properties from the input objects. When the same property +appears in multiple objects, the value from the last object in the array with that property is +retained, replacing all prior values for the property. + +```yaml +Type: object +``` + +## Error conditions + +The function will return an error in the following cases: + +- **Not an array**: The input is not an array (e.g., object, string, number, null) + +## Notes + +- This function performs a _shallow merge_ - the function replaces nested objects, it doesn't merge + them recursively. +- The function replaces the value for properties defined by earlier objects in the input array with + the value from objects later in the array. +- The function ignores empty objects in the input array. +- The function ignores non-object elements in the input array. +- The function returns an empty object when the input is an empty array. +- The function processes objects in array order, so the last object has highest precedence +- For recursive/deep merging of nested objects, consider using [`union()`][00] instead. + +## Related functions + +- [`union()`][00] - Combines arrays or performs deep merge of objects +- [`createArray()`][02] - Creates an array from values +- [`createObject()`][03] - Creates an object from key-value pairs +- [`objectKeys()`][01] - Returns an array of keys from an object +- [`items()`][04] - Converts an object to an array of key-value pairs +- [`contains()`][05] - Checks if an array contains a specific value +- [`length()`][06] - Returns the number of elements in an array +- [`equals()`][07] - Compares two values for equality + + +[00]: ./union.md +[01]: ./objectKeys.md +[02]: ./createArray.md +[03]: ./createObject.md +[04]: ./items.md +[05]: ./contains.md +[06]: ./length.md +[07]: ./equals.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/skip.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/skip.md new file mode 100644 index 00000000..222a58ff --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/skip.md @@ -0,0 +1,149 @@ +--- +description: Reference for the 'skip' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: skip +--- + +# skip + +## Synopsis + +Returns an array with all the elements after the specified number in the array, +or returns a string with all the characters after the specified number in the +string. + +## Syntax + +```Syntax +skip(, ) +``` + +## Description + +The `skip()` function returns the tail of an array or string by skipping a +specified number of items from the start. + +- For arrays: returns a new array containing elements after the specified index +- For strings: returns a new string containing characters after the specified index + +Both parameters are required. `originalValue` must be an array or a string. +`numberToSkip` must be an integer; negative values are treated as zero. If the +number is greater than the length of the array or string, the function returns +an empty array or an empty string respectively. + +## Examples + +### Example 1 - Skip elements in an array + +The following example returns the tail of an array by skipping the first two +elements. + +```yaml +# skip.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Tail of array + type: Microsoft.DSC.Debug/Echo + properties: + output: + tail: "[skip(createArray('a','b','c','d'), 2)]" +``` + +```bash +dsc config get --file skip.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Tail of array + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + tail: + - c + - d +messages: [] +hadErrors: false +``` + +### Example 2 - Skip characters in a string + +The following example returns the substring of a string by skipping the first +two characters. + +```yaml +# skip.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Tail of string + type: Microsoft.DSC.Debug/Echo + properties: + output: + tail: "[skip('hello', 2)]" +``` + +```bash +dsc config get --file skip.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Tail of string + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + tail: llo +messages: [] +hadErrors: false +``` + +## Parameters + +### originalValue + +The value to skip items from. Can be an array or a string. + +```yaml +Type: array | string +Required: true +Position: 1 +``` + +### numberToSkip + +The number of items to skip from the start. Must be an integer. Negative values +are treated as zero. + +```yaml +Type: int +Required: true +Position: 2 +``` + +## Output + +Returns the same type as `originalValue`: + +- If `originalValue` is an array, returns an array +- If `originalValue` is a string, returns a string + +```yaml +Type: array | string +``` + +## Error conditions + +- `originalValue` is not an array or string +- `numberToSkip` is not an integer + +## Related functions + +- [`first()`][00] - Returns the first element or character +- [`length()`][01] - Returns the number of elements or characters + + +[00]: ./first.md +[01]: ./length.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/startsWith.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/startsWith.md new file mode 100644 index 00000000..2980ecb6 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/startsWith.md @@ -0,0 +1,183 @@ +--- +description: Reference for the 'startsWith' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: startsWith +--- + +# startsWith + +## Synopsis + +Determines whether a string starts with the specified prefix. + +## Syntax + +```Syntax +startsWith(, ) +``` + +## Description + +The `startsWith()` function returns `true` if the first string starts with the +specified prefix. Comparison is case-sensitive. Use it for conditional logic in +configuration documents such as grouping resource names, validating identifiers, +or routing operations based on naming conventions. + +## Examples + +### Example 1 - Validate resource naming convention + +The following example checks if a resource name follows a standard prefix. + +```yaml +# startswith.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + resourceName: + type: string + defaultValue: svc-api-west +resources: +- name: Resource naming check + type: Microsoft.DSC.Debug/Echo + properties: + output: + hasSvcPrefix: "[startsWith(parameters('resourceName'), 'svc-')]" +``` + +```bash +dsc config get --file startswith.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Resource naming check + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + hasSvcPrefix: true +messages: [] +hadErrors: false +``` + +### Example 2 - Conditional routing + +The following example shows using `startsWith()` with `if()` to categorize a +service by its name prefix. + +```yaml +# startswith.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + serviceName: + type: string + defaultValue: api-orders +resources: +- name: Service classification + type: Microsoft.DSC.Debug/Echo + properties: + output: + classification: >- + [if(startsWith(parameters('serviceName'), 'api-'), 'API Service', + 'Other Service')] +``` + +```bash +dsc config get --file startswith.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Service classification + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + classification: API Service +messages: [] +hadErrors: false +``` + +### Example 3 - Multi-prefix evaluation + +The following example evaluates multiple possible prefixes. + +```yaml +# startswith.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + name: + type: string + defaultValue: db-primary-01 +resources: +- name: Prefix grouping + type: Microsoft.DSC.Debug/Echo + properties: + output: + isDb: "[startsWith(parameters('name'), 'db-')]" + isApi: "[startsWith(parameters('name'), 'api-')]" + isCache: "[startsWith(parameters('name'), 'cache-')]" +``` + +```bash +dsc config get --file startswith.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Prefix grouping + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + isDb: true + isApi: false + isCache: false +messages: [] +hadErrors: false +``` + +## Parameters + +### string + +The input string to evaluate. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### prefix + +The prefix string to test for. + +```yaml +Type: string +Required: true +Position: 2 +``` + +## Output + +The `startsWith()` function returns a boolean value indicating whether the +input string starts with the specified prefix. + +```yaml +Type: bool +``` + +## Related functions + +- [`endsWith()`][00] - Determines whether a string ends with a suffix +- [`concat()`][01] - Concatenates strings together +- [`if()`][02] - Returns values based on a condition +- [`string()`][03] - Converts values to strings + + +[00]: ./endsWith.md +[01]: ./concat.md +[02]: ./if.md +[03]: ./string.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/stateChanged.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/stateChanged.md new file mode 100644 index 00000000..d556945c --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/stateChanged.md @@ -0,0 +1,109 @@ +--- +description: Reference for the 'stateChanged' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: stateChanged +--- + +# stateChanged + +## Synopsis + +Returns whether a resource instance changed state during the current `set` operation. + +## Syntax + +```Syntax +stateChanged(resourceId('', '')) +``` + +## Description + +The `stateChanged()` function returns `true` when the referenced resource instance changed one or +more properties during the current `set` operation. Otherwise, it returns `false`. + +The function can only evaluate an instance after DSC has executed it. Use [resourceId()][01] to +identify the instance and add that instance to the calling resource's [dependsOn][02] property. +When DSC evaluates `stateChanged()` for an instance that has not run or does not exist, it returns +an error. + +## Examples + +### Example 1 - Report whether a resource changed state + +The configuration sets the **Install OpenSSH Client** instance with the +[Microsoft.Windows/FeatureOnDemandList][03] resource and then runs the **Report change** instance. +The second instance uses `stateChanged()` to report whether the feature resource changed state. Its +`dependsOn` property ensures the feature instance has completed before DSC evaluates the function. + +> [!NOTE] +> This example requires Windows, an elevated session, and access to a Windows Update or WSUS +> source. The output is `true` only when installing the feature changes state. + +```yaml +# stateChanged.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Install OpenSSH Client + type: Microsoft.Windows/FeatureOnDemandList + properties: + capabilities: + - identity: OpenSSH.Client~~~~0.0.1.0 + state: Installed +- name: Report change + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [stateChanged(resourceId('Microsoft.Windows/FeatureOnDemandList', + 'Install OpenSSH Client'))] + dependsOn: + - "[resourceId('Microsoft.Windows/FeatureOnDemandList', 'Install OpenSSH Client')]" +``` + +```bash +dsc config set --file stateChanged.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Install OpenSSH Client + type: Microsoft.Windows/FeatureOnDemandList + result: + changedProperties: + - capabilities +- name: Report change + type: Microsoft.DSC.Debug/Echo + result: + afterState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +### resourceId + +The resource ID of the instance whose state change information you want to retrieve. Use the +[resourceId()][01] function to create this value. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `stateChanged()` function returns `true` if the resource changed one or more properties in the +current `set` operation. Otherwise, it returns `false`. + +```yaml +Type: bool +``` + + +[01]: ./resourceId.md +[02]: ../resource.md#dependson +[03]: ../../../resources/Microsoft/Windows/FeatureOnDemandList/index.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/stdout.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/stdout.md new file mode 100644 index 00000000..b16fec02 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/stdout.md @@ -0,0 +1,179 @@ +--- +description: Reference for the 'stdout' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: stdout +--- + +# stdout + +## Synopsis + +Returns the standard output of the command that a DSC extension ran to import a file, for use in +the `output` expression of the extension manifest's `import` method. + +## Syntax + +```Syntax +stdout() +``` + +## Description + +The `stdout()` function returns, as a string, the standard output that DSC captured from the last +command it ran. DSC only provides this value in one situation: when it processes the `output` +expression of an extension's `import` method. + +When you pass a file to DSC with the `--file` option, DSC first checks whether any discovered +extension with the `import` capability lists the file's extension in the `fileExtensions` property +of its `import` method. If one does, DSC runs the command defined by that method's `executable` +and `args` properties and captures the command's standard output. Then: + +- If the `import` method doesn't define the `output` property, DSC uses the captured standard + output as the imported content. +- If the `import` method defines the `output` property, DSC evaluates that property as an + expression. Inside the expression, `stdout()` returns the captured standard output. DSC converts + the value the expression returns to JSON and uses it as the imported content. + +DSC then processes the imported content as the configuration document. + +Use `stdout()` when the command's standard output isn't a configuration document by itself but +contains one or can be converted into one. For example, the expression can parse the output with +[`json()`][00] and use the property access syntax to extract the document from a wrapper object. + +The `output` expression must return an object for the imported content to be a valid +configuration document. If the expression returns a string, DSC converts it to a JSON string +literal, which isn't a valid document. To use the standard output as-is, omit the `output` +property instead of defining it as `[stdout()]`. + +DSC evaluates the `output` expression in a new, empty context. The expression can't access +configuration parameters, variables, or resource references. It can only use `stdout()` and +functions that don't depend on the configuration document. + +Despite the wording of the description in the output of `dsc function list`, DSC doesn't provide +the standard output of resources to configuration documents. Using `stdout()` in a configuration +document always raises an error. + +## Examples + +### Example 1 - Import a wrapped configuration document + +The following extension manifest defines an `import` method for files with the `wrapped` file +extension. The command uses PowerShell to read the file and write its content to standard output. +The `output` expression parses that output with [`json()`][00] and returns the `document` +property, which contains the actual configuration document. + +Save the manifest as `wrapped.dsc.extension.json` in a folder that's included in the `PATH` +environment variable so DSC can discover it. + +```json +{ + "$schema": "https://aka.ms/dsc/schemas/v3/bundled/extension/manifest.json", + "type": "Example.Import/Wrapped", + "version": "0.1.0", + "description": "Imports configuration documents wrapped in a JSON envelope.", + "import": { + "fileExtensions": ["wrapped"], + "executable": "pwsh", + "args": ["-NoProfile", "-Command", "Get-Content", "-Raw", { "fileArg": "-Path" }], + "output": "[json(stdout()).document]" + } +} +``` + +When an entry in `args` is an object with the `fileArg` property, DSC replaces it with the value +of `fileArg` followed by the absolute path to the file being imported. + +The following file wraps a configuration document in an object with `format` and `document` +properties. Save it as `stdout.example.1.dsc.config.wrapped`. + +```json +{ + "format": "wrapped", + "document": { + "$schema": "https://aka.ms/dsc/schemas/v3/bundled/config/document.json", + "resources": [ + { + "name": "Echo", + "type": "Microsoft.DSC.Debug/Echo", + "properties": { + "output": "Imported through stdout()" + } + } + ] + } +} +``` + +```bash +dsc config get --file stdout.example.1.dsc.config.wrapped +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Imported through stdout() +messages: [] +hadErrors: false +``` + +When DSC processes this command, it: + +1. Discovers the `Example.Import/Wrapped` extension and matches the file's `wrapped` extension + against the `fileExtensions` property. +1. Runs `pwsh -NoProfile -Command Get-Content -Raw -Path ` and captures + the standard output. +1. Evaluates `[json(stdout()).document]`, where `stdout()` returns the captured content. +1. Processes the object returned by the expression as the configuration document. + +## Parameters + +The function doesn't accept any arguments. + +## Output + +Returns the standard output that DSC captured from the extension's import command. + +```yaml +Type: string +``` + +## Error conditions + +The function raises an error in the following cases: + +- **No standard output available**: The function is used anywhere other than in the `output` + expression of an extension's `import` method, including in a configuration document. DSC raises + `No standard output is available from the last executed resource`. +- **Arguments passed**: The function is called with one or more arguments. DSC raises + `Function 'stdout' does not accept arguments`. + +If the `output` expression itself raises an error while DSC imports a file, DSC doesn't report +that error. Instead, it tries any other extension with the `import` capability and then reads the +file directly as a configuration document, which usually fails with a parsing error about the +file's content. + +## Notes + +- The only place DSC sets the value that `stdout()` returns is when it processes the `output` + expression of an extension's `import` method. Resources don't expose their standard output to + configuration documents through this function. +- DSC only evaluates the `output` expression when the import command wrote something to standard + output. +- DSC evaluates the `output` expression in a new context without any configuration parameters or + variables. +- The `output` expression should return an object, not a string, so that the imported content is + a valid configuration document. +- For more information about extension manifests, see the + [DSC extension manifest schema reference][01]. + +## Related functions + +- [`json()`][00] - Parses a JSON string and returns the resulting value + + +[00]: ./json.md +[01]: ../../extension/manifest/root.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/string.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/string.md new file mode 100644 index 00000000..9c92ef73 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/string.md @@ -0,0 +1,262 @@ +--- +description: Reference for the 'string' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: string +--- + +# string + +## Synopsis + +Converts a value to a string representation. + +## Syntax + +```Syntax +string() +``` + +## Description + +The `string()` function converts a value of any type to its string +representation. This is useful for formatting output, concatenating values, or +ensuring consistent data types. Arrays and objects are converted to JSON +strings, while primitive types are converted to their standard string +representations. + +## Examples + +### Example 1 - Convert integers to strings + +The following example shows how to convert numbers to strings for display +purposes. + +```yaml +# string.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + serverCount: + type: int + defaultValue: 42 + memorySize: + type: int + defaultValue: 16 +resources: +- name: Convert numbers + type: Microsoft.DSC.Debug/Echo + properties: + output: + serverCountString: "[string(parameters('serverCount'))]" + memorySizeString: "[string(parameters('memorySize'))]" + literalNumber: "[string(123)]" +``` + +```bash +dsc config get --file string.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Convert numbers + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + serverCountString: '42' + memorySizeString: '16' + literalNumber: '123' +messages: [] +hadErrors: false +``` + +### Example 2 - Convert arrays and objects to JSON strings + +The following example shows how arrays and objects are converted to JSON +strings. + +```yaml +# string.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + serverList: + type: array + defaultValue: + - web01 + - web02 + - db01 + config: + type: object + defaultValue: + timeout: 30 + retries: 3 + enabled: true +resources: +- name: Convert collections + type: Microsoft.DSC.Debug/Echo + properties: + output: + serversJson: "[string(parameters('serverList'))]" + configJson: "[string(parameters('config'))]" + arrayLiteral: "[string(createArray('a', 'b'))]" +``` + +```bash +dsc config get --file string.example.3.dsc.config.yaml +``` + +```yaml +results: +- metadata: + Microsoft.DSC: + duration: PT0.1452881S + name: Convert collections + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + serversJson: '["web01","web02","db01"]' + configJson: '{"timeout":30,"retries":3,"enabled":true}' + arrayLiteral: '["a","b"]' +messages: [] +hadErrors: false +``` + +### Example 3 - Building formatted messages + +The following example shows a practical use case for building formatted +messages using string conversion. + +```yaml +# string.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + deploymentId: + type: int + defaultValue: 12345 + isProduction: + type: bool + defaultValue: false + serverCount: + type: int + defaultValue: 3 +resources: +- name: Build status message + type: Microsoft.DSC.Debug/Echo + properties: + output: + deploymentInfo: >- + [concat('Deployment ', string(parameters('deploymentId')), ' running in ', + if(parameters('isProduction'), 'production', 'development'), ' mode')] + serverMessage: >- + [concat('Managing ', string(parameters('serverCount')), ' server(s)')] + statusFlag: "[concat('Production: ', string(parameters('isProduction')))]" +``` + +```bash +dsc config get --file string.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Build status message + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + deploymentInfo: Deployment 12345 running in development mode + serverMessage: Managing 3 server(s) + statusFlag: 'Production: false' +messages: [] +hadErrors: false +``` + +### Example 4 - String conversion for logging + +The following example demonstrates converting various data types for logging +purposes. + +```yaml +# string.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + timestamp: + type: int + defaultValue: 1691596800 + errorCode: + type: int + defaultValue: 404 + metadata: + type: object + defaultValue: + source: "api" + level: "error" +resources: +- name: Generate log entry + type: Microsoft.DSC.Debug/Echo + properties: + output: + logEntry: >- + [concat('[', string(parameters('timestamp')), '] ERROR ', + string(parameters('errorCode')), ': ', string(parameters('metadata')))] +``` + +```bash +dsc config get --file string.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Generate log entry + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + logEntry: '[1691596800] ERROR 404: {"source":"api","level":"error"}' +messages: [] +hadErrors: false +``` + +## Parameters + +### value + +The value to convert to a string. + +```yaml +Type: [string, number, bool, null, array, object] +Required: true +``` + +The `string()` function accepts exactly one input value of any type. The +conversion behavior depends on the input type: + +- **String**: Returns the string unchanged +- **Number**: Converts to decimal string representation +- **Boolean**: Converts to "true" or "false" +- **Null**: Converts to "null" +- **Array**: Converts to JSON array string +- **Object**: Converts to JSON object string + +## Output + +The `string()` function returns the string representation of the input value. + +```yaml +Type: string +``` + +## Related functions + +- [`concat()`][00] - Concatenates strings together +- [`int()`][01] - Converts a string to an integer +- [`bool()`][02] - Converts a string to a boolean +- [`base64()`][03] - Encodes a string to base64 format +- [`length()`][04] - Returns the length of a string + + +[00]: ./concat.md +[01]: ./int.md +[02]: ./bool.md +[03]: ./base64.md +[04]: ./length.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/sub.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/sub.md index 35532769..a83bceaf 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/sub.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/sub.md @@ -1,6 +1,6 @@ --- description: Reference for the 'sub' DSC configuration document function -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: sub --- @@ -19,8 +19,8 @@ sub() ## Description -The `sub()` function returns the difference of two integers. It subtracts the second operand from the -first operand. You can nest calls to `sub()` to subtract more than two integers. +The `sub()` function returns the difference of two integers. It subtracts the second operand from +the first operand. You can nest calls to `sub()` to subtract more than two integers. ## Examples diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/substring.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/substring.md new file mode 100644 index 00000000..d2324644 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/substring.md @@ -0,0 +1,267 @@ +--- +description: Reference for the 'substring' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: substring +--- + +# substring + +## Synopsis + +Returns a substring that starts at the specified character position and contains +the specified number of characters. + +## Syntax + +```Syntax +substring(, ) +substring(, , ) +``` + +## Description + +The `substring()` function extracts a portion of a string based on the specified +starting position and optional length. The function uses zero-based indexing, +meaning the first character is at position 0. This is useful for parsing +identifiers, extracting prefixes or suffixes, manipulating configuration values, +or formatting display strings. + +Key behaviors: + +- **Zero-based indexing**: The first character is at index 0 +- **Optional length**: If length is omitted, returns the remainder of the string + from the start position +- **Boundary validation**: Prevents access beyond string boundaries with clear + error messages + +## Examples + +### Example 1 - Extract environment from resource name + +This example demonstrates extracting environment information from standardized +resource names for conditional configuration. It uses the [`parameters()`][08] +function to retrieve the resource name. + +```yaml +# substring.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + resourceName: + type: string + defaultValue: svc-api-prod-east +resources: +- name: Extract environment + type: Microsoft.DSC.Debug/Echo + properties: + output: + environment: "[substring(parameters('resourceName'), 8, 4)]" +``` + +```bash +dsc config get --file substring.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Extract environment + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + environment: prod +messages: [] +hadErrors: false +``` + +### Example 2 - Extract region from resource identifier + +This example shows extracting a region code from a standardized resource +identifier without specifying length, using [`parameters()`][08] to retrieve +the identifier. + +```yaml +# substring.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + resourceId: + type: string + defaultValue: app-web-eastus2-001 +resources: +- name: Extract region + type: Microsoft.DSC.Debug/Echo + properties: + output: + region: "[substring(parameters('resourceId'), 8)]" +``` + +```bash +dsc config get --file substring.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Extract region + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + region: eastus2-001 +messages: [] +hadErrors: false +``` + +### Example 3 - Parse version components + +This example demonstrates parsing semantic version strings to extract major, +minor, and patch components. It uses [`parameters()`][08] to retrieve the +version string. + +```yaml +# substring.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + version: + type: string + defaultValue: "3.2.1" +resources: +- name: Parse version + type: Microsoft.DSC.Debug/Echo + properties: + output: + major: "[substring(parameters('version'), 0, 1)]" + minor: "[substring(parameters('version'), 2, 1)]" + patch: "[substring(parameters('version'), 4, 1)]" +``` + +```bash +dsc config get --file substring.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Parse version + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + major: "3" + minor: "2" + patch: "1" +messages: [] +hadErrors: false +``` + +### Example 4 - Unicode and emoji support + +This example shows that `substring()` correctly handles Unicode characters and +emojis. It uses [`parameters()`][08] to retrieve the message string. + +```yaml +# substring.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + message: + type: string + defaultValue: "Hello 🌍 World!" +resources: +- name: Unicode substring + type: Microsoft.DSC.Debug/Echo + properties: + output: + greeting: "[substring(parameters('message'), 0, 5)]" + emoji: "[substring(parameters('message'), 6, 1)]" + remainder: "[substring(parameters('message'), 8)]" +``` + +```bash +dsc config get --file substring.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Unicode substring + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + greeting: Hello + emoji: 🌍 + remainder: " World!" +messages: [] +hadErrors: false +``` + +## Parameters + +### stringToParse + +The original string from which the substring is extracted. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### startIndex + +The zero-based starting character position for the substring. Must be a +non-negative integer and cannot exceed the length of the string. + +```yaml +Type: int +Required: true +Position: 2 +``` + +### length + +The number of characters for the substring. Must be a non-negative integer. The +start index plus length cannot exceed the length of the string. If omitted, the +remainder of the string from the start position is returned. + +```yaml +Type: int +Required: false +Position: 3 +``` + +## Output + +The `substring()` function returns a string containing the extracted portion of +the original string. + +```yaml +Type: string +``` + +## Exceptions + +The `substring()` function raises errors for the following conditions: + +- **Invalid start index**: When `startIndex` is negative +- **Start index out of bounds**: When `startIndex` exceeds the string length +- **Invalid length**: When `length` is negative +- **Length out of bounds**: When `startIndex + length` exceeds the string + length + +## Related functions + +- [`string()`][00] - Converts values to strings +- [`concat()`][01] - Concatenates strings together +- [`indexOf()`][02] - Finds the index of a substring in a string +- [`lastIndexOf()`][03] - Finds the last index of a substring in a string +- [`length()`][04] - Returns the length of a string or array +- [`startsWith()`][05] - Checks if a string starts with a prefix +- [`endsWith()`][06] - Checks if a string ends with a suffix + + +[00]: ./string.md +[01]: ./concat.md +[02]: ./indexOf.md +[03]: ./lastIndexOf.md +[04]: ./length.md +[05]: ./startsWith.md +[06]: ./endsWith.md +[08]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/systemRoot.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/systemRoot.md new file mode 100644 index 00000000..e0d5decd --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/systemRoot.md @@ -0,0 +1,98 @@ +--- +description: Reference for the 'systemRoot' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: systemRoot +--- + +# systemRoot + +## Synopsis + +Returns the system root path. + +## Syntax + +```Syntax +systemRoot() +``` + +## Description + +The `systemRoot()` function returns the value of the [system root path][01]. + +## Examples + +### Example 1 - Get the current system root + +The configuration uses the `systemRoot()` function to echo the current system root. + +```yaml +# systemRoot.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo system root + type: Microsoft.DSC.Debug/Echo + properties: + output: "[systemRoot()]" +``` + +```bash +dsc config get --file systemRoot.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo system root + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: C:\ +messages: [] +hadErrors: false +``` + +### Example 2 - Construct and override the system root path + +The configuration uses the [`path()`][02] function to construct a path from the `systemRoot()`, +which is overridden using in the command line. + +```yaml +# joinSystemRoot.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo system home + type: Microsoft.DSC.Debug/Echo + properties: + output: "[path(systemRoot(), 'home')]" +``` + +```bash +dsc config --system-root / get --file joinSystemRoot.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo system home + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: /home +messages: [] +hadErrors: false +``` + +## Output + +The `systemRoot()` function returns the system root of the current host, or the value overriden +using the [`--system-root` command line flag][01]. + +This is usually `C:\` on Windows system and `/` on Unix systems. + +```yaml +Type: string +``` + + +[01]: ../../../cli/config/index.md#-r---system-root +[02]: ./path.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/take.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/take.md new file mode 100644 index 00000000..0371f9b1 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/take.md @@ -0,0 +1,327 @@ +--- +description: Reference for the 'take' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: take +--- + +# take + +## Synopsis + +Returns an array with the specified number of elements from the start of an +array, or a string with the specified number of characters from the start of a +string. + +## Syntax + +```Syntax +take(originalValue, numberToTake) +``` + +## Description + +The `take()` function extracts a specified number of elements from the beginning +of an array or characters from the beginning of a string. This is useful for +limiting results, implementing pagination, or extracting prefixes from larger +datasets. + +- For arrays: returns a new array containing the first `n` elements +- For strings: returns a new string containing the first `n` characters + +Both parameters are required. The `originalValue` must be an array or a string. +The `numberToTake` must be an integer. If the number is zero or negative, an +empty array or empty string is returned. If the number is larger than the length +of the array or string, all elements or characters are returned. + +This function is particularly useful when you need to: + +- Limit the number of items processed from a list +- Extract a fixed-length prefix from identifiers or paths +- Implement top-N selections without complex filtering +- Create pagination or batch processing logic + +## Examples + +### Example 1 - Limit deployment to top priority servers + +Deploy configuration changes to only the highest priority servers first, limiting +risk during rollout. The `take()` function extracts the first N servers from +your priority list. This example uses [`parameters()`][00] to reference the +server list. + +```yaml +# take.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + allServers: + type: array + defaultValue: + - prod-web-01 + - prod-web-02 + - prod-web-03 + - prod-web-04 + - prod-web-05 +resources: +- name: Priority Deployment + type: Microsoft.DSC.Debug/Echo + properties: + output: + allServers: "[parameters('allServers')]" + deployToFirst: "[take(parameters('allServers'), 2)]" + description: Deploy to first 2 servers in priority order +``` + +```bash +dsc config get --file take.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Priority Deployment + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + allServers: + - prod-web-01 + - prod-web-02 + - prod-web-03 + - prod-web-04 + - prod-web-05 + deployToFirst: + - prod-web-01 + - prod-web-02 + description: Deploy to first 2 servers in priority order +messages: [] +hadErrors: false +``` + +The function returns only the first two servers from the list, allowing you to +implement a staged rollout strategy. + +### Example 2 - Extract environment prefix from resource names + +When working with standardized naming conventions, extracting prefixes helps +with categorization and routing logic. This example shows how to use `take()` to +get environment codes from resource identifiers. This example uses +[`createArray()`][01] to build the resource name list. + +```yaml +# take.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Resource Prefixes + type: Microsoft.DSC.Debug/Echo + properties: + output: + resources: >- + [createArray('prod-db-east-01', 'dev-api-west-02', 'test-cache-central')] + prodPrefix: "[take('prod-db-east-01', 4)]" + devPrefix: "[take('dev-api-west-02', 3)]" + testPrefix: "[take('test-cache-central', 4)]" +``` + +```bash +dsc config get --file take.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Resource Prefixes + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + resources: + - prod-db-east-01 + - dev-api-west-02 + - test-cache-central + prodPrefix: prod + devPrefix: dev + testPrefix: test +messages: [] +hadErrors: false +``` + +The function extracts the environment prefix from each resource name, enabling +environment-specific configuration logic. + +### Example 3 - Implement batch processing with size limits + +Processing items in controlled batches prevents resource exhaustion when dealing +with large datasets. By using `take()`, you can limit the number of items +processed in each run. This example uses [`parameters()`][00] to reference the +pending jobs array and [`length()`][02] to show the total count. + +```yaml +# take.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + pendingJobs: + type: array + defaultValue: + - job-001 + - job-002 + - job-003 + - job-004 + - job-005 + - job-006 + - job-007 + - job-008 +resources: +- name: Batch Processing + type: Microsoft.DSC.Debug/Echo + properties: + output: + totalPending: "[length(parameters('pendingJobs'))]" + currentBatch: "[take(parameters('pendingJobs'), 3)]" + batchSize: 3 + description: Process first 3 jobs from queue +``` + +```bash +dsc config get --file take.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Batch Processing + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + totalPending: 8 + currentBatch: + - job-001 + - job-002 + - job-003 + batchSize: 3 + description: Process first 3 jobs from queue +messages: [] +hadErrors: false +``` + +The function returns the first three jobs for processing, allowing you to +implement controlled batch processing with predictable resource usage. + +### Example 4 - Select top-N log entries for monitoring + +Pagination-style access to log entries or event streams can be implemented by +combining `take()` with [`skip()`][03]. This example shows how to get the most +recent entries while demonstrating the complementary relationship between these +functions. This example uses [`parameters()`][00] to reference the log entries +array. + +```yaml +# take.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + recentLogs: + type: array + defaultValue: + - 2025-11-01 10:00:00 - System started + - 2025-11-01 10:05:32 - User login: admin + - 2025-11-01 10:07:15 - Config updated + - 2025-11-01 10:12:48 - Service restarted + - 2025-11-01 10:15:03 - Backup completed + - 2025-11-01 10:20:17 - Health check passed + - 2025-11-01 10:25:44 - Cache cleared +resources: +- name: Log Monitoring + type: Microsoft.DSC.Debug/Echo + properties: + output: + topThree: "[take(parameters('recentLogs'), 3)]" + nextThree: "[take(skip(parameters('recentLogs'), 3), 3)]" + description: Show first 3 and next 3 log entries +``` + +```bash +dsc config get --file take.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Log Monitoring + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + topThree: + - 2025-11-01 10:00:00 - System started + - 2025-11-01 10:05:32 - User login: admin + - 2025-11-01 10:07:15 - Config updated + nextThree: + - 2025-11-01 10:12:48 - Service restarted + - 2025-11-01 10:15:03 - Backup completed + - 2025-11-01 10:20:17 - Health check passed + description: Show first 3 and next 3 log entries +messages: [] +hadErrors: false +``` + +By combining `take()` and `skip()`, you can implement pagination logic to +process logs or events in manageable chunks. + +## Parameters + +### originalValue + +The array or string to take elements from. Required. + +```yaml +Type: array | string +Required: true +Position: 1 +``` + +### numberToTake + +The number of elements or characters to take from the start. Must be an integer. +If this value is 0 or less, an empty array or string is returned. If it's larger +than the length of the given array or string, all elements or characters are +returned. Required. + +```yaml +Type: integer +Required: true +Position: 2 +``` + +## Output + +Returns the same type as `originalValue`: + +- If `originalValue` is an array, returns an array with up to `numberToTake` + elements from the start +- If `originalValue` is a string, returns a string with up to `numberToTake` + characters from the start + +```yaml +Type: array | string +``` + +## Errors + +The function returns an error in the following cases: + +- **Invalid original value type**: The first argument is not an array or string +- **Invalid number type**: The second argument is not an integer + +## Related functions + +- [`skip()`][03] - Returns an array or string with elements skipped from the start +- [`first()`][04] - Returns the first element of an array or first character of a string +- [`last()`][05] - Returns the last element of an array or last character of a string +- [`length()`][02] - Returns the number of elements in an array or characters in a string +- [`createArray()`][01] - Creates an array from provided values +- [`parameters()`][00] - Returns the value of a specified configuration parameter + + +[00]: ./parameters.md +[01]: ./createArray.md +[02]: ./length.md +[03]: ./skip.md +[04]: ./first.md +[05]: ./last.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/toLower.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/toLower.md new file mode 100644 index 00000000..2d5674dd --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/toLower.md @@ -0,0 +1,222 @@ +--- +description: Reference for the 'toLower' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: toLower +--- + +# toLower + +## Synopsis + +Converts the specified string to lower case. + +## Syntax + +```Syntax +toLower() +``` + +## Description + +The `toLower()` function converts all uppercase letters in the input string to +lowercase letters. Numbers, symbols, punctuation, and whitespace are unchanged. +The function supports Unicode characters and preserves the original string +structure. Use it for normalizing string comparisons, creating consistent +naming conventions, or formatting output for case-sensitive operations. + +## Examples + +### Example 1 - Normalize resource names + +The following example converts a parameter value to lowercase for consistent +resource naming. + +```yaml +# tolower.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + resourceName: + type: string + defaultValue: WEB-API-SERVICE +resources: +- name: Resource name normalization + type: Microsoft.DSC.Debug/Echo + properties: + output: + originalName: "[parameters('resourceName')]" + normalizedName: "[toLower(parameters('resourceName'))]" +``` + +```bash +dsc config get --file tolower.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Resource name normalization + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + originalName: WEB-API-SERVICE + normalizedName: web-api-service +messages: [] +hadErrors: false +``` + +### Example 2 - Create consistent file paths + +The following example demonstrates using `toLower()` with the [`concat()`][01] +function to create lowercase file paths. + +```yaml +# tolower.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + fileName: + type: string + defaultValue: CONFIG-FILE + extension: + type: string + defaultValue: JSON +resources: +- name: File path creation + type: Microsoft.DSC.Debug/Echo + properties: + output: + filePath: >- + [concat('/etc/', toLower(parameters('fileName')), '.', + toLower(parameters('extension')))] +``` + +```bash +dsc config get --file tolower.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: File path creation + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + filePath: /etc/config-file.json +messages: [] +hadErrors: false +``` + +### Example 3 - Case-insensitive comparison preparation + +The following example uses `toLower()` to normalize strings for comparison +using the `equals()` function. + +```yaml +# tolower.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + userInput: + type: string + defaultValue: Production + expectedValue: + type: string + defaultValue: PRODUCTION +resources: +- name: Case-insensitive comparison + type: Microsoft.DSC.Debug/Echo + properties: + output: + matches: >- + [equals(toLower(parameters('userInput')), toLower(parameters('expectedValue')))] +``` + +```bash +dsc config get --file tolower.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Case-insensitive comparison + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + matches: true +messages: [] +hadErrors: false +``` + +### Example 4 - Unicode and special character handling + +The following example shows how `toLower()` handles Unicode characters and +preserves special characters. + +```yaml +# tolower.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Unicode and special character conversion + type: Microsoft.DSC.Debug/Echo + properties: + output: + ascii: "[toLower('HELLO WORLD!')]" + unicode: "[toLower('CAFÉ RÉSUMÉ')]" + mixed: "[toLower('SERVER-01 (PRIMARY)')]" +``` + +```bash +dsc config get --file tolower.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Unicode and special character conversion + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + ascii: hello world! + unicode: café résumé + mixed: server-01 (primary) +messages: [] +hadErrors: false +``` + +## Parameters + +### stringToChange + +The string value to convert to lower case. + +```yaml +Type: string +Required: true +Position: 1 +``` + +## Output + +The `toLower()` function returns the input string with all uppercase letters +converted to lowercase. Numbers, symbols, punctuation, and whitespace remain +unchanged. + +```yaml +Type: string +``` + +## Related functions + +- [`toUpper()`][00] - Converts a string to upper case +- [`concat()`][01] - Concatenates strings together +- [`equals()`][02] - Compares two values for equality +- [`if()`][03] - Returns values based on a condition +- [`string()`][04] - Converts values to strings +- [`parameters()`][05] - Retrieves parameter values + + +[00]: ./toUpper.md +[01]: ./concat.md +[02]: ./equals.md +[03]: ./if.md +[04]: ./string.md +[05]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/toUpper.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/toUpper.md new file mode 100644 index 00000000..5565528c --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/toUpper.md @@ -0,0 +1,221 @@ +--- +description: Reference for the 'toUpper' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: toUpper +--- + +# toUpper + +## Synopsis + +Converts the specified string to upper case. + +## Syntax + +```Syntax +toUpper() +``` + +## Description + +The `toUpper()` function converts all lowercase letters in the input string to +uppercase letters. Numbers, symbols, punctuation, and whitespace are unchanged. +The function supports Unicode characters and preserves the original string +structure. Use it for normalizing string comparisons, formatting output, or +ensuring consistent casing in configuration values. + +## Examples + +### Example 1 - Convert user input to uppercase + +The following example converts a parameter value to uppercase for consistent +processing. + +```yaml +# toupper.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + serviceName: + type: string + defaultValue: web-api-service +resources: +- name: Service name conversion + type: Microsoft.DSC.Debug/Echo + properties: + output: + originalName: "[parameters('serviceName')]" + upperName: "[toUpper(parameters('serviceName'))]" +``` + +```bash +dsc config get --file toupper.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Service name conversion + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + originalName: web-api-service + upperName: WEB-API-SERVICE +messages: [] +hadErrors: false +``` + +### Example 2 - Format configuration values + +The following example demonstrates using `toUpper()` with the [`concat()`][01] +function to create formatted configuration keys. + +```yaml +# toupper.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + environment: + type: string + defaultValue: production + component: + type: string + defaultValue: database +resources: +- name: Configuration key formatting + type: Microsoft.DSC.Debug/Echo + properties: + output: + configKey: >- + [concat(toUpper(parameters('environment')), '_', + toUpper(parameters('component')), '_CONFIG')] +``` + +```bash +dsc config get --file toupper.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Configuration key formatting + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + configKey: PRODUCTION_DATABASE_CONFIG +messages: [] +hadErrors: false +``` + +### Example 3 - Conditional uppercase conversion + +The following example uses `toUpper()` conditionally with the [`if()`][02] +function based on a parameter value. + +```yaml +# toupper.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + text: + type: string + defaultValue: Hello World + shouldCapitalize: + type: bool + defaultValue: true +resources: +- name: Conditional uppercase + type: Microsoft.DSC.Debug/Echo + properties: + output: + result: >- + [if(parameters('shouldCapitalize'), toUpper(parameters('text')), + parameters('text'))] +``` + +```bash +dsc config get --file toupper.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Conditional uppercase + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + result: HELLO WORLD +messages: [] +hadErrors: false +``` + +### Example 4 - Unicode and special character handling + +The following example shows how `toUpper()` handles Unicode characters and +preserves special characters. + +```yaml +# toupper.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Unicode and special character conversion + type: Microsoft.DSC.Debug/Echo + properties: + output: + ascii: "[toUpper('hello world!')]" + unicode: "[toUpper('café résumé')]" + mixed: "[toUpper('Server-01 (primary)')]" +``` + +```bash +dsc config get --file toupper.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Unicode and special character conversion + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + ascii: HELLO WORLD! + unicode: CAFÉ RÉSUMÉ + mixed: SERVER-01 (PRIMARY) +messages: [] +hadErrors: false +``` + +## Parameters + +### stringToChange + +The string value to convert to upper case. + +```yaml +Type: string +Required: true +Position: 1 +``` + +## Output + +The `toUpper()` function returns the input string with all lowercase letters +converted to uppercase. Numbers, symbols, punctuation, and whitespace remain +unchanged. + +```yaml +Type: string +``` + +## Related functions + +- [`toLower()`][00] - Converts a string to lower case +- [`concat()`][01] - Concatenates strings together +- [`if()`][02] - Returns values based on a condition +- [`string()`][03] - Converts values to strings +- [`parameters()`][04] - Retrieves parameter values + + +[00]: ./toLower.md +[01]: ./concat.md +[02]: ./if.md +[03]: ./string.md +[04]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/trim.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/trim.md new file mode 100644 index 00000000..b8bede8a --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/trim.md @@ -0,0 +1,257 @@ +--- +description: Reference for the 'trim' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: trim +--- + +# trim + +## Synopsis + +Removes all leading and trailing whitespace characters from the specified string. + +## Syntax + +```Syntax +trim() +``` + +## Description + +The `trim()` function removes all leading and trailing whitespace characters from +the input string. Whitespace characters include spaces, tabs, newlines, carriage +returns, and other Unicode whitespace characters. The function preserves internal +whitespace within the string. Use it for cleaning user input, normalizing +configuration values, or preparing strings for comparison. + +## Examples + +### Example 1 - Clean user input + +The following example removes leading and trailing spaces from a parameter value. + +```yaml +# trim.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + userName: + type: string + defaultValue: ' admin ' +resources: +- name: Clean user input + type: Microsoft.DSC.Debug/Echo + properties: + output: + rawInput: "[parameters('userName')]" + cleanedInput: "[trim(parameters('userName'))]" +``` + +```bash +dsc config get --file trim.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Clean user input + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + rawInput: ' admin ' + cleanedInput: admin +messages: [] +hadErrors: false +``` + +### Example 2 - Normalize file paths + +The following example demonstrates using `trim()` with [`concat()`][01] to clean +path components before building a complete file path. + +```yaml +# trim.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + baseDir: + type: string + defaultValue: ' /var/log ' + fileName: + type: string + defaultValue: ' app.log ' +resources: +- name: Build clean file path + type: Microsoft.DSC.Debug/Echo + properties: + output: + filePath: "[concat(trim(parameters('baseDir')), '/', trim(parameters('fileName')))]" +``` + +```bash +dsc config get --file trim.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Build clean file path + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + filePath: /var/log/app.log +messages: [] +hadErrors: false +``` + +### Example 3 - Clean configuration values for comparison + +The following example uses `trim()` to normalize strings before comparing them with +the [`equals()`][02] function. + +```yaml +# trim.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + expectedEnv: + type: string + defaultValue: production + actualEnv: + type: string + defaultValue: ' production ' +resources: +- name: Environment comparison + type: Microsoft.DSC.Debug/Echo + properties: + output: + matches: "[equals(trim(parameters('actualEnv')), parameters('expectedEnv'))]" +``` + +```bash +dsc config get --file trim.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Environment comparison + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + matches: true +messages: [] +hadErrors: false +``` + +### Example 4 - Process multi-line configuration + +The following example shows how `trim()` handles tabs, newlines, and various +whitespace characters. + +```yaml +# trim.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Whitespace handling + type: Microsoft.DSC.Debug/Echo + properties: + output: + spaces: "[trim(' content ')]" + mixed: "[trim(' \t\n content \n\t ')]" + internal: "[trim(' multiple spaces inside ')]" +``` + +```bash +dsc config get --file trim.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Whitespace handling + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + spaces: content + mixed: content + internal: multiple spaces inside +messages: [] +hadErrors: false +``` + +### Example 5 - Combine with case conversion + +The following example demonstrates using `trim()` with [`toLower()`][00] to both +clean and normalize a string value. + +```yaml +# trim.example.5.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + serviceName: + type: string + defaultValue: ' WEB-SERVER ' +resources: +- name: Clean and normalize service name + type: Microsoft.DSC.Debug/Echo + properties: + output: + original: "[parameters('serviceName')]" + normalized: "[toLower(trim(parameters('serviceName')))]" +``` + +```bash +dsc config get --file trim.example.5.dsc.config.yaml +``` + +```yaml +results: +- name: Clean and normalize service name + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + original: ' WEB-SERVER ' + normalized: web-server +messages: [] +hadErrors: false +``` + +## Parameters + +### stringToTrim + +The string value to remove leading and trailing whitespace from. + +```yaml +Type: string +Required: true +Position: 1 +``` + +## Output + +The `trim()` function returns the input string with all leading and trailing +whitespace characters removed. Internal whitespace is preserved. + +```yaml +Type: string +``` + +## Related functions + +- [`toLower()`][00] - Converts a string to lower case +- [`concat()`][01] - Concatenates strings together +- [`equals()`][02] - Compares two values for equality +- [`startsWith()`][03] - Checks if a string starts with a value +- [`endsWith()`][04] - Checks if a string ends with a value +- [`substring()`][05] - Extracts a portion of a string +- [`parameters()`][06] - Retrieves parameter values + + +[00]: ./toLower.md +[01]: ./concat.md +[02]: ./equals.md +[03]: ./startsWith.md +[04]: ./endsWith.md +[05]: ./substring.md +[06]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/true.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/true.md new file mode 100644 index 00000000..4c5ce8fe --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/true.md @@ -0,0 +1,76 @@ +--- +description: Reference for the 'true' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: true +--- + +# true + +## Synopsis + +Returns the boolean value true. + +## Syntax + +```Syntax +true() +``` + +## Description + +The `true()` function returns the boolean value `true`. This function takes no arguments and +always returns `true`. It's useful for providing explicit boolean values in configurations +or for logical operations. + +## Examples + +### Example 1 - Basic true value + +This configuration demonstrates basic usage of the `true()` function. + +```yaml +# true.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo true value + type: Microsoft.DSC.Debug/Echo + properties: + output: "[true()]" +``` + +```bash +dsc config get --file true.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo true value + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: true +messages: [] +hadErrors: false +``` + +## Parameters + +The `true()` function takes no arguments. + +```yaml +Type: none +Required: false +MinimumCount: 0 +MaximumCount: 0 +``` + +## Output + +The `true()` function always returns the boolean value `true`. + +```yaml +Type: boolean +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryGet.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryGet.md new file mode 100644 index 00000000..d42ff131 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryGet.md @@ -0,0 +1,336 @@ +--- +description: Reference for the 'tryGet' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: tryGet +--- + +# tryGet + +## Synopsis + +Safely retrieves a value from an array by index or an object by key without +throwing an error if the key or index doesn't exist. + +## Syntax + +```Syntax +tryGet(source, keyOrIndex) +``` + +## Description + +The `tryGet()` function provides a safe way to access elements in arrays or +objects without causing errors when the key or index doesn't exist. Unlike +direct property access that might fail, this function returns `null` when the +requested element cannot be found. + +For arrays, the function uses zero-based indexing where `0` refers to the first +element. For objects, it retrieves values by their property key name. This is +particularly useful when working with dynamic data structures where the presence +of keys or the length of arrays isn't guaranteed. + +The function returns `null` in the following cases: + +- The specified key doesn't exist in the object +- The array index is negative +- The array index is greater than or equal to the array length +- The array is empty + +## Examples + +### Example 1 - Safely access configuration settings with fallbacks + +Access optional configuration values that might not be present in all +environments without causing errors. This example demonstrates retrieving +feature flags that may or may not be defined. This example uses +[`createObject()`][03] to build the configuration object and [`coalesce()`][02] +for fallback values. + +```yaml +# tryGet.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Feature Flags + type: Microsoft.DSC.Debug/Echo + properties: + output: + config: "[createObject('enableBeta', true, 'enableDebug', false)]" + betaEnabled: >- + [coalesce(tryGet(createObject('enableBeta', true, 'enableDebug', false), + 'enableBeta'), false)] + alphaEnabled: >- + [coalesce(tryGet(createObject('enableBeta', true, 'enableDebug', false), + 'enableAlpha'), false)] + debugEnabled: >- + [tryGet(createObject('enableBeta', true, 'enableDebug', false), 'enableDebug')] +``` + +```bash +dsc config get --file tryGet.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Feature Flags + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + config: + enableBeta: true + enableDebug: false + betaEnabled: true + alphaEnabled: false + debugEnabled: false +messages: [] +hadErrors: false +``` + +The function safely returns `true` for the existing `enableBeta` flag, `null` +for the non-existent `enableAlpha` flag (which `coalesce()` converts to +`false`), and `false` for the `enableDebug` flag. + +### Example 2 - Access deployment environment settings + +Retrieve environment-specific configuration values with safe defaults. This is +useful when different environments might have different configuration keys. This +example uses [`parameters()`][07] to reference the environment configuration, +making the complex nested object structure easier to understand. + +```yaml +# tryGet.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + environments: + type: object + defaultValue: + production: + replicas: 5 + region: us-east-1 + staging: + replicas: 2 +resources: +- name: Environment Config + type: Microsoft.DSC.Debug/Echo + properties: + output: + environments: "[parameters('environments')]" + productionEnv: "[tryGet(parameters('environments'), 'production')]" + stagingEnv: "[tryGet(parameters('environments'), 'staging')]" + developmentEnv: "[tryGet(parameters('environments'), 'development')]" + prodReplicas: >- + [tryGet(tryGet(parameters('environments'), 'production'), 'replicas')] + prodRegion: "[tryGet(tryGet(parameters('environments'), 'production'), 'region')]" + stagingRegion: "[tryGet(tryGet(parameters('environments'), 'staging'), 'region')]" +``` + +```bash +dsc config get --file tryGet.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Environment Config + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + environments: + production: + replicas: 5 + region: us-east-1 + staging: + replicas: 2 + productionEnv: + replicas: 5 + region: us-east-1 + stagingEnv: + replicas: 2 + developmentEnv: null + prodReplicas: 5 + prodRegion: us-east-1 + stagingRegion: null +messages: [] +hadErrors: false +``` + +The function safely returns the environment objects when they exist, or `null` +for the non-existent `development` environment. It also demonstrates accessing +nested object properties separately. + +### Example 3 - Safely access array elements by position + +Access array elements without worrying about index out-of-range errors. This is +particularly useful when processing arrays of unknown or varying length. This +example uses [`createArray()`][00] to build the version history. + +```yaml +# tryGet.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Version History + type: Microsoft.DSC.Debug/Echo + properties: + output: + versions: "[createArray('v1.0.0', 'v1.1.0', 'v1.2.0')]" + current: "[tryGet(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'), 2)]" + previous: "[tryGet(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'), 1)]" + future: "[tryGet(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'), 5)]" + invalid: "[tryGet(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'), -1)]" +``` + +```bash +dsc config get --file tryGet.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Version History + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + versions: + - v1.0.0 + - v1.1.0 + - v1.2.0 + current: v1.2.0 + previous: v1.1.0 + future: null + invalid: null +messages: [] +hadErrors: false +``` + +The function safely returns array elements at valid indices, and `null` for +out-of-range indices (both negative and beyond the array length). + +### Example 4 - Parse API responses with optional fields + +Process data structures that might have optional or conditional fields, such as +API responses where certain fields only appear in specific scenarios. This +example uses [`createObject()`][03] to simulate API response data. + +```yaml +# tryGet.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: API Response Parser + type: Microsoft.DSC.Debug/Echo + properties: + output: + successResponse: >- + [createObject('status', 200, 'data', createObject('id', 123, 'name', 'example'))] + errorResponse: "[createObject('status', 404, 'error', 'Not Found')]" + successData: >- + [tryGet(createObject('status', 200, 'data', + createObject('id', 123, 'name', 'example')), 'data')] + successError: >- + [tryGet(createObject('status', 200, 'data', + createObject('id', 123, 'name', 'example')), 'error')] + errorData: "[tryGet(createObject('status', 404, 'error', 'Not Found'), 'data')]" + errorMessage: "[tryGet(createObject('status', 404, 'error', 'Not Found'), 'error')]" +``` + +```bash +dsc config get --file tryGet.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: API Response Parser + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + successResponse: + status: 200 + data: + id: 123 + name: example + errorResponse: + status: 404 + error: Not Found + successData: + id: 123 + name: example + successError: null + errorData: null + errorMessage: Not Found +messages: [] +hadErrors: false +``` + +The function gracefully handles missing fields, allowing you to build robust +parsers that work with varying response structures. + +## Parameters + +### source + +The array or object to retrieve the value from. For arrays, elements are +accessed by zero-based index. For objects, values are accessed by string key. +Required. + +```yaml +Type: array | object +Required: true +Position: 1 +``` + +### keyOrIndex + +For arrays: the zero-based integer index of the element to retrieve. For +objects: the string key name of the property to retrieve. Required. + +```yaml +Type: integer | string +Required: true +Position: 2 +``` + +## Output + +Returns the value at the specified index or key if it exists. Returns `null` if: + +- The array index is negative, out of range, or the array is empty +- The object key doesn't exist + +The return type matches the type of the element or property value in the +array or object. + +```yaml +Type: any | null +``` + +## Errors + +The function returns an error in the following cases: + +- **Invalid source type**: The first argument is neither an array nor an object +- **Invalid key type for object**: When accessing an object, the second argument + must be a string +- **Invalid index type for array**: When accessing an array, the second argument + must be an integer + +## Related functions + +- [`createArray()`][00] - Creates an array from provided values +- [`createObject()`][03] - Creates an object from key-value pairs +- [`coalesce()`][02] - Returns the first non-null value from a list +- [`if()`][04] - Returns one of two values based on a condition +- [`equals()`][05] - Compares two values for equality +- [`not()`][06] - Inverts a boolean value +- [`tryIndexFromEnd()`][01] - Safely retrieves array elements by counting backward from the end +- [`parameters()`][07] - Returns the value of a specified configuration parameter + + +[00]: ./createArray.md +[01]: ./tryIndexFromEnd.md +[02]: ./coalesce.md +[03]: ./createObject.md +[04]: ./if.md +[05]: ./equals.md +[06]: ./not.md +[07]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryIndexFromEnd.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryIndexFromEnd.md new file mode 100644 index 00000000..509bacaa --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryIndexFromEnd.md @@ -0,0 +1,316 @@ +--- +description: Reference for the 'tryIndexFromEnd' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: tryIndexFromEnd +--- + +# tryIndexFromEnd + +## Synopsis + +Safely retrieves a value from an array by counting backward from the end without +throwing an error if the index is out of range. + +## Syntax + +```Syntax +tryIndexFromEnd(sourceArray, reverseIndex) +``` + +## Description + +The `tryIndexFromEnd()` function provides a safe way to access array elements by +counting backward from the end using a one-based index. Unlike standard array +indexing that might fail with out-of-bounds errors, this function returns `null` +when the index is invalid or out of range. + +This is particularly useful when working with dynamic arrays where the length +isn't known in advance, or when implementing fallback logic that needs to handle +missing data gracefully. The function uses a one-based index, meaning `1` +refers to the last element, `2` to the second-to-last, and so on. + +The function returns `null` in the following cases: + +- The reverse index is greater than the array length +- The reverse index is zero or negative +- The array is empty + +## Examples + +### Example 1 - Access recent deployment history safely + +Use `tryIndexFromEnd()` to access recent deployment records when you're not +certain how many deployments have occurred. This is useful for rollback +scenarios where you want to retrieve the previous deployment without causing +errors if the history is empty or shorter than expected. This example uses +[`createArray()`][05] to build the deployment history and [`last()`][00] to get +the current deployment. + +```yaml +# tryIndexFromEnd.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Deployment Rollback + type: Microsoft.DSC.Debug/Echo + properties: + output: + currentDeployment: "[last(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'))]" + previousDeployment: >- + [tryIndexFromEnd(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'), 2)] + fallbackDeployment: >- + [tryIndexFromEnd(createArray('v1.0.0', 'v1.1.0', 'v1.2.0'), 10)] +``` + +```bash +dsc config get --file tryIndexFromEnd.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Deployment Rollback + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + currentDeployment: v1.2.0 + previousDeployment: v1.1.0 + fallbackDeployment: null +messages: [] +hadErrors: false +``` + +The function returns `v1.1.0` for the second-to-last deployment, and `null` for +the non-existent 10th-from-last deployment, allowing your configuration to +handle missing data gracefully. + +### Example 2 - Select backup retention with safe defaults + +Use `tryIndexFromEnd()` to implement flexible backup retention policies that +adapt to available backups without failing when fewer backups exist than +expected. This example retrieves the third-most-recent backup if available. This +example uses [`parameters()`][06] to reference the backup timestamps array. + +```yaml +# tryIndexFromEnd.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + backupTimestamps: + type: array + defaultValue: + - 20250101 + - 20250108 + - 20250115 + - 20250122 + - 20250129 +resources: +- name: Backup Retention + type: Microsoft.DSC.Debug/Echo + properties: + output: + backups: "[parameters('backupTimestamps')]" + retainAfter: "[tryIndexFromEnd(parameters('backupTimestamps'), 3)]" + description: "Retain backups newer than the third-most-recent" +``` + +```bash +dsc config get --file tryIndexFromEnd.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Backup Retention + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + backups: + - 20250101 + - 20250108 + - 20250115 + - 20250122 + - 20250129 + retainAfter: 20250115 + description: Retain backups newer than the third-most-recent +messages: [] +hadErrors: false +``` + +The function safely returns `20250115` (the third-from-last backup), allowing +you to implement a retention policy that keeps the three most recent backups. + +### Example 3 - Parse log levels from configuration arrays + +Use `tryIndexFromEnd()` to access configuration values from arrays of varying +lengths. This is useful when configuration arrays might have different numbers +of elements across environments. This example uses [`parameters()`][06] to +reference the log level arrays. + +```yaml +# tryIndexFromEnd.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + productionLevels: + type: array + defaultValue: [ERROR, WARN, INFO] + devLevels: + type: array + defaultValue: [ERROR, WARN, INFO, DEBUG, TRACE] +resources: +- name: Log Configuration + type: Microsoft.DSC.Debug/Echo + properties: + output: + productionLevels: "[parameters('productionLevels')]" + devLevels: "[parameters('devLevels')]" + prodThirdLevel: "[tryIndexFromEnd(parameters('productionLevels'), 3)]" + devThirdLevel: "[tryIndexFromEnd(parameters('devLevels'), 3)]" + prodFifthLevel: "[tryIndexFromEnd(parameters('productionLevels'), 5)]" +``` + +```bash +dsc config get --file tryIndexFromEnd.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Log Configuration + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + productionLevels: + - ERROR + - WARN + - INFO + devLevels: + - ERROR + - WARN + - INFO + - DEBUG + - TRACE + prodThirdLevel: ERROR + devThirdLevel: INFO + prodFifthLevel: null +messages: [] +hadErrors: false +``` + +The function safely handles arrays of different lengths, returning the +appropriate log level or `null` without throwing errors. + +### Example 4 - Access region-specific configuration with fallback + +Use `tryIndexFromEnd()` with [`coalesce()`][02] to implement fallback logic when +accessing configuration values from arrays that might have different lengths +across regions. This example shows how to safely access regional endpoints with +a default fallback. This example uses [`createArray()`][05] to build the +regional endpoint arrays. + +```yaml +# tryIndexFromEnd.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Regional Endpoints + type: Microsoft.DSC.Debug/Echo + properties: + output: + primaryRegion: "[createArray('us-east-1', 'us-west-2', 'eu-west-1')]" + secondaryRegion: "[createArray('us-west-1')]" + preferredPrimary: >- + [coalesce(tryIndexFromEnd(createArray('us-east-1', 'us-west-2', 'eu-west-1'), 2), + 'us-east-1')] + preferredSecondary: >- + [coalesce(tryIndexFromEnd(createArray('us-west-1'), 2), 'us-west-1')] +``` + +```bash +dsc config get --file tryIndexFromEnd.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Regional Endpoints + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + primaryRegion: + - us-east-1 + - us-west-2 + - eu-west-1 + secondaryRegion: + - us-west-1 + preferredPrimary: us-west-2 + preferredSecondary: us-west-1 +messages: [] +hadErrors: false +``` + +By combining `tryIndexFromEnd()` with `coalesce()`, you get robust fallback +behavior: `preferredPrimary` returns `us-west-2` (the second-to-last region), +while `preferredSecondary` falls back to the default `us-west-1` when the +second-to-last element doesn't exist. + +## Parameters + +### sourceArray + +The array to retrieve the element from by counting backward from the end. +Required. + +```yaml +Type: array +Required: true +Position: 1 +``` + +### reverseIndex + +The one-based index from the end of the array. Must be a positive integer where +`1` refers to the last element, `2` to the second-to-last, and so on. Required. + +```yaml +Type: integer +Required: true +Position: 2 +Minimum: 1 +``` + +## Output + +Returns the array element at the specified reverse index if the index is valid +(within array bounds). Returns `null` if the index is out of range, zero, +negative, or if the array is empty. + +The return type matches the type of the element in the array. + +```yaml +Type: any | null +``` + +## Errors + +The function returns an error in the following cases: + +- **Invalid source type**: The first argument is not an array +- **Invalid index type**: The second argument is not an integer + +## Related functions + +- [`last()`][00] - Returns the last element of an array (throws error if empty) +- [`first()`][01] - Returns the first element of an array or character of a string +- [`coalesce()`][02] - Returns the first non-null value from a list +- [`equals()`][03] - Compares two values for equality +- [`not()`][04] - Inverts a boolean value +- [`createArray()`][05] - Creates an array from provided values +- [`parameters()`][06] - Returns the value of a specified configuration parameter + + +[00]: ./last.md +[01]: ./first.md +[02]: ./coalesce.md +[03]: ./equals.md +[04]: ./not.md +[05]: ./createArray.md +[06]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryWhich.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryWhich.md new file mode 100644 index 00000000..6ea9e8fc --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/tryWhich.md @@ -0,0 +1,228 @@ +--- +description: Reference for the 'tryWhich' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: tryWhich +--- + +# tryWhich + +## Synopsis + +Looks for an executable in the `PATH` environment variable and returns the full path to the first +matching executable or null if not found. + +## Syntax + +```Syntax +tryWhich() +``` + +## Description + +The `tryWhich()` function searches for an executable in the `PATH` environment variable and returns +the full path to the first matching executable if found. If the executable isn't discoverable, the +function returns `null` instead of generating an error. + +This function is useful for: + +- Checking whether a required command-line tool is available before invoking it. +- Conditionally configuring resources based on available system tools. +- Validating prerequisites in configurations. +- Finding the exact path to executables for use in scripts or commands. + +The function searches the `PATH` in the same way the operating system would when executing a +command. On Windows, it automatically checks for common executable extensions, like `.exe`, `.cmd`, +and `.bat`, if no extension is provided. + +Unlike a strict path lookup that would fail if the executable is missing, `tryWhich()` +gracefully returns `null`, making it ideal for conditional logic with [`if()`][00] or +[`coalesce()`][01]. + +## Examples + +### Example 1 - Check if tool exists before using it + +The following example uses `tryWhich()` with [`not()`][06] and [`equals()`][03] to set a +property based on whether the `git` command is available. + +```yaml +# tryWhich.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: + gitPath: "[tryWhich('git')]" + hasGit: "[not(equals(tryWhich('git'), null()))]" +``` + +```bash +dsc config get --file tryWhich.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + gitPath: C:\Program Files\Git\cmd\git.exe + hasGit: true +messages: [] +hadErrors: false +``` + +If `git` wasn't discoverable in the `PATH` environmental variable, `gitPath` would be `null` and +`hasGit` would be `false`. + +### Example 2 - Provide fallback paths with coalesce + +The following example uses `tryWhich()` with [`coalesce()`][01] to provide fallback options +when searching for an executable, returning the first non-null path found. + +```yaml +# tryWhich.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: + pythonPath: >- + [coalesce( + tryWhich('python3'), + tryWhich('python'), + '/usr/bin/python' + )] +``` + +```bash +dsc config get --file tryWhich.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + pythonPath: /usr/bin/python3 +messages: [] +hadErrors: false +``` + +In this example, the function first looks for `python3` in the `PATH` environmental variable. If +that executable isn't discovered, it then looks for `python`. If neither executable is discovered, +it falls back to the specified default value, `/usr/bin/python`. + +### Example 3 - Validate multiple prerequisites + +The following example demonstrates checking for multiple required tools and building a status +report using [`createObject()`][02]. + +```yaml +# tryWhich.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Echo + type: Microsoft.DSC.Debug/Echo + properties: + output: + prerequisites: + docker: "[tryWhich('docker')]" + kubectl: "[tryWhich('kubectl')]" + helm: "[tryWhich('helm')]" + allFound: >- + [and( + not(equals(tryWhich('docker'), null())), + not(equals(tryWhich('kubectl'), null())), + not(equals(tryWhich('helm'), null())) + )] +``` + +```bash +dsc config get --file tryWhich.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + prerequisites: + docker: /usr/bin/docker + kubectl: /usr/local/bin/kubectl + helm: null + allFound: false +messages: [] +hadErrors: false +``` + +This checks for three tools and determines if all are available. In this example, `helm` is +not found, so `allFound` is `false`. + +## Parameters + +### commandName + +The name of the executable to locate. On Windows, it automatically checks for common executable +extensions, like `.exe`, `.cmd`, and `.bat`, if no extension is provided. + +```yaml +Type: string +Required: true +Position: 1 +``` + +## Output + +Returns the full path to the first matching executable as a string if found in the system PATH. +Returns `null` if the executable is not found. + +```yaml +Type: string or null +``` + +## Error conditions + +The function returns `null` instead of generating errors when the executable isn't found. + +The function only returns an error when the input isn't a string. + +## Notes + +- The function searches the `PATH` environment variable in the same order as the operating system. +- On Windows, the function automatically checks for the executable with common extensions, like + `.exe`, `.cmd`, and `.bat`, when the input string doesn't define an extension. For example, if + the input is `dsc`, the function would return `dsc.exe` if available in `PATH`. +- The function returns `null` when the executable isn't found instead of raising an error. +- The function always returns the absolute path to a discovered executable. +- Use with [`if()`][00] or [`coalesce()`][01] for conditional logic based on tool availability. +- The function searches for the executable case-insensitively on Windows and case-sensitively on + other platforms. +- The function resolves symbolic links to their target paths. + +## Related functions + +- [`if()`][00] - Conditional expression for checking if a tool exists +- [`coalesce()`][01] - Returns the first non-null value from a list +- [`equals()`][03] - Compares values for equality +- [`null()`][04] - Returns a null value +- [`and()`][05] - Logical AND for checking multiple conditions +- [`not()`][06] - Logical NOT for negating conditions +- [`createObject()`][02] - Creates an object from key-value pairs + + +[00]: ./if.md +[01]: ./coalesce.md +[02]: ./createObject.md +[03]: ./equals.md +[04]: ./null.md +[05]: ./and.md +[06]: ./not.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/union.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/union.md new file mode 100644 index 00000000..99ba200f --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/union.md @@ -0,0 +1,320 @@ +--- +description: Reference for the 'union' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: union +--- + +# union + +## Synopsis + +Combines two or more arrays or objects, returning a single collection with +unique elements or merged properties. + +## Syntax + +```Syntax +union(, , [collection3], ...) +``` + +## Description + +The `union()` function combines multiple collections into a single collection. +For arrays, it returns a new array containing all unique elements from the +input arrays, preserving order and removing duplicates. For objects, it +merges properties from all input objects, with later objects overriding +properties from earlier ones when keys conflict. + +All input parameters must be of the same type (all arrays or all objects). +Mixing arrays and objects will result in an error. + +## Examples + +### Example 1 - Union of arrays + +The following example shows how to combine multiple arrays into one. + +```yaml +# union.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + serverGroup1: + type: array + defaultValue: + - web01 + - web02 + - db01 + serverGroup2: + type: array + defaultValue: + - web02 + - web03 + - cache01 + serverGroup3: + type: array + defaultValue: + - db01 + - backup01 +resources: +- name: Combine server groups + type: Microsoft.DSC.Debug/Echo + properties: + output: + allServers: "[union(parameters('serverGroup1'), parameters('serverGroup2'))]" + threeGroups: >- + [union(parameters('serverGroup1'), parameters('serverGroup2'), + parameters('serverGroup3'))] +``` + +```bash +dsc config get --file union.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Combine server groups + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + allServers: + - web01 + - web02 + - db01 + - web03 + - cache01 + threeGroups: + - web01 + - web02 + - db01 + - web03 + - cache01 + - backup01 +messages: [] +hadErrors: false +``` + +### Example 2 - Union of objects + +The following example shows how to merge multiple objects. + +```yaml +# union.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + defaultConfig: + type: object + defaultValue: + timeout: 30 + retries: 3 + debug: false + userConfig: + type: object + defaultValue: + timeout: 60 + logLevel: info + envConfig: + type: object + defaultValue: + debug: true + environment: production +resources: +- name: Merge configurations + type: Microsoft.DSC.Debug/Echo + properties: + output: + finalConfig: >- + [union(parameters('defaultConfig'), parameters('userConfig'), + parameters('envConfig'))] +``` + +```bash +dsc config get --file union.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Merge configurations + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + finalConfig: + timeout: 60 + retries: 3 + debug: true + logLevel: info + environment: production +messages: [] +hadErrors: false +``` + +### Example 3 - Union with duplicate arrays + +The following example shows how union handles duplicate values in arrays. + +```yaml +# union.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + permissions1: + type: array + defaultValue: + - read + - write + - execute + permissions2: + type: array + defaultValue: + - read + - admin + - delete +resources: +- name: Combine permissions + type: Microsoft.DSC.Debug/Echo + properties: + output: + uniquePermissions: "[union(parameters('permissions1'), parameters('permissions2'))]" + selfUnion: "[union(parameters('permissions1'), parameters('permissions1'))]" +``` + +```bash +dsc config get --file union.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Combine permissions + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + uniquePermissions: + - read + - write + - execute + - admin + - delete + selfUnion: + - read + - write + - execute +messages: [] +hadErrors: false +``` + +### Example 5 - Union with string conversion for logging + +The following example shows how to use union with string conversion for +building comprehensive log messages. + +```yaml +# union.example.5.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + baseLogData: + type: object + defaultValue: + timestamp: 1691596800 + level: "INFO" + requestData: + type: object + defaultValue: + requestId: 12345 + method: "GET" + responseData: + type: object + defaultValue: + statusCode: 200 + duration: 150 +resources: +- name: Build comprehensive log entry + type: Microsoft.DSC.Debug/Echo + properties: + output: + logEntry: >- + [string(union(parameters('baseLogData'), parameters('requestData'), + parameters('responseData')))] + logArray: "[union(createArray('timestamp'), createArray('level', 'requestId'))]" +``` + +```bash +dsc config get --file union.example.5.dsc.config.yaml +``` + +```yaml +results: +- name: Build comprehensive log entry + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + logEntry: '{"timestamp":1691596800,"level":"INFO","requestId":12345,"method":"GET","statusCode":200,"duration":150}' + logArray: + - timestamp + - level + - requestId +messages: [] +hadErrors: false +``` + +## Parameters + +### collection1 + +The first collection to union. + +```yaml +Type: [array, object] +Required: true +``` + +### collection2 + +The second collection to union. Must be the same type as collection1. + +```yaml +Type: [array, object] +Required: true +``` + +### Additional collections + +Additional collections to union (optional). All must be the same type as +collection1. + +```yaml +Type: [array, object] +Required: false +``` + +The `union()` function requires at least two input values and accepts +additional values. All input values must be of the same type (all arrays or +all objects). + +For arrays, the function preserves the order of elements and removes +duplicates. For objects, properties from later objects override properties +from earlier objects when there are key conflicts. + +## Output + +The `union()` function returns a single collection of the same type as the +input collections. + +```yaml +Type: [array, object] +``` + +## Related functions + +- [`createArray()`][00] - Creates arrays that can be combined with union +- [`createObject()`][01] - Creates objects that can be merged with union +- [`string()`][02] - Converts objects or arrays to JSON strings +- [`concat()`][03] - Concatenates arrays (alternative to union for arrays) + + +[00]: ./createArray.md +[01]: ./createObject.md +[02]: ./string.md +[03]: ./concat.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uniqueString.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uniqueString.md new file mode 100644 index 00000000..18b9fe79 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uniqueString.md @@ -0,0 +1,199 @@ +--- +description: Reference for the 'uniqueString' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: uniqueString +--- + +# uniqueString + +## Synopsis + +Creates a deterministic lowercase Base32 string from one or more input strings. + +## Syntax + +```Syntax +uniqueString([, , ...]) +``` + +## Description + +The `uniqueString()` function produces a stable hash-based string from one or +more input strings. The inputs are concatenated with dash (`-`) separators then +hashed using MurmurHash64 and Base32-encoded (RFC 4648 lowercase, no padding). +The same inputs always produce the same output, making it useful for generating +repeatable names that satisfy length and character constraints. + +Because the output is a non-cryptographic hash, there's no direct reverse +operation, but it doesn't provide secrecy. If the possible inputs are +predictable (such as a small set of env, region, or service names), an attacker +can brute-force or dictionary-guess the original values by recomputing hashes. +Don't use `uniqueString()` for secrets or security decisions. Use it only for +stable, deterministic naming. + +## Examples + +### Example 1 - Generate a name from components + +The following example generates a unique, deterministic identifier from a set +of input properties. + +```yaml +# uniquestring.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + env: + type: string + defaultValue: prod + service: + type: string + defaultValue: billing + region: + type: string + defaultValue: westus +resources: +- name: Deterministic name + type: Microsoft.DSC.Debug/Echo + properties: + output: + name: >- + [uniqueString(parameters('env'), parameters('service'), parameters('region'))] +``` + +```bash +dsc config get --file uniquestring.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Deterministic name + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + name: f5saooq7aoueg +messages: [] +hadErrors: false +``` + +### Example 2 - Stable bucket partition keys + +The following example shows using `uniqueString()` to build a stable partition +key for storage or grouping. + +```yaml +# uniquestring.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + tenantId: + type: string + defaultValue: tenantA + dataType: + type: string + defaultValue: metrics +resources: +- name: Partition key generation + type: Microsoft.DSC.Debug/Echo + properties: + output: + partitionKey: "[uniqueString(parameters('tenantId'), parameters('dataType'))]" +``` + +```bash +dsc config get --file uniquestring.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Partition key generation + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + partitionKey: i5w466eimgg52 +messages: [] +hadErrors: false +``` + +### Example 3 - Compose with other functions + +The following example builds a prefixed resource identifier combining a literal +prefix and the hash output. + +```yaml +# uniquestring.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + project: + type: string + defaultValue: analytics + zone: + type: string + defaultValue: eu-central +resources: +- name: Prefixed identifier + type: Microsoft.DSC.Debug/Echo + properties: + output: + resourceId: >- + [concat('res-', uniqueString(parameters('project'), parameters('zone')))] +``` + +```bash +dsc config get --file uniquestring.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Prefixed identifier + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + resourceId: res-ce56slj5eites +messages: [] +hadErrors: false +``` + +## Parameters + +### value1 + +The first string value to include in the hash input sequence. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### value2, ... (additional values) + +Optional additional string values to include. Each is appended with a dash +separator before hashing. Argument order affects the result. + +```yaml +Type: string +Required: false +Position: 2+ +``` + +## Output + +The `uniqueString()` function returns a deterministic lowercase Base32 string. + +```yaml +Type: string +``` + +## Related functions + +- [`concat()`][00] - Concatenates strings together +- [`string()`][01] - Converts values to strings +- [`utcNow()`][02] - Returns the current UTC timestamp + + +[00]: ./concat.md +[01]: ./string.md +[02]: ./utcNow.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uri.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uri.md new file mode 100644 index 00000000..58f067af --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uri.md @@ -0,0 +1,345 @@ +--- +description: Reference for the 'uri' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: uri +--- + +# uri + +## Synopsis + +Creates an absolute URI by combining the baseUri and the relativeUri string. + +## Syntax + +```Syntax +uri(, ) +``` + +## Description + +The `uri()` function combines a base URI with a relative URI to create an absolute URI according to +[RFC 3986](https://www.rfc-editor.org/rfc/rfc3986) URI resolution rules. This standardized behavior +ensures consistent and predictable URI construction. + +### Requirements + +- **Base URI must be absolute**: The base URI must include a scheme (such as `https://`, `http://`, + or `file://`). Relative URIs or URIs without schemes return an error. +- **Base URI cannot be empty**: An empty base URI returns an error because an absolute URI requires + a valid base. + +### URI Resolution Behavior + +The function follows RFC 3986 Section 5.2 (Relative Resolution) rules: + +- **Absolute relative URIs**: If the relative URI contains a scheme (e.g., + `https://other.com/path`), it completely replaces the base URI. +- **Protocol-relative URIs** (starting with `//`): The relative URI inherits the scheme from the + base URI. For example, `uri('https://example.com/', '//cdn.example.org/assets')` returns + `https://cdn.example.org/assets`. +- **Path-absolute relative URIs** (starting with `/`): The relative path replaces the entire path + of the base URI, keeping the scheme and authority. For example, + `uri('https://example.com/old/path', '/new/path')` returns `https://example.com/new/path`. +- **Path-relative URIs** (not starting with `/`): The relative path is merged with the base URI's + path. The last segment of the base path is removed and replaced with the relative URI. For + example, `uri('https://example.com/api/v1', 'users')` returns `https://example.com/api/users`. +- **Empty relative URI**: Returns the base URI unchanged. + +### Special Cases + +- **Triple slash sequences** (`///`): Returns an error. Three or more consecutive slashes are + invalid URI syntax. +- **Path normalization**: The function automatically normalizes paths, resolving `.` (current + directory) and `..` (parent directory) references. For example, + `uri('https://example.com/', 'path/../other')` returns `https://example.com/other`. +- **Query strings and fragments**: Query strings (`?query=value`) and fragments (`#section`) in the + relative URI are preserved in the result. + +Use this function to build API endpoints, file paths, or resource URLs dynamically from +configuration parameters. + +## Examples + +### Example 1 - Build API endpoint with trailing slash + +The following example combines a base API URL ending with a slash with a relative path. + +```yaml +# uri.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + apiBase: + type: string + defaultValue: https://api.example.com/v1/ + resourcePath: + type: string + defaultValue: users/123 +resources: +- name: Build API endpoint + type: Microsoft.DSC.Debug/Echo + properties: + output: + endpoint: "[uri(parameters('apiBase'), parameters('resourcePath'))]" +``` + +```bash +dsc config get --file uri.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Build API endpoint + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + endpoint: https://api.example.com/v1/users/123 +messages: [] +hadErrors: false +``` + +### Example 2 - Handle duplicate slashes + +The following example shows how the function automatically handles cases where both the base URI +ends with a slash and the relative URI begins with a slash. + +```yaml +# uri.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Combine URIs with duplicate slashes + type: Microsoft.DSC.Debug/Echo + properties: + output: + withDuplicateSlashes: "[uri('https://example.com/', '/api/data')]" + result: The function combines the slashes into one +``` + +```bash +dsc config get --file uri.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Combine URIs with duplicate slashes + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + withDuplicateSlashes: https://example.com/api/data + result: The function combines the slashes into one +messages: [] +hadErrors: false +``` + +### Example 3 - Replace path segments + +The following example demonstrates how `uri()` replaces the last path segment when the base URI +doesn't end with a trailing slash. It uses the [`concat()`][01] function to build the base URL. + +```yaml +# uri.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + currentVersion: + type: string + defaultValue: v1 + newVersion: + type: string + defaultValue: v2 +resources: +- name: Update API version + type: Microsoft.DSC.Debug/Echo + properties: + output: + oldEndpoint: "[concat('https://api.example.com/', parameters('currentVersion'))]" + newEndpoint: >- + [uri(concat('https://api.example.com/', parameters('currentVersion')), + parameters('newVersion'))] +``` + +```bash +dsc config get --file uri.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Update API version + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + oldEndpoint: https://api.example.com/v1 + newEndpoint: https://api.example.com/v2 +messages: [] +hadErrors: false +``` + +### Example 4 - Build resource URLs + +The following example shows how to use `uri()` with [`concat()`][01] to build complete resource +URLs from configuration parameters. + +```yaml +# uri.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + storageAccount: + type: string + defaultValue: mystorageaccount + containerName: + type: string + defaultValue: documents + blobName: + type: string + defaultValue: report.pdf +resources: +- name: Build blob URL + type: Microsoft.DSC.Debug/Echo + properties: + output: + blobUrl: >- + [uri( + concat('https://', parameters('storageAccount'), '.blob.core.windows.net/'), + concat(parameters('containerName'), '/', parameters('blobName')) + )] +``` + +```bash +dsc config get --file uri.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Build blob URL + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + blobUrl: https://mystorageaccount.blob.core.windows.net/documents/report.pdf +messages: [] +hadErrors: false +``` + +### Example 5 - Handle query strings and ports + +The following example demonstrates that `uri()` preserves query strings and port numbers correctly. + +```yaml +# uri.example.5.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: URI with special components + type: Microsoft.DSC.Debug/Echo + properties: + output: + withPort: "[uri('https://example.com:8080/', 'api')]" + withQuery: "[uri('https://example.com/api/', 'search?q=test&limit=10')]" +``` + +```bash +dsc config get --file uri.example.5.dsc.config.yaml +``` + +```yaml +results: +- name: URI with special components + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + withPort: https://example.com:8080/api + withQuery: https://example.com/api/search?q=test&limit=10 +messages: [] +hadErrors: false +``` + +### Example 6 - Protocol-relative URI + +The following example shows how protocol-relative URIs (starting with `//`) inherit the scheme +from the base URI. + +```yaml +# uri.example.6.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Protocol-relative URI + type: Microsoft.DSC.Debug/Echo + properties: + output: + result: "[uri('https://example.com/', '//cdn.example.org/assets')]" + explanation: The relative URI inherits the https scheme from the base +``` + +```bash +dsc config get --file uri.example.6.dsc.config.yaml +``` + +```yaml +results: +- name: Protocol-relative URI + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + result: https://cdn.example.org/assets + explanation: The relative URI inherits the https scheme from the base +messages: [] +hadErrors: false +``` + +## Parameters + +### baseUri + +The base URI string. Must be an absolute URI containing a scheme (such as `https://`, `http://`, or +`file://`). The function uses this as the foundation for resolving the relative URI according to +RFC 3986 rules. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### relativeUri + +The relative URI string to combine with the base URI. Can be: + +- An absolute URI (replaces the base entirely) +- A protocol-relative URI starting with `//` (inherits scheme from base) +- A path-absolute URI starting with `/` (replaces base path) +- A path-relative URI (merges with base path) +- An empty string (returns base unchanged) + +This is combined with the base URI according to RFC 3986 URI resolution rules. + +```yaml +Type: string +Required: true +Position: 2 +``` + +## Output + +The `uri()` function returns a string containing the absolute URI created by combining the base URI +and relative URI according to RFC 3986 URI resolution rules. + +```yaml +Type: string +``` + +## Related functions + +- [`concat()`][01] - Concatenates multiple strings together +- [`format()`][02] - Creates a formatted string from a template +- [`substring()`][03] - Extracts a portion of a string +- [`parameters()`][04] - Retrieves parameter values + + +[01]: ./concat.md +[02]: ./format.md +[03]: ./substring.md +[04]: ./parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uriComponent.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uriComponent.md new file mode 100644 index 00000000..3617ce52 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uriComponent.md @@ -0,0 +1,273 @@ +--- +description: Reference for the 'uriComponent' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: uriComponent +--- + +# uriComponent + +## Synopsis + +Encodes a string for use as a URI component using percent-encoding. + +## Syntax + +```Syntax +uriComponent() +``` + +## Description + +The `uriComponent()` function encodes a string using percent-encoding (also known as URL encoding) +to make it safe for use as a component of a URI. The function encodes all characters except the +unreserved characters defined in RFC 3986: + +- **Unreserved characters** (not encoded): `A-Z`, `a-z`, `0-9`, `-`, `_`, `.`, `~` +- **All other characters** are percent-encoded as `%XX` where `XX` is the hexadecimal value + +Use this function when you need to include user-provided data, special characters, or spaces in +URLs, query strings, or other URI components. This ensures that the resulting URI is valid and that +special characters don't break the URI structure. + +## Examples + +### Example 1 - Encode query parameter value + +The following example shows how to encode a string containing spaces for use in a URL query +parameter. + +```yaml +# uricomponent.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + searchTerm: + type: string + defaultValue: hello world +resources: +- name: Build search URL + type: Microsoft.DSC.Debug/Echo + properties: + output: + original: "[parameters('searchTerm')]" + encoded: "[uriComponent(parameters('searchTerm'))]" + fullUrl: >- + [concat('https://example.com/search?q=', + uriComponent(parameters('searchTerm')))] +``` + +```bash +dsc config get --file uricomponent.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Build search URL + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + original: hello world + encoded: hello%20world + fullUrl: https://example.com/search?q=hello%20world +messages: [] +hadErrors: false +``` + +### Example 2 - Encode email address + +The following example demonstrates encoding an email address that contains special characters. + +```yaml +# uricomponent.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + email: + type: string + defaultValue: user+tag@example.com +resources: +- name: Encode email for URL + type: Microsoft.DSC.Debug/Echo + properties: + output: + encoded: "[uriComponent(parameters('email'))]" + mailtoLink: "[concat('mailto:', uriComponent(parameters('email')))]" +``` + +```bash +dsc config get --file uricomponent.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Encode email for URL + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + encoded: user%2Btag%40example.com + mailtoLink: mailto:user%2Btag%40example.com +messages: [] +hadErrors: false +``` + +### Example 3 - Encode complete URL + +The following example shows how `uriComponent()` encodes an entire URL, including the protocol, +slashes, and special characters. + +```yaml +# uricomponent.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Encode complete URL + type: Microsoft.DSC.Debug/Echo + properties: + output: + originalUrl: https://example.com/path?query=value + encodedUrl: "[uriComponent('https://example.com/path?query=value')]" +``` + +```bash +dsc config get --file uricomponent.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Encode complete URL + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + originalUrl: https://example.com/path?query=value + encodedUrl: https%3A%2F%2Fexample.com%2Fpath%3Fquery%3Dvalue +messages: [] +hadErrors: false +``` + +### Example 4 - Build API request with encoded parameters + +The following example demonstrates using `uriComponent()` with [`concat()`][01] and [`uri()`][02] +to build an API URL with safely encoded query parameters. + +```yaml +# uricomponent.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + apiBase: + type: string + defaultValue: https://api.example.com + resourcePath: + type: string + defaultValue: /users/search + nameFilter: + type: string + defaultValue: John Doe + ageFilter: + type: string + defaultValue: '30' +resources: +- name: Build API URL with query string + type: Microsoft.DSC.Debug/Echo + properties: + output: + apiUrl: >- + [concat( + uri(parameters('apiBase'), parameters('resourcePath')), + '?name=', + uriComponent(parameters('nameFilter')), + '&age=', + parameters('ageFilter') + )] +``` + +```bash +dsc config get --file uricomponent.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Build API URL with query string + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + apiUrl: https://api.example.com/users/search?name=John%20Doe&age=30 +messages: [] +hadErrors: false +``` + +### Example 5 - Unreserved characters remain unchanged + +The following example shows that unreserved characters (letters, numbers, hyphen, underscore, +period, and tilde) are not encoded. + +```yaml +# uricomponent.example.5.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Unreserved character handling + type: Microsoft.DSC.Debug/Echo + properties: + output: + original: ABCabc123-_.~ + encoded: "[uriComponent('ABCabc123-_.~')]" + identical: "[equals(uriComponent('ABCabc123-_.~'), 'ABCabc123-_.~')]" +``` + +```bash +dsc config get --file uricomponent.example.5.dsc.config.yaml +``` + +```yaml +results: +- name: Unreserved character handling + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + original: ABCabc123-_.~ + encoded: ABCabc123-_.~ + identical: true +messages: [] +hadErrors: false +``` + +## Parameters + +### stringToEncode + +The string value to encode using percent-encoding. All characters except unreserved characters +(A-Z, a-z, 0-9, -, _, ., ~) are encoded. + +```yaml +Type: string +Required: true +Position: 1 +``` + +## Output + +The `uriComponent()` function returns a string with all characters except unreserved characters +replaced with their percent-encoded equivalents (e.g., space becomes `%20`, `@` becomes `%40`). + +```yaml +Type: string +``` + +## Related functions + +- [`uri()`][02] - Combines base and relative URIs +- [`concat()`][01] - Concatenates multiple strings together +- [`format()`][03] - Creates a formatted string from a template +- [`base64()`][04] - Encodes a string to base64 +- [`parameters()`][05] - Retrieves parameter values +- [`equals()`][06] - Compares two values for equality + + +[01]: ./concat.md +[02]: ./uri.md +[03]: ./format.md +[04]: ./base64.md +[05]: ./parameters.md +[06]: ./equals.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uriComponentToString.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uriComponentToString.md new file mode 100644 index 00000000..d06a2297 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/uriComponentToString.md @@ -0,0 +1,209 @@ +--- +description: Reference for the 'uriComponentToString' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: uriComponentToString +--- + +# uriComponentToString + +## Synopsis + +Returns a decoded string from a URI-encoded value. + +## Syntax + +```Syntax +uriComponentToString() +``` + +## Description + +The `uriComponentToString()` function decodes a URI-encoded string back to its original form. +It converts percent-encoded sequences (like `%20` for space or `%40` for `@`) back to their +original characters. This function is the inverse of [`uriComponent()`][01]. + +This function is useful when you need to decode URI components that were previously encoded, +such as query parameters, path segments, or other URI parts. + +## Examples + +### Example 1 - Decode a URI-encoded query parameter + +This example decodes a URI-encoded query parameter value back to its original string. + +```yaml +# uriComponentToString.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo decoded value + type: Microsoft.DSC.Debug/Echo + properties: + output: "[uriComponentToString('John%20Doe')]" +``` + +```bash +dsc config get --file uriComponentToString.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo decoded value + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: John Doe +``` + +### Example 2 - Decode a URI-encoded email address + +This example decodes a URI-encoded email address with special characters. + +```yaml +# uriComponentToString.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo decoded email + type: Microsoft.DSC.Debug/Echo + properties: + output: "[uriComponentToString('user%2Btag%40example.com')]" +``` + +```bash +dsc config get --file uriComponentToString.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo decoded email + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: user+tag@example.com +``` + +### Example 3 - Decode a complete URI-encoded URL + +This example decodes a completely URI-encoded URL back to its readable form. + +```yaml +# uriComponentToString.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo decoded URL + type: Microsoft.DSC.Debug/Echo + properties: + output: >- + [uriComponentToString('https%3A%2F%2Fapi.example.com%2Fusers%3Fstatus%3Dactive')] +``` + +```bash +dsc config get --file uriComponentToString.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo decoded URL + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: https://api.example.com/users?status=active +``` + +### Example 4 - Round-trip encoding and decoding + +This example demonstrates encoding a string with [`uriComponent()`][01] and then decoding it +back with `uriComponentToString()`, showing that they are inverse operations. + +```yaml +# uriComponentToString.example.4.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo round-trip result + type: Microsoft.DSC.Debug/Echo + properties: + output: "[uriComponentToString(uriComponent('Hello, World!'))]" +``` + +```bash +dsc config get --file uriComponentToString.example.4.dsc.config.yaml +``` + +```yaml +results: +- name: Echo round-trip result + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: Hello, World! +``` + +### Example 5 - Decode Unicode characters + +This example decodes a URI-encoded string containing UTF-8 encoded Unicode characters. + +```yaml +# uriComponentToString.example.5.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Echo decoded Unicode + type: Microsoft.DSC.Debug/Echo + properties: + output: "[uriComponentToString('caf%C3%A9')]" +``` + +```bash +dsc config get --file uriComponentToString.example.5.dsc.config.yaml +``` + +```yaml +results: +- name: Echo decoded Unicode + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: café +``` + +## Parameters + +### uriEncodedString + +The `uriComponentToString()` function expects a single string argument representing a +URI-encoded value. The function decodes any percent-encoded sequences (like `%20`, `%40`, etc.) +back to their original characters. + +If the encoded string contains invalid percent-encoding sequences (such as incomplete sequences +or invalid hexadecimal digits), the function returns an error. + +```yaml +Type: string +Required: true +Position: 1 +``` + +## Output + +The `uriComponentToString()` function returns the decoded string with all percent-encoded +sequences converted back to their original characters. The output is always a string. + +```yaml +Type: string +``` + +## Related functions + +The following functions are related to `uriComponentToString()`: + +- [`uriComponent()`][01] - Encodes a string for safe use in URI components (inverse operation) +- [`uri()`][02] - Combines a base URI and relative URI with intelligent path handling +- [`base64ToString()`][03] - Decodes a base64-encoded string +- [`concat()`][04] - Combines multiple strings +- [`parameters()`][05] - Returns the value of a parameter + + +[01]: uriComponent.md +[02]: uri.md +[03]: base64ToString.md +[04]: concat.md +[05]: parameters.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/utcNow.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/utcNow.md new file mode 100644 index 00000000..0d335641 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/utcNow.md @@ -0,0 +1,173 @@ +--- +description: Reference for the 'utcNow' DSC configuration document function +ms.date: 09/01/2026 +ms.topic: reference +title: utcNow +--- + +# utcNow + +## Synopsis + +Returns the current UTC timestamp when used as a parameter default. + +## Syntax + +```Syntax +utcNow() +utcNow() +``` + +## Description + +The `utcNow()` function returns the current time in UTC. It can only be used +when defining the `defaultValue` of a parameter in a configuration document. +Using it elsewhere produces an error. When called without arguments, it returns +an ISO 8601 timestamp with microsecond precision. When a format string is +provided, the output uses that custom format. + +The format string uses a subset of .NET date/time format patterns that DSC +internally maps to its formatting system. Unsupported tokens are passed +through literally. + +## Examples + +### Example 1 - Parameter default timestamp + +The following example assigns the current UTC time as a default parameter +value, then echoes it. + +```yaml +# utcnow.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + generatedAt: + type: string + defaultValue: "[utcNow()]" +resources: +- name: Show timestamp + type: Microsoft.DSC.Debug/Echo + properties: + output: + generatedAt: "[parameters('generatedAt')]" +``` + +```bash +dsc config get --file utcnow.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Show timestamp + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + generatedAt: 2025-08-12T14:23:05.123456Z +messages: [] +hadErrors: false +``` + +### Example 2 - Custom formatted timestamp + +The following example uses a custom format string to produce a friendly date +stamp. The format maps .NET patterns (`yyyy-MM-dd HH:mm:ss`) to the internal +formatter. + +```yaml +# utcnow.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + buildStamp: + type: string + defaultValue: "[utcNow('yyyy-MM-dd HH:mm:ss')]" +resources: +- name: Build metadata + type: Microsoft.DSC.Debug/Echo + properties: + output: + buildStamp: "[parameters('buildStamp')]" +``` + +```bash +dsc config get --file utcnow.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Build metadata + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + buildStamp: 2025-08-12 14:23:05 +messages: [] +hadErrors: false +``` + +### Example 3 - Combine with other functions + +The following example combines `utcNow()` with `concat()` and `string()` to +build an identifier that contains a timestamp. + +```yaml +# utcnow.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + timestamp: + type: string + defaultValue: "[utcNow('yyyyMMdd-HHmmss')]" +resources: +- name: ID generator + type: Microsoft.DSC.Debug/Echo + properties: + output: + releaseId: "[concat('release-', parameters('timestamp'))]" +``` + +```bash +dsc config get --file utcnow.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: ID generator + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + releaseId: release-20250812-142305 +messages: [] +hadErrors: false +``` + +## Parameters + +### format + +An optional date/time format string using .NET-style tokens. If omitted, the +function returns an ISO 8601 UTC timestamp with microsecond precision. + +```yaml +Type: string +Required: false +``` + +## Output + +The `utcNow()` function returns the current UTC timestamp as a string. + +```yaml +Type: string +``` + +## Related functions + +- [`string()`][00] - Converts values to strings +- [`concat()`][01] - Concatenates strings together +- [`uniqueString()`][02] - Produces a deterministic hash-based string + + +[00]: ./string.md +[01]: ./concat.md +[02]: ./uniqueString.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/variables.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/variables.md index ad82687d..0e952283 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/variables.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/variables.md @@ -1,6 +1,6 @@ --- description: Reference for the 'variables' DSC configuration document function -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: variables --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/metadata.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/metadata.md index c26bcc54..a6d638a6 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/metadata.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/metadata.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for metadata in a Desired State Configuration document. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Configuration document metadata schema --- @@ -38,12 +38,20 @@ metadata: Define a baseline for securing web application servers. ``` +The same schema applies to the `metadata` property of a resource instance in the configuration +document. For more information, see [DSC Configuration document resource instance schema][01]. + ## Microsoft.DSC The `Microsoft.DSC` metadata property contains directives and information that DSC itself uses when processing a configuration document. Unlike other metadata key-value pairs, DSC validates these properties. This property is reserved and shouldn't contain any custom user-defined metadata. +The schema for this property also accepts the execution information properties that DSC returns in +command output, like `operation` and `version`. DSC doesn't use those properties when it processes +a configuration document. For the full list of properties, see +[Microsoft.DSC metadata property schema reference][02]. + ### Properties #### securityContext @@ -52,31 +60,42 @@ This property defines the security context a configuration requires. If you invo against the configuration document in a security context that conflicts with this metadata, DSC raises an error when it validates the configuration document. +> [!NOTE] +> Defining the required security context in metadata is deprecated. DSC raises a warning when a +> configuration document defines this property. Use the `securityContext` directive in the +> document's [directives][03] property instead. If you define both, the values must match or DSC +> raises an error. + The valid security contexts are: -- `Current` +- `current` Indicates that the configuration document is usable under any security context. You can invoke DSC operations against the document when elevated as root or an administrator and as a normal user or account. -- `Elevated` +- `elevated` Indicates that the configuration document is usable only in an elevated security context. You can invoke DSC operations against the document when elevated as root or an administrator. When you invoke DSC operations against the document as a non-elevated user or account, DSC raises an error when it validates the configuration document. -- `Restricted` +- `restricted` Indicates that the configuration document is usable only in a non-elevated security context. You can invoke DSC operations against the document as a non-elevated user or account. When you invoke DSC operations against the document as root or an administrator, DSC raises an error when it validates the configuration document. -The default security context is `Current`. +The default security context is `current`. ```yaml -Type: object -Required: false -Default: Current -ValidValues: [Current, Elevated, Restricted] +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] ``` + + +[01]: resource.md#metadata-1 +[02]: ../metadata/Microsoft.DSC/properties.md +[03]: document.md#securitycontext diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md index f76b803f..d2300ebb 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a parameter in a Desired State Configuration document. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Configuration document parameter schema --- @@ -79,7 +79,7 @@ For more information about data types, see ```yaml Type: string Required: true -ValidValues: [string, securestring, int, bool, object, secureobject, array] +ValidValues: [string, secureString, int, bool, object, secureObject, array] ``` ### defaultValue @@ -116,7 +116,7 @@ a string is its character count. The length of an array is its item count. If the default value or runtime value for the parameter is shorter than this property, DSC raises an error. If this property is defined for parameters whose `type` isn't `array`, `string`, or -`securestring`, DSC raises an error. +`secureString`, DSC raises an error. If this property is defined with the `maxLength` property, this property must be less than `maxLength`. If it isn't, DSC raises an error. @@ -134,7 +134,7 @@ a string is its character count. The length of an array is its item count. If the default value or runtime value for the parameter is longer than this property, DSC raises an error. If this property is defined for parameters whose `type` isn't `array`, `string`, or -`securestring`, DSC raises an error. +`secureString`, DSC raises an error. If this property is defined with the `minLength` property, this property must be greater than `minLength`. If it isn't, DSC raises an error. diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md index 74b3853c..f6bb03ea 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a resource instance in a Desired State Configuration document. -ms.date: 08/13/2026 +ms.date: 09/01/2026 ms.topic: reference title: DSC Configuration document resource instance schema --- @@ -21,9 +21,9 @@ Type: object ## Description -The `resources` property of a DSC Configuration document always includes at least one DSC Resource -instance. Together, the instances in a configuration define the desired state that DSC can get, -test, and set on a machine. +The `resources` property of a DSC Configuration document defines the DSC Resource instances for the +configuration. Together, the instances in a configuration define the desired state that DSC can +get, test, and set on a machine. This document describes the JSON schema for a valid DSC Resource instance in a configuration document. @@ -34,24 +34,34 @@ For more information about DSC Resources, see [Anatomy of a command-based DSC Re Every resource instance must be an object that defines these properties: -- [name](#name) - [type](#type) ## Properties -### name +### condition -The `name` property of a resource instance defines the short, human-readable name for a DSC -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 `condition` property defines an expression that DSC evaluates before invoking the instance. If +the expression evaluates to `true`, DSC invokes the instance as normal. If it evaluates to any other +value, DSC skips the instance and doesn't include it in the results for the operation. -The instance name must be a non-empty string containing only letters, numbers, and spaces. +For example, DSC only invokes this instance when the `enableFeature` parameter is `true`: ```yaml -Type: string -Required: true -MinimumLength: 1 -Pattern: ^[a-zA-Z0-9 ]+$ +parameters: + enableFeature: + type: bool + defaultValue: false +resources: + - name: Feature + type: Microsoft.DSC.Debug/Echo + condition: "[parameters('enableFeature')]" + properties: + output: Feature enabled +``` + +```yaml +Type: string +Required: false ``` ### type @@ -63,20 +73,111 @@ valid fully qualified type name for the resource. For more information about typ ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` -### properties +### requireVersion -The `properties` of a resource instance define its desired state. The value of this property must -be an object. For assertion resources, the value can be an empty object (`{}`). DSC uses the -DSC Resource's instance schema to validate the defined properties. +The `requireVersion` property pins the instance to a specific version or a range of versions of the +resource. DSC only invokes a discovered resource whose version satisfies the requirement and raises +an error if it can't find one. When this property isn't defined, DSC doesn't constrain the version +of the resource. + +Define the value as a semantic version requirement: one or more comparators separated by commas. +Each comparator is an operator (`=`, `>`, `>=`, `<`, `<=`, `^`, or `~`) followed by a version. +Build metadata isn't allowed in the version. For example: + +- `=1.2.3` - exactly version `1.2.3`. +- `>=1.2.3, <2.0.0` - any version from `1.2.3` up to, but not including, `2.0.0`. +- `^1.2` - any version from `1.2.0` up to, but not including, `2.0.0`. +- `~2.3` - any version from `2.3.0` up to, but not including, `2.4.0`. + +For compatibility with resources that use date versions, the value can also be a date version like +`2026-02-03` or `2026-11-27-preview`. A date version requirement only matches a resource with +exactly the same date version. Date versions are deprecated. Use semantic versions instead. + +This property has the alias `apiVersion`. You can define the requirement with either property name, +but not both. + +```yaml +Type: string +Required: false +``` + +### name + +The `name` property defines the short, human-readable name for the instance. DSC uses the name +together with the `type` to identify the instance in results and messages, and for the +[resourceId()][02] function. The combination of `type` and `name` must be unique within a +configuration document. If two instances share the same type and name, DSC raises an error. + +The value can be a configuration expression, like `"[format('Server-{0}', copyIndex())]"` for an +instance in a copy loop. DSC evaluates the expression to a string before invoking the instance. + +Although the schema doesn't require this property, always define a unique name for every instance. +When the property isn't defined, DSC uses an empty string as the name. + +```yaml +Type: string +Required: false +Default: "" +``` - +### directives + +The `directives` property of a resource instance defines per-instance overrides for how DSC should +process the resource. This property was added in DSC version 3.2. ```yaml Type: object -Required: true +Required: false +``` + +You can define the following directives for a resource instance: + +#### requireAdapter + +The `requireAdapter` directive indicates that DSC should use the specified adapter to invoke the +adapted resource instance. The value for this directive must be the fully qualified type name of +the adapter resource, like `Microsoft.Adapter/PowerShell`. + +When this directive isn't specified, DSC invokes the adapted resource through the first discovered +adapter that indicates it can invoke the resource. This directive has no effect on nonadapted +resource instances. + +```yaml +Type: string +Required: false +Pattern: ^\w+(\.\w+)*\/\w+$ +``` + +#### securityContext + +The `securityContext` directive indicates that DSC should validate the current security context +against this directive before invoking the resource. This value overrides the +`directives.securityContext` setting for the top level of the configuration document. This enables +you to selectively require or forbid elevated security contexts for a specific resource instance. + +```yaml +Type: string +Required: false +ValidValues: [current, elevated, restricted] +``` + +### executionInformation + +The `executionInformation` property describes the DSC operation that produced the instance. DSC +adds this property to every instance in the configuration document returned by the +`dsc config export` command. The schema accepts this property for any instance, but DSC ignores it +when it processes a configuration document. + +The value is an object with the same properties as the [Microsoft.DSC metadata][03] object that DSC +returns in command output, plus an optional `whatIf` property that describes any what-if +operations DSC performed. + +```yaml +Type: object +Required: false ``` ### dependsOn @@ -85,15 +186,14 @@ To declare that a resource instance is dependent on another instance in the conf the `dependsOn` property. 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() function][02] -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. +processing this instance. Each value for this property must be an expression that uses the +[resourceId() function][02] to look up another instance in the configuration. Multiple instances +can depend on the same instance. -The `resourceID()` function uses this syntax: +The `resourceId()` function uses this syntax: ```yaml -"[resourceId('', '']" +"[resourceId('', '')]" ``` The `` value is the `type` property of the dependent resource and @@ -120,8 +220,12 @@ resource named `Tailspin Key`: - "[resourceId('Microsoft.Windows/Registry', 'Tailspin Key')]" ``` +For an instance in a copy loop, you can use the [copyIndex()][04] function in the expression to +depend on the matching iteration of another copy loop, like +`"[resourceId('Microsoft.DSC.Debug/Echo', format('Policy-{0}', copyIndex()))]"`. + > [!NOTE] -> When defining dependencies for [nested resource instances][03], instances can only reference +> When defining dependencies for [nested resource instances][05], 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. @@ -130,64 +234,112 @@ resource named `Tailspin Key`: > the instance of the provider or group containing the dependency instance instead. For more information about using functions in configuration documents, see -[DSC Configuration document functions reference][04]. For more information about the `resourceId()` +[DSC Configuration document functions reference][06]. For more information about the `resourceId()` function, see [resourceId][02]. ```yaml -Type: array -Required: false -ItemsMustBeUnique: true -ItemsType: string -ItemsPattern: ^\[resourceId\(\s*'\w+(\.\w+){0,2}\/\w+'\s*,\s*'[a-zA-Z0-9 ]+'\s*\)\]$ +Type: array +Required: false +ItemsType: string ``` -### directives +### copy -The `directives` property of a resource instance defines per-instance overrides for how DSC should -process the resource. This property was added in DSC version 3.2. +The `copy` property defines a copy loop that expands the instance into multiple instances that +share the same definition. Before invoking any resources, DSC creates one instance for each +iteration of the loop. Use the [copyIndex()][04] function in the instance's `name`, `properties`, +and `dependsOn` expressions to make each expanded instance unique. The `name` of an instance in a +copy loop must be an expression that evaluates to a different string for every iteration. + +> [!IMPORTANT] +> Copy loops are deprecated. DSC raises a warning when a configuration document uses the `copy` +> property. The functionality remains available for compatibility but will be removed in DSC +> version 4.0.0. For more information, see [DSC issue #1429][07]. + +The value for this property is an object with the following properties: + +- `name` - Required. The name of the copy loop. Pass this name to `copyIndex()` to get the current + iteration index for a specific loop. +- `count` - Required. The number of iterations, as an integer or an expression that evaluates to an + integer, like `"[parameters('serverCount')]"`. A count of `0` expands to no instances. +- `mode` - Optional. Reserved for future use. The schema accepts the values `serial` and + `parallel`, but DSC raises an error if you define this property. +- `batchSize` - Optional. Reserved for future use. The schema accepts an integer or an expression, + but DSC raises an error if you define this property. + +For example, this instance expands into the `Server-0` and `Server-1` instances: + +```yaml +resources: + - name: "[format('Server-{0}', copyIndex())]" + type: Microsoft.DSC.Debug/Echo + copy: + name: serverLoop + count: 2 + properties: + output: "[format('Instance-{0}', copyIndex())]" +``` ```yaml Type: object Required: false ``` -You can define the following directives for a resource instance: - -#### requireAdapter +### properties -The `requireAdapter` directive indicates that DSC should use the specified adapter to invoke the -adapted resource instance. The value for this directive must be the fully qualified type name of -the adapter resource, like `Microsoft.Adapter/PowerShell`. +The `properties` of a resource instance define its desired state. The value of this property must +be an object. For assertion resources, the value can be an empty object (`{}`). DSC uses the +DSC Resource's instance schema to validate the defined properties. -When this directive isn't specified, DSC invokes the adapted resource through the first discovered -adapter that indicates it can invoke the resource. This directive has no effect on nonadapted -resource instances. + ```yaml -Type: string +Type: object Required: false -Pattern: ^\w+(\.\w+){0,2}\/\w+$ ``` -#### securityContext +### resources -The `securityContext` directive indicates that DSC should validate the current security context -against this directive before invoking the resource. This value overrides the -`metadata.Microsoft.DSC.securityContext` setting for the top level of the configuration document. -This enables you to selectively require or forbid elevated security contexts for a specific -resource instance. +The `resources` property defines a list of nested resource instances that use the same schema as a +top-level instance. This property mirrors the shape of a resource in an Azure Resource Manager +(ARM) template. The schema accepts this property, but DSC doesn't currently process instances +defined in it. To manage nested instances, use a group resource like `Microsoft.DSC/Group` and +define the nested instances in the group's `properties`. ```yaml -Type: string -Required: false -ValidValues: [Current, Elevated, Restricted] +Type: array +Required: false +ItemsType: object +``` + +### metadata + +The `metadata` property defines a set of key-value pairs as annotations for the resource instance. +Except for the `Microsoft.DSC` property, DSC doesn't validate the metadata. When DSC invokes the +resource, it passes the metadata to the resource as the `_metadata` property of the instance if the +resource's instance schema allows it. For adapters that accept the full configuration as input, DSC +passes the metadata as the `metadata` property instead. + +The `Microsoft.DSC` property is reserved for DSC. DSC honors the deprecated `securityContext` +setting in this property for the instance, and adds the `copyLoops` property to instances it +expands from a copy loop. For more information, see +[DSC Configuration document metadata schema][08]. + +```yaml +Type: object +Required: false ``` + [01]: ../definitions/resourceType.md [02]: functions/resourceId.md -[03]: /powershell/dsc/glossary#nested-resource-instance -[04]: functions/overview.md +[03]: ../metadata/Microsoft.DSC/properties.md +[04]: functions/copyIndex.md +[05]: /powershell/dsc/glossary#nested-resource-instance +[06]: functions/overview.md +[07]: https://github.com/PowerShell/DSC/issues/1429 +[08]: metadata.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/functions/builtin/dataTypes.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/functions/builtin/dataTypes.md new file mode 100644 index 00000000..8a149999 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/functions/builtin/dataTypes.md @@ -0,0 +1,49 @@ +--- +description: JSON schema reference for the data types that DSC functions operate on. +ms.date: 09/01/2026 +ms.topic: reference +title: Function data types schema reference +--- + +# Function data types schema reference + +## Synopsis + +Defines the available data types that DSC functions operate on. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/definitions/functions/builtin/argKind.json +Type: string +ValidValues: [ + array, + boolean, + lambda, + null, + number, + object, + string + ] +``` + +## Description + +Functions in DSC only support a subset of possible data types for input arguments and output +values. The `dsc function list` command reports these data types in the `acceptedArgOrderedTypes`, +`remainingArgAcceptedTypes`, and `returnTypes` properties for each function. For more information, +see [dsc function list result schema reference][01]. + +The supported data types are: + +- `array` - A collection of items +- `boolean` - Either `true` or `false` +- `lambda` - A valid lambda expression +- `null` - The JSON value `null` +- `number` - A 64-bit integer +- `object` - A collection of key-value pairs +- `string` - UTF-8 text + + +[01]: ../../../outputs/function/list.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/message.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/message.md index 6b5a3e08..63cdee72 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/message.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/message.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a structured message returned from a 'dsc config' command. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: Structured message schema reference --- @@ -21,6 +21,11 @@ Type: object ## Description +When DSC invokes a resource during a `dsc config` command, it captures any messages the resource +emits and returns them in the `messages` array of the command's output. Each message is an object +that identifies the resource instance the message came from, the text of the message, and its +severity. + ## Required properties Every message must be an object that defines these properties: @@ -50,7 +55,7 @@ type names, see [DSC Resource fully qualified type name schema reference][01]. ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` ### message diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md index 388f0716..62898f88 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for valid parameter data types in a configuration document. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC configuration parameter data type schema reference --- @@ -17,7 +17,7 @@ Defines valid data types for a DSC configuration parameter SchemaDialect: https://json-schema.org/draft/2020-12/schema SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/definitions/parameters/dataTypes.json Type: string -ValidValues: [array, bool, int, object, string, secureobject, securestring] +ValidValues: [array, bool, int, object, string, secureObject, secureString] ``` ## Description @@ -31,8 +31,11 @@ The valid data types for a parameter are: - `int` for integers - `object` for objects - `string` for strings -- `secureobject` for secure objects -- `securestring` for secure strings +- `secureObject` for secure objects +- `secureString` for secure strings + +The data type names are case-sensitive. For example, DSC raises an error for a parameter that +defines its `type` as `securestring` instead of `secureString`. Access parameters in a configuration using this syntax: @@ -244,9 +247,9 @@ secure object parameters. ```yaml parameters: password: - type: securestring + type: secureString sensitiveOptions: - type: secureobject + type: secureObject ``` [01]: ../../config/document.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceCapabilities.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceCapabilities.md index 6867e76d..502eaf3f 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceCapabilities.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceCapabilities.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for resource capabilities -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource capabilities schema reference --- @@ -15,7 +15,7 @@ Defines the operations you can invoke for a resource and how the resource behave ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/definitions/resourceKind.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/definitions/resourceCapabilities.json Type: array Required: true ItemsMustBeUnique: true @@ -24,9 +24,10 @@ ItemsValidValues: [ get, set, setHandlesExist, - whatIf, + setWhatIf, test, delete, + deleteWhatIf, export, resolve ] @@ -35,25 +36,53 @@ ItemsValidValues: [ ## Description DSC resources always have at least one capability. Resource capabilities define the operations you -can invoke for a resource and how the resource behaves when invoked. +can invoke for a resource and how the resource behaves when invoked. DSC reports the capabilities +of every discovered resource in the output of the `dsc resource list` command. DSC resources may have the following capabilities: -- `get` - The resource can retrieve the current state of an instance. -- `set` - The resource can enforce the desired state for an instance. -- `setHandlesExist` - The resource handles deleting an instance during - a **Set** operation. -- `whatIf` - The resource can report how it would change state for an instance - during a **Set** operation. -- `test` - The resource implements the **Test** operation and doesn't rely on - synthetic testing. -- `delete` - The resource can remove an instance. -- `export` - The resource can enumerate every instance. -- `resolve` - The resource can resolve nested instances from an external - source. - -For more information about resource capabilities, see [DSC resource capabilities][01]. For more -information about the operations you can invoke for a resource, see [DSC resource operations][02]. - -[01]: ../../../concepts/resources/capabilities.md -[02]: ../../../concepts/resources/operations.md +- `get` - The resource supports retrieving the current state of an instance. +- `set` - The resource supports enforcing the desired state for an instance. +- `setHandlesExist` - The resource handles the `_exist` canonical property directly during a + **Set** operation, including removing an instance when `_exist` is `false`. +- `setWhatIf` - The resource supports simulating the **Set** operation directly, reporting how it + would change the state of an instance without changing it. This capability was added in DSC + version 3.3.0. Through DSC version 3.2.x, this capability was reported as `whatIf`. +- `test` - The resource implements the **Test** operation and doesn't rely on synthetic testing. +- `delete` - The resource supports removing an instance. +- `deleteWhatIf` - The resource supports simulating the **Delete** operation directly, reporting + how it would remove an instance without removing it. This capability was added in DSC version + 3.3.0. +- `export` - The resource supports enumerating every instance. +- `resolve` - The resource supports resolving nested instances from an external source. + +### Capabilities for command resources + +DSC infers the capabilities of a command resource from the properties defined in its resource +manifest: + +| Capability | Manifest properties | +|:------------------|:---------------------------------------------------------------------| +| `get` | [get][01] | +| `set` | [set][02] | +| `setHandlesExist` | [set][02] with `handlesExist` set to `true` | +| `setWhatIf` | [set][02] with a `whatIfArg` item in `args`, or [whatIf][03] | +| `test` | [test][04] | +| `delete` | [delete][05] | +| `deleteWhatIf` | [delete][05] with a `whatIfArg` item in `args` | +| `export` | [export][06] | +| `resolve` | [resolve][07] | + +For more information about resource capabilities, see [DSC resource capabilities][08]. For more +information about the operations you can invoke for a resource, see [DSC resource operations][09]. + + +[01]: ../resource/manifest/get.md +[02]: ../resource/manifest/set.md +[03]: ../resource/manifest/whatif.md +[04]: ../resource/manifest/test.md +[05]: ../resource/manifest/delete.md +[06]: ../resource/manifest/export.md +[07]: ../resource/manifest/resolve.md +[08]: ../../../concepts/resources/capabilities.md +[09]: ../../../concepts/resources/operations.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md index 4b3d216b..56466305 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for resource kind -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource kind schema reference --- @@ -180,7 +180,7 @@ top-level instance of the `Microsoft/OSInfo` resource. The top-level instances o of the `Microsoft.DSC/Group` resource. ```yaml -# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json resources: # The top level echo references and depends on the top-level OSInfo. # It also depends on the top-level Group. @@ -207,8 +207,9 @@ resources: The top-level instance of `Microsoft.DSC/Group` defines three nested resource instances: `Microsoft.DSC.Debug/Echo`, `Microsoft/OSInfo`, and `Microsoft.DSC/Group`. As at the top-level, the -`Microsoft.DSC.Debug/Echo` instance references and depends on the adjacent nested`Microsoft/OSInfo` -instance and that instance depends on the adjacent nested `Microsoft.DSC/Group` instance. +`Microsoft.DSC.Debug/Echo` instance references and depends on the adjacent nested +`Microsoft/OSInfo` instance and that instance depends on the adjacent nested `Microsoft.DSC/Group` +instance. ```yaml # Other top-level instances snipped for brevity @@ -264,7 +265,7 @@ of `Microsoft/OSInfo`. dependsOn: - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]" - name: Deeply nested OSInfo - type: Microsoft.OSInfo + type: Microsoft/OSInfo properties: {} ``` @@ -277,7 +278,7 @@ nested instances in the same group. Putting the configuration together, you get this full document: ```yaml -# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: # The top level echo references and depends on the top-level OSInfo. @@ -332,7 +333,7 @@ resources: dependsOn: - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]" - name: Deeply nested OSInfo - type: Microsoft.OSInfo + type: Microsoft/OSInfo properties: {} ``` @@ -343,7 +344,7 @@ This example configuration is invalid, because the top-level instance of the instance. The nested instance is external to the top-level instance, not adjacent. ```yaml -# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Top level echo @@ -372,7 +373,7 @@ This example configuration is invalid, because the nested instance of the instance. The top-level instance is external to the nested instance, not adjacent. ```yaml -# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json +# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Top level OSInfo diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceType.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceType.md index de466c5a..4e3a9f13 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceType.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceType.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a resource instance type name -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource fully qualified type name schema reference --- @@ -17,25 +17,32 @@ Identifies a DSC Resource. SchemaDialect: https://json-schema.org/draft/2020-12/schema SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/definitions/resourceType.json Type: string -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` ## Description DSC Resources are identified by their fully qualified type name. Values of this type are used to specify a resource in configuration documents and as the value of the `--resource` flag when -using the `dsc resource *` commands. +using the `dsc resource *` commands. DSC extensions use the same syntax for their type names. The fully qualified type name of a resource uses the following syntax: ```text -`[.][.]/` +[.]*/ ``` -Each segment must be string of alphanumeric characters and underscores. No other characters are -permitted. Every resource must define an `owner` and a `name`. Use the `group` and `area` -components to organize resources into related namespaces. For example: +The portion of the type name before the forward slash (`/`) is the namespace. It consists of one +or more segments separated by a single period (`.`). The first segment is always the owner. Any +following segments organize related resources into groups and areas. The portion after the `/` is +the name. +Each segment must be a string of alphanumeric characters and underscores. No other characters are +permitted. Periods can't appear at the start or end of the namespace, and two periods can't appear +consecutively. Every resource must define an `owner` and a `name`. DSC doesn't limit the number of +segments in the namespace. For example: + +- `Microsoft/OSInfo` - `Microsoft.SqlServer/Database` - `Microsoft.SqlServer.Database/Role` - `Microsoft.SqlServer.Database/User` @@ -44,24 +51,32 @@ components to organize resources into related namespaces. For example: - `Microsoft.SqlServer/Login` - `Microsoft.SqlServer/MaxDop` +DSC compares fully qualified type names without regard to case. For example, DSC treats +`Microsoft/OSInfo` and `microsoft/osinfo` as the same type name. + +Earlier versions of the schema limited the number of namespace segments. The schemas published for +DSC 3.0 allow up to three segments and the schemas published for DSC 3.1 allow up to four. Starting +with DSC 3.2.0, the number of segments is unlimited. + ## Type name segments ### Owner -The owner segment of the type name is mandatory. It identifies the person or organization that -owns, develops and maintains the resource. +The owner segment of the type name is mandatory. It's always the first segment of the namespace. +It identifies the person or organization that owns, develops, and maintains the resource. -### Group +### Group and area -The group segment of the type name is optional. It defines a logical grouping for a collection of -resources. For example, resources that manage SQL Server might use the `SqlServer` group in their -type name. +The segments after the owner are optional. Use them to organize resources into related namespaces. +By convention, the first segment after the owner is the _group_. It defines a logical grouping for +a collection of resources. For example, resources that manage SQL Server might use the `SqlServer` +group in their type name. -### Area +The next segment is the _area_. It defines a grouping for a collection of resources by purpose or +higher-level component. For example, resources that manage components of a SQL Server database +might use the `Database` area in their type name. -The area segment of the type name is optional. It defines a grouping for a collection of resources -by purpose or higher-level component. For example, resources that manage components of a SQL Server -database might use the `Database` area in their type name. +You can add further segments after the area when you need to subdivide a namespace further. ### Name diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/manifest/discover.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/manifest/discover.md index 13dcc14f..d1e0bef0 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/manifest/discover.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/manifest/discover.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'discover' property in a DSC extension manifest -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC extension manifest discover property schema reference --- @@ -21,16 +21,39 @@ Type: object ## Description -A DSC extension that can enumerate DSC resource not discoverable in the `PATH` or -`DSC_RESOURCE_PATH` environment variables should define the `export` property in its manifest. This -property defines how DSC can get the path to otherwise undiscoverable manifests. +A DSC extension that can enumerate DSC resources not discoverable in the `PATH` or +`DSC_RESOURCE_PATH` environment variables should define the `discover` property in its manifest. +This property defines how DSC can get the path to, or the content of, otherwise undiscoverable +manifests. When the manifest defines this property, the extension has the `discover` capability. -When the DSC performs discovery for any operation, it calls the command defined by this property. -The extension must return the path to discovered manifests as [JSON lines][05]. Each JSON Line -should be an object representing the instance and validate against the -[DSC extension discover operation stdout schema reference][06]. +When DSC performs discovery for any operation, it calls the command defined by this property with +the folder containing the extension manifest as the working directory. The extension must return +the discovered manifests as [JSON Lines][01]. Each JSON Line must be an object that validates +against the [DSC extension discover operation stdout schema reference][02]. -## Required Properties +## Examples + +The following example shows the `discover` property from the manifest for the +`Microsoft.PowerShell/Discover` extension. It runs a PowerShell script and passes the list of +manifest file extensions that DSC recognizes to the script's `-extensions` parameter as a quoted +string. + +```yaml +discover: + executable: pwsh + args: + - -NoLogo + - -NonInteractive + - -ExecutionPolicy + - Bypass + - -NoProfile + - -Command + - ./powershell.discover.ps1 + - extensionsArg: -extensions + includeQuotes: true +``` + +## Required properties The `discover` definition must include these properties: @@ -52,18 +75,15 @@ Required: true ### args -The `args` property defines the list of arguments to pass to the command. The arguments can be any -number of strings. If you want to pass the JSON object representing the property bag for the -extension input to an argument, you can define a single item in the array as a -[JSON object](#json-input-argument), indicating the name of the argument with the `jsonInputArg` -string property and whether the argument is mandatory for the command with the `mandatory` boolean -property. +The `args` property defines the list of arguments to pass to the command. Each item in the array +can be a string representing a static argument or an +[extensions argument](#extensions-argument) object that receives the list of file extensions DSC +recognizes for manifests. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +ItemsType: [string, object(Extensions argument)] ``` #### String arguments @@ -75,23 +95,37 @@ command, like `discover` or `--format`. Type: string ``` -#### JSON input argument +#### Extensions argument + +Defines an argument that receives the list of file extensions DSC recognizes for manifests. Use +this argument so the extension can find manifests by file name without hard-coding the naming +conventions. This argument type was added in DSC version 3.3.0. + +DSC passes the value of `extensionsArg` to the command, followed by a single argument containing +the comma-separated list of recognized file extensions: + +- `.dsc.adaptedresource.json`, `.dsc.adaptedresource.yaml`, and `.dsc.adaptedresource.yml` +- `.dsc.extension.json`, `.dsc.extension.yaml`, and `.dsc.extension.yml` +- `.dsc.manifests.json`, `.dsc.manifests.yaml`, and `.dsc.manifests.yml` +- `.dsc.resource.json`, `.dsc.resource.yaml`, and `.dsc.resource.yml` -Defines an argument for the command that accepts the JSON input object as a string. DSC passes the -JSON input to the named argument when available. A JSON input argument is defined as a JSON object -with the following properties: +An extensions argument is defined as a JSON object with the following properties: -- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. -- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, - even when there's no JSON input for the command. In that case, DSC passes an empty string to the - JSON input argument. +- `extensionsArg` (required) - The argument to pass before the list of file extensions, like + `--extensions`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the list of file extensions in + double quotes. The default is `false`. -You can only define one JSON input argument per arguments array. +> [!NOTE] +> In DSC 3.2.x, the `args` array for the `discover` property accepted the same JSON input argument +> object (`jsonInputArg`) as the `get.args` property in resource manifests. Starting with DSC +> 3.3.0, that form isn't valid for the `discover` property. ```yaml -Type: object -RequiredProperties: [jsonInputArg] +Type: object +RequiredProperties: [extensionsArg] ``` -[05]: https://jsonlines.org/ -[06]: ../stdout/discover.md + +[01]: https://jsonlines.org/ +[02]: ../stdout/discover.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/manifest/root.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/manifest/root.md index 53d82785..1b9f3a93 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/manifest/root.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/manifest/root.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a DSC extension manifest -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: Command-based DSC extension manifest schema reference --- @@ -21,14 +21,20 @@ Type: object ## Description -Every command-based DSC Resource must have a manifest. The manifest file must: +Every command-based DSC extension must have a manifest. The manifest file must: 1. Be discoverable in the `PATH` environment variable. 1. Be formatted as either JSON or YAML. -1. Follow the naming convention `.dsc.resource.`. Valid extensions include `json`, - `yml`, and `yaml`. +1. Follow the naming convention `.dsc.extension.`. Valid extensions include + `json`, `yml`, and `yaml`. 1. Be valid for the schema described in this document. +DSC infers the capabilities of an extension from the operation properties defined in the manifest. +An extension has the `discover` capability when the manifest defines the [discover](#discover) +property, the `import` capability when the manifest defines the [import](#import) property, and +the `secret` capability when the manifest defines the [secret](#secret) property. An extension +that doesn't define any of these properties has no capabilities. + The rest of this document describes the manifest's schema. ## Required properties @@ -38,7 +44,6 @@ The manifest must include these properties: - [$schema](#schema) - [type](#type) - [version](#version) -- [discover](#discover) ## Properties @@ -52,10 +57,11 @@ The JSON schemas for DSC are published in multiple versions and forms. This docu the latest version of the schema. As a convenience, you can specify either the full URI for the schema hosted in GitHub or use the shorter `aka.ms` URI. You can specify the schema for a specific semantic version, the latest schema for a minor version, or the latest schema for a major version -of DSC. For more information about schema URIs and versioning, see -[DSC JSON Schema URIs](../../schema-uris.md). +of DSC. DSC recognizes the URIs for every version folder listed below, but the schemas aren't +published to every recognized folder. For more information about schema URIs and versioning, see +[DSC JSON Schema URIs][01]. -For every version of the schema, there are three valid urls: +For every version of the schema, there are three valid URLs: - `.../extension/manifest.json` @@ -77,8 +83,9 @@ For every version of the schema, there are three valid urls: it includes additional definitions that provide contextual help and snippets that the others don't include. - This schema uses keywords that are only recognized by VS Code. While DSC can still validate the - document when it uses this schema, other tools may error or behave in unexpected ways. + This schema uses keywords that are only recognized by Visual Studio Code. While DSC can still + validate the document when it uses this schema, other tools may error or behave in unexpected + ways. ```yaml Type: string @@ -88,44 +95,147 @@ ValidValues: [ https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/extension/manifest.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/extension/manifest.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/extension/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/extension/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/extension/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/extension/manifest.vscode.json https://aka.ms/dsc/schemas/v3/extension/manifest.json https://aka.ms/dsc/schemas/v3/bundled/extension/manifest.json https://aka.ms/dsc/schemas/v3/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.3/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.2/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.1/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.0/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/extension/manifest.vscode.json https://aka.ms/dsc/schemas/v3.1/extension/manifest.json https://aka.ms/dsc/schemas/v3.1/bundled/extension/manifest.json https://aka.ms/dsc/schemas/v3.1/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.3/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.2/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.1/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/extension/manifest.vscode.json https://aka.ms/dsc/schemas/v3.1.0/extension/manifest.json https://aka.ms/dsc/schemas/v3.1.0/bundled/extension/manifest.json https://aka.ms/dsc/schemas/v3.1.0/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.0/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.0.2/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.2/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.2/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.0.1/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.1/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.1/bundled/extension/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.0.0/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.0/bundled/extension/manifest.json + https://aka.ms/dsc/schemas/v3.0.0/bundled/extension/manifest.vscode.json ] ``` ### type -The `type` property represents the fully qualified type name of the extension. For more information -about extension type names, see [DSC resource fully qualified type name schema reference][01]. +The `type` property represents the fully qualified type name of the extension. Extension type +names use the same syntax as resource type names: an owner segment, any number of namespace +segments, a forward slash (`/`), and a name segment. For more information about type names, see +[DSC Resource fully qualified type name schema reference][02]. ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,3}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` ### version The `version` property must be the current version of the extension as a valid semantic version -(semver) string. +(SemVer) string. ```yaml Type: string Required: true -Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +Pattern: ^(?(?:0|[1-9]\d*))\.(?(?:0|[1-9]\d*))\.(?(?:0|[1-9]\d*))(?:-(?(?:(?:0|[1-9]\d*)|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:(?:0|[1-9]\d*)|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +``` + +### condition + +The `condition` property defines a DSC configuration expression that DSC evaluates during +discovery to determine whether the extension is usable on the system. If the expression evaluates +to `false`, DSC discards the extension during discovery and writes a debug message indicating that +the manifest's condition wasn't met. If the manifest doesn't define this property, or the +expression evaluates to `true`, DSC discovers the extension as normal. + +Use this property for extensions with external prerequisites. For example, the +`Microsoft.PowerShell/Discover` extension defines the condition +`[not(equals(tryWhich('pwsh'), null()))]` so that DSC ignores the extension when `pwsh` isn't +available on the system. + +```yaml +Type: string +Required: false +``` + +### deprecationMessage + +The `deprecationMessage` property indicates that the extension is deprecated. When this property +is defined, DSC raises a warning that includes the message whenever it invokes the extension. DSC +also reports the message in the output of the `dsc extension list` command. + +```yaml +Type: string +Required: false ``` ### description @@ -156,16 +266,86 @@ ItemsPattern: ^\w+$ The `discover` property defines how to call the extension to discover DSC resources that aren't available in the `PATH` or `DSC_RESOURCE_PATH` environment variables. When this property is -defined, DSC invokes the `discover` operation for the extension during the resource discovery phase -of any `dsc config` or `dsc resource` command. +defined, the extension has the `discover` capability and DSC invokes the `discover` operation for +the extension during the resource discovery phase of any `dsc config` or `dsc resource` command. The value of this property must be an object. The object's `executable` property, defining the name -of the command to call, is mandatory. The `args` property is optional. For more -information, see [DSC extension manifest discover property schema reference][02]. +of the command to call, is mandatory. The `args` property is optional. For more information, see +[DSC extension manifest discover property schema reference][03]. ```yaml Type: object -Required: true +Required: false +``` + +### import + +The `import` property defines how to call the extension to convert a file that DSC can't parse +directly into a configuration document. When this property is defined, the extension has the +`import` capability. + +When you pass a file to a `dsc config` command with the `--file` option, DSC checks whether any +extension with the `import` capability handles the file's extension. DSC uses the content returned +by the first extension that successfully imports the file as the configuration document. If no +extension imports the file, DSC reads the file directly. + +The value of this property must be an object with the following properties: + +- `fileExtensions` (required) - An array of strings defining the file extensions the extension can + import, like `["bicep"]`. Define the extensions without the leading period. If this array is + empty, DSC writes a warning during discovery and the extension can't import any files. +- `executable` (required) - The name of the command to run. The value must be the name of a + command discoverable in the system's `PATH` environment variable or the full path to the command. +- `args` (optional) - The list of arguments to pass to the command. Each item in the array can be + a string representing a static argument, like `--format`, or an object with the `fileArg` + property. For the `fileArg` item, DSC passes the value of `fileArg` followed by the absolute path + to the file to import. If `fileArg` is an empty string, DSC passes only the path. +- `output` (optional) - A DSC configuration expression that DSC evaluates after the command + completes to transform the command's output into the configuration document. Use the `stdout()` + function in the expression to access the text the command wrote to stdout. When this property + isn't defined, DSC uses the command's output as the configuration document without modification. + +```yaml +Type: object +Required: false +``` + +### importParameters + +The `importParameters` property has the same structure as the [import](#import) property. DSC +reserves this property for a future operation that imports parameters from files in formats DSC +can't parse directly. DSC validates this property when it loads the manifest but doesn't currently +invoke the command it defines. + +```yaml +Type: object +Required: false +``` + +### secret + +The `secret` property defines how to call the extension to retrieve a secret from a vault at +runtime. When this property is defined, the extension has the `secret` capability and DSC can +invoke the extension for the [secret()][04] configuration function. + +The value of this property must be an object with the following properties: + +- `executable` (required) - The name of the command to run. The value must be the name of a + command discoverable in the system's `PATH` environment variable or the full path to the command. +- `args` (optional) - The list of arguments to pass to the command. Each item in the array can be + a string representing a static argument, an object with the `nameArg` property, or an object + with the `vaultArg` property. For the `nameArg` item, DSC passes the value of `nameArg` followed + by the name of the secret to retrieve. For the `vaultArg` item, DSC passes the value of + `vaultArg` followed by the name of the vault when the `secret()` function specifies a vault. When + the function doesn't specify a vault, DSC omits the `vaultArg` item entirely. + +The command must write the secret value to stdout as a single line. If the command writes more +than one line to stdout, DSC raises an error. If the command writes nothing to stdout, DSC treats +the secret as not found for that extension. + +```yaml +Type: object +Required: false ``` ### exitCodes @@ -197,9 +377,24 @@ DSC interprets exit code `0` as a successful operation and any other exit code a ```yaml Type: object Required: false -PropertyNamePattern: ^-?[0-9]+# +PropertyNamePattern: ^-?[0-9]+$ PropertyValueType: string ``` -[01]: ../../definitions/resourceType.md -[02]: discover.md +### metadata + +The `metadata` property defines an object of arbitrary additional data for the extension. DSC +doesn't validate or use the values in this object. Use this property to include any information +about the extension that isn't covered by the other manifest properties, like details for +integrating tools. + +```yaml +Type: object +Required: false +``` + + +[01]: ../../schema-uris.md +[02]: ../../definitions/resourceType.md +[03]: discover.md +[04]: ../../config/functions/secret.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/stdout/discover.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/stdout/discover.md index 7517e8e0..eb9e3db6 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/stdout/discover.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/extension/stdout/discover.md @@ -1,6 +1,6 @@ --- -description: JSON schema reference for the output DSC expects for the 'discover' operation. -ms.date: 02/28/2025 +description: JSON schema reference for the 'discover' operation output in a DSC extension +ms.date: 09/01/2026 ms.topic: reference title: DSC extension discover operation stdout schema reference --- @@ -9,8 +9,7 @@ title: DSC extension discover operation stdout schema reference ## Synopsis -Represents the path to a manifest not discoverable in the `PATH` or `DSC_RESOURCE_PATH` environment -variables. +Represents a manifest not discoverable in the `PATH` or `DSC_RESOURCE_PATH` environment variables. ## Metadata @@ -22,28 +21,68 @@ Type: object ## Description -Represents the actual state of a resource instance in DSCpath to a discovered DSC resource or -extension manifest on the system. DSC expects every JSON Line emitted to stdout for the -**Discover** operation to adhere to this schema. +Represents a DSC manifest that the extension discovered, either as the absolute path to the +manifest file on the system or as the content of the manifest. DSC expects every JSON Line emitted +to stdout for the **Discover** operation to adhere to this schema. -The output must be a JSON object. The object must define the full path to the discovered manifest. -If an extension returns JSON that is invalid against this schema, DSC raises an error. +The output must be a JSON object. The object must define exactly one of the [manifestPath][01] or +[manifestContent][02] properties. If an extension returns JSON that is invalid against this schema, +DSC raises an error. -## Required Properties +Each discovered manifest must be emitted as a separate JSON Line to stdout. If the extension +doesn't discover any manifests, it must return nothing to stdout and exit with code `0`. An empty +output with a zero exit code indicates no resources were found. A non-zero exit code indicates an +error, even if stdout is empty. -The output for the `discover` operation must include these properties: +DSC uses the discovered manifests to find resources, including adapted resources and resources +defined in manifest lists. Extensions can't currently discover other extensions. If a discovered +manifest defines an extension, DSC ignores it. + +## Required properties + +The output for the `discover` operation must include exactly one of these properties: - [manifestPath](#manifestpath) +- [manifestContent](#manifestcontent) ## Properties ### manifestPath -The value for this property must be the absolute path to a manifest file on the system. The -manifest can be for a DSC resource or extension. If the returned path doesn't exist, DSC raises an -error. +The value for this property must be the absolute path to a manifest file on the system. DSC +determines how to load the manifest from the file name, so the file name must follow one of the +manifest naming conventions, like `.dsc.resource.json`, `.dsc.adaptedresource.json`, +or `.dsc.manifests.json`. + +If the returned path isn't absolute, DSC raises an error. If DSC can't load the manifest at the +returned path, it writes an informational message and skips that manifest. ```yaml Type: string -Required: true +Required: true (when manifestContent isn't defined) +``` + +### manifestContent + +The value for this property must be the content of a manifest as a JSON object. DSC processes the +value the same way it processes the content of a manifest file, including evaluating the +`condition` property of the manifest. The value can be a resource manifest, an adapted resource +manifest, or a manifest list. If the value isn't a valid manifest, DSC raises an error. This +property was added in DSC version 3.3.0. + +```yaml +Type: object +Required: true (when manifestPath isn't defined) ``` + +## Exit codes + +The extension must return one of the following exit codes: + +- `0` - Success. The extension completed discovery. If no manifests were found, stdout is empty. +- Non-zero - Error. DSC treats any non-zero exit code as a failure and surfaces the extension's + stderr output as an error message. + + +[01]: #manifestpath +[02]: #manifestcontent diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/metadata/Microsoft.DSC/properties.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/metadata/Microsoft.DSC/properties.md index ecd32e44..07f905bc 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/metadata/Microsoft.DSC/properties.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/metadata/Microsoft.DSC/properties.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the metadata field Microsoft.DSC -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: Microsoft.DSC metadata property schema reference --- @@ -13,19 +13,27 @@ Metadata properties used and returned by DSC for configuration and resource oper ## Description -The `Microsoft.DSC` metadata object captures execution details that DSC adds to -command output and, when applicable, to resource results. It describes what -operation ran, when it started and finished, how long it took, the security -context DSC ran under, and the DSC version that produced the output. These -properties are informational and help with diagnostics, auditing, and tooling. +The `Microsoft.DSC` metadata object captures execution details that DSC adds to command output and, +when applicable, to resource results. It describes what operation ran, when it started and +finished, how long it took, the security context DSC ran under, the DSC version that produced the +output, and any restarts that resources reported as required. These properties are informational +and help with diagnostics, auditing, and tooling. -Not every property is present for every operation. For example, `executionType` -is only meaningful for `Set` (and is `WhatIf` when you invoke DSC with -`--whatIf`), while `operation` is always provided. Timestamps use RFC 3339 -`date-time` format, and durations use the ISO 8601 `duration` format. +Every property is optional. Which properties DSC includes depends on the context. The top-level +metadata for a configuration operation includes the operation, execution type, timestamps, +duration, security context, version, and any required restarts. The metadata for an individual +resource instance result includes only the duration of that instance's operation. Timestamps use +RFC 3339 `date-time` format, and durations use the ISO 8601 `duration` format. -Consumers should tolerate additional, future metadata fields. Producers should -preserve unknown metadata they do not interpret. +Starting with DSC version 3.2.0, DSC returns the same execution information in the top-level +`executionInformation` property of command output and in the `executionInformation` property of +each resource instance result. The `metadata.Microsoft.DSC` property is retained for backwards +compatibility with tools and scripts that process DSC output. In DSC version 4.0.0, command output +will no longer include the `metadata.Microsoft.DSC` property. Prefer `executionInformation` when +writing new tools and scripts. + +Consumers should tolerate additional, future metadata fields. Producers should preserve unknown +metadata they do not interpret. ## Properties @@ -43,7 +51,7 @@ Type: string Format: duration ``` -### endDateTime +### endDatetime Defines the end date and time for the DSC operation as a timestamp following the format defined in [RFC3339, section 5.6 (see `date-time`)][02]. @@ -52,48 +60,84 @@ For example: `2024-04-14T08:49:51.395686600-07:00` ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/metadata/Microsoft.DSC/endDateTime.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/metadata/Microsoft.DSC/endDatetime.json Type: string Format: date-time ``` ### executionType -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 `--whatIf` argument. +Defines whether DSC actually applied an operation to the configuration or was 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. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/metadata/Microsoft.DSC/executionType.json Type: string -ValidValues: [Actual, WhatIf] +ValidValues: [actual, whatIf] ``` ### operation -Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or -`Export`. +Defines the operation that DSC applied to the configuration document: `get`, `set`, `test`, or +`export`. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/metadata/Microsoft.DSC/operation.json Type: string -ValidValues: [Get, Set, Test, Export] +ValidValues: [get, set, test, export] +``` + +### restartRequired + +Defines the list of restarts that resources reported as required after the operation. DSC collects +this information from the `_restartRequired` property that a resource returns in its result. The +top-level metadata for a configuration operation includes the entries reported by every instance in +the document. DSC only includes this property when at least one resource reported a required +restart. + +Each item in the list is an object with exactly one of the following properties: + +- `system` - A string that identifies the system that requires a restart. +- `service` - The name of a service that requires a restart. +- `process` - An object with the `name` (string) and `id` (integer) of a process that requires a + restart. + +Use the [restartRequired()][03] configuration function to check for required restarts in the +outputs of a configuration document. + +```yaml +Type: array +ItemsType: object +ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/executionInformation/restartRequired.json +``` + +### copyLoops + +Defines the copy loop context for a resource instance that DSC expanded from a copy loop. When DSC +expands a copy loop, it adds this property to the metadata of each expanded instance. The value is +an object where each key is the name of a copy loop and the value is the zero-based iteration index +of the instance in that loop. DSC uses this information to resolve the `copyIndex()` function when +it evaluates the instance's properties. DSC doesn't include this property in command output. + +```yaml +Type: object ``` ### securityContext 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 or account in a +`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. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/metadata/Microsoft.DSC/securityContext.json Type: string -ValidValues: [Current, Elevated, Restricted] +ValidValues: [current, elevated, restricted] ``` ### startDatetime @@ -118,9 +162,10 @@ DSC command, like `3.0.0-preview.7`. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/metadata/Microsoft.DSC/version.json -Type: object +Type: string ``` [01]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A [02]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 +[03]: ../../config/functions/restartRequired.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/get.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/get.md index 222f8893..3d730134 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/get.md +++ b/dsc/docs-conceptual/dsc-3.0/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,15 +57,43 @@ 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 @@ -83,16 +101,43 @@ 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 +``` + [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 diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md index dac24917..61fe8351 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc config set' command. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: dsc config set result schema reference --- @@ -29,34 +29,24 @@ for each instance. 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 @@ -68,15 +58,43 @@ 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 `set` 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 @@ -84,16 +102,46 @@ 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. +- `whatIf` defines the information the resource returned about the what-if operation. DSC only + includes this property when you invoke the command with the `--what-if` argument and the + resource returned what-if metadata for a delete operation. + +```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 @@ -109,12 +157,12 @@ Required: true An item's `result` property includes the enforced state for the resource instance. The value for this property adheres to the same schema as the output for the `dsc resource set` command. For more -information, see [dsc resource set result schema reference][11]. +information, see [dsc resource set result schema reference][13]. ### messages Defines the list of structured messages emitted by resources during the set operation. For more -information, see [Structured message schema reference][12]. +information, see [Structured message schema reference][14]. ```yaml Type: array @@ -131,6 +179,19 @@ 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. DSC doesn't evaluate outputs when +you invoke the command with the `--what-if` argument. For more information about defining outputs, +see the [outputs][15] property in the configuration document schema. + +```yaml +Type: object +Required: false +``` + [01]: ../../metadata/Microsoft.DSC/properties.md#version [02]: ../../metadata/Microsoft.DSC/properties.md#operation @@ -141,6 +202,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/set.md -[12]: ../../definitions/message.md +[10]: ../../metadata/Microsoft.DSC/properties.md#restartrequired +[11]: ../../metadata/Microsoft.DSC/properties.md +[12]: ../../definitions/resourceType.md +[13]: ../resource/set.md +[14]: ../../definitions/message.md +[15]: ../../config/document.md#outputs diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md index df64e67f..8f8d1f70 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc config test' command. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: dsc config test result schema reference --- @@ -21,42 +21,32 @@ Type: object ## Description -The output from the `dsc config test` command includes the state of every resource instance in the -configuration before and after the test operation, and the list of properties the operation changed -for each instance. +The output from the `dsc config test` command includes the desired and actual state of every +resource instance in the configuration, whether each instance is in the desired state, and the +list of properties that aren't in the desired state for each instance. ## Required properties 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 @@ -68,15 +58,43 @@ 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 `test` 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 @@ -84,16 +102,43 @@ 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 @@ -109,12 +154,12 @@ Required: true An item's `result` property includes the validation state for the resource instance. The value for this property adheres to the same schema as the output for the `dsc resource test` command. For -more information, see [dsc resource test result schema reference][11]. +more information, see [dsc resource test result schema reference][13]. ### messages Defines the list of structured messages emitted by resources during the test operation. For more -information, see [Structured message schema reference][12]. +information, see [Structured message schema reference][14]. ```yaml Type: array @@ -131,6 +176,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 +``` + [01]: ../../metadata/Microsoft.DSC/properties.md#version [02]: ../../metadata/Microsoft.DSC/properties.md#operation @@ -141,6 +198,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/test.md -[12]: ../../definitions/message.md +[10]: ../../metadata/Microsoft.DSC/properties.md#restartrequired +[11]: ../../metadata/Microsoft.DSC/properties.md +[12]: ../../definitions/resourceType.md +[13]: ../resource/test.md +[14]: ../../definitions/message.md +[15]: ../../config/document.md#outputs diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/extension/list.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/extension/list.md index f31dafc8..87deb996 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/extension/list.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/extension/list.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc extension list' command. -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: dsc extension list result schema reference --- @@ -31,7 +31,11 @@ Each extension in the output always includes these properties: - [type](#type) - [version](#version) +- [capabilities](#capabilities) +- [import](#import) - [path](#path) +- [deprecation_message](#deprecation_message) +- [description](#description) - [directory](#directory) - [author](#author) - [manifest](#manifest) @@ -40,18 +44,19 @@ Each extension in the output always includes these properties: ### type -Identifies the fully qualified type name of the extension. For more information about extension -type names, see [DSC extension fully qualified type name schema reference][02]. +Identifies the fully qualified type name of the extension. Extension type names use the same +syntax as resource type names. For more information, see +[DSC Resource fully qualified type name schema reference][02]. ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` ### version -Represents the current version of the extension as a valid semantic version (semver) string. +Represents the current version of the extension as a valid semantic version (SemVer) string. ```yaml Type: string @@ -62,13 +67,23 @@ Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z ### capabilities Defines the operations and behaviors the extension is implemented to support. This property is an -array of capabilities. +array of capabilities. DSC infers the capabilities from the properties defined in the extension +manifest. The following list describes the available capabilities for an extension: - `discover` - The extension supports finding DSC resource manifests that aren't in the `PATH` or `DSC_RESOURCE_PATH`, as with resources installed as Appx - packages. + packages. An extension has this capability when its manifest defines the [discover][03] + property. + +- `secret` - The extension supports retrieving secret values from a + vault at runtime instead of passing sensitive values directly to a command or with a parameter + file. An extension has this capability when its manifest defines the [secret][04] property. + +- `import` - The extension supports resolving files as DSC + configuration documents to enable passing those files to DSC for `dsc config` commands. An + extension has this capability when its manifest defines the [import][05] property. ```yaml Type: array @@ -76,17 +91,21 @@ Required: true ItemsMustBeUnique: true ItemsType: string ItemsValidValues: [ - discover + discover, + secret, + import ] ``` -### description +### import -Defines a synopsis for the extension's purpose as a short string. If the extension doesn't have a -description, this property is `null`. +Represents the definition of the `import` operation for the extension as defined in its manifest. +If the extension doesn't define the `import` property in its manifest, or defines it with an empty +`fileExtensions` list, this property is `null`. For more information about the value for this +property, see the [import][05] property in the extension manifest schema reference. ```yaml -Type: [string, 'null'] +Type: [object, 'null'] Required: true ``` @@ -99,6 +118,27 @@ Type: string Required: true ``` +### deprecation_message + +Represents the deprecation message for the extension as defined in its manifest. If the extension +isn't deprecated, this property is `null`. Note that this property uses an underscore in its name +rather than the camel case used by the `deprecationMessage` property in the manifest. + +```yaml +Type: [string, 'null'] +Required: true +``` + +### description + +Defines a synopsis for the extension's purpose as a short string. If the extension doesn't have a +description, this property is `null`. + +```yaml +Type: [string, 'null'] +Required: true +``` + ### directory Represents the path to the folder containing the extension's manifest on the machine. @@ -121,14 +161,17 @@ Required: true ### manifest Represents the values defined in the extension's manifest. For more information on the value for -this property, see [Command-based DSC extension manifest schema reference][03]. +this property, see [Command-based DSC extension manifest schema reference][06]. ```yaml -Type: [object] +Type: object Required: true ``` [01]: https://jsonlines.org/ [02]: ../../definitions/resourceType.md -[03]: ../../extension/manifest/root.md +[03]: ../../extension/manifest/root.md#discover +[04]: ../../extension/manifest/root.md#secret +[05]: ../../extension/manifest/root.md#import +[06]: ../../extension/manifest/root.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/function/list.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/function/list.md new file mode 100644 index 00000000..a0d14976 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/function/list.md @@ -0,0 +1,243 @@ +--- +description: JSON schema reference for the data returned by the 'dsc function list' command. +ms.date: 09/01/2026 +ms.topic: reference +title: dsc function list result schema reference +--- + +# dsc function list result schema reference + +## Synopsis + +The result output from the `dsc function list` command. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/function/list.json +Type: object +``` + +## Description + +The output from the `dsc function list` command includes a representation of discovered DSC +functions as a series of [JSON Lines][01]. This schema describes the JSON object returned for each +function. + +## Examples + +The following example shows the output of `dsc function list concat -o pretty-json`: + +```json +{ + "category": [ + "array", + "string" + ], + "name": "concat", + "description": "Concatenates two or more strings or arrays", + "syntax": "concat( , , ... )", + "constraints": "All arguments must be of the same type (all strings or all arrays)", + "minArgs": 2, + "maxArgs": 18446744073709551615, + "acceptedArgOrderedTypes": [ + [ + "string", + "array" + ], + [ + "string", + "array" + ] + ], + "remainingArgAcceptedTypes": [ + "string", + "array" + ], + "returnTypes": [ + "string", + "array" + ] +} +``` + +## Required properties + +Each function in the output always includes these properties: + +- [category](#category) +- [name](#name) +- [description](#description) +- [syntax](#syntax) +- [constraints](#constraints) +- [minArgs](#minargs) +- [maxArgs](#maxargs) +- [acceptedArgOrderedTypes](#acceptedargorderedtypes) +- [remainingArgAcceptedTypes](#remainingargacceptedtypes) +- [returnTypes](#returntypes) + +## Properties + +### category + +Identifies the categories that the function belongs to. Every function belongs to one or more +categories. The defined categories are: + +- `array` - functions for constructing and operating on arrays. +- `cidr` - functions for working with CIDR notation. +- `comparison` - functions for comparing values and return a boolean value. +- `date` - functions for working with dates. +- `deployment` - functions for working with runtime data, like retrieving secrets. +- `lambda` - functions for processing data with subexpressions. +- `logical` - functions for defining conditional logic and working with boolean values. +- `numeric` - functions for constructing and operating on numbers. +- `object` - functions for constructing and operating on objects. +- `resource` - functions for operating on resource instances. +- `string` - functions for constructing and operating on strings. +- `system` - functions that retrieve information from the operating system. + +> [!NOTE] +> This list is _not_ guaranteed to be stable. In future minor releases, DSC may add new function +> categories. No categories will be _removed_ except in a major version release with breaking +> changes. + +```yaml +Type: array +Required: true +ItemsType: string +ItemsValidValues: [ + array, + cidr, + comparison, + date, + deployment, + lambda, + logical, + numeric, + object, + resource, + string, + system + ] +``` + +### name + +Defines the name of the function as you would specify it in a configuration document or manifest +field that supports functions. Function names always use `camelCase`, like `tryWhich`. Function +names are always defined as ASCII alphabetical characters. + +```yaml +Type: string +Required: true +Pattern: ^[a-z][a-zA-Z]+$ +``` + +### description + +Defines a synopsis for the function's purpose as a short string. + +```yaml +Type: string +Required: true +``` + +### syntax + +Defines the syntax for calling the function as a short string, like +`concat( , , ... )`. The syntax string shows the arguments the +function accepts and the types it accepts for each argument. This property was added in DSC +version 3.3.0. + +```yaml +Type: string +Required: true +``` + +### constraints + +Defines any additional constraints on the arguments for the function that the argument types alone +don't express, like `All arguments must be of the same type (all strings or all arrays)`. When the +function doesn't have any additional constraints, this property is `null`. This property was added +in DSC version 3.3.0. + +```yaml +Type: [string, 'null'] +Required: true +``` + +### minArgs + +Indicates the minimum number of arguments for the function. When you provide fewer than the minimum +required arguments DSC raises a parsing error. + +```yaml +Type: integer +Required: true +MinimumValue: 0 +``` + +### maxArgs + +Indicates the maximum number of arguments for the function. When you provide more than the maximum +allowed arguments DSC raises a parsing error. For functions that accept an unlimited number of +arguments, this property is the largest value DSC can represent for an unsigned integer, like +`18446744073709551615` on 64-bit platforms. + +```yaml +Type: integer +Required: true +MinimumValue: 0 +``` + +### acceptedArgOrderedTypes + +Indicates the acceptable types for each argument in the order that the function expects them. This +property is an array of arrays. Each inner array contains a set of strings that map to allowed +[argument types][02]. + +DSC raises a parsing error when the value for an argument isn't a valid type for that argument. + +```yaml +Type: array +Required: true +ItemsMustBeUnique: false +ItemsType: array(Valid function argument types) +``` + +### remainingArgAcceptedTypes + +Indicates the acceptable types for the last parameter of a variadic function. Variadic functions +are functions that accept multiple values for the final parameter. + +When this field is defined as `null`, the function doesn't support multiple values for the last +parameter. When this field is defined as an array of [argument types][02] the function supports +passing multiple arguments of those types for the final parameter. + +DSC raises a parsing error when the value for a remaining argument isn't a valid type. + +```yaml +Type: ['null', 'array'] +Required: true +ItemsMustBeUnique: true +ItemsReference: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/definitions/functions/builtin/argKind.json +``` + +### returnTypes + +Indicates the [types][02] of values the function can return. When the only item in this array is +the `null` type the function doesn't return any data. When this field contains more than one item +the function may return any of the listed types. For more information about how the function +returns data, see the reference documentation for that function. + +```yaml +Type: array +Required: true +ItemsMustBeUnique: true +ItemsReference: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/definitions/functions/builtin/argKind.json +``` + + +[01]: https://jsonlines.org/ +[02]: ../../definitions/functions/builtin/dataTypes.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md index 093a10a9..dd489c23 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource get' command. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: dsc resource get result schema reference --- @@ -68,37 +68,39 @@ data is returned: ### Required properties -- [metadata](#metadata-1) - [name](#name) - [type](#type) - [result](#result) ### Properties -#### metadata +#### executionInformation -Defines metadata DSC returns for a configuration operation. The properties under the -`Microsoft.DSC` property describe the context of the operation. +Describes the context of the operation for the resource instance. The value is an object with the +following properties: - [duration][01] defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in [ISO8601 ABNF for `duration`][02]. For example, `PT0.611216S` represents a duration of about `0.61` seconds. +- [restartRequired][03] 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: true +Required: false ``` -#### type +#### metadata -The `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][03]. +Defines metadata DSC returns for a resource instance operation. The `Microsoft.DSC` property under +this property includes the [duration][01] 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: string -Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Type: object +Required: false ``` #### name @@ -110,6 +112,18 @@ Type: string Required: true ``` +#### type + +The `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][04]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+)*\/\w+$ +``` + #### result The `result` property includes the actual state for the resource. This value is either: @@ -126,4 +140,5 @@ Required: true [01]: ../../metadata/Microsoft.DSC/properties.md#duration [02]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A -[03]: ../../definitions/resourceType.md +[03]: ../../metadata/Microsoft.DSC/properties.md#restartrequired +[04]: ../../definitions/resourceType.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md index 0299dfdf..5fdd6ea3 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource list' command. -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: dsc resource list result schema reference --- @@ -22,22 +22,24 @@ Type: object ## Description The output from the `dsc resource list` command includes a representation of discovered DSC -Resources as a series of [JSON Lines][01]. This schema describes the JSON object returned for each -resource. +resources as a series of [JSON Lines][01]. This schema describes the JSON object returned for each +resource. DSC uses the same schema to represent the adapted resources a resource adapter returns +for the **List** operation. For more information, see +[DSC resource list operation stdout schema reference][02]. + +The output object for a resource always includes every property described in this document. When a +property isn't defined for a resource, DSC emits the property with the value `null`. ## Required properties -Each resource in the output always includes these properties: +Each resource in the output always defines these properties: - [type](#type) +- [kind](#kind) - [version](#version) +- [capabilities](#capabilities) - [path](#path) - [directory](#directory) -- [implementedAs](#implementedas) -- [author](#author) -- [properties](#properties) -- [requireAdapter](#requireadapter) -- [manifest](#manifest) ## Properties @@ -46,30 +48,32 @@ Each resource in the output always includes these properties: Identifies the fully qualified type name of the resource. It's used to specify the resource in configuration documents and as the value of the `--resource` flag when using the `dsc resource *` commands. For more information about resource type names, see -[DSC Resource fully qualified type name schema reference][02]. +[DSC Resource fully qualified type name schema reference][03]. ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` ### kind -Identifies whether a resource is an [adapter resource][03], a [group resource][04], or neither. -This value is either defined in the [resource manifest][05] or inferred by DSC. For more -information about resource kinds, see [DSC Resource kind schema reference][06]. +Identifies how DSC handles the resource. DSC supports several kinds of resources: `resource`, +`adapter`, `group`, `importer`, and `exporter`. This value is either defined in the +[resource manifest][04] or inferred by DSC. For more information about resource kinds, see +[DSC Resource kind schema reference][05]. ```yaml -Type: string -Required: true -ValidValues: [Resource, Adapter, Group] +Type: string +Required: true +ValidValues: [adapter, exporter, group, importer, resource] ``` ### version -Represents the current version of the resource as a valid semantic version (semver) string. The -version applies to the resource, not the software it manages. +Represents the current version of the resource as a valid semantic version (SemVer) string. The +version applies to the resource, not the software it manages. DSC also accepts a deprecated +date-based version in the format `YYYY-MM-DD` with an optional prerelease suffix. ```yaml Type: string @@ -79,23 +83,27 @@ Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z ### capabilities -DSC resources always have at least one capability. Resource capabilities define the operations you -can invoke for a resource and how the resource behaves when invoked. +Defines the list of capabilities for the resource. DSC resources always have at least one +capability. Resource capabilities define the operations you can invoke for a resource and how the +resource behaves when invoked. DSC resources may have the following capabilities: - `get` - The resource can retrieve the current state of an instance. - `set` - The resource can enforce the desired state for an instance. - `setHandlesExist` - The resource handles deleting an instance during a **Set** operation. -- `whatIf` - The resource can report how it would change state for an instance during a **Set** - operation. +- `setWhatIf` - The resource can report how it would change state for an instance during a **Set** + operation without modifying the system. This capability was added in DSC version 3.3.0. Through + DSC version 3.2, this capability was named `whatIf`. - `test` - The resource implements the **Test** operation and doesn't rely on synthetic testing. - `delete` - The resource can remove an instance. +- `deleteWhatIf` - The resource can report how it would remove an instance during a **Delete** + operation without modifying the system. This capability was added in DSC version 3.3.0. - `export` - The resource can enumerate every instance. - `resolve` - The resource can resolve nested instances from an external source. -For more information about resource capabilities, see [DSC resource capabilities][07]. For more -information about the operations you can invoke for a resource, see [DSC resource operations][08]. +For more information about resource capabilities, see [DSC resource capabilities][06]. For more +information about the operations you can invoke for a resource, see [DSC resource operations][07]. ```yaml Type: array @@ -106,34 +114,47 @@ ItemsValidValues: [ get, set, setHandlesExist, - whatIf, + setWhatIf, test, delete, + deleteWhatIf, export, resolve ] ``` -### description +### deprecationMessage -Defines a synopsis for the resource's purpose as a short string. If the resource doesn't have a -description, this property is `null`. +Indicates that the resource is deprecated. When a resource manifest defines the +`deprecationMessage` property, DSC emits the message as a warning whenever a user invokes an +operation for the resource and includes the message in this output. For resources that aren't +deprecated, this property is `null`. ```yaml Type: [string, 'null'] -Required: true +Required: false ``` ### path -Represents the path to the resource's manifest on the machine. For adapted resources, this property -identifies the path to the file that defines the resource instead. +Represents the path to the resource's manifest on the machine. For adapted resources, this +property identifies the path to the file that defines the resource instead. ```yaml Type: string Required: true ``` +### description + +Defines a synopsis for the resource's purpose as a short string. If the resource doesn't have a +description, this property is `null`. + +```yaml +Type: [string, 'null'] +Required: false +``` + ### directory Represents the path to the folder containing the resource's manifest on the machine. For adapted @@ -147,65 +168,101 @@ Required: true ### implementedAs -Indicates how the DSC Resource was implemented. For command-based resources, this value is always -`Command`. +Indicates how the resource is implemented. For command-based resources, this value is `null`. +Resource adapters set this property to a string that distinguishes between the implementations of +the resources they support. For example, the PowerShell adapters report `ClassBased`, +`ScriptBased`, or `Binary` for adapted resources. - +```yaml +Type: [string, 'null'] +Required: false +``` ### author -Indicates the name of the person or organization that developed and maintains the DSC Resource. If +Indicates the name of the person or organization that developed and maintains the resource. If this property is `null`, the author is unknown. ```yaml Type: [string, 'null'] -Required: true +Required: false ``` ### properties -Defines the property names for adapted resources. For non-adapted resources, this property is an -empty array. +Defines the property names for adapted resources. For non-adapted resources, this property is +`null`. ```yaml -Type: array -Required: true +Type: [array, 'null'] +Required: false ItemsType: string ItemsPattern: ^\w+$ ``` ### requireAdapter -Defines the fully qualified type name of the DSC Resource Adapter that this resource is made -available through. This value is only defined for adapted resources. For non-adapted resources, -this value is always `null`. +Defines the fully qualified type name of the resource adapter that this resource is made available +through. This value is only defined for adapted resources. For non-adapted resources, this value +is always `null`. ```yaml Type: [string, 'null'] -Required: true +Required: false +``` + +### schema + +Defines the JSON schema that validates instances of an adapted resource. When an adapter defines +this property for an adapted resource, DSC uses the schema to validate instances of the adapted +resource instead of invoking the adapter's [schema][08] command. For non-adapted resources, this +property is `null`. + +```yaml +Type: [object, 'null'] +Required: false +``` + +### targetResource + +Reserved for DSC. When DSC invokes an adapter for an adapted resource, DSC sets this property on +the adapter's representation to the adapted resource. In the output of the `dsc resource list` +command, this property is always `null`. + +```yaml +Type: [object, 'null'] +Required: false ``` ### manifest Represents the values defined in the resource's manifest. This value is `null` for resources that -aren't command-based. For more information on the value for this property, see -[Command-based DSC Resource manifest schema reference][09]. +aren't command-based, like adapted resources. For more information on the value for this property, +see [Command-based DSC Resource manifest schema reference][09]. ```yaml Type: [object, 'null'] -Required: true +Required: false +``` + +### adaptedContent + +Defines the inline content of an adapted resource as a JSON object. When an adapted resource is +defined with inline content instead of a path, DSC sets this property to that content. For other +resources, this property is `null`. This property was added in DSC version 3.3.0. + +```yaml +Type: [object, 'null'] +Required: false ``` [01]: https://jsonlines.org/ -[02]: ../../definitions/resourceType.md -[03]: ../../definitions/resourceKind.md#adapter-resources -[04]: ../../definitions/resourceKind.md#group-resources -[05]: ../../resource/manifest/root.md#kind -[06]: ../../definitions/resourceKind.md -[07]: ../../../../concepts/resources/capabilities.md -[08]: ../../../../concepts/resources/operations.md +[02]: ../../resource/stdout/list.md +[03]: ../../definitions/resourceType.md +[04]: ../../resource/manifest/root.md#kind +[05]: ../../definitions/resourceKind.md +[06]: ../../../../concepts/resources/capabilities.md +[07]: ../../../../concepts/resources/operations.md +[08]: ../../resource/manifest/schema/property.md [09]: ../../resource/manifest/root.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md index b72ca7a7..985aec16 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource set' command. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: dsc resource set result schema reference --- @@ -46,7 +46,6 @@ The output always includes these properties: - [beforeState](#beforestate) - [afterState](#afterstate) -- [changedProperties](#changedproperties) ### Properties @@ -72,12 +71,12 @@ Required: true #### changedProperties -Defines the names of the properties the set operation enforced. If this value is an empty array, -the resource made no changes during the set operation. +Defines the names of the properties the set operation enforced. If this value is an empty array or +`null`, the resource made no changes during the set operation. ```yaml Type: array -Required: true +Required: false ItemsType: string ``` @@ -91,37 +90,42 @@ data is returned: ### Required properties -- [metadata](#metadata-1) - [name](#name) - [type](#type) - [result](#result) ### Properties -#### metadata +#### executionInformation -Defines metadata DSC returns for a configuration operation. The properties under the -`Microsoft.DSC` property describe the context of the operation. +Describes the context of the operation for the resource instance. The value is an object with the +following properties: - [duration][01] defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in [ISO8601 ABNF for `duration`][02]. For example, `PT0.611216S` represents a duration of about `0.61` seconds. +- [restartRequired][03] defines the list of restarts the resource reported as required. DSC only + includes this property when the resource reported a required restart. +- `whatIf` defines the information the resource returned about the what-if operation. DSC only + includes this property when you invoke the command with the `--what-if` argument and the + resource returned what-if metadata for a delete operation. ```yaml Type: object -Required: true +Required: false ``` -#### type +#### metadata -The `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][03]. +Defines metadata DSC returns for a resource instance operation. The `Microsoft.DSC` property under +this property includes the [duration][01] 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: string -Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Type: object +Required: false ``` #### name @@ -133,6 +137,18 @@ Type: string Required: true ``` +#### type + +The `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][04]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+)*\/\w+$ +``` + #### result The `result` property includes the enforced state for the resource. This value is either: @@ -149,4 +165,5 @@ Required: true [01]: ../../metadata/Microsoft.DSC/properties.md#duration [02]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A -[03]: ../../definitions/resourceType.md +[03]: ../../metadata/Microsoft.DSC/properties.md#restartrequired +[04]: ../../definitions/resourceType.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md index 8f3622fa..1e3b3206 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource test' command. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: dsc resource test result schema reference --- @@ -21,7 +21,7 @@ Type: object ## Description -Describes the return data for a DSC Resource instance from the `dsc resource get` command. The +Describes the return data for a DSC Resource instance from the `dsc resource test` command. The return data is either a single object that describes the tested state of a non-nested instance or an array of objects that describe the tested state of the nested instances for a group or adapter resource. @@ -40,6 +40,9 @@ resource type and instance name. The output always includes these properties: - [desiredState](#desiredstate) +- [actualState](#actualstate) +- [inDesiredState](#indesiredstate) +- [differingProperties](#differingproperties) ### Properties @@ -94,37 +97,39 @@ data is returned: ### Required properties -- [metadata](#metadata-1) - [name](#name) - [type](#type) - [result](#result) ### Properties -#### metadata +#### executionInformation -Defines metadata DSC returns for a configuration operation. The properties under the -`Microsoft.DSC` property describe the context of the operation. +Describes the context of the operation for the resource instance. The value is an object with the +following properties: - [duration][01] defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in [ISO8601 ABNF for `duration`][02]. For example, `PT0.611216S` represents a duration of about `0.61` seconds. +- [restartRequired][03] 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: true +Required: false ``` -#### type +#### metadata -The `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][03]. +Defines metadata DSC returns for a resource instance operation. The `Microsoft.DSC` property under +this property includes the [duration][01] 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: string -Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Type: object +Required: false ``` #### name @@ -136,12 +141,24 @@ Type: string Required: true ``` +#### type + +The `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][04]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+)*\/\w+$ +``` + #### result The `result` property includes the validation state for the resource. This value is either: - The [simple test response](#simple-test-response) for the instance -- An array of full get result objects for each nested instance, if the resource is a group or +- An array of full test result objects for each nested instance, if the resource is a group or adapter resource. ```yaml @@ -152,4 +169,5 @@ Required: true [01]: ../../metadata/Microsoft.DSC/properties.md#duration [02]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A -[03]: ../../definitions/resourceType.md +[03]: ../../metadata/Microsoft.DSC/properties.md#restartrequired +[04]: ../../definitions/resourceType.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/overview.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/overview.md index 05941d62..334c86d4 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/overview.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/overview.md @@ -2,7 +2,7 @@ description: >- Overview of the reference documentation for the JSON schemas describing data types for Microsoft's Desired State Configuration platform. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC JSON Schema reference overview --- @@ -26,23 +26,68 @@ the DSC schemas. ## Configuration document schemas The article [DSC configuration document schema reference][03] describes the root JSON schema for -configuration documents. +configuration documents. The following articles describe the subschemas for the properties of a +configuration document: -The article [DSC Configuration document functions reference][04] describes DSC configuration -functions generally and links to the reference documentation for the available functions. +- [DSC Configuration document metadata schema][04] +- [DSC Configuration document parameter schema][05] +- [DSC configuration parameter data type schema reference][06] +- [DSC Configuration document resource instance schema][07] + +The article [DSC Configuration document functions reference][08] describes DSC configuration +functions generally and links to the reference documentation for the available functions. The +article [Function data types schema reference][09] describes the data types that configuration +functions accept and return. ## Extension schemas -The article [DSC command extension manifest schema reference][05] describes the root JSON schema for -extension manifests. +The article [DSC command extension manifest schema reference][10] describes the root JSON schema for +extension manifests. The following articles describe the schemas for the operations an extension +can define: -## Resource schemas +- [DSC extension manifest discover property schema reference][11] +- [DSC extension discover operation stdout schema reference][12] -The article [DSC command resource manifest schema reference][06] describes the root JSON schema for -resource manifests. +## Resource schemas -The article [# DSC canonical properties reference][07] describes DSC canonical resource properties -generally and links to the reference documentation for the available canonical properties. +The article [DSC command resource manifest schema reference][13] describes the root JSON schema for +resource manifests. The following articles describe the subschemas for the properties of a resource +manifest: + +- [DSC Resource manifest adapter property schema reference][14] +- [DSC Resource manifest delete property schema reference][15] +- [DSC Resource manifest export property schema reference][16] +- [DSC Resource manifest get property schema reference][17] +- [DSC Resource manifest resolve property schema reference][18] +- [DSC Resource manifest schema property schema reference][19] +- [DSC Resource manifest embedded schema reference][20] +- [DSC Resource manifest set property schema reference][21] +- [DSC Resource manifest test property schema reference][22] +- [DSC Resource manifest validate property schema reference][23] +- [DSC Resource manifest whatIf property schema reference][24] + +The article [DSC canonical properties reference][25] describes DSC canonical resource properties +generally and links to the reference documentation for the available canonical properties: + +- [DSC Resource _ensure property schema][26] +- [DSC Resource _exist property schema][27] +- [DSC Resource _inDesiredState property schema][28] +- [DSC Resource _purge property schema][29] + +The article [Overview of DSC resource operation stdout schemas][30] describes the data a command +resource must return for each operation and links to the reference documentation for each +operation: + +- [DSC resource delete operation stdout schema reference][31] +- [DSC resource export operation stdout schema reference][32] +- [DSC resource get operation stdout schema reference][33] +- [DSC resource list operation stdout schema reference][34] +- [DSC resource resolve operation stdout schema reference][35] +- [DSC resource schema command stdout schema reference][36] +- [DSC resource set operation stdout schema reference][37] +- [DSC resource test operation stdout schema reference][38] +- [DSC resource validate operation stdout schema reference][39] +- [DSC resource what-if operation stdout schema reference][40] ## Output schemas @@ -51,14 +96,15 @@ DSC returns for its commands: | Command | Article link | |:---------------------|:-------------------------------------------------| -| `dsc config get` | [dsc config get result schema reference][08] | -| `dsc config set` | [dsc config set result schema reference][09] | -| `dsc config test` | [dsc config test result schema reference][10] | -| `dsc extension list` | [dsc extension list result schema reference][11] | -| `dsc resource get` | [dsc resource get result schema reference][12] | -| `dsc resource list` | [dsc resource list result schema reference][13] | -| `dsc resource set` | [dsc resource set result schema reference][14] | -| `dsc resource test` | [dsc resource test result schema reference][15] | +| `dsc config get` | [dsc config get result schema reference][41] | +| `dsc config set` | [dsc config set result schema reference][42] | +| `dsc config test` | [dsc config test result schema reference][43] | +| `dsc extension list` | [dsc extension list result schema reference][44] | +| `dsc function list` | [dsc function list result schema reference][45] | +| `dsc resource get` | [dsc resource get result schema reference][46] | +| `dsc resource list` | [dsc resource list result schema reference][47] | +| `dsc resource set` | [dsc resource set result schema reference][48] | +| `dsc resource test` | [dsc resource test result schema reference][49] | ## Definition schemas @@ -66,30 +112,71 @@ The following list defines the reference documentation for JSON schemas included throughout DSC. - For more information about the `Microsoft.DSC` metadata property, see - [Microsoft.DSC metadata property schema reference][16] -- For more information about the messages DSC emits, see [Structured message schema reference][17] + [Microsoft.DSC metadata property schema reference][50]. +- For more information about the messages DSC emits, see [Structured message schema reference][51]. - For more information about the kinds of DSC resources and how they affect schema validation, see - [DSC Resource kind schema reference][18]. + [DSC Resource kind schema reference][52]. - For more information about the naming of DSC resources and how they're validated, see - [DSC Resource fully qualified type name schema reference][19] - - + [DSC Resource fully qualified type name schema reference][53]. +- For more information about the operations a DSC resource supports, see + [DSC Resource capabilities schema reference][54]. +- For more information about the data types for configuration document parameters, see + [DSC configuration parameter data type schema reference][06]. +- For more information about the data types that configuration functions operate on, see + [Function data types schema reference][09]. + + [01]: https://json-schema.org/overview/what-is-jsonschema [02]: ./schema-uris.md [03]: ./config/document.md -[04]: ./config/functions/overview.md -[05]: ./extension/manifest/root.md -[06]: ./resource/manifest/root.md -[07]: ./resource/properties/overview.md -[08]: ./outputs/config/get.md -[09]: ./outputs/config/set.md -[10]: ./outputs/config/test.md -[11]: ./outputs/extension/list.md -[12]: ./outputs/resource/get.md -[13]: ./outputs/resource/list.md -[14]: ./outputs/resource/set.md -[15]: ./outputs/resource/test.md -[16]: ./metadata/Microsoft.DSC/properties.md -[17]: ./definitions/message.md -[18]: ./definitions/resourceKind.md -[19]: ./definitions/resourceType.md +[04]: ./config/metadata.md +[05]: ./config/parameter.md +[06]: ./definitions/parameters/dataTypes.md +[07]: ./config/resource.md +[08]: ./config/functions/overview.md +[09]: ./definitions/functions/builtin/dataTypes.md +[10]: ./extension/manifest/root.md +[11]: ./extension/manifest/discover.md +[12]: ./extension/stdout/discover.md +[13]: ./resource/manifest/root.md +[14]: ./resource/manifest/adapter.md +[15]: ./resource/manifest/delete.md +[16]: ./resource/manifest/export.md +[17]: ./resource/manifest/get.md +[18]: ./resource/manifest/resolve.md +[19]: ./resource/manifest/schema/property.md +[20]: ./resource/manifest/schema/embedded.md +[21]: ./resource/manifest/set.md +[22]: ./resource/manifest/test.md +[23]: ./resource/manifest/validate.md +[24]: ./resource/manifest/whatif.md +[25]: ./resource/properties/overview.md +[26]: ./resource/properties/ensure.md +[27]: ./resource/properties/exist.md +[28]: ./resource/properties/inDesiredState.md +[29]: ./resource/properties/purge.md +[30]: ./resource/stdout/index.md +[31]: ./resource/stdout/delete.md +[32]: ./resource/stdout/export.md +[33]: ./resource/stdout/get.md +[34]: ./resource/stdout/list.md +[35]: ./resource/stdout/resolve.md +[36]: ./resource/stdout/schema.md +[37]: ./resource/stdout/set.md +[38]: ./resource/stdout/test.md +[39]: ./resource/stdout/validate.md +[40]: ./resource/stdout/whatIf.md +[41]: ./outputs/config/get.md +[42]: ./outputs/config/set.md +[43]: ./outputs/config/test.md +[44]: ./outputs/extension/list.md +[45]: ./outputs/function/list.md +[46]: ./outputs/resource/get.md +[47]: ./outputs/resource/list.md +[48]: ./outputs/resource/set.md +[49]: ./outputs/resource/test.md +[50]: ./metadata/Microsoft.DSC/properties.md +[51]: ./definitions/message.md +[52]: ./definitions/resourceKind.md +[53]: ./definitions/resourceType.md +[54]: ./definitions/resourceCapabilities.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/adapter.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/adapter.md index 64926a33..afc43522 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/adapter.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/adapter.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'adapter' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest adapter property schema reference --- @@ -23,7 +23,9 @@ Type: object DSC Resource Adapters must define the `adapter` property in their manifest. This property identifies the resource as an adapter and defines how DSC can call the adapter to get the resources -the adapter supports and how to pass resource instances to the adapter. +the adapter supports and how to pass resource instances to the adapter. When a manifest defines +this property and doesn't define the [kind][01] property, DSC infers the resource kind as +`adapter`. ## Examples @@ -39,16 +41,18 @@ This example is from the `Microsoft.DSC/PowerShell` DSC Resource Adapter. "-NoLogo", "-NonInteractive", "-NoProfile", + "-ExecutionPolicy", + "Bypass", "-Command", - "./powershell.resource.ps1 List" + "./psDscAdapter/powershell.resource.ps1 List" ] - }, - "config": "full" -}, + }, + "inputKind": "full" +} ``` -The manifest sets `config` to `full`, indicating that the adapter expects a JSON blob representing -the full and unprocessed configuration from `stdin`. +The manifest sets `inputKind` to `full`, indicating that the adapter expects a JSON blob +representing the full and unprocessed configuration from `stdin`. It defines `list.executable` as `pwsh`. The arguments defined in `list.args` ensure that DSC runs PowerShell: @@ -56,47 +60,95 @@ PowerShell: - Without the logo banner - In non-interactive mode - Without loading any profile scripts -- To invoke the `powershell.resource.ps1` script in the same folder as the `dsc` command and - pass the `List` argument. +- With the execution policy set to `Bypass` +- To invoke the `powershell.resource.ps1` script in the `psDscAdapter` folder next to the manifest + and pass the `List` argument. With this definition, DSC calls the `list` method for this adapter by running: ```sh -pwsh -NoLogo -NonInteractive -NoProfile -Command "./powershellgroup.resource.ps1 List" +pwsh -NoLogo -NonInteractive -NoProfile -ExecutionPolicy Bypass \ + -Command "./psDscAdapter/powershell.resource.ps1 List" ``` -## Required Properties +### Example 2 - Microsoft.Adapter/PowerShell + +This example is from the `Microsoft.Adapter/PowerShell` DSC Resource Adapter. + +```json +"adapter": { + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-ExecutionPolicy", + "Bypass", + "-Command", + "./psDscAdapter/powershell.resource.ps1", + "List", + "-ResourceType", + "Single" + ] + }, + "inputKind": "single" +} +``` + +The manifest sets `inputKind` to `single`, indicating that DSC should invoke the adapter for one +adapted resource instance at a time. The adapter's `get`, `set`, `test`, and `export` definitions +use the [resource type argument][02] and [resource path argument][03] to identify which adapted +resource to invoke. + +## Required properties The `adapter` definition must include these properties: -- [config](#config) -- [list](#list) +- [inputKind](#inputkind) ## Properties -### config +### inputKind -The `config` property defines how the adapter expects to receive resource configurations. The +The `inputKind` property defines how the adapter expects to receive resource configurations. The value must be one of the following options: - `full` - Indicates that the adapter expects a JSON blob containing the full and unprocessed - configuration as a single JSON blob over `stdin`. + configuration as a single JSON blob over `stdin`. DSC adds a `metadata` property with the + `Microsoft.DSC.context` value set to `configuration` to the input so the adapter can distinguish + a full configuration from a single resource instance. - `sequence` - Indicates that the adapter expects each resource's configuration as a - [JSON Line][01] over `stdin`. + [JSON Line][04] over `stdin`. +- `single` - Indicates that the adapter expects a single adapted resource instance. DSC invokes + the adapter's operation commands directly for each adapted resource instance and passes the + instance properties as the input for the command. Use the [resource type argument][02], + [resource path argument][03], [resource version argument][05], and + [adapted content argument][06] in the operation definitions to tell the adapter which adapted + resource to invoke. + +Prior to DSC version 3.2.0, this property was named `config`. DSC still accepts the `config` name +for backward compatibility, but new manifests should use `inputKind`. ```yaml Type: string -ValidValues: [full, sequence] +Required: true +ValidValues: [full, sequence, single] ``` ### list The `list` property defines how to call the adapter to list the resources it supports. The value -of this property must be an object and define the `executable` sub-property. +of this property must be an object and define the `executable` sub-property. For more information +about the expected output, see [DSC resource list operation stdout schema reference][07]. + +When this property isn't defined, DSC can't discover the adapter's resources by invoking the +adapter. Users can still define adapted resources for the adapter with adapted resource manifests +that specify the adapter with their `requireAdapter` property. ```yaml Type: object -Required: true +Required: false RequiredProperties: [executable] ``` @@ -115,12 +167,21 @@ Required: true #### args The `args` sub-property defines an array of strings to pass as arguments to the command. DSC passes -the arguments to the command in the order they're specified. +the arguments to the command in the order they're specified. Unlike the `args` property for the +operation methods, this array only accepts strings. ```yaml -Type: array -Required: false -Default: [] +Type: array +Required: false +Default: [] +ItemsType: string ``` -[01]: https://jsonlines.org/ + +[01]: root.md#kind +[02]: get.md#resource-type-argument +[03]: get.md#resource-path-argument +[04]: https://jsonlines.org/ +[05]: get.md#resource-version-argument +[06]: get.md#adapted-content-argument +[07]: ../stdout/list.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/delete.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/delete.md index 938c4a55..193979a4 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/delete.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/delete.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'delete' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest delete property schema reference --- @@ -25,7 +25,7 @@ Defines how DSC must call the DSC Resource to delete an instance. Define this me as an alternative to handling the [`_exist`][01] property in a `set` operation, which can lead to highly complex code. If the `set` method for the resource is able to handle deleting an instance when `_exist` is `false`, set the [`handlesExist`][02] property of the set method definition to -`true` instead. +`true` instead. When this property is defined, the resource has the `delete` capability. If you define the delete method in a resource manifest, ensure that you also define the [`_exist`][01] property in the [JSON schema for the resource's properties][03]. @@ -45,8 +45,51 @@ input JSON to the resource. You can only define one JSON input argument for a co You must define the `input` property, one JSON input argument in the `args` property array, or both. +When the `args` array includes a [what-if argument](#what-if-argument), the resource has the +`deleteWhatIf` capability. DSC calls the `delete` command with the what-if argument when a user +invokes the operation in what-if mode, like with the `--what-if` option for the +[dsc resource delete][04] command, and the resource reports how it would remove the instance +without modifying the system. When the `args` array doesn't include a what-if argument, DSC +synthesizes the what-if result from the `test` operation. The `deleteWhatIf` capability was added +in DSC version 3.3.0. + ## Examples +### Example 1 - Definition with a what-if argument + +```json +"delete": { + "executable": "my_app", + "args": [ + "config", + "delete", + { "whatIfArg": "--what-if" } + ], + "input": "stdin" +} +``` + +It defines `executable` as `my_app`, rather than `my_app.exe`. The extension isn't required when +the operating system recognizes the command as an executable. + +The manifest defines two string arguments, `config` and `delete`, and a what-if argument. The value +of the `input` property indicates that the `delete` command expects its input as a JSON blob from +`stdin`. + +When a user invokes the `delete` operation normally, DSC calls the command as: + +```sh +{ ... } | my_app config delete +``` + +When a user invokes the `delete` operation in what-if mode, DSC calls the command as: + +```sh +{ ... } | my_app config delete --what-if +``` + +Because the manifest defines the what-if argument, the resource has the `deleteWhatIf` capability. + ## Required properties The `delete` definition must include these properties: @@ -69,17 +112,31 @@ Required: true ### args -The `args` property defines the list of arguments to pass to the command. The arguments can be any -number of strings. If you want to pass the JSON object representing the property bag for the -resource to an argument, you can define a single item in the array as a [JSON object], indicating the -name of the argument with the `jsonInputArg` string property and whether the argument is mandatory -for the command with the `mandatory` boolean property. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. +- [What-if argument](#what-if-argument) - The argument to pass when the operation runs in what-if + mode. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments and the what-if argument, DSC passes the argument name followed by its +value as two separate arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -91,15 +148,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][05]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### JSON input argument Defines an argument for the command that accepts the JSON input object as a string. DSC passes the -JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: +JSON input to the named argument when available. -- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. -- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the - JSON input argument. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -115,14 +192,80 @@ ways: JSON input as a string to the defined argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. This makes the manifest invalid. You must define the `input` property, -a JSON input argument in the `args` property array, or both. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][06] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + +#### What-if argument + +Defines the argument to pass to the command when a user invokes the `delete` operation in what-if +mode. DSC only passes the named argument when the operation runs in what-if mode. When the +operation runs normally, DSC omits the argument. + +When the `args` array includes a what-if argument, the resource has the `deleteWhatIf` capability. +In what-if mode, DSC calls the `delete` command with the argument instead of synthesizing the +result from the `test` operation. The resource must not modify the system and must return a JSON +object describing the expected result. For more information about the expected output, see +[DSC resource delete operation stdout schema reference][07]. + +- `whatIfArg` (required) - The argument to pass in what-if mode, like `--what-if`. + +```yaml +Type: object +RequiredProperties: [whatIfArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -160,7 +303,32 @@ Required: false ValidValues: [env, stdin] ``` +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`delete` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + [01]: ../properties/exist.md [02]: set.md#handlesexist [03]: schema/property.md +[04]: ../../../cli/resource/delete.md +[05]: adapter.md +[06]: ../stdout/list.md#path +[07]: ../stdout/delete.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/export.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/export.md index 0a98fda5..3f830f00 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/export.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/export.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'export' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest export property schema reference --- @@ -23,7 +23,8 @@ Type: object A command-based DSC Resource that can enumerate every instance of itself with a single command should define the `export` property in its manifest. This property defines how DSC can get the -current state for every resource instance. When this property is defined, users can: +current state for every resource instance. When this property is defined, the resource has the +`export` capability and users can: - Specify an instance of the resource in the input configuration for the [dsc config export][01] command to generate an usable configuration document. @@ -34,24 +35,36 @@ current state for every resource instance. When this property is defined, users When the DSC calls the command defined by this property, the resource must return the current state of every instance as [JSON lines][05]. Each JSON Line should be an object representing the instance -and validate against the [defined resource instance schema][06]. +and validate against the [defined resource instance schema][06]. For more information about the +expected output, including the output for exporter resources, see +[DSC resource export operation stdout schema reference][07]. + +Users can provide input for the `export` operation to filter the exported instances, like with the +[--input][08] option for the `dsc resource export` command or the properties of an instance in a +configuration document. Before sending the input to the command, DSC validates it: + +1. If the manifest defines [supportsFiltering](#supportsfiltering) as `false`, DSC raises an + error. +1. If the manifest defines the [schema](#schema) property, DSC validates the input against that + schema. +1. Otherwise, if the manifest defines the [validate][09] property, DSC calls the `validate` command + to validate the input. +1. Otherwise, DSC validates the input against the resource's instance schema. DSC sends data to this command in three ways: - 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed - JSON object without spaces or newlines between the object properties. - 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment - variable for each property in the input data object, using the name and value of the property. - 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a - string representing the data as a compressed JSON object to the specified argument. +1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. +1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. +1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. You can only define one JSON input argument for a command. +input JSON to the resource. This is only appropriate for resources that don't support filtering +the exported instances. You can only define one JSON input argument for a command. -You must define the `input` property, one JSON input argument in the `args` property array, or -both. - -## Required Properties +## Required properties The `export` definition must include these properties: @@ -73,17 +86,29 @@ Required: true ### args -The `args` property defines the list of arguments to pass to the command. The arguments can be any -number of strings. If you want to pass the JSON object representing the property bag for the -resource to an argument, you can define a single item in the array as a [JSON object], indicating the -name of the argument with the `jsonInputArg` string property and whether the argument is mandatory -for the command with the `mandatory` boolean property. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments, DSC passes the argument name followed by its value as two separate +arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -95,15 +120,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][10]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### JSON input argument Defines an argument for the command that accepts the JSON input object as a string. DSC passes the -JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: +JSON input to the named argument when available. -- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. -- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the - JSON input argument. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -119,14 +164,60 @@ ways: JSON input as a string to the defined argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. This makes the manifest invalid. You must define the `input` property, -a JSON input argument in the `args` property array, or both. +input JSON to the resource. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][11] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -164,9 +255,82 @@ Required: false ValidValues: [env, stdin] ``` +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`export` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + +### schema + +The `schema` property defines the JSON schema that DSC uses to validate the input for the `export` +operation. Define this property when the properties the resource accepts for filtering exported +instances differ from the resource's instance schema. This property uses the same shape as the +manifest [schema][12] property. The value must be an object that defines one of the following +properties: + +- `command` - When you specify the `command` property, DSC calls the defined command to get the + JSON schema for the export input. The `command` object must define the `executable` property and + may define the `args` property, which accepts the same argument kinds as the manifest + [schema.command.args][13] property. +- `embedded` - When you specify the `embedded` property, DSC uses the defined value as the JSON + schema for the export input. + +When the manifest doesn't define this property, DSC validates the export input with the +[validate][09] command if the manifest defines it, or against the resource's instance schema +otherwise. A manifest can't define both this property and `supportsFiltering`. + +This property was added in DSC version 3.3.0. + +```yaml +Type: object +Required: false +RequiredProperties: [command | embedded] +``` + +### supportsFiltering + +The `supportsFiltering` property indicates whether the resource accepts input for the `export` +operation to filter the exported instances. When this property is `false`, DSC raises an error if +a user provides input for the `export` operation. When this property is `true` or isn't defined, +DSC validates the input and sends it to the command. + +A manifest can't define both this property and `schema`. + +This property was added in DSC version 3.3.0. + +```yaml +Type: boolean +Required: false +Default: true +``` + + [01]: ../../../cli/config/export.md [02]: ../../../cli/resource/export.md [03]: ../../../cli/resource/get.md [04]: ../../../cli/resource/get.md#-a---all [05]: https://jsonlines.org/ [06]: schema/property.md +[07]: ../stdout/export.md +[08]: ../../../cli/resource/export.md#-i---input +[09]: validate.md +[10]: adapter.md +[11]: ../stdout/list.md#path +[12]: root.md#schema-1 +[13]: schema/property.md#args diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/get.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/get.md index 7ffae514..086d88b4 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/get.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/get.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'get' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest get property schema reference --- @@ -21,8 +21,11 @@ Type: object ## Description -Every command-based DSC Resource must define the `get` property in its manifest. This property -defines how DSC can get the current state of a resource instance. +Nearly every command-based DSC Resource should define the `get` property in its manifest. This +property defines how DSC can get the current state of a resource instance. When a manifest doesn't +define this property, the resource doesn't have the `get` capability and DSC can't retrieve the +current state of the resource's instances or synthesize results for the `test` and `set` +operations. DSC sends data to the command in three ways: @@ -34,10 +37,13 @@ DSC sends data to the command in three ways: representing the data as a compressed JSON object to the specified argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. You can only define one JSON input argument for a command. +input JSON to the resource. This is only appropriate for resources that don't need any input to +return their current state, like `Microsoft/OSInfo`. You can only define one JSON input argument +for a command. -You must define the `input` property, one JSON input argument in the `args` property array, or -both. +DSC only sends input to the `get` command when the user or configuration document provides +instance properties for the operation. When there's no input, DSC omits the JSON input argument +unless the argument is defined as mandatory. ## Examples @@ -52,13 +58,13 @@ This example is from the `Microsoft/OSInfo` DSC Resource. ``` It only defines the `executable` property. When a manifest doesn't define `args`, DSC passes no -arguments to the command. When a manifest doesn't define `input`, the default behavior is to send a -JSON blob to the command over `stdin`. +arguments to the command. When a manifest doesn't define `input` or a JSON input argument, DSC +doesn't send any input to the command. With this definition, DSC calls the `get` method for this resource by running: ```sh -{ ... } | osinfo +osinfo ``` ### Example 2 - Input from stdin @@ -97,11 +103,14 @@ This example uses a JSON input argument to send the data to the command. "config", "get", { "jsonInputArg": "--input", "mandatory": true } - ], + ] } ``` -It defines the executable as `tstoy`. It defines two [string arguments](#string-arguments) and one [JSON input argument](#json-input-argument). When DSC invokes the `get` operation for this resource, it passes the JSON data to the resource as a compressed JSON string to the `--input` argument. +It defines the executable as `tstoy`. It defines two [string arguments](#string-arguments) and one +[JSON input argument](#json-input-argument). When DSC invokes the `get` operation for this +resource, it passes the JSON data to the resource as a compressed JSON string to the `--input` +argument. The combined call for this operation is: @@ -115,7 +124,36 @@ Because the `mandatory` option for the JSON input argument is set to `true`, DSC string to the argument when there's no data to send to the command. If the property wasn't defined, or was defined as `false`, DSC would omit the argument entirely when there's no data to send. -## Required Properties +### Example 4 - Adapter arguments + +This example is from the `Microsoft.Adapter/PowerShell` DSC Resource Adapter. + +```json +"get": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-ExecutionPolicy", + "Bypass", + "-Command", + "$Input | ./psDscAdapter/powershell.resource.ps1", + "Get", + { "resourceTypeArg": "-ResourceType" }, + { "resourcePathArg": "-ResourcePath", "includeQuotes": true } + ], + "input": "stdin" +} +``` + +The adapter defines a [resource type argument](#resource-type-argument) and a +[resource path argument](#resource-path-argument). When DSC invokes the adapter to get the state of +an adapted resource, it passes the adapted resource's fully qualified type name to the +`-ResourceType` argument and the path to the file that defines the adapted resource, wrapped in +double quotes, to the `-ResourcePath` argument. DSC sends the instance properties over `stdin`. + +## Required properties The `get` definition must include these properties: @@ -137,17 +175,29 @@ Required: true ### args -The `args` property defines the list of arguments to pass to the command. The arguments can be any -number of strings. If you want to pass the JSON object representing the property bag for the -resource to an argument, you can define a single item in the array as a [JSON object], indicating the -name of the argument with the `jsonInputArg` string property and whether the argument is mandatory -for the command with the `mandatory` boolean property. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments, DSC passes the argument name followed by its value as two separate +arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -159,15 +209,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][01]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### JSON input argument Defines an argument for the command that accepts the JSON input object as a string. DSC passes the -JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: +JSON input to the named argument when available. -- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. -- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the - JSON input argument. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -183,14 +253,60 @@ ways: JSON input as a string to the defined argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. This makes the manifest invalid. You must define the `input` property, -a JSON input argument in the `args` property array, or both. +input JSON to the resource. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][02] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -227,3 +343,28 @@ Type: string Required: false ValidValues: [env, stdin] ``` + +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`get` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + + +[01]: adapter.md +[02]: ../stdout/list.md#path diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/resolve.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/resolve.md index b53f40ab..ed278784 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/resolve.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/resolve.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'resolve' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest resolve property schema reference --- @@ -24,7 +24,8 @@ Type: object Defines how DSC must call the DSC Resource to resolve an external source to nested DSC Configuration Document. Define this method for [importer resources][01] and set the [kind][02] -property in the manifest root to `Import`. +property in the manifest root to `importer`. When this property is defined, the resource has the +`resolve` capability. DSC sends data to the command in three ways: @@ -63,17 +64,29 @@ Required: true ### args -The `args` property defines the list of arguments to pass to the command. The arguments can be any -number of strings. If you want to pass the JSON object representing the property bag for the -resource to an argument, you can define a single item in the array as a [JSON object], indicating the -name of the argument with the `jsonInputArg` string property and whether the argument is mandatory -for the command with the `mandatory` boolean property. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments, DSC passes the argument name followed by its value as two separate +arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -85,16 +98,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][03]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### JSON input argument Defines an argument for the command that accepts the JSON input object as a string. DSC passes the -JSON input to the named argument when available. A JSON input argument is defined as a JSON object -with the following properties: +JSON input to the named argument when available. -- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. -- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the - JSON input argument. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -110,14 +142,61 @@ ways: JSON input as a string to the defined argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. This makes the manifest invalid. You must define the `input` property, -a JSON input argument in the `args` property array, or both. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][04] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -158,3 +237,5 @@ ValidValues: [env, stdin] [01]: ../../definitions/resourceKind.md#importer-resources [02]: ./root.md#kind +[03]: adapter.md +[04]: ../stdout/list.md#path diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md index 2d6ebf97..d173f92a 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a DSC Resource manifest -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: Command-based DSC Resource manifest schema reference --- @@ -38,7 +38,6 @@ The manifest must include these properties: - [$schema](#schema) - [type](#type) - [version](#version) -- [get](#get) ## Properties @@ -55,7 +54,7 @@ semantic version, the latest schema for a minor version, or the latest schema fo of DSC. For more information about schema URIs and versioning, see [DSC JSON Schema URIs](../../schema-uris.md). -For every version of the schema, there are three valid urls: +For every version of the schema, there are three valid URLs: - `.../resource/manifest.json` @@ -77,8 +76,9 @@ For every version of the schema, there are three valid urls: it includes additional definitions that provide contextual help and snippets that the others don't include. - This schema uses keywords that are only recognized by VS Code. While DSC can still validate the - document when it uses this schema, other tools may error or behave in unexpected ways. + This schema uses keywords that are only recognized by Visual Studio Code. While DSC can still + validate the document when it uses this schema, other tools may error or behave in unexpected + ways. ```yaml Type: string @@ -88,9 +88,33 @@ ValidValues: [ https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/resource/manifest.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/resource/manifest.vscode.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/resource/manifest.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.vscode.json @@ -109,9 +133,33 @@ ValidValues: [ https://aka.ms/dsc/schemas/v3/resource/manifest.json https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.3/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.3/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.2/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.2/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.1/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.1/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.2.0/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.2.0/bundled/resource/manifest.vscode.json https://aka.ms/dsc/schemas/v3.1/resource/manifest.json https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.json https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.3/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.3/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.2/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.2/bundled/resource/manifest.vscode.json + https://aka.ms/dsc/schemas/v3.1.1/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/resource/manifest.json + https://aka.ms/dsc/schemas/v3.1.1/bundled/resource/manifest.vscode.json https://aka.ms/dsc/schemas/v3.1.0/resource/manifest.json https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.json https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.vscode.json @@ -134,30 +182,43 @@ ValidValues: [ The `type` property represents the fully qualified type name of the resource. It's used to specify the resource in configuration documents and as the value of the `--resource` flag when using the -`dsc resource *` commands. For more information about resource type names, see +`dsc resource *` commands. The type name must define an owner segment, any number of optional +namespace segments separated by periods (`.`), and a name segment separated from the preceding +segments by a forward slash (`/`), like `Microsoft.Windows/Registry`. Each segment must contain +only alphanumeric characters and underscores. For more information about resource type names, see [DSC Resource fully qualified type name schema reference][01]. ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` -### version +### condition -The `version` property must be the current version of the resource as a valid semantic version -(semver) string. The version applies to the resource, not the software it manages. +The `condition` property defines a DSC expression that DSC evaluates during resource discovery to +decide whether the manifest is active. The value must be an expression string that returns a +boolean value, like `[not(equals(tryWhich('pwsh'), null()))]`. When the expression returns +`false`, DSC skips the manifest and doesn't include the resource in discovery results. When the +expression returns any value other than a boolean, DSC raises an error. + +Use this property to hide a resource when its dependencies aren't available on the system, like an +adapter that requires a specific shell or runtime. For more information about the available +functions, see [DSC configuration document functions reference][02] and the [tryWhich()][03] +function. ```yaml Type: string -Required: true -Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +Required: false ``` -### description +### deprecationMessage -The `description` property defines a synopsis for the resource's purpose. The value for this -property must be a short string. +The `deprecationMessage` property indicates that the resource is deprecated. When a manifest +defines this property, DSC emits the message as a warning whenever a user invokes an operation for +the resource and includes the message in the output of the `dsc resource list` command. Use this +property to direct users to a replacement resource, like +`Use the 'Microsoft.Adapter/PowerShell' adapter instead.` ```yaml Type: string @@ -166,24 +227,49 @@ Required: false ### kind -The `kind` property defines how DSC should handle the resource. DSC supports several kinds -of DSC resources: `resource`, `group`, `adapter`, `importer`, and `exporter`. +The `kind` property defines how DSC should handle the resource. DSC supports several kinds of +resources: `resource`, `adapter`, `group`, `importer`, and `exporter`. When `kind` isn't defined in the resource manifest, DSC infers the value for the property. If the -`adapter` property is defined in the resource manifest, DSC infers the value of `kind` as -`adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as `resource`. -DSC can't infer whether a manifest is for a `group` or `importer` resource. +[adapter](#adapter) property is defined in the resource manifest, DSC infers the value of `kind` +as `adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as +`resource`. DSC can't infer whether a manifest is for a `group`, `importer`, or `exporter` +resource. -When defining a group resource, always explicitly define the `kind` property in the manifest as -`group`. When defining an importer resource, always explicitly define the `kind` property in the -manifest as `importer`. +When defining a group, importer, or exporter resource, always explicitly define the `kind` property +in the manifest. -For more information, see [DSC Resource kind schema reference][02]. +For more information, see [DSC Resource kind schema reference][04]. ```yaml Type: string Required: false -ValidValues: [resource, adapter, group, importer, exporter] +ValidValues: [adapter, exporter, group, importer, resource] +``` + +### version + +The `version` property must be the current version of the resource as a valid semantic version +(SemVer) string. The version applies to the resource, not the software it manages. + +For backward compatibility, DSC also accepts a date-based version in the format `YYYY-MM-DD` with +an optional prerelease suffix, like `2026-08-31-preview`. Date-based versions are deprecated. DSC +emits a warning when it discovers a manifest that defines a date-based version. + +```yaml +Type: string +Required: true +Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +``` + +### description + +The `description` property defines a synopsis for the resource's purpose. The value for this +property must be a short string. + +```yaml +Type: string +Required: false ``` ### tags @@ -200,39 +286,21 @@ ItemsType: string ItemsPattern: ^\w+$ ``` -### export - -The `export` property defines how to call the resource to get the current state of every instance. -When this property is defined, users can: - -- Specify an instance of the resource in the input configuration for the [dsc config export][03] - command to generate an usable configuration document. -- Specify the resource with the [dsc resource export][04] command to generate a configuration - document that defines every instance of the resource. -- Specify the resource with the [dsc resource get][05] command and the [--all][06] option to return - the current state for every instance of the resource. - -The value of this property must be an object. The object's `executable` property, defining the name -of the command to call, is mandatory. The `args` property is optional. For more -information, see [DSC Resource manifest export property schema reference][07]. - -```yaml -Type: object -Required: true -``` - ### get -The `get` property defines how to call the resource to get the current state of an instance. This -property is mandatory for all resources. +The `get` property defines how to call the resource to get the current state of an instance. +Although the schema doesn't require this property, nearly every resource should define it. When a +manifest doesn't define `get`, the resource doesn't have the `get` capability and DSC can't +retrieve the current state of the resource's instances or synthesize results for the `test` and +`set` operations. The value of this property must be an object. The object's `executable` property, defining the name -of the command to call, is mandatory. The `args` and `input` properties are optional. For more -information, see [DSC Resource manifest get property schema reference][08]. +of the command to call, is mandatory. The `args`, `input`, and `requireSecurityContext` properties +are optional. For more information, see [DSC Resource manifest get property schema reference][05]. ```yaml Type: object -Required: true +Required: false ``` ### set @@ -243,8 +311,9 @@ defined, the DSC can't manage instances of the resource. It can only get their c test whether the instance is in the desired state. The value of this property must be an object. The `executable` property, defining the name of the -command to call, is mandatory. The `args` `input`, `implementsPretest`, and `returns` properties -are optional. For more information, see [DSC Resource manifest set property schema reference][09]. +command to call, is mandatory. The `args`, `input`, `implementsPretest`, `handlesExist`, `return`, +`requireSecurityContext`, and `whatIfReturns` properties are optional. For more information, see +[DSC Resource manifest set property schema reference][06]. ```yaml Type: object @@ -253,15 +322,26 @@ Required: false ### whatIf -Defines how DSC must call the DSC Resource to indicate whether and how the set command will modify -an instance and how to process the output from the DSC Resource. If a resource doesn't define this -method in the manifest, DSC synthesizes this behavior by converting the result of the test -operation for the resource into the set result. +The `whatIf` property defines how to call the resource to indicate whether and how the `set` +operation would modify an instance without changing the system. This property uses the same schema +as the [set](#set) property. + +Defining a separate `whatIf` command is deprecated. Instead, define a [what-if argument][07] in the +`args` array of the `set` property. When the `set` definition includes a what-if argument, DSC +ignores the `whatIf` property. When the `set` definition doesn't include a what-if argument and the +manifest defines `whatIf`, DSC calls the `whatIf` command in what-if mode and emits a warning. When +the manifest defines neither, DSC synthesizes the what-if result by converting the result of the +`test` operation for the resource into a set result. The value of this property must be an object. The `executable` property, defining the name of the -command to call, is mandatory. The `args` `input`, `implementsPretest`, and `returns` properties -are optional. For more information, see -[DSC Resource manifest whatIf property schema reference][10]. +command to call, is mandatory. The `args`, `input`, `implementsPretest`, `handlesExist`, `return`, +`requireSecurityContext`, and `whatIfReturns` properties are optional. For more information, see +[DSC Resource manifest whatIf property schema reference][08]. + +```yaml +Type: object +Required: false +``` ### test @@ -270,8 +350,65 @@ state. It also defines how to process the output from the resource for this meth property isn't defined, DSC performs a basic synthetic test for instances of the DSC Resource. The value of this property must be an object. The object's `executable` property, defining the name -of the command to call, is mandatory. The `args` `input`, and `returns` properties are optional. -For more information, see [DSC Resource manifest test property schema reference][11]. +of the command to call, is mandatory. The `args`, `input`, `return`, and `requireSecurityContext` +properties are optional. For more information, see +[DSC Resource manifest test property schema reference][09]. + +```yaml +Type: object +Required: false +``` + +### delete + +The `delete` property defines how to call the resource to remove an instance. When this property is +defined, the resource has the `delete` capability. Define this property as an alternative to +handling the [_exist][10] property in the `set` operation. If the resource's `set` command handles +removing an instance when `_exist` is `false`, define the `handlesExist` property of the `set` +method as `true` instead. + +The value of this property must be an object. The object's `executable` property, defining the name +of the command to call, is mandatory. The `args`, `input`, and `requireSecurityContext` properties +are optional. For more information, see +[DSC Resource manifest delete property schema reference][11]. + +```yaml +Type: object +Required: false +``` + +### export + +The `export` property defines how to call the resource to get the current state of every instance. +When this property is defined, the resource has the `export` capability and users can: + +- Specify an instance of the resource in the input configuration for the [dsc config export][12] + command to generate an usable configuration document. +- Specify the resource with the [dsc resource export][13] command to generate a configuration + document that defines every instance of the resource. +- Specify the resource with the [dsc resource get][14] command and the [--all][15] option to return + the current state for every instance of the resource. + +The value of this property must be an object. The object's `executable` property, defining the name +of the command to call, is mandatory. The `args`, `input`, `requireSecurityContext`, `schema`, and +`supportsFiltering` properties are optional. For more information, see +[DSC Resource manifest export property schema reference][16]. + +```yaml +Type: object +Required: false +``` + +### resolve + +The `resolve` property defines how to call an importer resource to resolve an external source into +a nested configuration document. When this property is defined, the resource has the `resolve` +capability. Define this property for [importer resources][04] and set the `kind` property to +`importer`. + +The value of this property must be an object. The object's `executable` property, defining the name +of the command to call, is mandatory. The `args` and `input` properties are optional. For more +information, see [DSC Resource manifest resolve property schema reference][17]. ```yaml Type: object @@ -280,26 +417,35 @@ Required: false ### validate -The `validate` property defines how to call a DSC Group Resource to validate its instances. This -property is mandatory for DSC Group Resources. DSC ignores this property for all other resources. +The `validate` property defines how to call the resource to validate the JSON for an instance. +When a manifest defines this property, DSC calls the command to validate instance JSON instead of +validating the JSON against the resource's instance schema. Group resources, importer resources, +and resource adapters process nested resource instances that don't share a single instance schema. +Always define this property for those resources. The value of this property must be an object. The object's `executable` property, defining the name -of the command to call, is mandatory. The `args` property is optional. For more information, see -[DSC Resource manifest validate property schema reference][12]. +of the command to call, is mandatory. The `args` and `input` properties are optional. For more +information, see [DSC Resource manifest validate property schema reference][18]. ```yaml Type: object Required: false ``` -### provider +### adapter + +When specified, the `adapter` property defines the resource as a DSC Resource Adapter. When the +manifest doesn't define the `kind` property, DSC infers the kind as `adapter`. -When specified, the `provider` property defines the resource as a DSC Resource Provider. +The value of this property must be an object. The object's `inputKind` property is mandatory and +defines how the adapter expects to receive input. The `list` property is optional and defines how to +call the adapter to return the resources that the adapter can manage. For more information, see the +[DSC Resource manifest adapter property schema reference][19]. -The value of this property must be an object. The object's `list` and `config` properties are -mandatory. The `list` property defines how to call the provider to return the resources that the -provider can manage. The `config` property defines how the provider expects input. For more -information, see the [DSC Resource manifest provider property schema reference][13]. +```yaml +Type: object +Required: false +``` ### exitCodes @@ -312,7 +458,9 @@ Define this property as a set of key-value pairs where: exit code as `-2147024891`. - The value is a string describing the semantic meaning of that exit code for a human reader. -DSC interprets exit code `0` as a successful operation and any other exit code as an error. +DSC interprets exit code `0` as a successful operation and any other exit code as an error. When +the manifest doesn't define this property, DSC describes exit code `0` as `Success` and every other +exit code as `Error` in its messages. > [!TIP] > If you're authoring your resource manifest in yaml, be sure to wrap the exit code in single @@ -330,7 +478,7 @@ DSC interprets exit code `0` as a successful operation and any other exit code a ```yaml Type: object Required: false -PropertyNamePattern: ^-?[0-9]+# +PropertyNamePattern: ^-?[0-9]+$ PropertyValueType: string ``` @@ -344,24 +492,49 @@ resource. This property must always be an object that defines one of the followi - `embedded` - When you specify the `embedded` property, DSC uses the defined value as the JSON schema. -For more information, see [DSC Resource manifest schema property reference][14]. +DSC uses the schema to validate the input for an operation and, for resources with the `resource` +kind, the output the resource returns. When a manifest defines the [validate](#validate) property, +DSC calls that command instead of validating against the schema. When a manifest defines neither +`schema` nor `validate`, DSC raises an error when it needs to validate instance JSON for the +resource. + +For more information, see [DSC Resource manifest schema property reference][20]. ```yaml Type: object -Required: true +Required: false +``` + +### metadata + +The `metadata` property defines an arbitrary set of key-value pairs for the resource. DSC doesn't +validate or process the values in this object. Resource authors and integrating tools can use this +property to store additional information about the resource, like links to documentation or the +source repository for the resource. + +```yaml +Type: object +Required: false ``` + [01]: ../../definitions/resourceType.md -[02]: ../../definitions/resourceKind.md -[03]: ../../../cli/config/export.md -[04]: ../../../cli/resource/export.md -[05]: ../../../cli/resource/get.md -[06]: ../../../cli/resource/get.md#-a---all -[07]: export.md -[08]: get.md -[09]: set.md -[10]: whatif.md -[11]: test.md -[12]: validate.md -[13]: provider.md -[14]: schema/property.md +[02]: ../../config/functions/overview.md +[03]: ../../config/functions/tryWhich.md +[04]: ../../definitions/resourceKind.md +[05]: get.md +[06]: set.md +[07]: set.md#what-if-argument +[08]: whatif.md +[09]: test.md +[10]: ../properties/exist.md +[11]: delete.md +[12]: ../../../cli/config/export.md +[13]: ../../../cli/resource/export.md +[14]: ../../../cli/resource/get.md +[15]: ../../../cli/resource/get.md#-a---all +[16]: export.md +[17]: resolve.md +[18]: validate.md +[19]: adapter.md +[20]: schema/property.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md index f49617b6..e85b2b25 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the embedded instance schema in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest embedded schema reference --- @@ -25,10 +25,10 @@ The `embedded` subproperty defines a full JSON schema for a DSC Resource's insta JSON schema to validate every instance of the resource before calling the resource's commands and after receiving an instance as output from the resource. -Embedded JSON schemas are also used by integrating and authoring tools like VS Code to validate -resource instances and provide IntelliSense. +Embedded JSON schemas are also used by integrating and authoring tools like Visual Studio Code to +validate resource instances and provide IntelliSense. -## Required keywordds +## Required keywords The `embedded` definition must include these keywords: @@ -94,7 +94,6 @@ in the embedded schema, the schema _must_ define the property as a reference. - [_exist](#_exist) - [_inDesiredState](#_indesiredstate) - [_purge](#_purge) -- [_rebootRequested](#_rebootrequested) #### _exist @@ -111,7 +110,7 @@ If defined, this property must be a reference to the schema for the canonical pr } ``` -For more information, see [DSC Resource _ensure property schema][01]. +For more information, see [DSC Resource _exist property schema][01]. #### _inDesiredState @@ -145,24 +144,8 @@ If defined, this property must be a reference to the schema for the canonical pr For more information, see [DSC Resource _purge property schema][04]. -#### _rebootRequested - -The read-only `_rebootRequested` property indicates whether a resource instance requires a reboot -after a set operation. To use DSC's built-in reboot notification processing, resources must define -this property in their manifest. - -If defined, this property must be a reference to the schema for the canonical property: - -```json -"_rebootRequested": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/resource/properties/rebootRequested.json" -} -``` - -For more information, see [DSC Resource _rebootRequested property schema][05] - -[01]: ../../properties/ensure.md + +[01]: ../../properties/exist.md [02]: ../test.md [03]: ../../properties/inDesiredState.md [04]: ../../properties/purge.md -[05]: ../../properties/rebootRequested.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/property.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/property.md index 8a0bb87f..a54cc4a0 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/property.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/property.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'schema' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest schema property schema reference --- @@ -21,8 +21,12 @@ Type: object ## Description -Every command-based DSC Resource must define the `schema` property in its manifest. This property -defines how DSC can get the JSON schema it needs to validate instances of the resource. +Every command-based DSC Resource that doesn't define the [validate][01] property should define the +`schema` property in its manifest. This property defines how DSC can get the JSON schema it needs +to validate instances of the resource. DSC validates the input for an operation against the schema +before invoking the resource and, for resources with the `resource` [kind][02], validates the +output the resource returns. When a manifest defines neither `schema` nor `validate`, DSC raises an +error when it needs to validate an instance of the resource. The JSON schema can be defined dynamically with the [command](#command) property or statically with the [embedded](#embedded) property. @@ -88,7 +92,31 @@ DSC uses to validate an instance of the resource. } ``` -## Required Properties +### Example 3 - Get JSON schema for an adapted resource + +This example defines a schema command for a resource adapter that operates on a single adapted +resource at a time. DSC passes the type name and version of the adapted resource to the command. + +```json +"schema": { + "command": { + "executable": "my_adapter", + "args": [ + "schema", + { "resourceTypeArg": "--type" }, + { "resourceVersionArg": "--version" } + ] + } +} +``` + +When DSC needs the schema for the adapted resource `Contoso/Example` version `1.0.0`, it runs: + +```sh +my_adapter schema --type Contoso/Example --version 1.0.0 +``` + +## Required properties The `schema` definition must include exactly one of these properties: @@ -107,6 +135,9 @@ schema to a publicly available URI that matches the `$id` property of the instan enables authoring tools and other integrating applications to validate instances without running the command locally. +For more information about the expected output, see +[DSC resource schema command stdout schema reference][03]. + ```yaml Type: object RequiredProperties: [executable] @@ -126,22 +157,77 @@ Required: true #### args -The `args` property defines an array of strings to pass as arguments to the command. DSC passes the -arguments to the command in the order they're specified. +The `args` property defines the list of arguments to pass to the command. DSC passes the arguments +to the command in the order they're specified. Each item in the array must be a string or an object +that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `schema`. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +For every argument kind except string arguments, DSC passes the argument name followed by its value +as two separate arguments. + +```yaml +Type: array +Required: false +Default: [] +ItemsType: [string, object] +``` + +##### String arguments + +Any item in the argument array can be a string representing a static argument to pass to the +command, like `schema` or `--format`. + +```yaml +Type: string +``` + +##### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that returns the schema for a single adapted resource. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `--type`. ```yaml -Type: array -Required: false -Default: [] +Type: object +RequiredProperties: [resourceTypeArg] +``` + +##### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `--version`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] ``` ### embedded The `embedded` property defines the full JSON schema for DSC to validate instances of the DSC Resource. The value for this property must be a valid JSON schema that defines the `$schema`, -`type`, and `properties` keywords. +`type`, and `properties` keywords. For more information, see +[DSC Resource manifest embedded schema reference][04]. ```yaml Type: object MinimumPropertyCount: 1 ``` + + +[01]: ../validate.md +[02]: ../root.md#kind +[03]: ../../stdout/schema.md +[04]: embedded.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md index cd451c29..3ca90392 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'set' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest set property schema reference --- @@ -22,26 +22,34 @@ Type: object ## Description To manage an instance with DSC, a DSC Resource must define the `set` property in its manifest. This -property defines how DSC can enforce the current state of an instance. +property defines how DSC can enforce the current state of an instance. When this property is +defined, the resource has the `set` capability. When this property isn't defined, DSC can only get the current state of instances and test whether they're in the desired state. DSC can't enforce desired state for the resource. DSC sends data to the command in three ways: - 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed - JSON object without spaces or newlines between the object properties. - 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment - variable for each property in the input data object, using the name and value of the property. - 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a - string representing the data as a compressed JSON object to the specified argument. +1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. +1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. +1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. You can only define one JSON input argument for a command. +desired state to the resource. You can only define one JSON input argument for a command. You must define the `input` property, one JSON input argument in the `args` property array, or both. +When the `args` array includes a [what-if argument](#what-if-argument), the resource has the +`setWhatIf` capability. DSC calls the `set` command with the what-if argument when a user invokes +the operation in what-if mode, like with the [--what-if][01] option for the `dsc config set` +command, and the resource reports how it would change the instance without modifying the system. +When the `args` array doesn't include a what-if argument, DSC synthesizes the what-if result from +the `test` operation, unless the manifest defines the deprecated [whatIf][02] property. + ## Examples ### Example 1 - Full definition @@ -82,7 +90,39 @@ The manifest defines `return` as `state`, indicating that it only returns the fi resource after the `set` method runs. DSC compares the desired state to the return data of this resource to identify which of the resource's properties the `set` method enforced, if any. -## Required Properties +### Example 2 - What-if argument + +This example defines a what-if argument so that the resource can report the expected result of the +`set` operation without changing the system. + +```json +"set": { + "executable": "my_app", + "args": [ + "config", + "set", + { "whatIfArg": "--what-if" } + ], + "input": "stdin", + "return": "state" +} +``` + +When a user invokes the `set` operation normally, DSC calls the command as: + +```sh +{ ... } | my_app config set +``` + +When a user invokes the `set` operation in what-if mode, DSC calls the command as: + +```sh +{ ... } | my_app config set --what-if +``` + +Because the manifest defines the what-if argument, the resource has the `setWhatIf` capability. + +## Required properties The `set` definition must include these properties: @@ -104,17 +144,31 @@ Required: true ### args -The `args` property defines the list of arguments to pass to the command. The arguments can be any -number of strings. If you want to pass the JSON object representing the property bag for the -resource to an argument, you can define a single item in the array as a [JSON object], indicating the -name of the argument with the `jsonInputArg` string property and whether the argument is mandatory -for the command with the `mandatory` boolean property. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. +- [What-if argument](#what-if-argument) - The argument to pass when the operation runs in what-if + mode. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments and the what-if argument, DSC passes the argument name followed by its +value as two separate arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -126,15 +180,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][03]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### JSON input argument Defines an argument for the command that accepts the JSON input object as a string. DSC passes the -JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: +JSON input to the named argument when available. -- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. -- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the - JSON input argument. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -150,14 +224,81 @@ ways: JSON input as a string to the defined argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. This makes the manifest invalid. You must define the `input` property, -a JSON input argument in the `args` property array, or both. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][04] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + +#### What-if argument + +Defines the argument to pass to the command when a user invokes the `set` operation in what-if +mode, like with the [--what-if][01] option for the `dsc config set` command. DSC only passes the +named argument when the operation runs in what-if mode. When the operation runs normally, DSC omits +the argument. + +When the `args` array includes a what-if argument, the resource has the `setWhatIf` capability. +In what-if mode, DSC calls the `set` command with the argument instead of synthesizing the result +from the `test` operation. The resource must return the expected result of the operation without +changing the system. For more information about the expected output, see +[DSC resource what-if operation stdout schema reference][05]. + +- `whatIfArg` (required) - The argument to pass in what-if mode, like `--what-if`. + +```yaml +Type: object +RequiredProperties: [whatIfArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -216,24 +357,30 @@ Default: false ### handlesExist The `handlesExist` property defines whether the resource has built-in handling for the -[_exist][01] property in the `set` operation. The default value is `false`. +[_exist][06] property in the `set` operation. The default value is `false`. Set this property to `true` when the resource meets the following implementation requirements: -- The resource's [instance schema][02] defines the `_exist` property as a valid instance property. +- The resource's [instance schema][07] defines the `_exist` property as a valid instance property. - The resource's `set` command handles creating, updating, and deleting an instance based on the current state of the instance and the value of the `_exist` property in the desired state. -When this property is set to `true`, the resource indicates that it has the [SetHandlesExist][03] -[capability][04]. When processing resources with the `SetHandlesExist` capability in a +When this property is set to `true`, the resource indicates that it has the `setHandlesExist` +[capability][08]. When processing resources with the `setHandlesExist` capability in a configuration, DSC calls the `set` operation for the resource when an instance defines `_exist` as -`false`. Without this capability, a resource must define the [delete][05] operation to support +`false`. Without this capability, a resource must define the [delete][09] operation to support removing instances of the resource. If a resource manifest doesn't define this property as `true` and doesn't define the `delete` operation, DSC raises an error when it encounters an instance of the resource with `_exist` set to `false`. +```yaml +Type: boolean +Required: false +Default: false +``` + ### return The `return` property defines how DSC should process the output for this method. The value of this @@ -244,18 +391,70 @@ property must be one of the following strings: - `stateAndDiff` - Indicates that the resource returns the instance's final state and an array of property names that the resource modified. -The default value is `state`. +When this property isn't defined, DSC doesn't expect the resource to return any output for the +`set` operation. Instead, DSC invokes the `get` operation for the resource after the `set` +operation concludes and compares the result to the state of the instance before the operation to +determine which properties the operation changed. For more information, see +[DSC resource set operation stdout schema reference][10]. + +```yaml +Type: string +Required: false +ValidValues: [state, stateAndDiff] +``` + +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`set` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + +### whatIfReturns + +The `whatIfReturns` property defines how DSC should process the output for this method when a user +invokes the `set` operation in what-if mode. When this property is defined, it overrides the +[return](#return) property during what-if execution. When this property isn't defined, DSC +processes the output in what-if mode the same way it processes the output for an actual `set` +operation. + +Define this property when the resource returns differently shaped data in what-if mode than it +returns for an actual `set` operation. The value must be one of the same strings as the `return` +property: + +- `state` - Indicates that the resource returns only the instance's expected final state after the + set operation as a JSON blob. +- `stateAndDiff` - Indicates that the resource returns the instance's expected final state and an + array of property names that the resource would modify. ```yaml Type: string Required: false -Default: state ValidValues: [state, stateAndDiff] ``` - -[01]: ../properties/exist.md -[02]: ./root.md#schema-1 -[03]: ../../definitions/resourceCapabilities.md#setHandlesExist -[04]: ../../definitions/resourceCapabilities.md -[05]: ./delete.md + +[01]: ../../../cli/config/set.md#-w---what-if +[02]: whatif.md +[03]: adapter.md +[04]: ../stdout/list.md#path +[05]: ../stdout/whatIf.md +[06]: ../properties/exist.md +[07]: ./root.md#schema-1 +[08]: ../../definitions/resourceCapabilities.md +[09]: ./delete.md +[10]: ../stdout/set.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/test.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/test.md index 7305b345..9519e4d3 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/test.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'test' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest test property schema reference --- @@ -23,7 +23,8 @@ Type: object If a DSC Resource implements its own logic for determining whether an instance is in the desired state, it must define the `test` property in its manifest. This property defines how DSC can call -the resource to test whether an instance is in the desired state. +the resource to test whether an instance is in the desired state. When this property is defined, +the resource has the `test` capability. When this property isn't defined, DSC uses a synthetic test method for the resource. The synthetic test method: @@ -44,15 +45,15 @@ For resources with properties that can't be evaluated by equivalency alone, alwa DSC sends data to the command in three ways: - 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed - JSON object without spaces or newlines between the object properties. - 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment - variable for each property in the input data object, using the name and value of the property. - 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a - string representing the data as a compressed JSON object to the specified argument. +1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. +1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. +1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. You can only define one JSON input argument for a command. +desired state to the resource. You can only define one JSON input argument for a command. You must define the `input` property, one JSON input argument in the `args` property array, or both. @@ -90,7 +91,7 @@ Combined with the value for `executable`, DSC calls the `test` method for this r The manifest defines `return` as `state`, indicating that it only returns the actual state of the resource when the `test` method runs. -## Required Properties +## Required properties The `test` definition must include these properties: @@ -112,17 +113,29 @@ Required: true ### args -The `args` property defines the list of arguments to pass to the command. The arguments can be any -number of strings. If you want to pass the JSON object representing the property bag for the -resource to an argument, you can define a single item in the array as a [JSON object], indicating the -name of the argument with the `jsonInputArg` string property and whether the argument is mandatory -for the command with the `mandatory` boolean property. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments, DSC passes the argument name followed by its value as two separate +arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -134,15 +147,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][01]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### JSON input argument Defines an argument for the command that accepts the JSON input object as a string. DSC passes the -JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: +JSON input to the named argument when available. -- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. -- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the - JSON input argument. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -158,18 +191,66 @@ ways: JSON input as a string to the defined argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. This makes the manifest invalid. You must define the `input` property, -a JSON input argument in the `args` property array, or both. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][02] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + ### input -The `input` property defines how to pass input to the resource. If this property isn't defined, DSC -doesn't send any input to the resource when invoking the `test` operation. +The `input` property defines how to pass input to the resource. If this property isn't defined and +the definition doesn't define a [JSON input argument](#json-input-argument), DSC doesn't send any +input to the resource when invoking the `test` operation. The value of this property must be one of the following strings: @@ -207,15 +288,46 @@ ValidValues: [env, stdin] The `return` property defines how DSC should process the output for this method. The value of this property must be one of the following strings: -- `state` - Indicates that the resource returns only the instance's actual state. +- `state` - Indicates that the resource returns only the instance's actual state, including the + [_inDesiredState][03] canonical property. - `stateAndDiff` - Indicates that the resource returns the instance's actual state and an array of property names that are out of the desired state. -The default value is `state`. +When this property isn't defined, DSC ignores any output from the `test` command. Instead, DSC +invokes the `get` operation for the resource after the `test` command completes and compares each +property of the desired state to the actual state to determine whether the instance is in the +desired state. Always define this property when the resource returns its own test result. For more +information, see [DSC resource test operation stdout schema reference][04]. ```yaml Type: string Required: false -Default: state ValidValues: [state, stateAndDiff] ``` + +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`test` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + + +[01]: adapter.md +[02]: ../stdout/list.md#path +[03]: ../properties/inDesiredState.md +[04]: ../stdout/test.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/validate.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/validate.md index 449305cb..ca1c8ef3 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/validate.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/validate.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'validate' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest validate property schema reference --- @@ -9,7 +9,7 @@ title: DSC Resource manifest validate property schema reference ## Synopsis -Indicates how to call a group resource to test whether nested instances are valid. +Indicates how to call a resource to test whether an instance is valid. ## Metadata @@ -21,23 +21,28 @@ Type: object ## Description -DSC Group Resources must define the `validate` property in their DSC Resource manifest. This -property defines how DSC can call the group resource to test whether instances in the group -have valid definitions. +The `validate` property defines how DSC can call a resource to test whether the JSON for an +instance is valid. When a manifest defines this property, DSC calls the command whenever it needs +to validate instance JSON for the resource instead of validating the JSON against the resource's +[instance schema][01]. DSC validates the input for an operation before invoking the resource and, +for resources with the `resource` [kind][02], the output the resource returns. -Always define the `validate` property for group resources in the DSC Resource manifest. +Group resources, importer resources, and resource adapters process nested resource instances that +don't share a single instance schema. Always define the `validate` property for these resources. +For more information about the expected output, see +[DSC resource validate operation stdout schema reference][03]. DSC sends data to the command in three ways: - 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed - JSON object without spaces or newlines between the object properties. - 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment - variable for each property in the input data object, using the name and value of the property. - 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a - string representing the data as a compressed JSON object to the specified argument. +1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. +1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. +1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. You can only define one JSON input argument for a command. +instance JSON to the resource. You can only define one JSON input argument for a command. You must define the `input` property, one JSON input argument in the `args` property array, or both. @@ -46,28 +51,32 @@ both. ### Example 1 - Full definition -This example is from the `DSC/AssertionGroup` DSC Group Resource. +This example is from the `Microsoft.DSC/Group` DSC Group Resource. ```json "validate": { "executable": "dsc", "args": [ + "--trace-format", + "pass-through", "config", - "validate" + "validate", + { "jsonInputArg": "--input", "mandatory": true } ] } ``` -It defines the executable as `dsc` with the arguments `config` and `validate`. The `validate` -method always sends the method's input as a JSON blob over `stdin`. +It defines the executable as `dsc` with four string arguments and a +[JSON input argument](#json-input-argument). DSC passes the instance JSON to the `--input` +argument as a compressed JSON string. With this definition, DSC calls the `validate` method for this DSC Group Resource by running: ```sh -{ ... } | dsc config validate +dsc --trace-format pass-through config validate --input "{ ... }" ``` -## Required Properties +## Required properties The `validate` definition must include these properties: @@ -89,17 +98,29 @@ Required: true ### args -The `args` property defines the list of arguments to pass to the command. The arguments can be any -number of strings. If you want to pass the JSON object representing the property bag for the -resource to an argument, you can define a single item in the array as a [JSON object], indicating the -name of the argument with the `jsonInputArg` string property and whether the argument is mandatory -for the command with the `mandatory` boolean property. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments, DSC passes the argument name followed by its value as two separate +arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -111,15 +132,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][04]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### JSON input argument Defines an argument for the command that accepts the JSON input object as a string. DSC passes the -JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: +JSON input to the named argument when available. -- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. -- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the - JSON input argument. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -135,18 +176,66 @@ ways: JSON input as a string to the defined argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. This makes the manifest invalid. You must define the `input` property, -a JSON input argument in the `args` property array, or both. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][05] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + ### input -The `input` property defines how to pass input to the resource. If this property isn't defined, DSC -doesn't send any input to the resource when invoking the `validate` operation. +The `input` property defines how to pass input to the resource. If this property isn't defined and +the definition doesn't define a [JSON input argument](#json-input-argument), DSC doesn't send any +input to the resource when invoking the `validate` operation. The value of this property must be one of the following strings: @@ -178,3 +267,10 @@ Type: string Required: false ValidValues: [env, stdin] ``` + + +[01]: schema/property.md +[02]: root.md#kind +[03]: ../stdout/validate.md +[04]: adapter.md +[05]: ../stdout/list.md#path diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md index 003ac47b..f6528b1a 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'whatIf' property in a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource manifest whatIf property schema reference --- @@ -26,12 +26,22 @@ the [--what-if][02] option to see whether and how resources will change system s actually doing so. This property defines how DSC can invoke the resource to return that information directly. -When this property isn't defined, DSC synthesizes this behavior by converting the result of a test -operation against the resource into a set result. The synthetic result can only indicate how the -operation will change the resource properties. It can't indicate whether the `set` operation will -fail due to invalid parameters or which read-only properties the resource will return from the -operation. The following list describes a few cases where a synthetic what-if result won't return -sufficient information to the user: +The `whatIf` property has the same schema and shape as the [set][03] property. Every property that +you can define for the `set` method is valid for the `whatIf` method. + +> [!IMPORTANT] +> Defining a separate `whatIf` command is deprecated. Instead, define a [what-if argument][04] in +> the `args` array of the `set` property. When the `set` definition includes a what-if argument, +> DSC ignores the `whatIf` property. When the `set` definition doesn't include a what-if argument +> and the manifest defines `whatIf`, DSC calls the `whatIf` command in what-if mode and emits a +> warning. + +When the manifest defines neither a what-if argument nor the `whatIf` property, DSC synthesizes +this behavior by converting the result of a test operation against the resource into a set result. +The synthetic result can only indicate how the operation will change the resource properties. It +can't indicate whether the `set` operation will fail due to invalid parameters or which read-only +properties the resource will return from the operation. The following list describes a few cases +where a synthetic what-if result won't return sufficient information to the user: - A resource requiring a credential parameter might successfully test the instance but not have permissions to modify it. In this case, the user might run `dsc config set --what-if` and see an @@ -44,21 +54,21 @@ sufficient information to the user: what-if result, a user might then inadvertently restart a service or leave the configuration in a partially-configured state until that service is rebooted. -If your resource uses parameters or returns read-only properties from a `set` operation, define this -method to ensure your users get the best information about whether and how the resource will modify -system state in what-if mode. +If your resource uses parameters or returns read-only properties from a `set` operation, define a +what-if argument for the `set` method to ensure your users get the best information about whether +and how the resource will modify system state in what-if mode. DSC sends data to the command in three ways: - 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed - JSON object without spaces or newlines between the object properties. - 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment - variable for each property in the input data object, using the name and value of the property. - 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a - string representing the data as a compressed JSON object to the specified argument. +1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. +1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. +1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. You can only define one JSON input argument for a command. +desired state to the resource. You can only define one JSON input argument for a command. You must define the `input` property, one JSON input argument in the `args` property array, or both. @@ -68,15 +78,15 @@ both. ### Example 1 - Full definition ```json -"set": { +"whatIf": { "executable": "my_app", "args": [ "config", "set", "--what-if" ], - "input": "stdin", - "return": "state" + "input": "stdin", + "return": "state" } ``` @@ -97,7 +107,29 @@ The manifest defines `return` as `state`, indicating that it only returns the ex of the resource after the `set` method runs. DSC compares the desired state to the return data of this resource to identify which of the resource's properties the `set` method will enforce, if any. -## Required Properties +### Example 2 - Equivalent definition with a what-if argument + +This example defines the same behavior as the previous example with a what-if argument for the +`set` method instead of a separate `whatIf` definition. This is the recommended approach. + +```json +"set": { + "executable": "my_app", + "args": [ + "config", + "set", + { "whatIfArg": "--what-if" } + ], + "input": "stdin", + "return": "state" +} +``` + +DSC only passes the `--what-if` argument to the command when a user invokes the `set` operation in +what-if mode. Because the manifest defines the what-if argument, the resource has the `setWhatIf` +capability. + +## Required properties The `whatIf` definition must include these properties: @@ -119,17 +151,31 @@ Required: true ### args -The `args` property defines the list of arguments to pass to the command. The arguments can be any -number of strings. If you want to pass the JSON object representing the property bag for the -resource to an argument, you can define a single item in the array as a JSON object, indicating the -name of the argument with the `jsonInputArg` string property and whether the argument is mandatory -for the command with the `mandatory` boolean property. +The `args` property defines the list of arguments to pass to the command. Each item in the array +must be a string or an object that defines one of the following argument kinds: + +- [String arguments](#string-arguments) - A static argument, like `config` or `--format`. +- [Adapted content argument](#adapted-content-argument) - The inline content of an adapted + resource. +- [JSON input argument](#json-input-argument) - The JSON object representing the property bag for + the resource instance. +- [Resource path argument](#resource-path-argument) - The path to the resource being invoked. +- [Resource type argument](#resource-type-argument) - The fully qualified type name of the resource + being invoked. +- [Resource version argument](#resource-version-argument) - The version of the resource being + invoked. +- [What-if argument](#what-if-argument) - The argument to pass when the operation runs in what-if + mode. + +DSC passes the arguments to the command in the order they're defined. For every argument kind +except string arguments and the what-if argument, DSC passes the argument name followed by its +value as two separate arguments. ```yaml -Type: array -Required: false -Default: [] -Type: [string, object(JSON Input Argument)] +Type: array +Required: false +Default: [] +ItemsType: [string, object] ``` #### String arguments @@ -141,16 +187,35 @@ command, like `config` or `--format`. Type: string ``` +#### Adapted content argument + +Defines an argument for the command that accepts the inline content of an adapted resource as a +compressed JSON string. An adapted resource manifest can define the adapted resource inline with +its `content` property instead of pointing to a file with its `path` property. When the adapted +resource defines inline content, DSC passes the content to the named argument. When it doesn't, +DSC passes the argument name without a value. + +This argument kind is only useful for [resource adapters][05]. This argument kind was added in DSC +version 3.3.0. + +- `adaptedContentArg` (required) - The argument to pass the adapted content to for the command, + like `--content`. + +```yaml +Type: object +RequiredProperties: [adaptedContentArg] +``` + #### JSON input argument Defines an argument for the command that accepts the JSON input object as a string. DSC passes the -JSON input to the named argument when available. A JSON input argument is defined as a JSON object -with the following properties: +JSON input to the named argument when available. -- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. -- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, +- `jsonInputArg` (required) - The argument to pass the JSON data to for the command, like + `--input`. +- `mandatory` (optional) - Indicates whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the - JSON input argument. + JSON input argument. The default value is `false`. You can only define one JSON input argument per arguments array. @@ -166,14 +231,75 @@ ways: JSON input as a string to the defined argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the -input JSON to the resource. This makes the manifest invalid. You must define the `input` property, -a JSON input argument in the `args` property array, or both. +input JSON to the resource. You must define the `input` property, a JSON input argument in the +`args` property array, or both. ```yaml -Type: object +Type: object RequiredProperties: [jsonInputArg] ``` +#### Resource path argument + +Defines an argument for the command that accepts the path to the resource being invoked. For +resource adapters, this is the value of the [path][06] property that the adapter returned for the +adapted resource when DSC listed the adapter's resources. Use this argument kind to tell the +adapter which file defines the adapted resource, like the path to a PowerShell module. + +- `resourcePathArg` (required) - The argument to pass the resource path to for the command, like + `-ResourcePath`. +- `includeQuotes` (optional) - Indicates whether DSC should wrap the path in double quotes before + passing it to the command. Set this to `true` when the path might contain spaces. The default + value is `false`. + +```yaml +Type: object +RequiredProperties: [resourcePathArg] +``` + +#### Resource type argument + +Defines an argument for the command that accepts the fully qualified type name of the resource +being invoked. For resource adapters, this is the type name of the adapted resource. Use this +argument kind to implement an adapter that operates on a single adapted resource instance instead +of processing the full configuration. + +- `resourceTypeArg` (required) - The argument to pass the type name to for the command, like + `-ResourceType`. + +```yaml +Type: object +RequiredProperties: [resourceTypeArg] +``` + +#### Resource version argument + +Defines an argument for the command that accepts the version of the resource being invoked. For +resource adapters, this is the version of the adapted resource. This argument kind was added in +DSC version 3.3.0. + +- `resourceVersionArg` (required) - The argument to pass the version to for the command, like + `-ResourceVersion`. + +```yaml +Type: object +RequiredProperties: [resourceVersionArg] +``` + +#### What-if argument + +Defines the argument to pass to the command when the operation runs in what-if mode. DSC always +invokes the `whatIf` command in what-if mode, so DSC always passes the named argument to the +command. Define the what-if argument for the [set method][04] instead of the `whatIf` method to +use a single command for both modes. + +- `whatIfArg` (required) - The argument to pass in what-if mode, like `--what-if`. + +```yaml +Type: object +RequiredProperties: [whatIfArg] +``` + ### input The `input` property defines how to pass input to the resource. If this property isn't defined and @@ -233,26 +359,32 @@ Default: false ### handlesExist The `handlesExist` property defines whether the resource has built-in handling for the -[_exist][04] property in the `set` operation. The default value is `false`. In most cases, this -value should be set the same as the `implementsPretest` property in the definition for the +[_exist][07] property in the `set` operation. The default value is `false`. In most cases, this +value should be set the same as the `handlesExist` property in the definition for the [set method][03] in the resource manifest. Set this property to `true` when the resource meets the following implementation requirements: -- The resource's [instance schema][05] defines the `_exist` property as a valid instance property. +- The resource's [instance schema][08] defines the `_exist` property as a valid instance property. - The resource's `set` command handles creating, updating, and deleting an instance based on the current state of the instance and the value of the `_exist` property in the desired state. -When this property is set to `true`, the resource indicates that it has the [SetHandlesExist][06] -[capability][07]. When processing resources with the `SetHandlesExist` capability in a +When this property is set to `true`, the resource indicates that it has the `setHandlesExist` +[capability][09]. When processing resources with the `setHandlesExist` capability in a configuration, DSC calls the `set` operation for the resource when an instance defines `_exist` as -`false`. Without this capability, a resource must define the [delete][08] operation to support +`false`. Without this capability, a resource must define the [delete][10] operation to support removing instances of the resource. If a resource manifest doesn't define this property as `true` and doesn't define the `delete` operation, DSC raises an error when it encounters an instance of the resource with `_exist` set to `false`. +```yaml +Type: boolean +Required: false +Default: false +``` + ### return The `return` property defines how DSC should process the output for this method. The value of this @@ -261,23 +393,67 @@ property must be one of the following strings: - `state` - Indicates that the resource returns only the instance's expected final state after the set operation as a JSON blob. - `stateAndDiff` - Indicates that the resource returns the instance's expected final state and an - array of property names that the resource modified. + array of property names that the resource would modify. -The default value is `state`. +When this property isn't defined, DSC doesn't expect the resource to return any output. Instead, +DSC invokes the `get` operation for the resource after the command concludes and compares the +result to the state of the instance before the operation. For more information, see +[DSC resource what-if operation stdout schema reference][11]. + +```yaml +Type: string +Required: false +ValidValues: [state, stateAndDiff] +``` + +### requireSecurityContext + +The `requireSecurityContext` property defines the security context the resource requires for the +`whatIf` operation. Before invoking the command, DSC compares the current security context to this +value and raises an error if the context doesn't satisfy the requirement. The value must be one of +the following strings: + +- `current` - DSC invokes the command in any security context. This is the default behavior. +- `elevated` - DSC only invokes the command when it's running in an elevated security context, + like as an administrator on Windows or as `root` on Linux and macOS. Otherwise, DSC raises an + error. +- `restricted` - DSC only invokes the command when it's running in a non-elevated security + context. Otherwise, DSC raises an error. + +```yaml +Type: string +Required: false +Default: current +ValidValues: [current, elevated, restricted] +``` + +### whatIfReturns + +The `whatIfReturns` property defines how DSC should process the output for this method in what-if +mode. Because DSC always invokes the `whatIf` command in what-if mode, this property overrides the +[return](#return) property whenever it's defined. The value must be one of the same strings as the +`return` property: + +- `state` - Indicates that the resource returns only the instance's expected final state after the + set operation as a JSON blob. +- `stateAndDiff` - Indicates that the resource returns the instance's expected final state and an + array of property names that the resource would modify. ```yaml Type: string Required: false -Default: state ValidValues: [state, stateAndDiff] ``` - + [01]: ../../../cli/config/set.md [02]: ../../../cli/config/set.md#-w---what-if [03]: ./set.md -[04]: ../properties/exist.md -[05]: ./root.md#schema-1 -[06]: ../../definitions/resourceCapabilities.md#setHandlesExist -[07]: ../../definitions/resourceCapabilities.md -[08]: ./delete.md +[04]: ./set.md#what-if-argument +[05]: adapter.md +[06]: ../stdout/list.md#path +[07]: ../properties/exist.md +[08]: ./root.md#schema-1 +[09]: ../../definitions/resourceCapabilities.md +[10]: ./delete.md +[11]: ../stdout/whatIf.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/ensure.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/ensure.md index 97085e75..8979e749 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/ensure.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/ensure.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_ensure' well-known DSC Resource property. -ms.date: 01/17/2024 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource _ensure property schema --- @@ -26,6 +26,10 @@ ValidValues: [Absent, Present] > Starting with DSC v3.0.0-alpha.4 and schema version `2023/10` this well-known property is removed > from the schema. It's replaced by the [_exist][01] property. Microsoft recommends migrating > resources to use the `_exist` keyword instead. +> +> This page describes a legacy property and is retained for reference only. No released version +> of DSC v3 recognizes `_ensure` as a canonical property, DSC doesn't publish a schema for it under +> the `v3` schema folders, and the [canonical properties overview][02] doesn't list it. The `_ensure` property indicates that the resource can enforce whether instances exist using the shared present and absent semantics. @@ -60,4 +64,6 @@ specifically a file, or exists as a symlink. In that case, the resource would de } ``` + [01]: exist.md +[02]: overview.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md index dab30869..afa1c4ba 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_exist' canonical DSC Resource property. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource _exist property schema --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/inDesiredState.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/inDesiredState.md index a0c04d6a..9a0d927c 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/inDesiredState.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/inDesiredState.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_inDesiredState' canonical DSC Resource property. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource _inDesiredState property schema --- @@ -47,5 +47,6 @@ snippet: } ``` + [01]: ../manifest/root.md [02]: ../manifest/test.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md index 02797a47..3f18f7ea 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md @@ -2,7 +2,7 @@ description: >- Information about the list of canonical DSC Resource properties, including their purpose and how to add them to a resource's manifest. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC canonical properties --- @@ -38,17 +38,29 @@ DSC. For more information, see [DSC Resource _purge property schema][05]. -## _rebootRequested +## _restartRequired -The read-only `_rebootRequested` property indicates whether a resource instance requires a reboot -after a set operation. To use DSC's built-in reboot notification processing, resources must define -this property in their manifest. +The read-only `_restartRequired` property indicates that the machine, specific services, or +specific processes need to be restarted after the resource enforces the desired state. When a +resource includes this property in the output of a set operation, DSC records the restart +requirements in the execution information for the operation and makes them available to the +[restartRequired()][06] configuration function. -For more information, see [DSC Resource _rebootRequested property schema][06]. +The value of this property must be an array of objects. Each object defines exactly one of the +following properties: +- `system` - A string describing why the system needs to be restarted. +- `service` - The name of a service that needs to be restarted. +- `process` - An object with the `name` and `id` properties identifying a process that needs to be + restarted. + +This property replaces the `_rebootRequested` property, which earlier schemas defined but DSC +never processed. + + [01]: exist.md [02]: ../manifest/test.md [03]: ../manifest/root.md [04]: inDesiredState.md [05]: purge.md -[06]: rebootRequested.md +[06]: ../../config/functions/restartRequired.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md index dc427435..97363e1f 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_purge' canonical DSC Resource property. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource _purge property schema --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/rebootRequested.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/rebootRequested.md deleted file mode 100644 index f31bdc75..00000000 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/rebootRequested.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -description: JSON schema reference for the '_rebootRequested' canonical DSC Resource property. -ms.date: 07/03/2025 -ms.topic: reference -title: DSC Resource _rebootRequested property schema ---- - -# DSC Resource _rebootRequested property schema - -## Synopsis - -Indicates whether an instance is in the desired state. - -## Metadata - -```yaml -SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/properties/rebootRequested.json -Type: [boolean, 'null'] -ReadOnly: true -``` - -## Description - -The `_rebootRequested` canonical property indicates whether a resource instance requires a reboot -after a set operation. - -If the resource determines during a set operation that the node needs to reboot before the state -change takes full effect, it should return the instance's data with the `_rebootRequested` property -set to `true`. If a resource returns an instance from the set operation with the `_rebootRequested` -property set to `true`, DSC generates a reboot notification. - -If the resource returns an instance from the set operation without the `_rebootRequested` property -defined, or if the property value is `false`, DSC doesn't generate a reboot notification. - -Resources must define this property to use DSC's built-in reboot request notifications. - -This property is read-only. The resource returns instances with this property, but the desired -state can't include it. - -To add this property to a resource's instance schema, define the property with the following -snippet: - -```json -"_rebootRequested": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/rebootRequested.json" -} -``` diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/delete.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/delete.md index a759e986..1a0ca13c 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/delete.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/delete.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the delete resource operation -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource delete operation stdout schema reference --- @@ -9,18 +9,86 @@ title: DSC resource delete operation stdout schema reference ## Synopsis -DSC doesn't expect the **Delete** operation for a resource to return any JSON to stdout. +Defines the JSON DSC expects a resource to emit to stdout for the **Delete** operation. ## Metadata ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/delete.json -Type: 'null' +Type: ['null', object] ``` ## Description -DSC resources that implement the **Delete** operation shouldn't emit any data to stdout. DSC -doesn't expect any output for the **Delete** operation and ignores any data emitted to stdout when -invoking the operation. +DSC expects different output from the command resource depending on whether the user invokes the +**Delete** operation in what-if mode: + +- For an actual **Delete** operation, DSC doesn't expect the resource to return any JSON to stdout + and ignores any data emitted to stdout. +- For a **Delete** operation in what-if mode, when the resource defines a [what-if argument][01] + for the `delete` method, DSC expects the resource to emit a JSON object to stdout describing the + expected result of the operation. + +## Null output + +DSC resources that implement the **Delete** operation shouldn't emit any data to stdout for an +actual **Delete** operation. DSC doesn't expect any output for the operation and ignores any data +emitted to stdout when invoking the operation. + +```yaml +Type: 'null' +``` + +## What-if output + +When a resource defines a [what-if argument][01] for the `delete` method, the resource has the +`deleteWhatIf` capability. When a user invokes the **Delete** operation in what-if mode, DSC calls +the `delete` command with the what-if argument and expects the resource to emit a single JSON +object to stdout without modifying the system. DSC returns this object as the result of the +operation. The `deleteWhatIf` capability was added in DSC version 3.3.0. + +When a resource doesn't define a what-if argument for the `delete` method, DSC synthesizes the +what-if result from the **Test** operation and doesn't invoke the `delete` command. + +The object may be empty. DSC ignores any properties of the object other than `_metadata`. + +```yaml +Type: object +``` + +### _metadata + +Defines metadata for the what-if result. When defined, this property must be an object that only +defines the `whatIf` property. + +```yaml +Type: object +Required: false +``` + +#### whatIf + +Describes how the resource would change the system when the user invokes the **Delete** operation +without what-if mode. The value can be any valid JSON value, like a string describing the change or +an object representing the instance that the resource would remove. + +```yaml +Type: any +Required: false +``` + +For example, a resource might emit the following object in what-if mode: + +```json +{ + "_metadata": { + "whatIf": { + "message": "Would remove the registry key HKCU\\Example" + } + } +} +``` + + +[01]: ../manifest/delete.md#what-if-argument diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/export.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/export.md index dc43ab0c..adfc7618 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/export.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/export.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the export resource operation -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource export operation stdout schema reference --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/get.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/get.md index 5af4a3fc..ec2e13df 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/get.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/get.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the get resource operation -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource get operation stdout schema reference --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/index.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/index.md index c953d1fb..40fcc074 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/index.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/index.md @@ -1,6 +1,6 @@ --- description: Overview for the JSON Schemas defining expected stdout for DSC Resource operations. -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: Overview of DSC resource operation stdout schemas --- @@ -14,12 +14,23 @@ resources emit to stdout for each resource operation. The following schemas describe the expected output for each operation and how DSC validates the data a resource emits: -- [DSC resource delete operation stdout schema reference](./delete.md) -- [DSC resource export operation stdout schema reference](./export.md) -- [DSC resource get operation stdout schema reference](./get.md) -- [DSC resource list operation stdout schema reference](./list.md) -- [DSC resource resolve operation stdout schema reference](./resolve.md) -- [DSC resource schema operation stdout schema reference](./schema.md) -- [DSC resource test operation stdout schema reference](./test.md) -- [DSC resource validate operation stdout schema reference](./validate.md) -- [DSC resource what-if operation stdout schema reference](./whatIf.md) +- [DSC resource delete operation stdout schema reference][01] +- [DSC resource export operation stdout schema reference][02] +- [DSC resource get operation stdout schema reference][03] +- [DSC resource list operation stdout schema reference][04] +- [DSC resource resolve operation stdout schema reference][05] +- [DSC resource schema operation stdout schema reference][06] +- [DSC resource test operation stdout schema reference][07] +- [DSC resource validate operation stdout schema reference][08] +- [DSC resource what-if operation stdout schema reference][09] + + +[01]: ./delete.md +[02]: ./export.md +[03]: ./get.md +[04]: ./list.md +[05]: ./resolve.md +[06]: ./schema.md +[07]: ./test.md +[08]: ./validate.md +[09]: ./whatIf.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/list.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/list.md index 2d64a358..3d568807 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/list.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/list.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the list resource operation -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource list operation stdout schema reference --- @@ -23,21 +23,28 @@ Type: object ## Description Defines the representation of an adapted resource in DSC. DSC expects every JSON Line emitted to -stdout for the **List** operation to adhere to this schema. +stdout for the **List** operation to adhere to this schema. DSC invokes the **List** operation for +a resource adapter with the command defined by the [adapter.list][01] property in the adapter's +manifest. + +This schema is the same schema DSC uses to represent every discovered resource, including the +output of the [dsc resource list][02] command. DSC parses each JSON Line independently. When a line +doesn't adhere to this schema, DSC logs a warning and skips the line. When a line doesn't define +the [requireAdapter](#requireadapter) property, DSC logs a warning and skips the adapted resource. DSC includes the following adapter resources: -- [Microsoft.DSC/PowerShell][01] run PowerShell and enables you to use PowerShell DSC (PSDSC) -resources implemented as PowerShell classes in DSC. -- [Microsoft.Windows/WindowsPowerShell][02] runs Windows PowerShell and enables you to use any -available PSDSC resources in DSC. This adapter is only available when you install DSC on -Windows. -- [Microsoft.Windows/WMI][03] enables you to use WMI classes as resources in DSC. This adapter is -only available when you install DSC on Windows. +- [Microsoft.DSC/PowerShell][03] run PowerShell and enables you to use PowerShell DSC (PSDSC) + resources implemented as PowerShell classes in DSC. +- [Microsoft.Windows/WindowsPowerShell][04] runs Windows PowerShell and enables you to use any + available PSDSC resources in DSC. This adapter is only available when you install DSC on + Windows. +- [Microsoft.Windows/WMI][05] enables you to use WMI classes as resources in DSC. This adapter is + only available when you install DSC on Windows. -## Required Properties +## Required properties -The output for the `discover` operation must include these properties: +The output for the **List** operation must include these properties: - [type](#type) - [kind](#kind) @@ -45,42 +52,43 @@ The output for the `discover` operation must include these properties: - [capabilities](#capabilities) - [path](#path) - [directory](#directory) -- [implementedAs](#implementedas) -- [properties](#properties-1) - [requireAdapter](#requireadapter) ## Properties ### type -The `type` property represents the fully qualified type name of the resource. It's used to specify -the resource in configuration documents and as the value of the `--resource` flag when using the -`dsc resource *` commands. For more information about resource type names, see -[DSC Resource fully qualified type name schema reference][04]. +The `type` property represents the fully qualified type name of the adapted resource. It's used to +specify the resource in configuration documents and as the value of the `--resource` flag when +using the `dsc resource *` commands. For more information about resource type names, see +[DSC Resource fully qualified type name schema reference][06]. ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ ``` ### kind The `kind` property defines how DSC should handle the adapted resource. DSC supports several kinds -of resources: `resource`, `group`, `adapter`, `importer`, and `exporter`. +of resources: `resource`, `adapter`, `group`, `importer`, and `exporter`. Adapters typically +report every adapted resource with the `resource` kind. -For more information, see [DSC resource kinds][05]. +For more information, see [DSC resource kinds][07]. ```yaml Type: string -Required: false -ValidValues: [resource, adapter, group, importer, exporter] +Required: true +ValidValues: [adapter, exporter, group, importer, resource] ``` ### version The `version` property represents the current version of the adapted resource as a valid semantic -version (semver) string. The version applies to the adapted resource, not the software it manages. +version (SemVer) string. The version applies to the adapted resource, not the software it manages. +DSC also accepts a deprecated date-based version in the format `YYYY-MM-DD` with an optional +prerelease suffix. ```yaml Type: string @@ -99,14 +107,18 @@ DSC resources may have the following capabilities: - `get` - The resource can retrieve the current state of an instance. - `set` - The resource can enforce the desired state for an instance. - `setHandlesExist` - The resource handles deleting an instance during a **Set** operation. -- `whatIf` - The resource can report how it would change state for an instance during a **Set** operation. +- `setWhatIf` - The resource can report how it would change state for an instance during a **Set** + operation without modifying the system. This capability was added in DSC version 3.3.0. Through + DSC version 3.2, this capability was named `whatIf`. - `test` - The resource implements the **Test** operation and doesn't rely on synthetic testing. - `delete` - The resource can remove an instance. +- `deleteWhatIf` - The resource can report how it would remove an instance during a **Delete** + operation without modifying the system. This capability was added in DSC version 3.3.0. - `export` - The resource can enumerate every instance. - `resolve` - The resource can resolve nested instances from an external source. -For more information about resource capabilities, see [DSC resource capabilities][06]. For more -information about the operations you can invoke for a resource, see [DSC resource operations][07]. +For more information about resource capabilities, see [DSC resource capabilities][08]. For more +information about the operations you can invoke for a resource, see [DSC resource operations][09]. ```yaml Type: array @@ -117,23 +129,46 @@ ItemsValidValues: [ get, set, setHandlesExist, - whatIf, + setWhatIf, test, delete, + deleteWhatIf, export, resolve ] ``` +### deprecationMessage + +Indicates that the adapted resource is deprecated. When defined, DSC emits the message as a warning +whenever a user invokes an operation for the adapted resource and includes the message in the +output of the `dsc resource list` command. + +```yaml +Type: [string, 'null'] +Required: false +``` + ### path -Indicates the path to the adapted resource on the file system. +Indicates the path to the adapted resource on the file system, like the path to the module that +implements a PSDSC resource. DSC passes this value to the adapter when the adapter's operation +definitions include a [resource path argument][10]. ```yaml Type: string Required: true ``` +### description + +Defines a synopsis for the adapted resource's purpose as a short string. + +```yaml +Type: [string, 'null'] +Required: false +``` + ### directory Indicates the path to the folder containing the adapted resource on the file system. @@ -145,22 +180,23 @@ Required: true ### implementedAs -Indicates that the adapted resource uses a custom implementation. The name can be used to -distinguish between different implementations for the adapted resources. +Indicates how the adapted resource is implemented. When the value is `null` or the property is +omitted, DSC treats the resource as a command-based resource. Adapters should set this property to +a string that distinguishes between the implementations of the resources they support. For +example, the PowerShell adapters report `ClassBased`, `ScriptBased`, or `Binary`. ```yaml -Type: string -Required: true +Type: [string, 'null'] +Required: false ``` ### author -Indicates the name of the person or organization that developed and maintains the adapted Resource. +Indicates the name of the person or organization that developed and maintains the adapted resource. ```yaml Type: [string, 'null'] -Required: false -Pattern: ^\w+( \w+)* +Required: false ``` ### properties @@ -168,7 +204,7 @@ Pattern: ^\w+( \w+)* Defines the adapted resource's property names. ```yaml -Type: array +Type: [array, 'null'] Required: false ItemsType: string ItemsPattern: ^\w+$ @@ -177,19 +213,72 @@ ItemsPattern: ^\w+$ ### requireAdapter Defines the fully qualified type name of the adapter that the adapted resource depends on. An -adapter should always set this value to its own fully qualified resource type name. +adapter should always set this value to its own fully qualified resource type name. Although the +schema doesn't mark this property as required, DSC skips any adapted resource that doesn't define +it and logs a warning. ```yaml Type: string Required: true -Pattern: ^\w+(\.\w+){0,2}\/\w+$ +Pattern: ^\w+(\.\w+)*\/\w+$ +``` + +### schema + +Defines the JSON schema that validates instances of the adapted resource. When an adapter defines +this property for an adapted resource, DSC uses the schema to validate instances of the adapted +resource instead of invoking the adapter's [schema][11] command for the adapted resource. + +```yaml +Type: [object, 'null'] +Required: false +``` + +### targetResource + +Reserved for DSC. When DSC invokes an adapter for an adapted resource, DSC sets this property on +the adapter's representation to the adapted resource. Adapters shouldn't define this property in +the output for the **List** operation. + +```yaml +Type: [object, 'null'] +Required: false +``` + +### manifest + +Represents the values defined in a command-based resource's manifest. Adapted resources don't have +a manifest of their own, so adapters shouldn't define this property in the output for the **List** +operation. + +```yaml +Type: [object, 'null'] +Required: false +``` + +### adaptedContent + +Defines the inline content of the adapted resource as a JSON object. When an adapted resource +manifest defines the resource with the `content` property instead of the `path` property, DSC sets +this property to that content. DSC passes this value to the adapter when the adapter's operation +definitions include an [adapted content argument][12]. This property was added in DSC version +3.3.0. + +```yaml +Type: [object, 'null'] +Required: false ``` -[01]: ../../../resources/Microsoft/DSC/PowerShell/index.md -[02]: ../../../resources/Microsoft/Windows/WindowsPowerShell/index.md -[03]: ../../../resources/Microsoft/Windows/WMI/index.md -[04]: ../../definitions/resourceType.md -[05]: ../../../../concepts/resources/kinds.md -[06]: ../../../../concepts/resources/capabilities.md -[07]: ../../../../concepts/resources/operations.md +[01]: ../manifest/adapter.md#list +[02]: ../../outputs/resource/list.md +[03]: ../../../resources/Microsoft/DSC/PowerShell/index.md +[04]: ../../../resources/Microsoft/Windows/WindowsPowerShell/index.md +[05]: ../../../resources/Microsoft/Windows/WMI/index.md +[06]: ../../definitions/resourceType.md +[07]: ../../../../concepts/resources/kinds.md +[08]: ../../../../concepts/resources/capabilities.md +[09]: ../../../../concepts/resources/operations.md +[10]: ../manifest/get.md#resource-path-argument +[11]: ../manifest/schema/property.md +[12]: ../manifest/get.md#adapted-content-argument diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/resolve.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/resolve.md index 7c19b0ff..50ddd839 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/resolve.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/resolve.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the resolve resource operation -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource resolve operation stdout schema reference --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/schema.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/schema.md index f7278d3d..403f713c 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/schema.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/schema.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the schema resource command -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource schema command stdout schema reference --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/set.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/set.md index 21b92d27..be7526ac 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/set.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the set resource operation -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource set operation stdout schema reference --- @@ -22,12 +22,14 @@ SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3. Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation. -DSC expects this output for both actual **Set** operations and **Set** operations in `whatIf` mode. -If the resource has the `whatIf` capability, the output should be the same for both modes. +DSC expects this output for actual **Set** operations. For **Set** operations in what-if mode, see +[DSC resource what-if operation stdout schema reference][04]. When the resource has the +`setWhatIf` capability, DSC expects the same output shape in what-if mode unless the resource +manifest defines [set.whatIfReturns][05]. DSC expects different output from the command resource depending on the definition of [set.return][01] in the resource manifest: - + - If the field isn't defined, DSC doesn't expect the resource to return any JSON to stdout. Instead, DSC invokes the **Get** operation on the resource after the **Set** operation concludes and synthesizes the **Set** result, including the after state of the resource and the list of @@ -91,3 +93,5 @@ ItemsType: string [01]: ../manifest/set.md#return [02]: ../manifest/schema/property.md [03]: ../manifest/schema/embedded.md +[04]: ./whatIf.md +[05]: ../manifest/set.md#whatifreturns diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/test.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/test.md index faee8986..2c4c6c39 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/test.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the test resource operation -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource test operation stdout schema reference --- @@ -25,9 +25,12 @@ Defines the JSON DSC expects a resource to emit to stdout for the **Test** opera DSC expects different output from the command resource depending on the definition of [test.return][01] in the resource manifest: -- If the field is omitted or defined as `state` (the default value), DSC expects the resource to - emit a JSON Line to stdout representing the actual state of the resource instance with the - [_inDesiredState][02] canonical resource property included in the returned object. +- If the field isn't defined, DSC ignores any data the resource emits to stdout. Instead, DSC + invokes the **Get** operation on the resource after the **Test** command concludes and compares + the actual state to the desired state to synthesize the **Test** result. +- If the field is defined as `state`, DSC expects the resource to emit a JSON Line to stdout + representing the actual state of the resource instance with the [_inDesiredState][02] canonical + resource property included in the returned object. - If the field is defined as `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The first JSON Line should be an object representing the actual state of the resource instance with the `_inDesiredState` included in the returned object. The second JSON Line should be an array @@ -35,9 +38,10 @@ DSC expects different output from the command resource depending on the definiti ## state output -For the **Test** operation, DSC always expects the resource to emit a JSON Line to stdout -representing the actual state of the resource instance with the [_inDesiredState][02] canonical -resource property included in the returned object. +When a command resource defines [test.return][01] in its manifest as `state` or `stateAndDiff`, +DSC expects the resource to emit a JSON Line to stdout representing the actual state of the +resource instance with the [_inDesiredState][02] canonical resource property included in the +returned object. The output must be a JSON object. The object must be a valid representation of an instance of the resource. diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/validate.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/validate.md index c7896e14..b6d446e3 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/validate.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/validate.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the expected stdout from the validate resource operation -ms.date: 08/21/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC resource validate operation stdout schema reference --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/whatIf.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/whatIf.md index 919b8977..c341def5 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/whatIf.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/whatIf.md @@ -1,6 +1,7 @@ --- -description: JSON schema reference for the expected stdout from the set resource operation in what-if mode -ms.date: 08/21/2025 +description: >- + JSON schema reference for the expected stdout from the set resource operation in what-if mode +ms.date: 09/01/2026 ms.topic: reference title: DSC resource what-if operation stdout schema reference --- @@ -22,46 +23,67 @@ SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3. ## Description Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation in what-if -mode. +mode. DSC invokes a resource in what-if mode when a user specifies the `--what-if` option for the +`dsc config set` or `dsc resource set` commands: + +- When the `set` definition in the resource manifest includes a [what-if argument][01], DSC calls + the `set` command with that argument. +- Otherwise, when the resource manifest defines the deprecated [whatIf][02] method, DSC calls that + command. +- Otherwise, DSC synthesizes the what-if result from the **Test** operation and doesn't invoke the + resource in what-if mode. + +DSC expects different output from the command resource depending on the return kind for the +invoked method. The return kind is the value of the [whatIfReturns][03] field for the method when +it's defined, or the value of the [return][04] field otherwise: + +- If neither field is defined, DSC doesn't expect the resource to return any JSON to stdout. + Instead, DSC invokes the **Get** operation on the resource after the command concludes and + synthesizes the result from the state of the resource. +- If the return kind is `state`, DSC expects the resource to emit a JSON Line to stdout + representing the expected state of the resource instance after the **Set** operation would + change the system. +- If the return kind is `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The first + JSON Line should be an object representing the expected state of the resource after the **Set** + operation. The second JSON Line should be an array representing the names of the resource + properties that the operation would change on the system. + +## Null output + +When the return kind for the invoked method isn't defined, DSC doesn't expect the resource to emit +any JSON to stdout in what-if mode. -DSC expects different output from the command resource depending on the definition of -[whatIf.return][01] in the resource manifest: - -- If the field is defined as `state`, DSC expects the resource to emit a JSON Line to stdout - representing the actual state of the resource instance after the **Set** operation changes the - system. -- If the field is defined as `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The - first JSON Line should be an object representing the actual state of the resource after the - **Set** operation. The second JSON Line should be an array representing the names of the resource - properties that the operation changed on the system. +```yaml +Type: 'null' +``` ## state output -When a command resource defines [whatIf.return][01] in its manifest as `state` or `stateAndDiff`, -DSC expects the resource to emit a JSON Line to stdout representing the expected actual state of -the resource instance after the **Set** operation changes the system. +When the return kind for the invoked method is `state` or `stateAndDiff`, DSC expects the resource +to emit a JSON Line to stdout representing the expected actual state of the resource instance after +the **Set** operation would change the system. The output must be a JSON object. The object must be a valid representation of an instance of the resource. -Command resources define their instance schema with the [schema.command][02] or -[schema.embedded][03] fields in their resource manifest. If a command resource returns JSON that is +Command resources define their instance schema with the [schema.command][05] or +[schema.embedded][06] fields in their resource manifest. If a command resource returns JSON that is invalid against the resource instance schema, DSC raises an error. Adapted resource instances are validated by their adapter when the adapter invokes them. ```yaml -type: object +Type: object ``` ## diff output -When a command resource defines [whatIf.return][01] in its manifest as `stateAndDiff`, DSC expects -the resource to emit a second JSON Line to stdout representing the names of the resource properties -that the operation changed on the system. +When the return kind for the invoked method is `stateAndDiff`, DSC expects the resource to emit a +second JSON Line to stdout representing the names of the resource properties that the operation +would change on the system. -This output must be emitted after the JSON Line representing the state of the resource instance -after the operation changes the system. +This output must be emitted after the JSON Line representing the expected state of the resource +instance after the operation would change the system. The output must be a JSON array. The array may be empty, or it may contain one or more strings. Each string in the array must be the name of one of the resource's properties. Each string in the @@ -74,6 +96,9 @@ ItemsType: string ``` -[01]: ../manifest/whatif.md#return -[02]: ../manifest/schema/property.md -[03]: ../manifest/schema/embedded.md +[01]: ../manifest/set.md#what-if-argument +[02]: ../manifest/whatif.md +[03]: ../manifest/set.md#whatifreturns +[04]: ../manifest/set.md#return +[05]: ../manifest/schema/property.md +[06]: ../manifest/schema/embedded.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/schema-uris.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/schema-uris.md index 431c1177..43b84feb 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/schema-uris.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/schema-uris.md @@ -1,6 +1,7 @@ --- -description: Reference for how DSC schemas are versioned and published and the URIs used to retrieve them. -ms.date: 07/03/2025 +description: >- + Reference for how DSC schemas are versioned and published and the URIs used to retrieve them. +ms.date: 09/01/2026 ms.topic: reference title: DSC JSON Schema URIs --- @@ -58,6 +59,10 @@ For every release of DSC, the schemas are published to three versioned folders: - `v` - The major version folder. The schemas in this folder are always for the latest release of that major version. +DSC also recognizes the `vNext` version folder. This folder is reserved for the in-development +schemas of the next release of DSC and isn't published. Don't use `vNext` URIs in production +configuration documents, manifests, or integrating tools. + To illustrate the versioning, the following table shows which folders the schemas for each release publish to. Entries in the table with an asterisk suffix (`*`) indicate that the entry is the latest schema for that version folder. @@ -65,9 +70,45 @@ latest schema for that version folder. | Release | Major version folder | Minor version folder | Full version folder | |:-------:|:--------------------:|:--------------------:|:-------------------:| | `3.0.0` | `v3` | `v3.0` | `v3.0.0*` | -| `3.0.1` | `v3` | `v3.0*` | `v3.0.1*` | +| `3.0.1` | `v3` | `v3.0` | `v3.0.1*` | +| `3.0.2` | `v3` | `v3.0*` | `v3.0.2*` | | `3.1.0` | `v3` | `v3.1` | `v3.1.0*` | -| `3.1.1` | `v3*` | `v3.1*` | `v3.1.1*` | +| `3.1.1` | `v3` | `v3.1` | `v3.1.1*` | +| `3.1.2` | `v3` | `v3.1` | `v3.1.2*` | +| `3.1.3` | `v3` | `v3.1*` | `v3.1.3*` | +| `3.2.0` | `v3` | `v3.2` | `v3.2.0*` | +| `3.2.1` | `v3` | `v3.2` | `v3.2.1*` | +| `3.2.2` | `v3` | `v3.2` | `v3.2.2*` | +| `3.2.3` | `v3*` | `v3.2*` | `v3.2.3*` | + +### Recognized and published version folders + +DSC recognizes the version folder for every release in the `$schema` property of configuration +documents and manifests. However, the schemas haven't been published to every recognized version +folder. DSC accepts a `$schema` URI for any recognized version folder, but tools that retrieve the +schema over the network, like Visual Studio Code, can only resolve the URIs for published version +folders. + +The following table lists every recognized version folder and indicates whether the schemas are +published to that folder: + +| Version folder | Published | +|:---------------|:---------:| +| `v3` | Yes | +| `v3.2` | No | +| `v3.2.3` | No | +| `v3.2.2` | No | +| `v3.2.1` | No | +| `v3.2.0` | No | +| `v3.1` | Yes | +| `v3.1.3` | No | +| `v3.1.2` | No | +| `v3.1.1` | No | +| `v3.1.0` | Yes | +| `v3.0` | Yes | +| `v3.0.2` | Yes | +| `v3.0.1` | Yes | +| `v3.0.0` | Yes | ### Pinning to a version folder @@ -124,7 +165,7 @@ The following table illustrates these differences between schema forms: |:-----------------------|:-------------:|:--------------:| | Canonical (nonbundled) | _None_ | `.json` | | Canonically bundled | `bundled` | `.json` | -| Enhanced autoring | `bundled` | `.vscode.json` | +| Enhanced authoring | `bundled` | `.vscode.json` | ### Canonical (nonbundled) schemas @@ -155,18 +196,18 @@ the `$schema` keyword. ### Enhanced authoring schemas Every DSC Schema published in the canonically bundled form is also published in the enhanced -authoring form. These schemas use the extended vocabulary that VS Code recognizes for JSON Schemas -to provide improved IntelliSense, hover documentation, error messaging, and default snippets. These -schemas make it easier to author, edit, and review your configuration documents, resource -manifests, and DSC's output in VS Code. +authoring form. These schemas use the extended vocabulary that Visual Studio Code recognizes for +JSON Schemas to provide improved IntelliSense, hover documentation, error messaging, and default +snippets. These schemas make it easier to author, edit, and review your configuration documents, +resource manifests, and DSC's output in Visual Studio Code. These schemas validate the data with the same vocabulary as the canonical forms of the schema. They -only affect the experience for authoring, editing, and reviewing the data in VS Code. +only affect the experience for authoring, editing, and reviewing the data in Visual Studio Code. These JSON Schemas are _not_ canonical. They use a vocabulary that most JSON Schema libraries and tools don't understand. In most cases, using these schemas with those tools shouldn't raise any -errors. However, when you want to use the DSC schemas with tools other than VS Code, you should -consider using the canonically bundled form of the schema instead. +errors. However, when you want to use the DSC schemas with tools other than Visual Studio Code, +you should consider using the canonically bundled form of the schema instead. ## Bundled schema URIs list @@ -185,42 +226,77 @@ schemas from the following uri: ### Configuration document schema -The following table defines the value of the `$id` keyword for each published version of the +The following table defines the value of the `$id` keyword for each recognized version of the configuration document schema. The `$id` is the same across all forms of the schema and regardless -of the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:--------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/config/document.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/config/document.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/config/document.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/config/document.json` | -| `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/config/document.json` | -| `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/config/document.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.json` | - -The following list of tables defines the recognized URIs for the configuration document schema: +of the prefix URI used to retrieve the schema. The **Published** column indicates whether the schema +is published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:--------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/config/document.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/config/document.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/config/document.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/config/document.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/config/document.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/config/document.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/config/document.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/config/document.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/config/document.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/config/document.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/config/document.json` | +| `v3.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/config/document.json` | +| `v3.0.2` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/config/document.json` | +| `v3.0.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/config/document.json` | +| `v3.0.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.json` | + +The following list of tables defines the recognized URIs for the configuration document schema. DSC +accepts any of these URIs in the `$schema` property, but only the URIs for published version folders +resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/config/document.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/config/document.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/config/document.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/config/document.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/config/document.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/config/document.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/config/document.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/config/document.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/config/document.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/config/document.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/config/document.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/config/document.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/config/document.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/config/document.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/config/document.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/config/document.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/config/document.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/config/document.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/config/document.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/config/document.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/config/document.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/config/document.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/config/document.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/config/document.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/config/document.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/config/document.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/config/document.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/config/document.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/config/document.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/config/document.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/config/document.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/config/document.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/config/document.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/config/document.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/config/document.vscode.json` | @@ -232,21 +308,45 @@ The following list of tables defines the recognized URIs for the configuration d | Form | Version | Recognized URI | |:-----------------------|:---------|:-----------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/config/document.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/config/document.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/config/document.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/config/document.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/config/document.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/config/document.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/config/document.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/config/document.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/config/document.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/config/document.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/config/document.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/config/document.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/config/document.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/config/document.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/config/document.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/config/document.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/config/document.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/config/document.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/config/document.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/config/document.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/config/document.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/config/document.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/config/document.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/config/document.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/config/document.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/config/document.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/config/document.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/config/document.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/config/document.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/config/document.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/config/document.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/config/document.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/config/document.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/config/document.vscode.json` | @@ -255,42 +355,77 @@ The following list of tables defines the recognized URIs for the configuration d ### Resource manifest schema -The following table defines the value of the `$id` keyword for each published version of the -resource manifest schema. The `$id` is the same across all forms of the schema and regardless of -the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:----------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/resource/manifest.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/manifest.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/resource/manifest.json` | -| `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/resource/manifest.json` | -| `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/resource/manifest.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/manifest.json` | - -The following list of tables defines the recognized URIs for the resource manifest schema: +The following table defines the value of the `$id` keyword for each recognized version of the +resource manifest schema. The `$id` is the same across all forms of the schema and regardless of the +prefix URI used to retrieve the schema. The **Published** column indicates whether the schema is +published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:----------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/resource/manifest.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/resource/manifest.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/resource/manifest.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/resource/manifest.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/resource/manifest.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/resource/manifest.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/resource/manifest.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/resource/manifest.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/resource/manifest.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/manifest.json` | +| `v3.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/resource/manifest.json` | +| `v3.0.2` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/resource/manifest.json` | +| `v3.0.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/resource/manifest.json` | +| `v3.0.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/manifest.json` | + +The following list of tables defines the recognized URIs for the resource manifest schema. DSC +accepts any of these URIs in the `$schema` property, but only the URIs for published version folders +resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:--------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/resource/manifest.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/resource/manifest.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/resource/manifest.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/resource/manifest.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/resource/manifest.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/resource/manifest.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/resource/manifest.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/resource/manifest.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/resource/manifest.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/resource/manifest.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/resource/manifest.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/resource/manifest.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/resource/manifest.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/resource/manifest.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/resource/manifest.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/resource/manifest.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/resource/manifest.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/resource/manifest.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/resource/manifest.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/resource/manifest.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/resource/manifest.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/resource/manifest.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/resource/manifest.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/resource/manifest.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/resource/manifest.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/resource/manifest.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/resource/manifest.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/resource/manifest.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/resource/manifest.vscode.json` | @@ -302,21 +437,45 @@ The following list of tables defines the recognized URIs for the resource manife | Form | Version | Recognized URI | |:-----------------------|:---------|:-------------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/resource/manifest.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/resource/manifest.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/resource/manifest.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/resource/manifest.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/resource/manifest.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/resource/manifest.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/resource/manifest.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/resource/manifest.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/resource/manifest.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/resource/manifest.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/resource/manifest.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/resource/manifest.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/resource/manifest.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/resource/manifest.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/resource/manifest.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/resource/manifest.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/resource/manifest.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/resource/manifest.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/resource/manifest.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/manifest.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/resource/manifest.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/resource/manifest.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/resource/manifest.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/manifest.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/resource/manifest.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/resource/manifest.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/resource/manifest.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/resource/manifest.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/resource/manifest.vscode.json` | @@ -325,42 +484,77 @@ The following list of tables defines the recognized URIs for the resource manife ### Extension manifest schema -The following table defines the value of the `$id` keyword for each published version of the +The following table defines the value of the `$id` keyword for each recognized version of the extension manifest schema. The `$id` is the same across all forms of the schema and regardless of -the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:-----------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/extension/manifest.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/extension/manifest.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/extension/manifest.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/extension/manifest.json` | -| `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/extension/manifest.json` | -| `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/extension/manifest.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/extension/manifest.json` | - -The following list of tables defines the recognized URIs for the resource manifest schema: +the prefix URI used to retrieve the schema. The **Published** column indicates whether the schema is +published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:-----------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/extension/manifest.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/extension/manifest.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/extension/manifest.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/extension/manifest.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/extension/manifest.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/extension/manifest.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/extension/manifest.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/extension/manifest.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/extension/manifest.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/extension/manifest.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/extension/manifest.json` | +| `v3.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/extension/manifest.json` | +| `v3.0.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/extension/manifest.json` | +| `v3.0.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/extension/manifest.json` | +| `v3.0.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/extension/manifest.json` | + +The following list of tables defines the recognized URIs for the extension manifest schema. DSC +accepts any of these URIs in the `$schema` property, but only the URIs for published version folders +resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:---------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/extension/manifest.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/extension/manifest.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/extension/manifest.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/extension/manifest.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/extension/manifest.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/extension/manifest.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/extension/manifest.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/extension/manifest.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/extension/manifest.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/extension/manifest.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/extension/manifest.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/extension/manifest.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/extension/manifest.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/extension/manifest.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/extension/manifest.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/extension/manifest.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/extension/manifest.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/extension/manifest.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/extension/manifest.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/extension/manifest.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/extension/manifest.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/extension/manifest.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/extension/manifest.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/extension/manifest.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/extension/manifest.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/extension/manifest.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/extension/manifest.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/extension/manifest.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/extension/manifest.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/extension/manifest.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/extension/manifest.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/extension/manifest.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/extension/manifest.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/extension/manifest.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/extension/manifest.vscode.json` | @@ -372,21 +566,45 @@ The following list of tables defines the recognized URIs for the resource manife | Form | Version | Recognized URI | |:-----------------------|:---------|:--------------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/extension/manifest.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/extension/manifest.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/extension/manifest.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/extension/manifest.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/extension/manifest.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/extension/manifest.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/extension/manifest.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/extension/manifest.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/extension/manifest.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/extension/manifest.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/extension/manifest.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/extension/manifest.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/extension/manifest.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/extension/manifest.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/extension/manifest.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/extension/manifest.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/extension/manifest.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/extension/manifest.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/extension/manifest.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/extension/manifest.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/extension/manifest.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/extension/manifest.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/extension/manifest.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/extension/manifest.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/extension/manifest.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/extension/manifest.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/extension/manifest.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/extension/manifest.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/extension/manifest.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/extension/manifest.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/extension/manifest.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/extension/manifest.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/extension/manifest.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/extension/manifest.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/extension/manifest.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/extension/manifest.vscode.json` | @@ -395,42 +613,77 @@ The following list of tables defines the recognized URIs for the resource manife ### Output schema for dsc config get command -The following table defines the value of the `$id` keyword for each published version of the output +The following table defines the value of the `$id` keyword for each recognized version of the output schema for the `dsc config get` command. The `$id` is the same across all forms of the schema and -regardless of the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:-----------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/get.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/config/get.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/config/get.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/get.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/get.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/get.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/get.json` | - -The following list of tables defines the recognized URIs for the output schema: +regardless of the prefix URI used to retrieve the schema. The **Published** column indicates whether +the schema is published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:-----------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/get.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/config/get.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/config/get.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/config/get.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/config/get.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/config/get.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/config/get.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/config/get.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/config/get.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/config/get.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/config/get.json` | +| `v3.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/get.json` | +| `v3.0.2` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/config/get.json` | +| `v3.0.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/config/get.json` | +| `v3.0.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/get.json` | + +The following list of tables defines the recognized URIs for the output schema for the `dsc config +get` command. DSC accepts any of these URIs in the `$schema` property, but only the URIs for +published version folders resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:---------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/config/get.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/config/get.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/config/get.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/outputs/config/get.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/outputs/config/get.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/outputs/config/get.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/config/get.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/outputs/config/get.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/outputs/config/get.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/config/get.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/config/get.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/config/get.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/config/get.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/get.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/config/get.vscode.json` | @@ -442,21 +695,45 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:-----------------------|:---------|:--------------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/config/get.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/config/get.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/config/get.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/outputs/config/get.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/config/get.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/config/get.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/config/get.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/config/get.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/config/get.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/get.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/config/get.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/config/get.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/get.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/config/get.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/config/get.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/config/get.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/config/get.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/get.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/config/get.vscode.json` | @@ -465,42 +742,77 @@ The following list of tables defines the recognized URIs for the output schema: ### Output schema for dsc config set command -The following table defines the value of the `$id` keyword for each published version of the output +The following table defines the value of the `$id` keyword for each recognized version of the output schema for the `dsc config set` command. The `$id` is the same across all forms of the schema and -regardless of the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:-----------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/set.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/config/set.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/config/set.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/set.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/set.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/set.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/set.json` | - -The following list of tables defines the recognized URIs for the output schema: +regardless of the prefix URI used to retrieve the schema. The **Published** column indicates whether +the schema is published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:-----------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/set.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/config/set.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/config/set.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/config/set.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/config/set.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/config/set.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/config/set.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/config/set.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/config/set.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/config/set.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/config/set.json` | +| `v3.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/set.json` | +| `v3.0.2` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/config/set.json` | +| `v3.0.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/config/set.json` | +| `v3.0.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/set.json` | + +The following list of tables defines the recognized URIs for the output schema for the `dsc config +set` command. DSC accepts any of these URIs in the `$schema` property, but only the URIs for +published version folders resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:---------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/config/set.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/config/set.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/config/set.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/outputs/config/set.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/outputs/config/set.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/outputs/config/set.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/config/set.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/outputs/config/set.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/outputs/config/set.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/config/set.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/config/set.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/config/set.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/config/set.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/set.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/config/set.vscode.json` | @@ -512,21 +824,45 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:-----------------------|:---------|:--------------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/config/set.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/config/set.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/config/set.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/outputs/config/set.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/config/set.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/config/set.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/config/set.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/config/set.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/config/set.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/set.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/config/set.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/config/set.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/set.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/config/set.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/config/set.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/config/set.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/config/set.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/set.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/config/set.vscode.json` | @@ -535,42 +871,77 @@ The following list of tables defines the recognized URIs for the output schema: ### Output schema for dsc config test command -The following table defines the value of the `$id` keyword for each published version of the output +The following table defines the value of the `$id` keyword for each recognized version of the output schema for the `dsc config test` command. The `$id` is the same across all forms of the schema and -regardless of the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:------------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/test.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/config/test.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/config/test.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/test.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/test.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/test.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/test.json` | - -The following list of tables defines the recognized URIs for the output schema: +regardless of the prefix URI used to retrieve the schema. The **Published** column indicates whether +the schema is published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:------------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/test.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/config/test.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/config/test.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/config/test.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/config/test.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/config/test.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/config/test.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/config/test.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/config/test.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/config/test.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/config/test.json` | +| `v3.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/test.json` | +| `v3.0.2` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/config/test.json` | +| `v3.0.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/config/test.json` | +| `v3.0.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/test.json` | + +The following list of tables defines the recognized URIs for the output schema for the `dsc config +test` command. DSC accepts any of these URIs in the `$schema` property, but only the URIs for +published version folders resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:----------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/config/test.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/config/test.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/config/test.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/outputs/config/test.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/outputs/config/test.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/outputs/config/test.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/config/test.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/outputs/config/test.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/outputs/config/test.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/config/test.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/config/test.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/config/test.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/config/test.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/config/test.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/config/test.vscode.json` | @@ -582,21 +953,45 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:-----------------------|:---------|:---------------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/config/test.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/config/test.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/config/test.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/outputs/config/test.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/config/test.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/config/test.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/config/test.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/config/test.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/config/test.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/config/test.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/config/test.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/config/test.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/config/test.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/config/test.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/config/test.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/config/test.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/config/test.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/config/test.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/config/test.vscode.json` | @@ -605,42 +1000,77 @@ The following list of tables defines the recognized URIs for the output schema: ### Output schema for dsc extension list command -The following table defines the value of the `$id` keyword for each published version of the output +The following table defines the value of the `$id` keyword for each recognized version of the output schema for the `dsc extension list` command. The `$id` is the same across all forms of the schema -and regardless of the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:---------------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/extension/list.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/extension/list.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/extension/list.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/extension/list.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/extension/list.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/extension/list.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/extension/list.json` | - -The following list of tables defines the recognized URIs for the output schema: +and regardless of the prefix URI used to retrieve the schema. The **Published** column indicates +whether the schema is published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:---------------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/extension/list.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/extension/list.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/extension/list.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/extension/list.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/extension/list.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/extension/list.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/extension/list.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/extension/list.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/extension/list.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/extension/list.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/extension/list.json` | +| `v3.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/extension/list.json` | +| `v3.0.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/extension/list.json` | +| `v3.0.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/extension/list.json` | +| `v3.0.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/extension/list.json` | + +The following list of tables defines the recognized URIs for the output schema for the `dsc +extension list` command. DSC accepts any of these URIs in the `$schema` property, but only the URIs +for published version folders resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:-------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/extension/list.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/extension/list.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/extension/list.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/extension/list.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/extension/list.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/extension/list.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/extension/list.vscode.json` | @@ -652,21 +1082,45 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:-----------------------|:---------|:------------------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/extension/list.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/outputs/extension/list.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/extension/list.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/extension/list.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/extension/list.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/extension/list.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/extension/list.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/extension/list.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/extension/list.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/extension/list.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/extension/list.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/extension/list.vscode.json` | @@ -675,42 +1129,77 @@ The following list of tables defines the recognized URIs for the output schema: ### Output schema for dsc resource get command -The following table defines the value of the `$id` keyword for each published version of the output +The following table defines the value of the `$id` keyword for each recognized version of the output schema for the `dsc resource get` command. The `$id` is the same across all forms of the schema and -regardless of the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:-------------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/get.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/get.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/get.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/get.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/get.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/get.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/get.json` | - -The following list of tables defines the recognized URIs for the output schema: +regardless of the prefix URI used to retrieve the schema. The **Published** column indicates whether +the schema is published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:-------------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/get.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/resource/get.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/resource/get.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/resource/get.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/resource/get.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/resource/get.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/get.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/resource/get.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/resource/get.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/resource/get.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/get.json` | +| `v3.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/get.json` | +| `v3.0.2` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/resource/get.json` | +| `v3.0.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/resource/get.json` | +| `v3.0.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/get.json` | + +The following list of tables defines the recognized URIs for the output schema for the `dsc resource +get` command. DSC accepts any of these URIs in the `$schema` property, but only the URIs for +published version folders resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:-----------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/get.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/get.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/resource/get.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/resource/get.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/resource/get.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/get.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/resource/get.vscode.json` | @@ -722,21 +1211,45 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:-----------------------|:---------|:----------------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/resource/get.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/outputs/resource/get.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/get.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/resource/get.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/resource/get.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/get.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/resource/get.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/resource/get.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/resource/get.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/resource/get.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/get.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/resource/get.vscode.json` | @@ -745,42 +1258,77 @@ The following list of tables defines the recognized URIs for the output schema: ### Output schema for dsc resource list command -The following table defines the value of the `$id` keyword for each published version of the output +The following table defines the value of the `$id` keyword for each recognized version of the output schema for the `dsc resource list` command. The `$id` is the same across all forms of the schema and -regardless of the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:--------------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/list.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/list.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/list.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/list.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/list.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/list.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/list.json` | - -The following list of tables defines the recognized URIs for the output schema: +regardless of the prefix URI used to retrieve the schema. The **Published** column indicates whether +the schema is published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:--------------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/list.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/resource/list.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/resource/list.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/resource/list.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/resource/list.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/resource/list.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/list.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/resource/list.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/resource/list.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/resource/list.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/list.json` | +| `v3.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/list.json` | +| `v3.0.2` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/resource/list.json` | +| `v3.0.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/resource/list.json` | +| `v3.0.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/list.json` | + +The following list of tables defines the recognized URIs for the output schema for the `dsc resource +list` command. DSC accepts any of these URIs in the `$schema` property, but only the URIs for +published version folders resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/list.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/list.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/resource/list.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/resource/list.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/resource/list.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/list.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/resource/list.vscode.json` | @@ -792,21 +1340,45 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:-----------------------|:---------|:-----------------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/resource/list.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/outputs/resource/list.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/list.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/resource/list.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/resource/list.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/list.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/resource/list.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/resource/list.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/resource/list.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/resource/list.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/list.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/resource/list.vscode.json` | @@ -815,42 +1387,77 @@ The following list of tables defines the recognized URIs for the output schema: ### Output schema for dsc resource schema command -The following table defines the value of the `$id` keyword for each published version of the output -schema for the `dsc resource schema` command. The `$id` is the same across all forms of the schema and -regardless of the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:----------------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/schema.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/schema.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/schema.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/schema.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/schema.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/schema.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/schema.json` | - -The following list of tables defines the recognized URIs for the output schema: +The following table defines the value of the `$id` keyword for each recognized version of the output +schema for the `dsc resource schema` command. The `$id` is the same across all forms of the schema +and regardless of the prefix URI used to retrieve the schema. The **Published** column indicates +whether the schema is published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:----------------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/schema.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/resource/schema.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/resource/schema.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/resource/schema.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/resource/schema.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/resource/schema.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/schema.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/resource/schema.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/resource/schema.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/resource/schema.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/schema.json` | +| `v3.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/schema.json` | +| `v3.0.2` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/resource/schema.json` | +| `v3.0.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/resource/schema.json` | +| `v3.0.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/schema.json` | + +The following list of tables defines the recognized URIs for the output schema for the `dsc resource +schema` command. DSC accepts any of these URIs in the `$schema` property, but only the URIs for +published version folders resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:--------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/schema.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/resource/schema.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/resource/schema.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/resource/schema.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/schema.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/resource/schema.vscode.json` | @@ -862,21 +1469,45 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:-----------------------|:---------|:-------------------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/resource/schema.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/outputs/resource/schema.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/resource/schema.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/resource/schema.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/schema.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/resource/schema.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/resource/schema.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/resource/schema.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/resource/schema.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/schema.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/resource/schema.vscode.json` | @@ -885,42 +1516,77 @@ The following list of tables defines the recognized URIs for the output schema: ### Output schema for dsc resource set command -The following table defines the value of the `$id` keyword for each published version of the output +The following table defines the value of the `$id` keyword for each recognized version of the output schema for the `dsc resource set` command. The `$id` is the same across all forms of the schema and -regardless of the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:-------------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/set.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/set.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/set.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/set.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/set.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/set.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/set.json` | - -The following list of tables defines the recognized URIs for the output schema: +regardless of the prefix URI used to retrieve the schema. The **Published** column indicates whether +the schema is published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:-------------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/set.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/resource/set.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/resource/set.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/resource/set.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/resource/set.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/resource/set.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/set.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/resource/set.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/resource/set.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/resource/set.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/set.json` | +| `v3.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/set.json` | +| `v3.0.2` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/resource/set.json` | +| `v3.0.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/resource/set.json` | +| `v3.0.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/set.json` | + +The following list of tables defines the recognized URIs for the output schema for the `dsc resource +set` command. DSC accepts any of these URIs in the `$schema` property, but only the URIs for +published version folders resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:-----------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/set.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/set.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/resource/set.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/resource/set.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/resource/set.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/set.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/resource/set.vscode.json` | @@ -932,21 +1598,45 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:-----------------------|:---------|:----------------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/resource/set.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/outputs/resource/set.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/set.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/resource/set.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/resource/set.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/set.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/resource/set.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/resource/set.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/resource/set.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/resource/set.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/set.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/resource/set.vscode.json` | @@ -955,42 +1645,77 @@ The following list of tables defines the recognized URIs for the output schema: ### Output schema for dsc resource test command -The following table defines the value of the `$id` keyword for each published version of the output +The following table defines the value of the `$id` keyword for each recognized version of the output schema for the `dsc resource test` command. The `$id` is the same across all forms of the schema and -regardless of the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:--------------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/test.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/test.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/test.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/test.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/test.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/test.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/test.json` | - -The following list of tables defines the recognized URIs for the output schema: +regardless of the prefix URI used to retrieve the schema. The **Published** column indicates whether +the schema is published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:--------------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/test.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/resource/test.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/resource/test.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/resource/test.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/resource/test.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/resource/test.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/test.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/resource/test.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/resource/test.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/resource/test.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/test.json` | +| `v3.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/test.json` | +| `v3.0.2` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/resource/test.json` | +| `v3.0.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/resource/test.json` | +| `v3.0.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/test.json` | + +The following list of tables defines the recognized URIs for the output schema for the `dsc resource +test` command. DSC accepts any of these URIs in the `$schema` property, but only the URIs for +published version folders resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/resource/test.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/resource/test.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/resource/test.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/resource/test.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/resource/test.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/resource/test.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/resource/test.vscode.json` | @@ -1002,21 +1727,45 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:-----------------------|:---------|:-----------------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/resource/test.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/outputs/resource/test.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/resource/test.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/resource/test.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/resource/test.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/resource/test.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/resource/test.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/resource/test.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/resource/test.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/resource/test.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/resource/test.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/resource/test.vscode.json` | @@ -1025,42 +1774,77 @@ The following list of tables defines the recognized URIs for the output schema: ### Output schema for dsc schema command -The following table defines the value of the `$id` keyword for each published version of the output +The following table defines the value of the `$id` keyword for each recognized version of the output schema for the `dsc schema` command. The `$id` is the same across all forms of the schema and -regardless of the prefix URI used to retrieve the schema. - -| Version folder | ID | -|:---------------|:-------------------------------------------------------------------------------------------| -| `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/schema.json` | -| `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/schema.json` | -| `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/schema.json` | -| `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/schema.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/schema.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/schema.json` | -| `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/schema.json` | - -The following list of tables defines the recognized URIs for the output schema: +regardless of the prefix URI used to retrieve the schema. The **Published** column indicates whether +the schema is published to that version folder. + +| Version folder | Published | ID | +|:---------------|:---------:|:-------------------------------------------------------------------------------------------| +| `v3` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/schema.json` | +| `v3.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/schema.json` | +| `v3.2.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/schema.json` | +| `v3.2.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/schema.json` | +| `v3.2.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/schema.json` | +| `v3.2.0` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/schema.json` | +| `v3.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/schema.json` | +| `v3.1.3` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/schema.json` | +| `v3.1.2` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/schema.json` | +| `v3.1.1` | No | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/schema.json` | +| `v3.1.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/schema.json` | +| `v3.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/schema.json` | +| `v3.0.2` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/schema.json` | +| `v3.0.1` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/schema.json` | +| `v3.0.0` | Yes | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/schema.json` | + +The following list of tables defines the recognized URIs for the output schema for the `dsc schema` +command. DSC accepts any of these URIs in the `$schema` property, but only the URIs for published +version folders resolve to a schema document. - Short URIs by version and form: | Form | Version | Recognized URI | |:-----------------------|:---------|:-----------------------------------------------------------------------| | Canonically bundled | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/schema.json` | + | Canonically bundled | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/schema.json` | + | Canonically bundled | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/schema.json` | + | Canonically bundled | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/schema.json` | + | Canonically bundled | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/schema.json` | + | Canonically bundled | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/schema.json` | | Canonically bundled | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/schema.json` | + | Canonically bundled | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/schema.json` | + | Canonically bundled | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/schema.json` | + | Canonically bundled | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/schema.json` | | Canonically bundled | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/schema.json` | | Canonically bundled | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/schema.json` | | Canonically bundled | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/schema.json` | | Canonically bundled | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/bundled/outputs/schema.json` | | Canonically bundled | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/bundled/outputs/schema.json` | | Canonical (nonbundled) | `v3` | `https://aka.ms/dsc/schemas/v3/outputs/schema.json` | + | Canonical (nonbundled) | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/outputs/schema.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/outputs/schema.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/outputs/schema.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/outputs/schema.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/outputs/schema.json` | | Canonical (nonbundled) | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/outputs/schema.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/outputs/schema.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/outputs/schema.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/outputs/schema.json` | | Canonical (nonbundled) | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/outputs/schema.json` | | Canonical (nonbundled) | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/outputs/schema.json` | | Canonical (nonbundled) | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/outputs/schema.json` | | Canonical (nonbundled) | `v3.0.1` | `https://aka.ms/dsc/schemas/v3.0.1/outputs/schema.json` | | Canonical (nonbundled) | `v3.0.0` | `https://aka.ms/dsc/schemas/v3.0.0/outputs/schema.json` | | Enhanced authoring | `v3` | `https://aka.ms/dsc/schemas/v3/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.2` | `https://aka.ms/dsc/schemas/v3.2/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://aka.ms/dsc/schemas/v3.2.3/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://aka.ms/dsc/schemas/v3.2.2/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://aka.ms/dsc/schemas/v3.2.1/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://aka.ms/dsc/schemas/v3.2.0/bundled/outputs/schema.vscode.json` | | Enhanced authoring | `v3.1` | `https://aka.ms/dsc/schemas/v3.1/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://aka.ms/dsc/schemas/v3.1.3/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://aka.ms/dsc/schemas/v3.1.2/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://aka.ms/dsc/schemas/v3.1.1/bundled/outputs/schema.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://aka.ms/dsc/schemas/v3.1.0/bundled/outputs/schema.vscode.json` | | Enhanced authoring | `v3.0` | `https://aka.ms/dsc/schemas/v3.0/bundled/outputs/schema.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://aka.ms/dsc/schemas/v3.0.2/bundled/outputs/schema.vscode.json` | @@ -1072,21 +1856,45 @@ The following list of tables defines the recognized URIs for the output schema: | Form | Version | Recognized URI | |:-----------------------|:---------|:----------------------------------------------------------------------------------------------------------| | Canonically bundled | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/schema.json` | + | Canonically bundled | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/schema.json` | + | Canonically bundled | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/schema.json` | + | Canonically bundled | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/schema.json` | + | Canonically bundled | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/schema.json` | + | Canonically bundled | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/schema.json` | | Canonically bundled | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/schema.json` | + | Canonically bundled | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/schema.json` | + | Canonically bundled | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/schema.json` | + | Canonically bundled | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/schema.json` | | Canonically bundled | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/schema.json` | | Canonically bundled | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/schema.json` | | Canonically bundled | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/schema.json` | | Canonically bundled | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/bundled/outputs/schema.json` | | Canonically bundled | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/outputs/schema.json` | | Canonical (nonbundled) | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/schema.json` | + | Canonical (nonbundled) | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/outputs/schema.json` | + | Canonical (nonbundled) | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/outputs/schema.json` | + | Canonical (nonbundled) | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/outputs/schema.json` | + | Canonical (nonbundled) | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/outputs/schema.json` | + | Canonical (nonbundled) | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/schema.json` | | Canonical (nonbundled) | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/outputs/schema.json` | + | Canonical (nonbundled) | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/outputs/schema.json` | + | Canonical (nonbundled) | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/outputs/schema.json` | + | Canonical (nonbundled) | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/outputs/schema.json` | | Canonical (nonbundled) | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/outputs/schema.json` | | Canonical (nonbundled) | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/outputs/schema.json` | | Canonical (nonbundled) | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/outputs/schema.json` | | Canonical (nonbundled) | `v3.0.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.1/outputs/schema.json` | | Canonical (nonbundled) | `v3.0.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/outputs/schema.json` | | Enhanced authoring | `v3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.2.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.3/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.2.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.2/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.2.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.1/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.2.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/bundled/outputs/schema.vscode.json` | | Enhanced authoring | `v3.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.1.3` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.3/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.1.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.2/bundled/outputs/schema.vscode.json` | + | Enhanced authoring | `v3.1.1` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.1/bundled/outputs/schema.vscode.json` | | Enhanced authoring | `v3.1.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/bundled/outputs/schema.vscode.json` | | Enhanced authoring | `v3.0` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/outputs/schema.vscode.json` | | Enhanced authoring | `v3.0.2` | `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.2/bundled/outputs/schema.vscode.json` | diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml b/dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml index b654aee3..a28553d8 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml @@ -17,6 +17,10 @@ items: items: - name: dsc extension list output href: outputs/extension/list.md + - name: dsc function command outputs + items: + - name: dsc function list output + href: outputs/function/list.md - name: dsc resource command outputs items: - name: dsc resource get output @@ -37,30 +41,98 @@ items: href: config/parameter.md - name: Resource instances href: config/resource.md + - name: Copy loops + href: config/functions/copy.md - name: Functions items: - name: Overview href: config/functions/overview.md - name: add href: config/functions/add.md + - name: and + href: config/functions/and.md + - name: array + href: config/functions/array.md - name: base64 href: config/functions/base64.md + - name: base64ToString + href: config/functions/base64ToString.md + - name: bool + href: config/functions/bool.md + - name: cidrHost + href: config/functions/cidrHost.md + - name: cidrSubnet + href: config/functions/cidrSubnet.md + - name: coalesce + href: config/functions/coalesce.md - name: concat href: config/functions/concat.md + - name: contains + href: config/functions/contains.md + - name: context + href: config/functions/context.md + - name: copyIndex + href: config/functions/copyIndex.md - name: createArray href: config/functions/createArray.md + - name: createObject + href: config/functions/createObject.md + - name: dataUri + href: config/functions/dataUri.md + - name: dataUriToString + href: config/functions/dataUriToString.md - name: div href: config/functions/div.md + - name: empty + href: config/functions/empty.md + - name: endsWith + href: config/functions/endsWith.md - name: envvar href: config/functions/envvar.md - name: equals href: config/functions/equals.md + - name: false + href: config/functions/false.md + - name: filter + href: config/functions/filter.md + - name: first + href: config/functions/first.md - name: format href: config/functions/format.md + - name: greater + href: config/functions/greater.md + - name: greaterOrEquals + href: config/functions/greaterOrEquals.md - name: if href: config/functions/if.md + - name: indexOf + href: config/functions/indexOf.md - name: int href: config/functions/int.md + - name: intersection + href: config/functions/intersection.md + - name: items + href: config/functions/items.md + - name: join + href: config/functions/join.md + - name: json + href: config/functions/json.md + - name: lambda + href: config/functions/lambda.md + - name: lambdaVariables + href: config/functions/lambdaVariables.md + - name: last + href: config/functions/last.md + - name: lastIndexOf + href: config/functions/lastIndexOf.md + - name: length + href: config/functions/length.md + - name: less + href: config/functions/less.md + - name: lessOrEquals + href: config/functions/lessOrEquals.md + - name: map + href: config/functions/map.md - name: max href: config/functions/max.md - name: min @@ -69,14 +141,76 @@ items: href: config/functions/mod.md - name: mul href: config/functions/mul.md + - name: not + href: config/functions/not.md + - name: null + href: config/functions/null.md + - name: objectKeys + href: config/functions/objectKeys.md + - name: or + href: config/functions/or.md - name: parameters href: config/functions/parameters.md + - name: parseCidr + href: config/functions/parseCidr.md + - name: path + href: config/functions/path.md + - name: range + href: config/functions/range.md - name: reference href: config/functions/reference.md - name: resourceId href: config/functions/resourceId.md + - name: restartRequired + href: config/functions/restartRequired.md + - name: secret + href: config/functions/secret.md + - name: shallowMerge + href: config/functions/shallowMerge.md + - name: skip + href: config/functions/skip.md + - name: startsWith + href: config/functions/startsWith.md + - name: stateChanged + href: config/functions/stateChanged.md + - name: stdout + href: config/functions/stdout.md + - name: string + href: config/functions/string.md - name: sub href: config/functions/sub.md + - name: substring + href: config/functions/substring.md + - name: systemRoot + href: config/functions/systemRoot.md + - name: take + href: config/functions/take.md + - name: toLower + href: config/functions/toLower.md + - name: toUpper + href: config/functions/toUpper.md + - name: trim + href: config/functions/trim.md + - name: true + href: config/functions/true.md + - name: tryGet + href: config/functions/tryGet.md + - name: tryIndexFromEnd + href: config/functions/tryIndexFromEnd.md + - name: tryWhich + href: config/functions/tryWhich.md + - name: union + href: config/functions/union.md + - name: uniqueString + href: config/functions/uniqueString.md + - name: uri + href: config/functions/uri.md + - name: uriComponent + href: config/functions/uriComponent.md + - name: uriComponentToString + href: config/functions/uriComponentToString.md + - name: utcNow + href: config/functions/utcNow.md - name: variables href: config/functions/variables.md - name: Extension @@ -93,7 +227,7 @@ items: href: extension/stdout/discover.md - name: Resource items: - - name: Manifests + - name: Manifests items: - name: Root href: resource/manifest/root.md @@ -108,7 +242,7 @@ items: - name: set command field href: resource/manifest/set.md - name: whatIf command field - href: resource/manifest/whatIf.md + href: resource/manifest/whatif.md - name: test command field href: resource/manifest/test.md - name: validate command field @@ -133,8 +267,6 @@ items: href: resource/properties/inDesiredState.md - name: _purge href: resource/properties/purge.md - - name: _rebootRequested - href: resource/properties/rebootRequested.md - name: Resource operation stdout schemas items: - name: Overview @@ -167,9 +299,13 @@ items: items: - name: message href: definitions/message.md + - name: resourceCapabilities + href: definitions/resourceCapabilities.md - name: resourceKind href: definitions/resourceKind.md - name: resourceType href: definitions/resourceType.md - name: Parameter dataTypes href: definitions/parameters/dataTypes.md + - name: Function dataTypes + href: definitions/functions/builtin/dataTypes.md From 6a6dd9d7c80c0ea29fa24a8d1db39e69d0c16d94 Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:06:19 +0200 Subject: [PATCH 2/3] Resolve Copilot review feedback - contains: objects are checked by key only; replace the invalid number-as-collection example and re-run it against dsc 3.4.0-preview.1 - dataUri: remove the charset claim; output has no charset parameter - systemRoot: fix 'overriden' and 'Windows system' typos Co-Authored-By: Claude Fable 5 --- .../schemas/config/functions/contains.md | 29 +++++++++++-------- .../schemas/config/functions/dataUri.md | 7 ++--- .../schemas/config/functions/systemRoot.md | 4 +-- 3 files changed, 22 insertions(+), 18 deletions(-) diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/contains.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/contains.md index 50332a31..18689e58 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/contains.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/contains.md @@ -23,11 +23,14 @@ contains(, ) The `contains()` function checks whether a collection (array, object, or string) contains a specific value, returning `true` if it does and `false` otherwise. For arrays, it checks if the value exists as an element. For -objects, it checks if the value exists as a property key or value. For -strings, it checks if the value exists as a substring. +objects, it checks if the value exists as a property key. The function +doesn't check object property values. For strings, it checks if the value +exists as a substring. The function accepts string and number values for the search parameter when -used with arrays, objects, or strings. +used with arrays, objects, or strings. When the search value is a number and +the collection is an object or a string, DSC compares the number by its +string representation. ## Examples @@ -76,10 +79,12 @@ messages: [] hadErrors: false ``` -### Example 2 - Check object for keys and values +### Example 2 - Check object for keys -The following example shows how to check if an object contains specific keys -or values. +The following example shows how to check if an object contains specific keys. +For objects, `contains()` only checks keys, not property values. To check the +contents of a property value, access the property and check it as a string, +like the `cityHasSeattle` output in this example. ```yaml # contains.example.2.dsc.config.yaml @@ -96,10 +101,10 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - hasNameKey: "[contains(parameters('myObject'), 'name')]" - hasEmailKey: "[contains(parameters('myObject'), 'email')]" - hasSeattleValue: "[contains(parameters('myObject').city, 'Seattle')]" - hasAge30Value: "[contains(parameters('myObject').age, 30)]" + hasNameKey: "[contains(parameters('myObject'), 'name')]" + hasEmailKey: "[contains(parameters('myObject'), 'email')]" + hasAgeKey: "[contains(parameters('myObject'), 'age')]" + cityHasSeattle: "[contains(parameters('myObject').city, 'Seattle')]" ``` ```bash @@ -115,8 +120,8 @@ results: output: hasNameKey: true hasEmailKey: false - hasSeattleValue: true - hasAge30Value: true + hasAgeKey: true + cityHasSeattle: true messages: [] hadErrors: false ``` diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUri.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUri.md index 4038eea6..f722f304 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUri.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/dataUri.md @@ -20,8 +20,7 @@ dataUri() ## Description The `dataUri()` function converts a string value to a [data URI][01] format. The function encodes -the input string as base64 and returns it as a data URI with the `application/json` media type and -`utf8` charset. +the input string as base64 and returns it as a data URI with the `application/json` media type. Data URIs are useful for embedding small text content directly in configuration documents, especially when the content needs to be passed through systems that expect URI-formatted data. @@ -179,8 +178,8 @@ MaximumCount: 1 ## Output The `dataUri()` function returns a data URI string in the format -`data:application/json;charset=utf8;base64,` where `` is the -base64 representation of the **stringToConvert** value. +`data:application/json;base64,` where `` is the base64 +representation of the **stringToConvert** value. ```yaml Type: string diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/systemRoot.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/systemRoot.md index e0d5decd..27173635 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/systemRoot.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/systemRoot.md @@ -84,10 +84,10 @@ hadErrors: false ## Output -The `systemRoot()` function returns the system root of the current host, or the value overriden +The `systemRoot()` function returns the system root of the current host, or the value overridden using the [`--system-root` command line flag][01]. -This is usually `C:\` on Windows system and `/` on Unix systems. +This is usually `C:\` on Windows systems and `/` on Unix systems. ```yaml Type: string From 8e5ae2ca2eef0ece61b0c0e7c8aa97c1366f24f5 Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Wed, 2 Sep 2026 15:39:15 +0200 Subject: [PATCH 3/3] Sync file DSC repo --- .../dsc-3.0/reference/schemas/config/functions/json.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/json.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/json.md index bd41a1c2..bf955039 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/json.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/json.md @@ -222,12 +222,13 @@ Returns the parsed JSON value. The type depends on the JSON content: - Null for JSON null ```yaml -Type: object | array | string | number | boolean +Type: object | array | string | number | boolean | null ``` > [!NOTE] -> The declared return types for `json()` don't include null. Parsing the JSON literal `null` -> still returns a null value, so `[json('null')]` evaluates to `null`. +> The function metadata that the `dsc function list` command reports for `json()` doesn't include +> null in the return types. Parsing the JSON literal `null` still returns a null value, so +> `[json('null')]` evaluates to `null`. ## Related functions