From d70b0de47e898c637cb2f540257dbe854e8901c7 Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Wed, 2 Sep 2026 13:35:22 +0200 Subject: [PATCH 1/3] docs: Sync fixes from Microsoft Learn on schema reference --- docs/reference/cli/function/list.md | 144 +- docs/reference/schemas/config/document.md | 318 ++++- .../reference/schemas/config/functions/add.md | 4 +- .../schemas/config/functions/array.md | 4 +- .../config/functions/base64ToString.md | 4 +- .../schemas/config/functions/bool.md | 4 +- .../schemas/config/functions/cidrHost.md | 20 +- .../schemas/config/functions/cidrSubnet.md | 30 +- .../schemas/config/functions/coalesce.md | 4 +- .../schemas/config/functions/concat.md | 5 +- .../schemas/config/functions/copy.md | 51 +- .../schemas/config/functions/createObject.md | 21 +- .../schemas/config/functions/dataUri.md | 6 +- .../config/functions/dataUriToString.md | 5 +- .../reference/schemas/config/functions/div.md | 8 +- .../schemas/config/functions/empty.md | 8 +- .../schemas/config/functions/endsWith.md | 6 +- .../schemas/config/functions/equals.md | 20 +- .../schemas/config/functions/filter.md | 303 +++++ .../schemas/config/functions/greater.md | 7 +- .../config/functions/greaterOrEquals.md | 7 +- docs/reference/schemas/config/functions/if.md | 28 +- .../schemas/config/functions/indexOf.md | 7 +- .../schemas/config/functions/intersection.md | 35 +- .../schemas/config/functions/items.md | 4 +- .../schemas/config/functions/join.md | 19 +- .../schemas/config/functions/json.md | 15 +- .../schemas/config/functions/lambda.md | 280 ++++ .../config/functions/lambdaVariables.md | 240 ++++ .../schemas/config/functions/last.md | 4 +- .../schemas/config/functions/lastIndexOf.md | 20 +- .../schemas/config/functions/length.md | 8 +- .../schemas/config/functions/less.md | 7 +- .../schemas/config/functions/lessOrEquals.md | 4 +- .../reference/schemas/config/functions/map.md | 313 +++++ .../reference/schemas/config/functions/mul.md | 16 +- .../schemas/config/functions/null.md | 5 +- .../schemas/config/functions/objectKeys.md | 11 +- .../schemas/config/functions/overview.md | 224 ++-- .../schemas/config/functions/parameters.md | 11 +- .../schemas/config/functions/parseCidr.md | 6 +- .../schemas/config/functions/path.md | 20 +- .../schemas/config/functions/range.md | 4 +- .../schemas/config/functions/reference.md | 14 +- .../schemas/config/functions/resourceId.md | 18 +- .../schemas/config/functions/shallowMerge.md | 168 +-- .../schemas/config/functions/skip.md | 4 +- .../schemas/config/functions/startsWith.md | 6 +- .../schemas/config/functions/stateChanged.md | 6 +- .../schemas/config/functions/stdout.md | 179 +++ .../schemas/config/functions/string.md | 19 +- .../reference/schemas/config/functions/sub.md | 6 +- .../schemas/config/functions/systemRoot.md | 6 +- .../schemas/config/functions/take.md | 7 +- .../schemas/config/functions/toLower.md | 9 +- .../schemas/config/functions/toUpper.md | 10 +- .../schemas/config/functions/tryGet.md | 29 +- .../config/functions/tryIndexFromEnd.md | 17 +- .../schemas/config/functions/tryWhich.md | 21 +- .../schemas/config/functions/union.md | 14 +- .../schemas/config/functions/uniqueString.md | 8 +- .../reference/schemas/config/functions/uri.md | 6 +- .../schemas/config/functions/uriComponent.md | 6 +- .../config/functions/uriComponentToString.md | 31 +- docs/reference/schemas/config/metadata.md | 37 +- docs/reference/schemas/config/parameter.md | 8 +- docs/reference/schemas/config/resource.md | 270 +++- .../functions/builtin/dataTypes.md | 35 +- docs/reference/schemas/definitions/message.md | 9 +- .../definitions/parameters/dataTypes.md | 15 +- .../definitions/resourceCapabilities.md | 63 +- .../schemas/definitions/resourceKind.md | 51 +- .../schemas/definitions/resourceType.md | 49 +- .../schemas/extension/manifest/discover.md | 98 +- .../schemas/extension/manifest/root.md | 236 +++- .../schemas/extension/stdout/discover.md | 64 +- .../metadata/Microsoft.DSC/properties.md | 95 +- docs/reference/schemas/outputs/config/get.md | 116 +- docs/reference/schemas/outputs/config/set.md | 120 +- docs/reference/schemas/outputs/config/test.md | 122 +- .../schemas/outputs/extension/list.md | 70 +- .../schemas/outputs/function/list.md | 156 ++- .../reference/schemas/outputs/resource/get.md | 43 +- .../schemas/outputs/resource/list.md | 170 ++- .../reference/schemas/outputs/resource/set.md | 53 +- .../schemas/outputs/resource/test.md | 50 +- docs/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 | 344 +++-- .../resource/manifest/schema/embedded.md | 9 +- .../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 | 4 +- .../resource/properties/inDesiredState.md | 5 +- .../schemas/resource/properties/overview.md | 23 +- .../schemas/resource/properties/purge.md | 4 +- .../schemas/resource/stdout/delete.md | 80 +- .../reference/schemas/resource/stdout/list.md | 177 ++- docs/reference/schemas/resource/stdout/set.md | 12 +- .../reference/schemas/resource/stdout/test.md | 18 +- .../schemas/resource/stdout/whatIf.md | 79 +- docs/reference/schemas/schema-uris.md | 1190 ++++++++++++++--- 110 files changed, 7064 insertions(+), 1698 deletions(-) create mode 100644 docs/reference/schemas/config/functions/filter.md create mode 100644 docs/reference/schemas/config/functions/lambda.md create mode 100644 docs/reference/schemas/config/functions/lambdaVariables.md create mode 100644 docs/reference/schemas/config/functions/map.md create mode 100644 docs/reference/schemas/config/functions/stdout.md diff --git a/docs/reference/cli/function/list.md b/docs/reference/cli/function/list.md index 6e62fec3e..16ff5ba3f 100644 --- a/docs/reference/cli/function/list.md +++ b/docs/reference/cli/function/list.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc function list' command -ms.date: 07/20/2025 +ms.date: 09/01/2026 ms.topic: reference title: dsc function list --- @@ -49,16 +49,16 @@ dsc function list ``` ```output -Category Function MinArgs MaxArgs ReturnTypes Description ---------------------------------------------------------------------------------------------------- -Array array 1 1 a----- Convert the value to a… -Array createArray 0 maxInt a----- Creates an array from … -Array range 2 2 a----- Creates an array of in… -Array tryIndexFromEnd 2 2 ab-nso Retrieves a value from -Array, Lambda filter 2 2 a----- Filters an array with … -Array, Lambda map 2 2 a----- Transforms an array by -Array, Object intersection 2 maxInt a----o Returns a single array -Array, Object tryGet 2 2 ab-nso Attempts to retrieve a +Category Function Syntax Description +----------------------------------------------------------------------------------------- +Array array array( , ) 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( , , ) Constructs a resource ID from the gi… ``` ### Example 3 - Get details for a specific function @@ -90,23 +90,63 @@ dsc function list concat --output-format yaml ```yaml category: -- Array -- String +- array +- string name: concat description: Concatenates two or more strings or arrays +syntax: concat( , , ... ) +constraints: All arguments must be of the same type (all strings or all arrays) minArgs: 2 maxArgs: 18446744073709551615 acceptedArgOrderedTypes: -- - String - - Array -- - String - - Array +- - string + - array +- - string + - array remainingArgAcceptedTypes: -- String -- Array +- string +- array returnTypes: -- String -- Array +- string +- array +``` + +### Example 4 - Filter functions by category + + + +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 @@ -125,6 +165,39 @@ 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 @@ -183,29 +256,18 @@ ShortSyntax : -h ## Output -This command returns a formatted array containing an object for each function that includes the -function's type, version, manifest settings, and other metadata. For more information, see -[dsc function list result schema reference][03]. +This command returns an object for each function that includes the function's name, categories, +syntax, argument metadata, and return types. For more information, see +[dsc function list result schema reference][03]. For more information about the [data types][04] +used in the argument and return type metadata, see the linked schema reference. If the output of the command isn't captured or redirected, it displays in the console by default as a summary table for the returned functions. The summary table includes the following columns, displayed in the listed order: -- **Category** - The category the function belongs to. +- **Category** - The categories the function belongs to. - **Function** - The name of the function. -- **MinArgs** - The minimum number of arguments the function accepts. -- **MaxArgs** - The maximum number of arguments the function accepts. -- **ReturnTypes** - The [data types][04] the function emits as flags. The valid return types are - displayed in the following order, using a `-` instead of the appropriate letter if the function - doesn't return that data type: - - - `a` indicates that the function returns an array value. - - `b` indicates that the function returns a boolean value. - - `l` indicates that the function returns a lambda value. - - `n` indicates that the function returns a number value. - - `s` indicates that the function returns a string value. - - `o` indicates that the function returns an object value. - +- **Syntax** - The syntax for calling the function, showing its expected arguments. - **Description** - A synopsis of what the function does. For more information about the formatting of the output data, see the diff --git a/docs/reference/schemas/config/document.md b/docs/reference/schemas/config/document.md index 622054720..4ceb997bf 100644 --- a/docs/reference/schemas/config/document.md +++ b/docs/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 --- @@ -93,7 +93,7 @@ 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 Visual Studio Code. While DSC can still validate the + 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. ```yaml @@ -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 @@ -168,15 +413,33 @@ Parameters may be overridden at runtime, enabling re-use of the same configurati 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 @@ -190,37 +453,24 @@ which makes the document easier to read and maintain. Unlike parameters, variabl 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/docs/reference/schemas/config/functions/add.md b/docs/reference/schemas/config/functions/add.md index ddf0c4c1b..ee08f2c27 100644 --- a/docs/reference/schemas/config/functions/add.md +++ b/docs/reference/schemas/config/functions/add.md @@ -1,6 +1,6 @@ --- description: Reference for the 'add' DSC configuration document function -ms.date: 02/28/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/docs/reference/schemas/config/functions/array.md b/docs/reference/schemas/config/functions/array.md index 87839626f..7150eaf6c 100644 --- a/docs/reference/schemas/config/functions/array.md +++ b/docs/reference/schemas/config/functions/array.md @@ -1,6 +1,6 @@ --- description: Reference for the 'array' DSC configuration document function -ms.date: 08/12/2025 +ms.date: 09/01/2026 ms.topic: reference title: array --- @@ -153,7 +153,7 @@ The single value to wrap in the array. ```yaml Type: string, number, array, or object -Required: false +Required: true MinimumCount: 1 MaximumCount: 1 ``` diff --git a/docs/reference/schemas/config/functions/base64ToString.md b/docs/reference/schemas/config/functions/base64ToString.md index 2f5c02731..002b6991c 100644 --- a/docs/reference/schemas/config/functions/base64ToString.md +++ b/docs/reference/schemas/config/functions/base64ToString.md @@ -1,6 +1,6 @@ --- description: Reference for the 'base64ToString' DSC configuration document function -ms.date: 09/30/2025 +ms.date: 09/01/2026 ms.topic: reference title: base64ToString --- @@ -70,7 +70,7 @@ resources: ``` ```bash -dsc config get --file base64ToString.example.2.dsc.config.yaml +dsc config get --file base64ToString.example.2.dsc.config.yaml ``` ```yaml diff --git a/docs/reference/schemas/config/functions/bool.md b/docs/reference/schemas/config/functions/bool.md index b1ac488ce..67b892599 100644 --- a/docs/reference/schemas/config/functions/bool.md +++ b/docs/reference/schemas/config/functions/bool.md @@ -1,6 +1,6 @@ --- description: Reference for the 'bool' DSC configuration document function -ms.date: 01/19/2025 +ms.date: 09/01/2026 ms.topic: reference title: bool --- @@ -112,10 +112,12 @@ hadErrors: false 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` diff --git a/docs/reference/schemas/config/functions/cidrHost.md b/docs/reference/schemas/config/functions/cidrHost.md index 0de44842d..e74ae4e70 100644 --- a/docs/reference/schemas/config/functions/cidrHost.md +++ b/docs/reference/schemas/config/functions/cidrHost.md @@ -1,6 +1,6 @@ --- description: Reference for the 'cidrHost' DSC configuration document function -ms.date: 11/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: cidrHost --- @@ -83,9 +83,15 @@ resources: 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)]" + 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 @@ -100,9 +106,9 @@ results: actualState: output: subnet: 172.16.10.0/24 - webServer1: 172.16.10.10 - webServer2: 172.16.10.11 - webServer3: 172.16.10.12 + webServer1: 172.16.10.11 + webServer2: 172.16.10.12 + webServer3: 172.16.10.13 messages: [] hadErrors: false ``` diff --git a/docs/reference/schemas/config/functions/cidrSubnet.md b/docs/reference/schemas/config/functions/cidrSubnet.md index bf4ac7e74..82da1fd7d 100644 --- a/docs/reference/schemas/config/functions/cidrSubnet.md +++ b/docs/reference/schemas/config/functions/cidrSubnet.md @@ -1,6 +1,6 @@ --- description: Reference for the 'cidrSubnet' DSC configuration document function -ms.date: 11/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: cidrSubnet --- @@ -96,7 +96,8 @@ resources: 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)]" + southeastasia: >- + [cidrSubnet(parameters('baseNetwork'), parameters('newPrefix'), 4)] ``` ```bash @@ -142,9 +143,15 @@ resources: 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)]" + 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 @@ -167,8 +174,8 @@ results: firstUsable: 172.16.42.1 lastUsable: 172.16.42.254 cidr: 24 - gatewayIP: 172.16.42.1 - loadBalancerIP: 172.16.42.4 + gatewayIP: 172.16.42.2 + loadBalancerIP: 172.16.42.5 messages: [] hadErrors: false ``` @@ -194,9 +201,12 @@ resources: 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)]" + subnet0: >- + [cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 0)] + subnet1: >- + [cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 1)] + subnet10: >- + [cidrSubnet(parameters('ipv6BaseNetwork'), parameters('subnetPrefix'), 10)] ``` ```bash diff --git a/docs/reference/schemas/config/functions/coalesce.md b/docs/reference/schemas/config/functions/coalesce.md index ce2f00016..d3dae8385 100644 --- a/docs/reference/schemas/config/functions/coalesce.md +++ b/docs/reference/schemas/config/functions/coalesce.md @@ -1,6 +1,6 @@ --- description: Reference for the 'coalesce' DSC configuration document function -ms.date: 07/24/2025 +ms.date: 09/01/2026 ms.topic: reference title: coalesce --- @@ -38,7 +38,7 @@ resources: - name: Coalesce strings type: Microsoft.DSC.Debug/Echo properties: - output: + output: firstNonNull: "[coalesce(null(), 'DSC', 'landscape')]" allNull: "[coalesce(null(), null(), null())]" noneNull: "[coalesce('first', 'second', 'third')]" diff --git a/docs/reference/schemas/config/functions/concat.md b/docs/reference/schemas/config/functions/concat.md index c54ec1e64..cd9347979 100644 --- a/docs/reference/schemas/config/functions/concat.md +++ b/docs/reference/schemas/config/functions/concat.md @@ -1,6 +1,6 @@ --- description: Reference for the 'concat' DSC configuration document function -ms.date: 02/28/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/docs/reference/schemas/config/functions/copy.md b/docs/reference/schemas/config/functions/copy.md index 1c1312ecb..e1f4c3cac 100644 --- a/docs/reference/schemas/config/functions/copy.md +++ b/docs/reference/schemas/config/functions/copy.md @@ -1,6 +1,6 @@ --- description: Reference for the 'copy' DSC configuration document resource loop -ms.date: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: copy --- @@ -23,8 +23,16 @@ copy: 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, but without support -for variables and properties, which will be added in future releases. +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] @@ -186,27 +194,32 @@ resources: ``` ```bash -dsc config get --file copy.example.4.dsc.config.yaml --parameters '{"instanceCount": 4}' +params='{"parameters": {"instanceCount": 4}}' +dsc config --parameters "$params" get --file copy.example.4.dsc.config.yaml ``` ```yaml results: -- metadata: - Microsoft.DSC: - duration: PT0.2173106S - name: Dynamic-0 +- 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 0 of 2 -- metadata: - Microsoft.DSC: - duration: PT0.0161486S - name: Dynamic-1 + output: Instance 2 of 4 +- name: Dynamic-3 type: Microsoft.DSC.Debug/Echo result: actualState: - output: Instance 1 of 2 + output: Instance 3 of 4 messages: [] hadErrors: false ``` @@ -261,13 +274,16 @@ resources to create in each batch when using parallel mode. The current implementation has the following limitations: -- **Variables and properties**: Copy loops for variables and properties are not - yet supported. +- **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 +## Related functions - [`copyIndex()`][01] - Returns the current iteration index of a copy loop. - [`parameters()`][02] - Returns the value of a configuration parameter. @@ -275,3 +291,4 @@ The current implementation has the following limitations: [01]: ./copyIndex.md [02]: ./parameters.md +[03]: https://github.com/PowerShell/DSC/issues/1429 diff --git a/docs/reference/schemas/config/functions/createObject.md b/docs/reference/schemas/config/functions/createObject.md index 5ee3bae92..2a59ed7f4 100644 --- a/docs/reference/schemas/config/functions/createObject.md +++ b/docs/reference/schemas/config/functions/createObject.md @@ -1,10 +1,12 @@ --- description: Reference for the 'createObject' DSC configuration document function -ms.date: 07/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: createObject --- +# createObject + ## Synopsis Creates a JSON object from key-value pairs. @@ -75,7 +77,9 @@ resources: - name: Mixed data types type: Microsoft.DSC.Debug/Echo properties: - output: "[createObject('string', 'hello', 'number', 123, 'boolean', true, 'nullValue', null())]" + output: >- + [createObject('string', 'hello', 'number', 123, 'boolean', true, + 'nullValue', null())] ``` ```bash @@ -109,7 +113,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - nestedObject: "[createObject('config', createObject('timeout', 30, 'enabled', true))]" + nestedObject: >- + [createObject('config', createObject('timeout', 30, 'enabled', true))] objectWithArray: "[createObject('items', createArray('foo', 'bar', 'baz'))]" ``` @@ -153,8 +158,11 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - userConfig: "[createObject('user', parameters('userName'), 'role', coalesce(null(), 'default'))]" - fallbackObject: "[createObject('result', coalesce(null(), createObject('status', 'success')))]" + userConfig: >- + [createObject('user', parameters('userName'), 'role', + coalesce(null(), 'default'))] + fallbackObject: >- + [createObject('result', coalesce(null(), createObject('status', 'success')))] ``` ```bash @@ -203,7 +211,8 @@ 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. +The object property value. Can be any valid JSON type including strings, numbers, booleans, null, +arrays, or other objects. ```yaml Type: [any] diff --git a/docs/reference/schemas/config/functions/dataUri.md b/docs/reference/schemas/config/functions/dataUri.md index 27ce3b44c..4038eea60 100644 --- a/docs/reference/schemas/config/functions/dataUri.md +++ b/docs/reference/schemas/config/functions/dataUri.md @@ -1,6 +1,6 @@ --- description: Reference for the 'dataUri' DSC configuration document function -ms.date: 12/20/2025 +ms.date: 09/01/2026 ms.topic: reference title: dataUri --- @@ -179,8 +179,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;charset=utf8;base64,` where `` is the +base64 representation of the **stringToConvert** value. ```yaml Type: string diff --git a/docs/reference/schemas/config/functions/dataUriToString.md b/docs/reference/schemas/config/functions/dataUriToString.md index 9885fcb0a..0b87ec8f2 100644 --- a/docs/reference/schemas/config/functions/dataUriToString.md +++ b/docs/reference/schemas/config/functions/dataUriToString.md @@ -1,6 +1,6 @@ --- description: Reference for the 'dataUriToString' DSC configuration document function -ms.date: 12/20/2025 +ms.date: 09/01/2026 ms.topic: reference title: dataUriToString --- @@ -39,7 +39,8 @@ $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json parameters: encodedScript: type: string - defaultValue: "data:text/plain;charset=utf8;base64,V3JpdGUtSG9zdCAnSGVsbG8sIFdvcmxkISc=" + defaultValue: "data:text/plain;charset=utf8;base64,\ + V3JpdGUtSG9zdCAnSGVsbG8sIFdvcmxkISc=" resources: - name: Decode and display script type: Microsoft.DSC.Debug/Echo diff --git a/docs/reference/schemas/config/functions/div.md b/docs/reference/schemas/config/functions/div.md index 110d5e65d..ca3ce9eac 100644 --- a/docs/reference/schemas/config/functions/div.md +++ b/docs/reference/schemas/config/functions/div.md @@ -1,6 +1,6 @@ --- description: Reference for the 'div' DSC configuration document function -ms.date: 02/28/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/docs/reference/schemas/config/functions/empty.md b/docs/reference/schemas/config/functions/empty.md index 90fc2a200..6b8199bd2 100644 --- a/docs/reference/schemas/config/functions/empty.md +++ b/docs/reference/schemas/config/functions/empty.md @@ -1,6 +1,6 @@ --- description: Reference for the 'empty' DSC configuration document function -ms.date: 08/08/2025 +ms.date: 09/01/2026 ms.topic: reference title: empty --- @@ -170,7 +170,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - message: "[if(empty(parameters('serverList')), 'No servers to configure', concat('Configuring ', string(length(parameters('serverList'))), ' servers'))]" + message: >- + [if(empty(parameters('serverList')), 'No servers to configure', + concat('Configuring ', string(length(parameters('serverList'))), ' servers'))] ``` ```bash @@ -184,7 +186,7 @@ results: result: actualState: output: - message: "No servers to configure" + message: No servers to configure messages: [] hadErrors: false ``` diff --git a/docs/reference/schemas/config/functions/endsWith.md b/docs/reference/schemas/config/functions/endsWith.md index 2cafddfae..bcccca96e 100644 --- a/docs/reference/schemas/config/functions/endsWith.md +++ b/docs/reference/schemas/config/functions/endsWith.md @@ -1,6 +1,6 @@ --- description: Reference for the 'endsWith' DSC configuration document function -ms.date: 08/12/2025 +ms.date: 09/01/2026 ms.topic: reference title: endsWith --- @@ -78,7 +78,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - classification: "[if(endsWith(parameters('environment'), '-prod'), 'Production', 'Non-production')]" + classification: >- + [if(endsWith(parameters('environment'), '-prod'), 'Production', + 'Non-production')] ``` ```bash diff --git a/docs/reference/schemas/config/functions/equals.md b/docs/reference/schemas/config/functions/equals.md index 7dad419b9..1b27a06ee 100644 --- a/docs/reference/schemas/config/functions/equals.md +++ b/docs/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/docs/reference/schemas/config/functions/filter.md b/docs/reference/schemas/config/functions/filter.md new file mode 100644 index 000000000..7329fe016 --- /dev/null +++ b/docs/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/docs/reference/schemas/config/functions/greater.md b/docs/reference/schemas/config/functions/greater.md index 6b050fd96..e84a2a9c7 100644 --- a/docs/reference/schemas/config/functions/greater.md +++ b/docs/reference/schemas/config/functions/greater.md @@ -1,6 +1,6 @@ --- description: Reference for the 'greater' DSC configuration document function -ms.date: 07/24/2025 +ms.date: 09/01/2026 ms.topic: reference title: greater --- @@ -24,7 +24,8 @@ returning `true` if it is and otherwise `false`. You can use this function to co 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. +For strings, the comparison is case-sensitive and uses lexicographic ordering based on character +codes. ## Examples @@ -39,7 +40,7 @@ resources: - name: Compare numbers type: Microsoft.DSC.Debug/Echo properties: - output: + output: firstGreater: "[greater(5, 3)]" secondGreater: "[greater(3, 5)]" equalNumbers: "[greater(5, 5)]" diff --git a/docs/reference/schemas/config/functions/greaterOrEquals.md b/docs/reference/schemas/config/functions/greaterOrEquals.md index d6e970ba8..5072e0259 100644 --- a/docs/reference/schemas/config/functions/greaterOrEquals.md +++ b/docs/reference/schemas/config/functions/greaterOrEquals.md @@ -1,6 +1,6 @@ --- description: Reference for the 'greaterOrEquals' DSC configuration document function -ms.date: 07/24/2025 +ms.date: 09/01/2026 ms.topic: reference title: greaterOrEquals --- @@ -24,7 +24,8 @@ than or equal to the second value, returning `true` if it is and otherwise `fals 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. +For strings, the comparison is case-sensitive and uses lexicographic ordering based on character +codes. ## Examples @@ -39,7 +40,7 @@ resources: - name: Compare numbers type: Microsoft.DSC.Debug/Echo properties: - output: + output: firstGreater: "[greaterOrEquals(5, 3)]" secondGreater: "[greaterOrEquals(3, 5)]" equalNumbers: "[greaterOrEquals(5, 5)]" diff --git a/docs/reference/schemas/config/functions/if.md b/docs/reference/schemas/config/functions/if.md index faf1dd7cf..71f13e345 100644 --- a/docs/reference/schemas/config/functions/if.md +++ b/docs/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/docs/reference/schemas/config/functions/indexOf.md b/docs/reference/schemas/config/functions/indexOf.md index 76a9adb2c..95fbf5f9e 100644 --- a/docs/reference/schemas/config/functions/indexOf.md +++ b/docs/reference/schemas/config/functions/indexOf.md @@ -1,6 +1,6 @@ --- description: Reference for the 'indexOf' DSC configuration document function -ms.date: 08/12/2025 +ms.date: 09/01/2026 ms.topic: reference title: indexOf --- @@ -27,7 +27,7 @@ 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 +- **Numbers**: Numeric equality comparison - **Arrays**: Deep equality (same length, order, and element values) - **Objects**: Deep equality (same keys, values, and structure) @@ -94,7 +94,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - hasFeature: "[indexOf(array(createObject('name','Beta')), createObject('name','Beta'))]" + hasFeature: >- + [indexOf(array(createObject('name','Beta')), createObject('name','Beta'))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/intersection.md b/docs/reference/schemas/config/functions/intersection.md index 5e2066772..5aeb1dad8 100644 --- a/docs/reference/schemas/config/functions/intersection.md +++ b/docs/reference/schemas/config/functions/intersection.md @@ -1,10 +1,12 @@ --- description: Reference for the 'intersection' DSC configuration document function -ms.date: 09/26/2025 +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. @@ -47,8 +49,13 @@ resources: 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'))]" + 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 @@ -86,7 +93,10 @@ resources: 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'))]" + 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 @@ -101,8 +111,8 @@ results: actualState: output: commonSettings: - region: us-east retries: 3 + region: us-east messages: [] hadErrors: false ``` @@ -121,8 +131,12 @@ resources: 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'))]" + noOverlap: >- + [intersection(createArray('windows-iis', 'dotnet-core'), + createArray('linux-apache', 'php', 'mysql'))] + someOverlap: >- + [intersection(createArray('docker', 'kubernetes', 'monitoring'), + createArray('monitoring', 'logging', 'docker'))] ``` ```bash @@ -158,7 +172,10 @@ resources: 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'))]" + sharedCompliance: >- + [intersection(createObject('encryption', true, 'backup', 'daily', 'audit', true), + createObject('audit', true, 'encryption', true, 'access', 'restricted'), + createObject('encryption', true, 'audit', true, 'monitoring', 'enabled'))] ``` ```bash @@ -173,8 +190,8 @@ results: actualState: output: sharedCompliance: - audit: true encryption: true + audit: true messages: [] hadErrors: false ``` diff --git a/docs/reference/schemas/config/functions/items.md b/docs/reference/schemas/config/functions/items.md index 3eabd1544..da3d0b735 100644 --- a/docs/reference/schemas/config/functions/items.md +++ b/docs/reference/schemas/config/functions/items.md @@ -1,10 +1,12 @@ --- description: Reference for the 'items' DSC configuration document function -ms.date: 10/11/2025 +ms.date: 09/01/2026 ms.topic: reference title: items --- +# items + ## Synopsis Converts a dictionary object to an array of key-value pairs. diff --git a/docs/reference/schemas/config/functions/join.md b/docs/reference/schemas/config/functions/join.md index 51b96042b..3a84716e2 100644 --- a/docs/reference/schemas/config/functions/join.md +++ b/docs/reference/schemas/config/functions/join.md @@ -1,10 +1,12 @@ --- description: Reference for the 'join' DSC configuration document function -ms.date: 08/29/2025 +ms.date: 09/01/2026 ms.topic: reference title: join --- +# join + ## Synopsis Joins an array into a single string, separated using a delimiter. @@ -12,17 +14,18 @@ Joins an array into a single string, separated using a delimiter. ## Syntax ```Syntax -join(inputArray, delimiter) +join(, ) ``` ## Description The `join()` function takes an array and a delimiter. -- Each array element is converted to a string and concatenated with the - delimiter between elements. +- 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` can be any value; it’s converted to a string. +The `delimiter` must be a string. ## Examples @@ -89,7 +92,7 @@ hadErrors: false ### Example 3 - Format a version string from numeric parts -Convert version components (numbers) into a dotted version string. Non-string +Convert version components (numbers) into a dotted version string. Number elements are converted to strings automatically. ```yaml @@ -131,10 +134,10 @@ Position: 1 ### delimiter -Any value used between elements. Converted to a string. +The string to insert between elements. DSC raises an error when the delimiter isn't a string. ```yaml -Type: any +Type: string Required: true Position: 2 ``` diff --git a/docs/reference/schemas/config/functions/json.md b/docs/reference/schemas/config/functions/json.md index 98bbfdcd4..bd41a1c21 100644 --- a/docs/reference/schemas/config/functions/json.md +++ b/docs/reference/schemas/config/functions/json.md @@ -1,10 +1,12 @@ --- description: Reference for the 'json' DSC configuration document function -ms.date: 10/11/2025 +ms.date: 09/01/2026 ms.topic: reference title: json --- +# json + ## Synopsis Converts a valid JSON string into a JSON data type. @@ -12,7 +14,7 @@ Converts a valid JSON string into a JSON data type. ## Syntax ```Syntax -json(arg1) +json() ``` ## Description @@ -100,7 +102,8 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: "[json('{\"users\":[{\"name\":\"Alice\"},{\"name\":\"Bob\"}]}').users[0].name]" + output: >- + [json('{"users":[{"name":"Alice"},{"name":"Bob"}]}').users[0].name] ``` ```bash @@ -219,9 +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 | null +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 diff --git a/docs/reference/schemas/config/functions/lambda.md b/docs/reference/schemas/config/functions/lambda.md new file mode 100644 index 000000000..400d68831 --- /dev/null +++ b/docs/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/docs/reference/schemas/config/functions/lambdaVariables.md b/docs/reference/schemas/config/functions/lambdaVariables.md new file mode 100644 index 000000000..8763ad158 --- /dev/null +++ b/docs/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/docs/reference/schemas/config/functions/last.md b/docs/reference/schemas/config/functions/last.md index 595e8ede9..5989505b5 100644 --- a/docs/reference/schemas/config/functions/last.md +++ b/docs/reference/schemas/config/functions/last.md @@ -1,10 +1,12 @@ --- description: Reference for the 'last' DSC configuration document function -ms.date: 01/25/2025 +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. diff --git a/docs/reference/schemas/config/functions/lastIndexOf.md b/docs/reference/schemas/config/functions/lastIndexOf.md index 666c88c70..407efc52f 100644 --- a/docs/reference/schemas/config/functions/lastIndexOf.md +++ b/docs/reference/schemas/config/functions/lastIndexOf.md @@ -1,10 +1,12 @@ --- description: Reference for the 'lastIndexOf' DSC configuration document function -ms.date: 08/29/2025 +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. @@ -47,8 +49,10 @@ resources: 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')]" + lastWebIndex: >- + [lastIndexOf(createArray('web01','db01','web02','cache01','web03'), 'web03')] + lastWebFamilyIndex: >- + [lastIndexOf(createArray('web01','db01','web02','cache01','web02'), 'web02')] ``` ```bash @@ -86,7 +90,10 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - lastBetaIndex: "[lastIndexOf(createArray(createObject('name','Beta'), createObject('name','Gamma'), createObject('name','Beta')), createObject('name','Beta'))]" + lastBetaIndex: >- + [lastIndexOf(createArray(createObject('name','Beta'), + createObject('name','Gamma'), createObject('name','Beta')), + createObject('name','Beta'))] ``` ```bash @@ -105,8 +112,9 @@ 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))`. +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 diff --git a/docs/reference/schemas/config/functions/length.md b/docs/reference/schemas/config/functions/length.md index fee7f77c2..3b33c608a 100644 --- a/docs/reference/schemas/config/functions/length.md +++ b/docs/reference/schemas/config/functions/length.md @@ -1,6 +1,6 @@ --- description: Reference for the 'length' DSC configuration document function -ms.date: 08/08/2025 +ms.date: 09/01/2026 ms.topic: reference title: length --- @@ -136,7 +136,9 @@ parameters: defaultValue: "Hello DSC!" longText: type: string - defaultValue: "This is a longer string with more characters to demonstrate length calculation." + defaultValue: >- + This is a longer string with more characters to demonstrate length + calculation. resources: - name: Check string lengths type: Microsoft.DSC.Debug/Echo @@ -160,7 +162,7 @@ results: actualState: output: messageLength: 10 - longTextLength: 78 + longTextLength: 79 emptyStringLength: 0 literalLength: 3 messages: [] diff --git a/docs/reference/schemas/config/functions/less.md b/docs/reference/schemas/config/functions/less.md index 8c04bab85..7acc871f6 100644 --- a/docs/reference/schemas/config/functions/less.md +++ b/docs/reference/schemas/config/functions/less.md @@ -1,6 +1,6 @@ --- description: Reference for the 'less' DSC configuration document function -ms.date: 07/24/2025 +ms.date: 09/01/2026 ms.topic: reference title: less --- @@ -24,7 +24,8 @@ returning `true` if it is and otherwise `false`. You can use this function to co 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. +For strings, the comparison is case-sensitive and uses lexicographic ordering based on character +codes. ## Examples @@ -39,7 +40,7 @@ resources: - name: Compare numbers type: Microsoft.DSC.Debug/Echo properties: - output: + output: firstLess: "[less(3, 5)]" secondLess: "[less(5, 3)]" equalNumbers: "[less(5, 5)]" diff --git a/docs/reference/schemas/config/functions/lessOrEquals.md b/docs/reference/schemas/config/functions/lessOrEquals.md index 96a444c70..1e65cbe3d 100644 --- a/docs/reference/schemas/config/functions/lessOrEquals.md +++ b/docs/reference/schemas/config/functions/lessOrEquals.md @@ -1,6 +1,6 @@ --- description: Reference for the 'lessOrEquals' DSC configuration document function -ms.date: 07/24/2025 +ms.date: 09/01/2026 ms.topic: reference title: lessOrEquals --- @@ -41,7 +41,7 @@ resources: - name: Compare numbers type: Microsoft.DSC.Debug/Echo properties: - output: + output: firstLess: "[lessOrEquals(3, 5)]" secondLess: "[lessOrEquals(5, 3)]" equalNumbers: "[lessOrEquals(5, 5)]" diff --git a/docs/reference/schemas/config/functions/map.md b/docs/reference/schemas/config/functions/map.md new file mode 100644 index 000000000..ca240e3e3 --- /dev/null +++ b/docs/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/docs/reference/schemas/config/functions/mul.md b/docs/reference/schemas/config/functions/mul.md index 68e7ad280..aeb36c392 100644 --- a/docs/reference/schemas/config/functions/mul.md +++ b/docs/reference/schemas/config/functions/mul.md @@ -1,6 +1,6 @@ --- description: Reference for the 'mul' DSC configuration document function -ms.date: 02/28/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/docs/reference/schemas/config/functions/null.md b/docs/reference/schemas/config/functions/null.md index 5de697414..9b1ffee50 100644 --- a/docs/reference/schemas/config/functions/null.md +++ b/docs/reference/schemas/config/functions/null.md @@ -1,6 +1,6 @@ --- description: Reference for the 'null' DSC configuration document function -ms.date: 07/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: null --- @@ -136,7 +136,8 @@ Type: null - 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. +- 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 diff --git a/docs/reference/schemas/config/functions/objectKeys.md b/docs/reference/schemas/config/functions/objectKeys.md index 6f3e4e5c0..bf516d696 100644 --- a/docs/reference/schemas/config/functions/objectKeys.md +++ b/docs/reference/schemas/config/functions/objectKeys.md @@ -1,10 +1,12 @@ --- description: Reference for the 'objectKeys' DSC configuration document function -ms.date: 11/14/2025 +ms.date: 09/01/2026 ms.topic: reference title: objectKeys --- +# objectKeys + ## Synopsis Returns an array containing all the keys from an object. @@ -44,7 +46,8 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: "[objectKeys(createObject('firstName', 'John', 'lastName', 'Doe', 'age', 30))]" + output: >- + [objectKeys(createObject('firstName', 'John', 'lastName', 'Doe', 'age', 30))] ``` ```bash @@ -197,7 +200,9 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: "[objectKeys(createObject('user', createObject('name', 'John', 'age', 30), 'role', 'admin'))]" + output: >- + [objectKeys(createObject('user', createObject('name', 'John', 'age', 30), + 'role', 'admin'))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/overview.md b/docs/reference/schemas/config/functions/overview.md index 305e0b85e..d0d9b6ac0 100644 --- a/docs/reference/schemas/config/functions/overview.md +++ b/docs/reference/schemas/config/functions/overview.md @@ -1,6 +1,6 @@ --- description: Reference for available functions in a Desired State Configuration document. -ms.date: 02/28/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,135 +541,184 @@ 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 and collection functions +### Array functions -The following list of functions operate on arrays and collections: +The following functions operate on arrays: - [array()][array] - Convert a value into an array containing that value. -- [concat()][concat] - Combine multiple arrays of strings into a single array of strings. +- [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. - [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. -- [items()][items] - Convert an object into an array of key-value pair objects. -- [join()][join] - Combine array elements into a single string with a specified delimiter. +- [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. -- [max()][max] - Return the largest integer value from an array of integers. -- [min()][min] - Return the smallest integer value from an array of integers. +- [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. +- [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 list of functions compare values: +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. +- [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. +- [lessOrEquals()][lessOrEquals] - Check if the first value is less than or equal to the second + value. + +### Date functions -### Data functions +The following functions work with dates and times: -The following list of functions operate on data outside of a resource instance: +- [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. -- [envvar()][envvar] - Return the value of a specified environment variable. - [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. +### Lambda functions + +The following functions create and use lambda functions, which DSC evaluates once for each element +of an array: + +- [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 -The following list of functions perform logical operations: +The following functions perform logical operations: - [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. -- [null()][null] - Return a null value. - [or()][or] - Return true if any boolean value is true. - [true()][true] - Return the boolean value true. -### Mathematics functions +### Numeric functions -The following list of functions operate on integer values or arrays of integer values: +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 list of functions operate on objects: +The following functions operate on objects: -- [coalesce()][coalesce] - Return the first non-null value from the provided arguments. - [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. -- [tryGet()][tryGet] - Safely retrieve a value from an array by index or an object by key without throwing an error. +- [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: -- [copyIndex()][copyIndex] - Return the current iteration index of a copy loop. - [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. -- [base64ToString()][base64ToString] - Decode a base64-encoded string and return the original string. -- [concat()][concat] - Return a combined string where the input strings are concatenated in the - order they're specified. +- [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. @@ -677,14 +726,19 @@ The following list of functions are for manipulating strings: - [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. -- [length()][length] - Return the number of elements in an array, characters in a string, or top-level properties in an object. +- [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. -- [take()][take] - Return an array or string with the specified number of elements from the start. - [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. @@ -695,32 +749,24 @@ The following list of functions are for manipulating strings: ### System functions -The following list of functions provide system-level information: +The following functions return information about the system or the current execution of DSC: -- [path()][path] - Construct a file system path from one or more path segments. +- [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. +- [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. -- [utcNow()][utcNow] - Return the current UTC datetime in a specified format. - -### Type functions - -The following list of functions create or convert values of a given type: - -- [array()][array] - Convert a value into an array containing that value. -- [bool()][bool] - Convert a value to a boolean. -- [createArray()][createArray] - Create an array of a given type from zero or more values of the - same type. -- [createObject()][createObject] - Create an object from key-value pairs. -- [int()][int] - Convert a string or number with a fractional part into an integer. -- [string()][string] - Convert a value to its string representation. +- [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 [and]: ./and.md @@ -728,10 +774,13 @@ The following list of functions create or convert values of a given type: [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 @@ -743,6 +792,7 @@ The following list of functions create or convert values of a given type: [envvar]: ./envvar.md [equals]: ./equals.md [false]: ./false.md +[filter]: ./filter.md [first]: ./first.md [format]: ./format.md [greater]: ./greater.md @@ -754,39 +804,47 @@ The following list of functions create or convert values of a given type: [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 -[take]: ./take.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 diff --git a/docs/reference/schemas/config/functions/parameters.md b/docs/reference/schemas/config/functions/parameters.md index 43a313645..e8790caad 100644 --- a/docs/reference/schemas/config/functions/parameters.md +++ b/docs/reference/schemas/config/functions/parameters.md @@ -1,6 +1,6 @@ --- description: Reference for the 'parameters' DSC configuration document function -ms.date: 02/28/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/index.md#--parameters -[03]: ../../../cli/config/index.md#--parameters-file +[02]: ../../../cli/config/index.md#-p---parameters +[03]: ../../../cli/config/index.md#-f---parameters-file diff --git a/docs/reference/schemas/config/functions/parseCidr.md b/docs/reference/schemas/config/functions/parseCidr.md index 20cea2c70..dbc8a9d28 100644 --- a/docs/reference/schemas/config/functions/parseCidr.md +++ b/docs/reference/schemas/config/functions/parseCidr.md @@ -1,6 +1,6 @@ --- description: Reference for the 'parseCidr' DSC configuration document function -ms.date: 11/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: parseCidr --- @@ -88,7 +88,9 @@ resources: - name: Calculate subnet details type: Microsoft.DSC.Debug/Echo properties: - output: "[parseCidr(cidrSubnet(parameters('baseNetwork'), parameters('subnetPrefix'), parameters('subnetIndex')))]" + output: >- + [parseCidr(cidrSubnet(parameters('baseNetwork'), parameters('subnetPrefix'), + parameters('subnetIndex')))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/path.md b/docs/reference/schemas/config/functions/path.md index edc01ad80..b657d3ff4 100644 --- a/docs/reference/schemas/config/functions/path.md +++ b/docs/reference/schemas/config/functions/path.md @@ -1,6 +1,6 @@ --- description: Reference for the 'path' DSC configuration document function -ms.date: 06/04/2025 +ms.date: 09/01/2026 ms.topic: reference title: path --- @@ -20,13 +20,13 @@ 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. +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. +This configuration constructs a simple absolute path of two elements. ```yaml # parseChildPath.example.1.dsc.config.yaml @@ -55,7 +55,7 @@ hadErrors: false ### Example 2 - Relative path with multiple elements -This configuration constructs a simple relative path of three elements. +This configuration constructs a simple relative path of three elements. ```yaml # relativePath.example.2.dsc.config.yaml @@ -84,7 +84,7 @@ hadErrors: false ### Example 3 - Relative element in path -This configuration constructs a path with a double dot in that 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. @@ -129,6 +129,7 @@ Type: string Required: true Position: 1 ``` + ### child Defines the child path segments the function appends to the base path. The function expects at @@ -160,11 +161,12 @@ 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. + + 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. @@ -185,4 +187,4 @@ The function returns an error in the following cases: [01]: ./join.md -[02]: ./uri.md \ No newline at end of file +[02]: ./uri.md diff --git a/docs/reference/schemas/config/functions/range.md b/docs/reference/schemas/config/functions/range.md index 94058cdc5..63bbf4399 100644 --- a/docs/reference/schemas/config/functions/range.md +++ b/docs/reference/schemas/config/functions/range.md @@ -1,10 +1,12 @@ --- description: Reference for the 'range' DSC configuration document function -ms.date: 09/26/2025 +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 diff --git a/docs/reference/schemas/config/functions/reference.md b/docs/reference/schemas/config/functions/reference.md index 335666281..c986091a0 100644 --- a/docs/reference/schemas/config/functions/reference.md +++ b/docs/reference/schemas/config/functions/reference.md @@ -1,6 +1,6 @@ --- description: Reference for the 'reference' DSC configuration document function -ms.date: 02/28/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 @@ -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/docs/reference/schemas/config/functions/resourceId.md b/docs/reference/schemas/config/functions/resourceId.md index 25cb29b2c..18cf4ba2b 100644 --- a/docs/reference/schemas/config/functions/resourceId.md +++ b/docs/reference/schemas/config/functions/resourceId.md @@ -1,6 +1,6 @@ --- description: Reference for the 'resourceId' DSC configuration document function -ms.date: 02/28/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/docs/reference/schemas/config/functions/shallowMerge.md b/docs/reference/schemas/config/functions/shallowMerge.md index f2ad2c0cb..a85b65711 100644 --- a/docs/reference/schemas/config/functions/shallowMerge.md +++ b/docs/reference/schemas/config/functions/shallowMerge.md @@ -1,10 +1,12 @@ --- description: Reference for the 'shallowMerge' DSC configuration document function -ms.date: 11/19/2025 +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. @@ -23,25 +25,25 @@ 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: +- 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. + - 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. +- 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 +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 @@ -85,7 +87,7 @@ messages: [] hadErrors: false ``` -In this example, the `port` value from the second object (`9000`) replaces the value from the first +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 @@ -115,13 +117,13 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: >- - [shallowMerge( - createArray( - parameters('defaults'), - parameters('environment'), - parameters('userPrefs') - ) + output: >- + [shallowMerge( + createArray( + parameters('defaults'), + parameters('environment'), + parameters('userPrefs') + ) )] ``` @@ -158,18 +160,18 @@ 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') - ) - ) + output: >- + [shallowMerge( + createArray( + createObject( + 'database', + createObject('host', 'localhost', 'port', 5432, 'ssl', true()) + ), + createObject( + 'database', + createObject('host', 'prod.db.local') + ) + ) )] ``` @@ -204,13 +206,13 @@ resources: - name: Echo type: Microsoft.DSC.Debug/Echo properties: - output: >- - [shallowMerge( - createArray( - createObject('name', 'Service1', 'enabled', true()), - createObject(), - createObject('version', '2.0') - ) + output: >- + [shallowMerge( + createArray( + createObject('name', 'Service1', 'enabled', true()), + createObject(), + createObject('version', '2.0') + ) )] ``` @@ -246,12 +248,12 @@ 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()) - ) + output: >- + [shallowMerge( + createArray( + createObject('newUI', false(), 'darkMode', true(), 'beta', false()), + createObject('newUI', true()), createObject('beta', true()) + ) )] ``` @@ -344,33 +346,33 @@ resources: 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' + 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' )] ``` @@ -448,8 +450,8 @@ 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 +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 @@ -465,13 +467,13 @@ The function will return an error in the following cases: ## 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 + 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 diff --git a/docs/reference/schemas/config/functions/skip.md b/docs/reference/schemas/config/functions/skip.md index 7b3faa262..222a58ff9 100644 --- a/docs/reference/schemas/config/functions/skip.md +++ b/docs/reference/schemas/config/functions/skip.md @@ -1,10 +1,12 @@ --- description: Reference for the 'skip' DSC configuration document function -ms.date: 08/29/2025 +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, diff --git a/docs/reference/schemas/config/functions/startsWith.md b/docs/reference/schemas/config/functions/startsWith.md index 233bb4d1d..2980ecb6d 100644 --- a/docs/reference/schemas/config/functions/startsWith.md +++ b/docs/reference/schemas/config/functions/startsWith.md @@ -1,6 +1,6 @@ --- description: Reference for the 'startsWith' DSC configuration document function -ms.date: 08/12/2025 +ms.date: 09/01/2026 ms.topic: reference title: startsWith --- @@ -78,7 +78,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - classification: "[if(startsWith(parameters('serviceName'), 'api-'), 'API Service', 'Other Service')]" + classification: >- + [if(startsWith(parameters('serviceName'), 'api-'), 'API Service', + 'Other Service')] ``` ```bash diff --git a/docs/reference/schemas/config/functions/stateChanged.md b/docs/reference/schemas/config/functions/stateChanged.md index ff91a2c6d..d556945c3 100644 --- a/docs/reference/schemas/config/functions/stateChanged.md +++ b/docs/reference/schemas/config/functions/stateChanged.md @@ -1,6 +1,6 @@ --- description: Reference for the 'stateChanged' DSC configuration document function -ms.date: 07/11/2026 +ms.date: 09/01/2026 ms.topic: reference title: stateChanged --- @@ -53,7 +53,9 @@ resources: - name: Report change type: Microsoft.DSC.Debug/Echo properties: - output: "[stateChanged(resourceId('Microsoft.Windows/FeatureOnDemandList', 'Install OpenSSH Client'))]" + output: >- + [stateChanged(resourceId('Microsoft.Windows/FeatureOnDemandList', + 'Install OpenSSH Client'))] dependsOn: - "[resourceId('Microsoft.Windows/FeatureOnDemandList', 'Install OpenSSH Client')]" ``` diff --git a/docs/reference/schemas/config/functions/stdout.md b/docs/reference/schemas/config/functions/stdout.md new file mode 100644 index 000000000..b16fec02a --- /dev/null +++ b/docs/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/docs/reference/schemas/config/functions/string.md b/docs/reference/schemas/config/functions/string.md index 23dcd2590..9c92ef73e 100644 --- a/docs/reference/schemas/config/functions/string.md +++ b/docs/reference/schemas/config/functions/string.md @@ -1,6 +1,6 @@ --- description: Reference for the 'string' DSC configuration document function -ms.date: 08/09/2025 +ms.date: 09/01/2026 ms.topic: reference title: string --- @@ -145,13 +145,16 @@ resources: 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)')]" + 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.4.dsc.config.yaml +dsc config get --file string.example.3.dsc.config.yaml ``` ```yaml @@ -193,11 +196,13 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - logEntry: "[concat('[', string(parameters('timestamp')), '] ERROR ', string(parameters('errorCode')), ': ', string(parameters('metadata')))]" + logEntry: >- + [concat('[', string(parameters('timestamp')), '] ERROR ', + string(parameters('errorCode')), ': ', string(parameters('metadata')))] ``` ```bash -dsc config get --file string.example.5.dsc.config.yaml +dsc config get --file string.example.4.dsc.config.yaml ``` ```yaml @@ -207,7 +212,7 @@ results: result: actualState: output: - logEntry: '[1691596800] ERROR 404: {"level":"error","source":"api"}' + logEntry: '[1691596800] ERROR 404: {"source":"api","level":"error"}' messages: [] hadErrors: false ``` diff --git a/docs/reference/schemas/config/functions/sub.md b/docs/reference/schemas/config/functions/sub.md index c3e57423a..a83bceafb 100644 --- a/docs/reference/schemas/config/functions/sub.md +++ b/docs/reference/schemas/config/functions/sub.md @@ -1,6 +1,6 @@ --- description: Reference for the 'sub' DSC configuration document function -ms.date: 02/28/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/docs/reference/schemas/config/functions/systemRoot.md b/docs/reference/schemas/config/functions/systemRoot.md index 9ec5e6809..e0d5decd3 100644 --- a/docs/reference/schemas/config/functions/systemRoot.md +++ b/docs/reference/schemas/config/functions/systemRoot.md @@ -1,6 +1,6 @@ --- description: Reference for the 'systemRoot' DSC configuration document function -ms.date: 06/04/2025 +ms.date: 09/01/2026 ms.topic: reference title: systemRoot --- @@ -94,5 +94,5 @@ Type: string ``` -[01]: ../../../cli/config/index.md#--system-root -[02]: ./path.md \ No newline at end of file +[01]: ../../../cli/config/index.md#-r---system-root +[02]: ./path.md diff --git a/docs/reference/schemas/config/functions/take.md b/docs/reference/schemas/config/functions/take.md index ea8e23108..0371f9b10 100644 --- a/docs/reference/schemas/config/functions/take.md +++ b/docs/reference/schemas/config/functions/take.md @@ -1,10 +1,12 @@ --- description: Reference for the 'take' DSC configuration document function -ms.date: 11/01/2025 +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 @@ -113,7 +115,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - resources: "[createArray('prod-db-east-01', 'dev-api-west-02', 'test-cache-central')]" + 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)]" diff --git a/docs/reference/schemas/config/functions/toLower.md b/docs/reference/schemas/config/functions/toLower.md index 2227a129c..2d5674dd1 100644 --- a/docs/reference/schemas/config/functions/toLower.md +++ b/docs/reference/schemas/config/functions/toLower.md @@ -1,6 +1,6 @@ --- description: Reference for the 'toLower' DSC configuration document function -ms.date: 10/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: toLower --- @@ -85,7 +85,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - filePath: "[concat('/etc/', toLower(parameters('fileName')), '.', toLower(parameters('extension')))]" + filePath: >- + [concat('/etc/', toLower(parameters('fileName')), '.', + toLower(parameters('extension')))] ``` ```bash @@ -124,7 +126,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - matches: "[equals(toLower(parameters('userInput')), toLower(parameters('expectedValue')))]" + matches: >- + [equals(toLower(parameters('userInput')), toLower(parameters('expectedValue')))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/toUpper.md b/docs/reference/schemas/config/functions/toUpper.md index 48f367171..5565528c0 100644 --- a/docs/reference/schemas/config/functions/toUpper.md +++ b/docs/reference/schemas/config/functions/toUpper.md @@ -1,6 +1,6 @@ --- description: Reference for the 'toUpper' DSC configuration document function -ms.date: 10/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: toUpper --- @@ -85,7 +85,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - configKey: "[concat(toUpper(parameters('environment')), '_', toUpper(parameters('component')), '_CONFIG')]" + configKey: >- + [concat(toUpper(parameters('environment')), '_', + toUpper(parameters('component')), '_CONFIG')] ``` ```bash @@ -124,7 +126,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - result: "[if(parameters('shouldCapitalize'), toUpper(parameters('text')), parameters('text'))]" + result: >- + [if(parameters('shouldCapitalize'), toUpper(parameters('text')), + parameters('text'))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/tryGet.md b/docs/reference/schemas/config/functions/tryGet.md index 1e87f08d2..d42ff1314 100644 --- a/docs/reference/schemas/config/functions/tryGet.md +++ b/docs/reference/schemas/config/functions/tryGet.md @@ -1,10 +1,12 @@ --- description: Reference for the 'tryGet' DSC configuration document function -ms.date: 01/29/2025 +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 @@ -54,9 +56,14 @@ resources: 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')]" + 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 @@ -112,7 +119,8 @@ resources: productionEnv: "[tryGet(parameters('environments'), 'production')]" stagingEnv: "[tryGet(parameters('environments'), 'staging')]" developmentEnv: "[tryGet(parameters('environments'), 'development')]" - prodReplicas: "[tryGet(tryGet(parameters('environments'), 'production'), 'replicas')]" + prodReplicas: >- + [tryGet(tryGet(parameters('environments'), 'production'), 'replicas')] prodRegion: "[tryGet(tryGet(parameters('environments'), 'production'), 'region')]" stagingRegion: "[tryGet(tryGet(parameters('environments'), 'staging'), 'region')]" ``` @@ -212,10 +220,15 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - successResponse: "[createObject('status', 200, 'data', createObject('id', 123, 'name', 'example'))]" + 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')]" + 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')]" ``` diff --git a/docs/reference/schemas/config/functions/tryIndexFromEnd.md b/docs/reference/schemas/config/functions/tryIndexFromEnd.md index 58aab3880..509bacaa0 100644 --- a/docs/reference/schemas/config/functions/tryIndexFromEnd.md +++ b/docs/reference/schemas/config/functions/tryIndexFromEnd.md @@ -1,10 +1,12 @@ --- description: Reference for the 'tryIndexFromEnd' DSC configuration document function -ms.date: 01/29/2025 +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 @@ -54,8 +56,10 @@ resources: 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)]" + 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 @@ -213,8 +217,11 @@ resources: 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')]" + 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 diff --git a/docs/reference/schemas/config/functions/tryWhich.md b/docs/reference/schemas/config/functions/tryWhich.md index 6fba50259..6ea9e8fc0 100644 --- a/docs/reference/schemas/config/functions/tryWhich.md +++ b/docs/reference/schemas/config/functions/tryWhich.md @@ -1,10 +1,12 @@ --- description: Reference for the 'tryWhich' DSC configuration document function -ms.date: 11/19/2025 +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 @@ -41,8 +43,8 @@ gracefully returns `null`, making it ideal for conditional logic with [`if()`][0 ### Example 1 - Check if tool exists before using it -The following example uses `tryWhich()` with [`if()`][00] to conditionally set a property -based on whether the `git` command is available. +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 @@ -53,12 +55,7 @@ resources: properties: output: gitPath: "[tryWhich('git')]" - hasGit: >- - [if( - equals(tryWhich('git'), null()), - false(), - true() - )] + hasGit: "[not(equals(tryWhich('git'), null()))]" ``` ```bash @@ -72,14 +69,14 @@ results: result: actualState: output: - gitPath: /usr/bin/git + 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`. +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 diff --git a/docs/reference/schemas/config/functions/union.md b/docs/reference/schemas/config/functions/union.md index bd13c3269..99ba200ff 100644 --- a/docs/reference/schemas/config/functions/union.md +++ b/docs/reference/schemas/config/functions/union.md @@ -1,6 +1,6 @@ --- description: Reference for the 'union' DSC configuration document function -ms.date: 08/08/2025 +ms.date: 09/01/2026 ms.topic: reference title: union --- @@ -62,7 +62,9 @@ resources: properties: output: allServers: "[union(parameters('serverGroup1'), parameters('serverGroup2'))]" - threeGroups: "[union(parameters('serverGroup1'), parameters('serverGroup2'), parameters('serverGroup3'))]" + threeGroups: >- + [union(parameters('serverGroup1'), parameters('serverGroup2'), + parameters('serverGroup3'))] ``` ```bash @@ -122,7 +124,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - finalConfig: "[union(parameters('defaultConfig'), parameters('userConfig'), parameters('envConfig'))]" + finalConfig: >- + [union(parameters('defaultConfig'), parameters('userConfig'), + parameters('envConfig'))] ``` ```bash @@ -229,7 +233,9 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - logEntry: "[string(union(parameters('baseLogData'), parameters('requestData'), parameters('responseData')))]" + logEntry: >- + [string(union(parameters('baseLogData'), parameters('requestData'), + parameters('responseData')))] logArray: "[union(createArray('timestamp'), createArray('level', 'requestId'))]" ``` diff --git a/docs/reference/schemas/config/functions/uniqueString.md b/docs/reference/schemas/config/functions/uniqueString.md index c1340a0fd..18b9fe79e 100644 --- a/docs/reference/schemas/config/functions/uniqueString.md +++ b/docs/reference/schemas/config/functions/uniqueString.md @@ -1,6 +1,6 @@ --- description: Reference for the 'uniqueString' DSC configuration document function -ms.date: 08/12/2025 +ms.date: 09/01/2026 ms.topic: reference title: uniqueString --- @@ -57,7 +57,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - name: "[uniqueString(parameters('env'), parameters('service'), parameters('region'))]" + name: >- + [uniqueString(parameters('env'), parameters('service'), parameters('region'))] ``` ```bash @@ -135,7 +136,8 @@ resources: type: Microsoft.DSC.Debug/Echo properties: output: - resourceId: "[concat('res-', uniqueString(parameters('project'), parameters('zone')))]" + resourceId: >- + [concat('res-', uniqueString(parameters('project'), parameters('zone')))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/uri.md b/docs/reference/schemas/config/functions/uri.md index 174e70723..58f067af6 100644 --- a/docs/reference/schemas/config/functions/uri.md +++ b/docs/reference/schemas/config/functions/uri.md @@ -1,6 +1,6 @@ --- description: Reference for the 'uri' DSC configuration document function -ms.date: 01/10/2025 +ms.date: 09/01/2026 ms.topic: reference title: uri --- @@ -155,7 +155,9 @@ resources: properties: output: oldEndpoint: "[concat('https://api.example.com/', parameters('currentVersion'))]" - newEndpoint: "[uri(concat('https://api.example.com/', parameters('currentVersion')), parameters('newVersion'))]" + newEndpoint: >- + [uri(concat('https://api.example.com/', parameters('currentVersion')), + parameters('newVersion'))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/uriComponent.md b/docs/reference/schemas/config/functions/uriComponent.md index bcf0325d5..3617ce52b 100644 --- a/docs/reference/schemas/config/functions/uriComponent.md +++ b/docs/reference/schemas/config/functions/uriComponent.md @@ -1,6 +1,6 @@ --- description: Reference for the 'uriComponent' DSC configuration document function -ms.date: 01/10/2025 +ms.date: 09/01/2026 ms.topic: reference title: uriComponent --- @@ -51,7 +51,9 @@ resources: output: original: "[parameters('searchTerm')]" encoded: "[uriComponent(parameters('searchTerm'))]" - fullUrl: "[concat('https://example.com/search?q=', uriComponent(parameters('searchTerm')))]" + fullUrl: >- + [concat('https://example.com/search?q=', + uriComponent(parameters('searchTerm')))] ``` ```bash diff --git a/docs/reference/schemas/config/functions/uriComponentToString.md b/docs/reference/schemas/config/functions/uriComponentToString.md index 84f425d65..d06a22972 100644 --- a/docs/reference/schemas/config/functions/uriComponentToString.md +++ b/docs/reference/schemas/config/functions/uriComponentToString.md @@ -1,8 +1,8 @@ --- description: Reference for the 'uriComponentToString' DSC configuration document function -ms.date: 10/10/2025 -ms.topic: reference -title: uriComponentToString function +ms.date: 09/01/2026 +ms.topic: reference +title: uriComponentToString --- # uriComponentToString @@ -13,7 +13,7 @@ Returns a decoded string from a URI-encoded value. ## Syntax -```yaml +```Syntax uriComponentToString() ``` @@ -33,7 +33,7 @@ such as query parameters, path segments, or other URI parts. This example decodes a URI-encoded query parameter value back to its original string. ```yaml -# example1.dsc.yaml +# uriComponentToString.example.1.dsc.config.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Echo decoded value @@ -43,7 +43,7 @@ resources: ``` ```bash -dsc config get --document example1.dsc.yaml config get +dsc config get --file uriComponentToString.example.1.dsc.config.yaml ``` ```yaml @@ -60,7 +60,7 @@ results: This example decodes a URI-encoded email address with special characters. ```yaml -# example2.dsc.yaml +# uriComponentToString.example.2.dsc.config.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Echo decoded email @@ -70,7 +70,7 @@ resources: ``` ```bash -dsc config get --document example2.dsc.yaml config get +dsc config get --file uriComponentToString.example.2.dsc.config.yaml ``` ```yaml @@ -87,17 +87,18 @@ results: This example decodes a completely URI-encoded URL back to its readable form. ```yaml -# example3.dsc.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')]" + output: >- + [uriComponentToString('https%3A%2F%2Fapi.example.com%2Fusers%3Fstatus%3Dactive')] ``` ```bash -dsc config get --document example3.dsc.yaml config get +dsc config get --file uriComponentToString.example.3.dsc.config.yaml ``` ```yaml @@ -115,7 +116,7 @@ This example demonstrates encoding a string with [`uriComponent()`][01] and then back with `uriComponentToString()`, showing that they are inverse operations. ```yaml -# example4.dsc.yaml +# uriComponentToString.example.4.dsc.config.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Echo round-trip result @@ -125,7 +126,7 @@ resources: ``` ```bash -dsc config get --document example4.dsc.yaml config get +dsc config get --file uriComponentToString.example.4.dsc.config.yaml ``` ```yaml @@ -142,7 +143,7 @@ results: This example decodes a URI-encoded string containing UTF-8 encoded Unicode characters. ```yaml -# example5.dsc.yaml +# uriComponentToString.example.5.dsc.config.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Echo decoded Unicode @@ -152,7 +153,7 @@ resources: ``` ```bash -dsc config get --document example5.dsc.yaml config get +dsc config get --file uriComponentToString.example.5.dsc.config.yaml ``` ```yaml diff --git a/docs/reference/schemas/config/metadata.md b/docs/reference/schemas/config/metadata.md index c26bcc549..a6d638a6f 100644 --- a/docs/reference/schemas/config/metadata.md +++ b/docs/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/docs/reference/schemas/config/parameter.md b/docs/reference/schemas/config/parameter.md index f76b803f2..d2300ebba 100644 --- a/docs/reference/schemas/config/parameter.md +++ b/docs/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/docs/reference/schemas/config/resource.md b/docs/reference/schemas/config/resource.md index 0af1a659f..50816718a 100644 --- a/docs/reference/schemas/config/resource.md +++ b/docs/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]: ../../../glossary.md#nested-resource-instance -[04]: functions/overview.md +[03]: ../metadata/Microsoft.DSC/properties.md +[04]: functions/copyIndex.md +[05]: ../../../glossary.md#nested-resource-instance +[06]: functions/overview.md +[07]: https://github.com/PowerShell/DSC/issues/1429 +[08]: metadata.md diff --git a/docs/reference/schemas/definitions/functions/builtin/dataTypes.md b/docs/reference/schemas/definitions/functions/builtin/dataTypes.md index 2496cba7a..8a149999e 100644 --- a/docs/reference/schemas/definitions/functions/builtin/dataTypes.md +++ b/docs/reference/schemas/definitions/functions/builtin/dataTypes.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data types that DSC functions operate on. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: Function data types schema reference --- @@ -14,24 +14,28 @@ 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.2.0/definitions/functions/builtin/dataTypes.json -Type : string -ValidValues : [ - 'array' - 'boolean' - 'lambda' - 'null' - 'number' - 'object' - 'string' - ] +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 supported data types are: +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` @@ -40,3 +44,6 @@ values. The supported data types are: - `number` - A 64-bit integer - `object` - A collection of key-value pairs - `string` - UTF-8 text + + +[01]: ../../../outputs/function/list.md diff --git a/docs/reference/schemas/definitions/message.md b/docs/reference/schemas/definitions/message.md index 6b5a3e084..63cdee72d 100644 --- a/docs/reference/schemas/definitions/message.md +++ b/docs/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/docs/reference/schemas/definitions/parameters/dataTypes.md b/docs/reference/schemas/definitions/parameters/dataTypes.md index 388f07167..62898f882 100644 --- a/docs/reference/schemas/definitions/parameters/dataTypes.md +++ b/docs/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/docs/reference/schemas/definitions/resourceCapabilities.md b/docs/reference/schemas/definitions/resourceCapabilities.md index 4e671e3bd..502eaf3f2 100644 --- a/docs/reference/schemas/definitions/resourceCapabilities.md +++ b/docs/reference/schemas/definitions/resourceCapabilities.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for resource capabilities -ms.date: 07/03/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,21 +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. +- `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 can remove an instance. -- `export` - The resource can enumerate every instance. -- `resolve` - The resource can resolve nested instances from an external source. +- `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. -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]. +### Capabilities for command resources -[01]: ../../../concepts/resources/capabilities.md -[02]: ../../../concepts/resources/operations.md +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/docs/reference/schemas/definitions/resourceKind.md b/docs/reference/schemas/definitions/resourceKind.md index 2589bdc17..564663050 100644 --- a/docs/reference/schemas/definitions/resourceKind.md +++ b/docs/reference/schemas/definitions/resourceKind.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for resource kind -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC Resource kind schema reference --- @@ -9,7 +9,8 @@ title: DSC Resource kind schema reference ## Synopsis -Identifies whether a resource is an adapter resource, a group resource, an importer resource, an exporter resource, or a normal resource. +Identifies whether a resource is an adapter resource, a group resource, an importer resource, an +exporter resource, or a normal resource. ## Metadata @@ -35,7 +36,8 @@ the property. If the `adapter` property is defined in the resource manifest, DSC 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, importer, or exporter resource with a resource manifest, always explicitly define `kind`. +When defining a group, importer, or exporter resource with a resource manifest, always explicitly +define `kind`. ### Adapter resources @@ -172,13 +174,13 @@ The following examples show valid and invalid references and dependencies. The e This example configuration defines several valid references and dependencies. It also defines two instances of the `Microsoft.DSC/Group` resource, one nested inside the other. -The top level instance of the `Microsoft.DSC.Debug/Echo` resource references and depends on the top-level instance -of the `Microsoft/OSInfo` resource. The top-level instances of the `Microsoft.DSC.Debug/Echo` and -`Microsoft/OSInfo` resources both depend on the top-level instance of the `Microsoft.DSC/Group` -resource. +The top level instance of the `Microsoft.DSC.Debug/Echo` resource references and depends on the +top-level instance of the `Microsoft/OSInfo` resource. The top-level instances of the +`Microsoft.DSC.Debug/Echo` and `Microsoft/OSInfo` resources both depend on the top-level instance +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. @@ -204,9 +206,10 @@ 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`, `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. ```yaml # Other top-level instances snipped for brevity @@ -235,8 +238,8 @@ depends on the adjacent nested `Microsoft.DSC/Group` instance. ``` Finally, the nested instance of `Microsoft.DSC/Group` defines two nested instances. The deeply -nested instance of `Microsoft.DSC.Debug/Echo` references and depends on the deeply nested instance of -`Microsoft/OSInfo`. +nested instance of `Microsoft.DSC.Debug/Echo` references and depends on the deeply nested instance +of `Microsoft/OSInfo`. ```yaml - name: Top level group @@ -262,7 +265,7 @@ nested instance of `Microsoft.DSC.Debug/Echo` references and depends on the deep dependsOn: - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]" - name: Deeply nested OSInfo - type: Microsoft.OSInfo + type: Microsoft/OSInfo properties: {} ``` @@ -275,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. @@ -330,18 +333,18 @@ resources: dependsOn: - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]" - name: Deeply nested OSInfo - type: Microsoft.OSInfo + type: Microsoft/OSInfo properties: {} ``` #### Example 2 - Invalid reference and dependency on a nested instance -This example configuration is invalid, because the top-level instance of the `Microsoft.DSC.Debug/Echo` resource -references and depends on the nested `Microsoft/OSInfo` instance. The nested instance is external -to the top-level instance, not adjacent. +This example configuration is invalid, because the top-level instance of the +`Microsoft.DSC.Debug/Echo` resource references and depends on the nested `Microsoft/OSInfo` +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 @@ -365,12 +368,12 @@ resources: #### Example 3 - Invalid reference and dependency on an external instance -This example configuration is invalid, because the nested instance of the `Microsoft.DSC.Debug/Echo` resource -references and depends on the top-level `Microsoft/OSInfo` instance. The top-level instance is -external to the nested instance, not adjacent. +This example configuration is invalid, because the nested instance of the +`Microsoft.DSC.Debug/Echo` resource references and depends on the top-level `Microsoft/OSInfo` +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/docs/reference/schemas/definitions/resourceType.md b/docs/reference/schemas/definitions/resourceType.md index de466c5a2..4e3a9f13e 100644 --- a/docs/reference/schemas/definitions/resourceType.md +++ b/docs/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/docs/reference/schemas/extension/manifest/discover.md b/docs/reference/schemas/extension/manifest/discover.md index 44b70c8ae..d1e0bef01 100644 --- a/docs/reference/schemas/extension/manifest/discover.md +++ b/docs/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/docs/reference/schemas/extension/manifest/root.md b/docs/reference/schemas/extension/manifest/root.md index 8fa803f28..1b9f3a932 100644 --- a/docs/reference/schemas/extension/manifest/root.md +++ b/docs/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) -- [get](#get) ## Properties @@ -52,8 +57,9 @@ 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: @@ -77,8 +83,8 @@ 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 Visual Studio Code. While DSC can still - validate the document when it uses this schema, other tools may error or behave in unexpected + 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 @@ -89,33 +95,107 @@ 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 extension 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 @@ -126,7 +206,36 @@ The `version` property must be the current version of the extension as a valid s ```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 @@ -157,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 @@ -198,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/extensionType.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/docs/reference/schemas/extension/stdout/discover.md b/docs/reference/schemas/extension/stdout/discover.md index 7afbf4afd..eb9e3db6e 100644 --- a/docs/reference/schemas/extension/stdout/discover.md +++ b/docs/reference/schemas/extension/stdout/discover.md @@ -1,6 +1,6 @@ --- -description: JSON schema reference for the 'discover' property in a DSC extension manifest -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,37 +21,58 @@ Type: object ## Description -Represents the actual state of a resource instance in DSC path 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. -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. +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. -## Required 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. -The output for the `discover` operation must include these properties: +## 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`. -Each discovered manifest must be emitted as a separate JSON Line to stdout. If no manifests are -discovered, the extension must not emit any output to stdout. +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 @@ -62,3 +82,7 @@ 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/docs/reference/schemas/metadata/Microsoft.DSC/properties.md b/docs/reference/schemas/metadata/Microsoft.DSC/properties.md index ecd32e444..07f905bcd 100644 --- a/docs/reference/schemas/metadata/Microsoft.DSC/properties.md +++ b/docs/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/docs/reference/schemas/outputs/config/get.md b/docs/reference/schemas/outputs/config/get.md index 222f88934..3d7301345 100644 --- a/docs/reference/schemas/outputs/config/get.md +++ b/docs/reference/schemas/outputs/config/get.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc config get' command. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: dsc config get result schema reference --- @@ -28,34 +28,24 @@ in the configuration document. The output always includes these properties: -- [metadata](#metadata-1) - [results](#results) - [messages](#messages) - [hadErrors](#haderrors) ## Properties -### metadata +### executionInformation -Defines metadata DSC returns for a configuration operation. The properties under the -`Microsoft.DSC` property describe the context of the operation. - -```yaml -Type: object -Required: true -``` - -#### Microsoft.DSC - -The metadata under this property describes the context of the overall operation: +Describes the context of the overall operation. DSC adds this property to the output of every +configuration operation. The value is an object with the following properties: - [version][01] defines the version of DSC that ran the command. This value is always the semantic version of the DSC command, like `3.0.0-preview.7`. -- [operation][02] defines the operation that DSC applied to the configuration document: `Get`, - `Set`, `Test`, or `Export`. +- [operation][02] defines the operation that DSC applied to the configuration document: `get`, + `set`, `test`, or `export`. - [executionType][03] defines whether DSC actually applied an operation to the configuration or was - run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` - operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--what-if` + run in what-if mode. This property is always `actual` for `get`, `test`, and `export` + operations. For `set` operations, this value is `whatIf` when DSC is invoked with the `--what-if` argument. - [startDatetime][04] defines the start date and time for the DSC operation as a timestamp following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like @@ -67,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/docs/reference/schemas/outputs/config/set.md b/docs/reference/schemas/outputs/config/set.md index dac249178..61fe83512 100644 --- a/docs/reference/schemas/outputs/config/set.md +++ b/docs/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/docs/reference/schemas/outputs/config/test.md b/docs/reference/schemas/outputs/config/test.md index df64e67fa..8f8d1f70f 100644 --- a/docs/reference/schemas/outputs/config/test.md +++ b/docs/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/docs/reference/schemas/outputs/extension/list.md b/docs/reference/schemas/outputs/extension/list.md index 766ab7d3d..87deb9969 100644 --- a/docs/reference/schemas/outputs/extension/list.md +++ b/docs/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,13 +44,14 @@ 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 @@ -62,20 +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. + 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. + 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 @@ -83,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 ``` @@ -106,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. @@ -128,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/extensionType.md -[03]: ../../extension/manifest/root.md +[02]: ../../definitions/resourceType.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/docs/reference/schemas/outputs/function/list.md b/docs/reference/schemas/outputs/function/list.md index 2a7706371..a0d14976a 100644 --- a/docs/reference/schemas/outputs/function/list.md +++ b/docs/reference/schemas/outputs/function/list.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc function list' command. -ms.date: 07/03/2025 +ms.date: 09/01/2026 ms.topic: reference title: dsc function list result schema reference --- @@ -15,7 +15,7 @@ The result output from the `dsc function list` command. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/outputs/function/list.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/outputs/function/list.json Type: object ``` @@ -25,6 +25,43 @@ The output from the `dsc function list` command includes a representation of dis 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: @@ -32,6 +69,8 @@ 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) @@ -45,18 +84,18 @@ Each function in the output always includes these properties: 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. +- `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 @@ -68,18 +107,18 @@ Type: array Required: true ItemsType: string ItemsValidValues: [ - Array, - Cidr, - Comparison, - Date, - Deployment, - Lambda, - Logical, - Numeric, - Object, - Resource, - String, - System + array, + cidr, + comparison, + date, + deployment, + lambda, + logical, + numeric, + object, + resource, + string, + system ] ``` @@ -104,25 +143,51 @@ 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 +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. +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 +Type: integer +Required: true MinimumValue: 0 ``` @@ -130,7 +195,7 @@ MinimumValue: 0 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](../../definitions/functions/builtin/dataTypes.md). +[argument types][02]. DSC raises a parsing error when the value for an argument isn't a valid type for that argument. @@ -147,33 +212,32 @@ Indicates the acceptable types for the last parameter of a variadic function. Va 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](../../definitions/functions/builtin/dataTypes.md) the function supports passing multiple -arguments of those types for the final parameter. +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 +Type: ['null', 'array'] +Required: true ItemsMustBeUnique: true -ItemsReference: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/definitions/functions/builtin/argTypes.json +ItemsReference: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/definitions/functions/builtin/argKind.json ``` ### returnTypes -Indicates the [types](../../definitions/functions/builtin/dataTypes.md) 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. +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 +Type: array +Required: true ItemsMustBeUnique: true -ItemsReference: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/definitions/functions/builtin/argTypes.json +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/docs/reference/schemas/outputs/resource/get.md b/docs/reference/schemas/outputs/resource/get.md index 093a10a93..dd489c23b 100644 --- a/docs/reference/schemas/outputs/resource/get.md +++ b/docs/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/docs/reference/schemas/outputs/resource/list.md b/docs/reference/schemas/outputs/resource/list.md index 70787a612..5fdd6ea36 100644 --- a/docs/reference/schemas/outputs/resource/list.md +++ b/docs/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: 07/03/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. +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,22 +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 @@ -105,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 @@ -146,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/docs/reference/schemas/outputs/resource/set.md b/docs/reference/schemas/outputs/resource/set.md index b72ca7a7d..985aec16f 100644 --- a/docs/reference/schemas/outputs/resource/set.md +++ b/docs/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/docs/reference/schemas/outputs/resource/test.md b/docs/reference/schemas/outputs/resource/test.md index 8f3622fa3..1e3b3206c 100644 --- a/docs/reference/schemas/outputs/resource/test.md +++ b/docs/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/docs/reference/schemas/overview.md b/docs/reference/schemas/overview.md index 1fc0a7d30..334c86d46 100644 --- a/docs/reference/schemas/overview.md +++ b/docs/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: 03/25/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/docs/reference/schemas/resource/manifest/adapter.md b/docs/reference/schemas/resource/manifest/adapter.md index 64926a33d..afc43522d 100644 --- a/docs/reference/schemas/resource/manifest/adapter.md +++ b/docs/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/docs/reference/schemas/resource/manifest/delete.md b/docs/reference/schemas/resource/manifest/delete.md index 938c4a55c..193979a49 100644 --- a/docs/reference/schemas/resource/manifest/delete.md +++ b/docs/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/docs/reference/schemas/resource/manifest/export.md b/docs/reference/schemas/resource/manifest/export.md index 0a98fda5f..3f830f008 100644 --- a/docs/reference/schemas/resource/manifest/export.md +++ b/docs/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/docs/reference/schemas/resource/manifest/get.md b/docs/reference/schemas/resource/manifest/get.md index 7ffae514b..086d88b42 100644 --- a/docs/reference/schemas/resource/manifest/get.md +++ b/docs/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/docs/reference/schemas/resource/manifest/resolve.md b/docs/reference/schemas/resource/manifest/resolve.md index b53f40ab1..ed278784f 100644 --- a/docs/reference/schemas/resource/manifest/resolve.md +++ b/docs/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/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md index e60920132..d173f92ad 100644 --- a/docs/reference/schemas/resource/manifest/root.md +++ b/docs/reference/schemas/resource/manifest/root.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a DSC Resource manifest -ms.date: 07/03/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 @@ -77,7 +76,7 @@ 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 Visual Studio Code. While DSC can still + 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. @@ -89,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 @@ -110,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 @@ -135,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 @@ -167,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 @@ -201,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 @@ -244,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 @@ -254,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 @@ -271,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 @@ -281,12 +417,15 @@ 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 @@ -295,12 +434,18 @@ Required: false ### adapter -When specified, the `adapter` property defines the resource as a DSC Resource 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`. -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 adapter to return the resources that the -adapter can manage. The `config` property defines how the adapter expects input. For more -information, see the [DSC Resource manifest adapter property schema reference][13]. +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]. + +```yaml +Type: object +Required: false +``` ### exitCodes @@ -313,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 @@ -331,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 ``` @@ -345,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]: adapter.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/docs/reference/schemas/resource/manifest/schema/embedded.md b/docs/reference/schemas/resource/manifest/schema/embedded.md index 7876edc70..e85b2b257 100644 --- a/docs/reference/schemas/resource/manifest/schema/embedded.md +++ b/docs/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,7 +25,7 @@ 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 Visual Studio Code to +Embedded JSON schemas are also used by integrating and authoring tools like Visual Studio Code to validate resource instances and provide IntelliSense. ## Required keywords @@ -110,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 @@ -144,7 +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]. -[01]: ../../properties/ensure.md + +[01]: ../../properties/exist.md [02]: ../test.md [03]: ../../properties/inDesiredState.md [04]: ../../properties/purge.md diff --git a/docs/reference/schemas/resource/manifest/schema/property.md b/docs/reference/schemas/resource/manifest/schema/property.md index 8a0bb87f2..a54cc4a06 100644 --- a/docs/reference/schemas/resource/manifest/schema/property.md +++ b/docs/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/docs/reference/schemas/resource/manifest/set.md b/docs/reference/schemas/resource/manifest/set.md index 7a0f9e4a4..3ca90392b 100644 --- a/docs/reference/schemas/resource/manifest/set.md +++ b/docs/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]: ../../outputs/resource/list.md#capability-sethandlesexist -[04]: ../../outputs/resource/list.md#capabilities -[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/docs/reference/schemas/resource/manifest/test.md b/docs/reference/schemas/resource/manifest/test.md index 7305b3459..9519e4d3f 100644 --- a/docs/reference/schemas/resource/manifest/test.md +++ b/docs/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/docs/reference/schemas/resource/manifest/validate.md b/docs/reference/schemas/resource/manifest/validate.md index 449305cb4..ca1c8ef3b 100644 --- a/docs/reference/schemas/resource/manifest/validate.md +++ b/docs/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/docs/reference/schemas/resource/manifest/whatif.md b/docs/reference/schemas/resource/manifest/whatif.md index 404806d31..f6528b1a9 100644 --- a/docs/reference/schemas/resource/manifest/whatif.md +++ b/docs/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]: ../../outputs/resource/list.md#capability-sethandlesexist -[07]: ../../outputs/resource/list.md#capabilities -[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/docs/reference/schemas/resource/properties/ensure.md b/docs/reference/schemas/resource/properties/ensure.md index 97085e755..8979e7497 100644 --- a/docs/reference/schemas/resource/properties/ensure.md +++ b/docs/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/docs/reference/schemas/resource/properties/exist.md b/docs/reference/schemas/resource/properties/exist.md index 1bd6c29f9..afa1c4ba0 100644 --- a/docs/reference/schemas/resource/properties/exist.md +++ b/docs/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 --- @@ -47,5 +47,3 @@ snippet: "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/exist.json" } ``` - - diff --git a/docs/reference/schemas/resource/properties/inDesiredState.md b/docs/reference/schemas/resource/properties/inDesiredState.md index 71a17ba94..9a0d927c6 100644 --- a/docs/reference/schemas/resource/properties/inDesiredState.md +++ b/docs/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,7 +47,6 @@ snippet: } ``` - - + [01]: ../manifest/root.md [02]: ../manifest/test.md diff --git a/docs/reference/schemas/resource/properties/overview.md b/docs/reference/schemas/resource/properties/overview.md index aad231983..3f18f7ea5 100644 --- a/docs/reference/schemas/resource/properties/overview.md +++ b/docs/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: 02/28/2025 +ms.date: 09/01/2026 ms.topic: reference title: DSC canonical properties --- @@ -38,8 +38,29 @@ DSC. For more information, see [DSC Resource _purge property schema][05]. +## _restartRequired + +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. + +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]: ../../config/functions/restartRequired.md diff --git a/docs/reference/schemas/resource/properties/purge.md b/docs/reference/schemas/resource/properties/purge.md index e783b5a69..97363e1f7 100644 --- a/docs/reference/schemas/resource/properties/purge.md +++ b/docs/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 --- @@ -47,5 +47,3 @@ snippet: "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/purge.json" } ``` - - diff --git a/docs/reference/schemas/resource/stdout/delete.md b/docs/reference/schemas/resource/stdout/delete.md index 86e1c25b4..1a0ca13c4 100644 --- a/docs/reference/schemas/resource/stdout/delete.md +++ b/docs/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: 02/28/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/docs/reference/schemas/resource/stdout/list.md b/docs/reference/schemas/resource/stdout/list.md index f7175a8b6..3d568807a 100644 --- a/docs/reference/schemas/resource/stdout/list.md +++ b/docs/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: 07/29/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. +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/docs/reference/schemas/resource/stdout/set.md b/docs/reference/schemas/resource/stdout/set.md index 7fb917962..be7526aca 100644 --- a/docs/reference/schemas/resource/stdout/set.md +++ b/docs/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: 07/29/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/docs/reference/schemas/resource/stdout/test.md b/docs/reference/schemas/resource/stdout/test.md index 7536bab48..2c4c6c399 100644 --- a/docs/reference/schemas/resource/stdout/test.md +++ b/docs/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: 07/29/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/docs/reference/schemas/resource/stdout/whatIf.md b/docs/reference/schemas/resource/stdout/whatIf.md index 9fc08cc77..c341def55 100644 --- a/docs/reference/schemas/resource/stdout/whatIf.md +++ b/docs/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: 07/29/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/docs/reference/schemas/schema-uris.md b/docs/reference/schemas/schema-uris.md index 5feb48788..43b84feb8 100644 --- a/docs/reference/schemas/schema-uris.md +++ b/docs/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,7 +196,7 @@ 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 Visual Studio Code recognizes for +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. @@ -165,7 +206,7 @@ only affect the experience for authoring, editing, and reviewing the data in Vis 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 Visual Studio Code, +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` | From 40d6a6b808d45867a8a0fbdbf913801a73916cb4 Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Wed, 2 Sep 2026 14:26:25 +0200 Subject: [PATCH 2/3] Update with Copilot remarks --- .../schemas/config/functions/contains.md | 31 +++++++++++-------- .../schemas/config/functions/dataUri.md | 7 ++--- .../schemas/config/functions/systemRoot.md | 4 +-- lib/dsc-lib/src/parser/functions.rs | 4 +-- 4 files changed, 25 insertions(+), 21 deletions(-) diff --git a/docs/reference/schemas/config/functions/contains.md b/docs/reference/schemas/config/functions/contains.md index 76fc4db1a..18689e588 100644 --- a/docs/reference/schemas/config/functions/contains.md +++ b/docs/reference/schemas/config/functions/contains.md @@ -1,6 +1,6 @@ --- description: Reference for the 'contains' DSC configuration document function -ms.date: 08/08/2025 +ms.date: 09/01/2026 ms.topic: reference title: contains --- @@ -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/docs/reference/schemas/config/functions/dataUri.md b/docs/reference/schemas/config/functions/dataUri.md index 4038eea60..f722f3047 100644 --- a/docs/reference/schemas/config/functions/dataUri.md +++ b/docs/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/docs/reference/schemas/config/functions/systemRoot.md b/docs/reference/schemas/config/functions/systemRoot.md index e0d5decd3..27173635c 100644 --- a/docs/reference/schemas/config/functions/systemRoot.md +++ b/docs/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 diff --git a/lib/dsc-lib/src/parser/functions.rs b/lib/dsc-lib/src/parser/functions.rs index 6a507a582..68c68c74b 100644 --- a/lib/dsc-lib/src/parser/functions.rs +++ b/lib/dsc-lib/src/parser/functions.rs @@ -43,7 +43,7 @@ pub enum FunctionArg { /// /// Lambdas are created using the `lambda()` function syntax: /// ```text -/// "[lambda(['item', 'index'], mul(variables('item'), 2))]" +/// "[lambda('item', 'index', mul(lambdaVariables('item'), 2))]" /// ``` /// /// The lambda is stored in the context and referenced by UUID: @@ -53,7 +53,7 @@ pub enum FunctionArg { /// /// When used with `map()`, the lambda is invoked for each array element with bound parameters: /// ```text -/// "[map(createArray(1, 2, 3), lambda(['item'], mul(variables('item'), 2)))]" +/// "[map(createArray(1, 2, 3), lambda('item', mul(lambdaVariables('item'), 2)))]" /// ``` /// /// # Lifetime From abe029464dbb282799c66d1f7fb33d2027af2b3a Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Wed, 2 Sep 2026 15:38:58 +0200 Subject: [PATCH 3/3] Resolve Copilot remarks --- docs/reference/schemas/config/functions/json.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/reference/schemas/config/functions/json.md b/docs/reference/schemas/config/functions/json.md index bd41a1c21..bf9550393 100644 --- a/docs/reference/schemas/config/functions/json.md +++ b/docs/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