diff --git a/CHANGELOG.md b/CHANGELOG.md index 80ecbee5..66165022 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ title: "Desired State Configuration changelog" description: >- A log of the changes for releases of DSCv3. -ms.date: 02/05/2024 +ms.date: 03/06/2024 --- # Changelog @@ -22,10 +22,19 @@ This section includes a summary of user-facing changes since the last release. F changes since the last release, see the [diff on GitHub][unreleased]. -[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...main +[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.5...main +## [v3.0.0-alpha.5][release-v3.0.0-alpha.5] - 2024-02-27 + +This section includes a summary of changes for the `alpha.5` release. For the full list of changes +in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5]. + + +[release-v3.0.0-alpha.5]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.5 "Link to the DSC v3.0.0-alpha.5 release on GitHub" +[compare-v3.0.0-alpha.5]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...v3.0.0-alpha.5 + ### Changed - Updated the options for the `dsc` root command: @@ -57,6 +66,35 @@ changes since the last release, see the [diff on GitHub][unreleased]. +- Updated the JSON schemas for the [get][38], [set][39], and [test][40] output data. This change + corrects an issue with how DSC surfaced information about instances nested inside group and + adapter resources. Now when you review the output, you'll be able to see the results for each + nested instance instead of a confusing object that loses the nested instance type and name + information. + + This schema change is backwards compatible. + +
Related work items + + - Issues: + - [#165][#165] + - [#266][#266] + - [#284][#284] + - PRs: [#318][#318] + +
+ +- Changed the [concat][41] configuration function to match the behavior of the ARM template + function. The `concat()` function now only accepts strings or arrays of strings as input values. + It raises an error if the input values are not of the same type. + +
Related work items + + - Issues: [#271][#271] + - PRs: [#322][#322] + +
+ ### Added - Implemented support for referencing parameters in a configuration with the [parameters()][32] @@ -86,6 +124,77 @@ changes since the last release, see the [diff on GitHub][unreleased].
+- Added the [DSCConfigRoot][42] environment variable and the [envvar() configuration function][43] + to enable users to reference files and folders relative to the folder containing the + configuration document. DSC automatically creates the `DSCConfigRoot` environment variable when + you use the `--path` option to specify the configuration document instead of passing the document + as a string from stdin or with the `--document` option. + + > [!NOTE] + > In this release, DSC doesn't expand the specified path to an absolute path. You should always + > specify the full path to the configuration document if you want to reference the + > `DSCConfigRoot` variable in your configuration. Further, DSC always sets the value for this + > environment variable when you use the `--path` option. If the environment variable is already + > set, it overrides it silently. + > + > In a future release, the variable will be renamed to `DSC_CONFIG_ROOT` and DSC will + > automatically expand relative paths into absolute paths when setting the environment variable. + > It will also emit a warning when it overrides the variable. + +
Related work Items + + - Issues: [#75][#75] + - PRs: [#313][#313] + +
+ +- Added support for using the [dsc config export][44] and [dsc resource export][45] commands with + the PowerShell adapter resource. PSDSC resources can now participate in the `export` command if + they define a static method that returns an array of the PSDSC resource class. + +
Related work Items + + - Issues: [#183][#183] + - PRs: [#307][#307] + +
+ +- Added the `methods` column to the default table view for the console output of the + [dsc resource list][46] command. This new column indicates which methods the resource explicitly + implements. Valid values include `get`, `set`, `test`, and `export`. This information is only + available in the table view. It isn't part of the output object for the command. If you use the + [--format][47] parameter, capture the command output, or redirect the output, the `methods` + information isn't included. + + Resources that don't implement `test` rely on DSC's synthetic test behavior instead. They can + still be used for test and set operations. + + Resources that don't implement `export` can't be used with the `dsc config export` or + `dsc resource export` commands. + + Resources that don't implement `set` can be used for auditing, but not `dsc resource set`. They + can be used with the `dsc config set` command, but only if they're nested inside a + `DSC/AssertionGroup` instance. + +
Related work Items + + - Issues: [#309][#309] + - PRs: [#314][#314] + +
+ +- Added an prototype for a WMI resource adapter to enable users to query WMI. The adapter is + disabled by default, as enumerating the WMI resources can have a performance impact. To enable + it, rename the resource manifest from `wmigroup.dsc.resource.json.optout` to + `wmigroup.dsc.resource.json`. + +
Related work Items + + - Issues: [#263][#263] + - PRs: [#279][#279] + +
+ ## [v3.0.0-alpha.4][release-v3.0.0-alpha.4] - 2023-11-14 This section includes a summary of changes for the `alpha.4` release. For the full list of changes @@ -138,7 +247,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.4]. ### Added -- Added the [--input][24] and [--input-file][25] global options to the root `dsc` command. Now, you +- Added the `--input` and `--input-file` global options to the root `dsc` command. Now, you can pass input to DSC from a variable or file instead of piping from stdin.
Related work items @@ -171,7 +280,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.4]. - DSC now emits log messages to the stderr stream. This can make it easier to understand what DSC is doing. This doesn't affect the data output. By default, DSC emits errors, warnings, and informational messages, but not debug or trace messaging. You can control the level of the - logging with the new [--logging-level][27] option on the root `dsc` command. + logging with the new `--logging-level` option on the root `dsc` command.
Related work items @@ -523,10 +632,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [21]: docs/reference/schemas/config/document.md#schema [22]: docs/reference/schemas/resource/manifest/root.md#schema [23]: docs/reference/schemas/resource/properties/exist.md -[24]: docs/reference/cli/dsc.md#-i---input -[25]: docs/reference/cli/dsc.md#-p---input-file [26]: docs/reference/cli/completer/command.md -[27]: docs/reference/cli/dsc.md#-l---logging-level [28]: docs/reference/schemas/config/functions/overview.md [29]: docs/reference/schemas/config/functions/base64.md [30]: docs/reference/schemas/config/functions/concat.md @@ -539,6 +645,16 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [35]: docs/reference/cli/config/command.md [36]: docs/reference/cli/dsc.md#-l---trace-level [37]: docs/reference/cli/dsc.md#-f---trace-format +[38]: docs/reference/schemas/outputs/resource/get.md +[39]: docs/reference/schemas/outputs/resource/set.md +[40]: docs/reference/schemas/outputs/resource/test.md +[41]: docs/reference/schemas/config/functions/concat.md +[42]: docs/reference/cli/config/command.md#environment-variables +[43]: docs/reference/schemas/config/functions/envvar.md +[44]: docs/reference/cli/config/export.md +[45]: docs/reference/cli/resource/export.md +[46]: docs/reference/cli/resource/list.md +[47]: docs/reference/cli/resource/list.md#-f---format [#107]: https://github.com/PowerShell/DSC/issues/107 @@ -553,6 +669,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#159]: https://github.com/PowerShell/DSC/issues/159 [#162]: https://github.com/PowerShell/DSC/issues/162 [#163]: https://github.com/PowerShell/DSC/issues/163 +[#165]: https://github.com/PowerShell/DSC/issues/165 [#168]: https://github.com/PowerShell/DSC/issues/168 [#171]: https://github.com/PowerShell/DSC/issues/171 [#172]: https://github.com/PowerShell/DSC/issues/172 @@ -563,6 +680,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#177]: https://github.com/PowerShell/DSC/issues/177 [#181]: https://github.com/PowerShell/DSC/issues/181 [#182]: https://github.com/PowerShell/DSC/issues/182 +[#183]: https://github.com/PowerShell/DSC/issues/183 [#186]: https://github.com/PowerShell/DSC/issues/186 [#197]: https://github.com/PowerShell/DSC/issues/197 [#198]: https://github.com/PowerShell/DSC/issues/198 @@ -581,15 +699,27 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#241]: https://github.com/PowerShell/DSC/issues/241 [#248]: https://github.com/PowerShell/DSC/issues/248 [#252]: https://github.com/PowerShell/DSC/issues/252 +[#263]: https://github.com/PowerShell/DSC/issues/263 +[#266]: https://github.com/PowerShell/DSC/issues/266 +[#271]: https://github.com/PowerShell/DSC/issues/271 +[#279]: https://github.com/PowerShell/DSC/issues/279 +[#284]: https://github.com/PowerShell/DSC/issues/284 [#286]: https://github.com/PowerShell/DSC/issues/286 [#291]: https://github.com/PowerShell/DSC/issues/291 [#294]: https://github.com/PowerShell/DSC/issues/294 [#299]: https://github.com/PowerShell/DSC/issues/299 [#303]: https://github.com/PowerShell/DSC/issues/303 [#305]: https://github.com/PowerShell/DSC/issues/305 +[#307]: https://github.com/PowerShell/DSC/issues/307 +[#309]: https://github.com/PowerShell/DSC/issues/309 [#311]: https://github.com/PowerShell/DSC/issues/311 +[#313]: https://github.com/PowerShell/DSC/issues/313 +[#314]: https://github.com/PowerShell/DSC/issues/314 +[#318]: https://github.com/PowerShell/DSC/issues/318 +[#322]: https://github.com/PowerShell/DSC/issues/322 [#45]: https://github.com/PowerShell/DSC/issues/45 [#49]: https://github.com/PowerShell/DSC/issues/49 [#57]: https://github.com/PowerShell/DSC/issues/57 [#73]: https://github.com/PowerShell/DSC/issues/73 +[#75]: https://github.com/PowerShell/DSC/issues/75 [#98]: https://github.com/PowerShell/DSC/issues/98 diff --git a/docs/reference/cli/config/command.md b/docs/reference/cli/config/command.md index c9ac0350..376b6204 100644 --- a/docs/reference/cli/config/command.md +++ b/docs/reference/cli/config/command.md @@ -108,6 +108,21 @@ Type: Boolean Mandatory: false ``` +## Environment variables + +The `dsc config *` subcommands create the `DSCConfigRoot` environment variable when you call a +command with the `--path` option to specify the configuration document to use for the command. DSC +sets the value of the `DSCConfigRoot` environment variable to the folder containing the specified +configuration document. + +> [!NOTE] +> If you use a relative path, DSC doesn't expand the value into a full path before setting the +> environment variable. Always specify the full path to the configuration document when you want to +> use the `DSCConfigRoot` environment variable. + +You can use the [envvar][08] configuration function to reference that folder path for resource +instances in the configuration. + [01]: ../resource/command.md [02]: export.md [03]: get.md @@ -115,3 +130,4 @@ Mandatory: false [05]: test.md [06]: ../../schemas/config/parameter.md [07]: ../../schemas/config/functions/parameters.md +[08]: ../../schemas/config/functions/envvar.md diff --git a/docs/reference/cli/resource/list.md b/docs/reference/cli/resource/list.md index 30505139..22af6528 100644 --- a/docs/reference/cli/resource/list.md +++ b/docs/reference/cli/resource/list.md @@ -43,17 +43,21 @@ dsc resource list ``` ```Output -type version tags description ----- ------- ---- ----------- -Test/TestGroup 0.1.0 -Microsoft/OSInfo 0.1.0 {os, linux, windows, macos} Returns information about the operating system. -Microsoft.Windows/Registry 0.1.0 {Windows, NT} Registry configuration provider for the Windows Registry - This is a test resource. -DSC/PowerShellGroup 0.1.0 {PowerShell} Resource provider to classic DSC Powershell resources. -DSC/AssertionGroup 0.1.0 `test` will be invoked for all resources in the supplied configuration. -DSC/ParallelGroup 0.1.0 All resources in the supplied configuration run concurrently. - This is a test resource. -DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. +Type Version Methods Requires Description +---------------------------------------------------------------------------------------------------------------------------------------------------- +DSC.PackageManagement/Brew 0.1.0 get, set, export DSC resource to manage Homebrew packages +DSC/AssertionGroup 0.1.0 get, set, test `test` will be invoked for all resources in the supplied configuration. +DSC/Group 0.1.0 get, set, test All resources in the supplied configuration is treated as a group. +DSC/ParallelGroup 0.1.0 get, set, test All resources in the supplied configuration run concurrently. +DSC/PowerShellGroup 0.1.0 get, set, test, export Resource provider to classic DSC Powershell resources. +Microsoft.Windows/Registry 0.1.0 get, set, test Registry configuration provider for the Windows Registry +Microsoft/OSInfo 0.1.0 get, export Returns information about the operating system. +Microsoft/Process 0.1.0 get, set, test, export Returns information about running processes. +Test/Echo 0.1.0 get, set, test +Test/Sleep 0.1.0 get, set, test +Test/TestGroup 0.1.0 get +Test/TestResource1 1.0.0 get Test/TestGroup This is a test resource. +Test/TestResource2 1.0.1 get Test/TestGroup This is a test resource. ``` ### Example 2 - List a specific resource @@ -66,9 +70,9 @@ dsc resource list DSC/Group ``` ```Output -Type Version Requires Description ------------------------------------------------------------------------------------------------- -DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. +Type Version Methods Requires Description +---------------------------------------------------------------------------------------------------------------- +DSC/Group 0.1.0 get, set, test All resources in the supplied configuration is treated as a group. ``` ### Example 3 - List resources with a matching type name @@ -81,12 +85,12 @@ dsc resource list DSC/* ``` ```Output -Type Version Requires Description ---------------------------------------------------------------------------------------------------------------- -DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. -DSC/ParallelGroup 0.1.0 All resources in the supplied configuration run concurrently. -DSC/PowerShellGroup 0.1.0 Resource provider to classic DSC Powershell resources. -DSC/AssertionGroup 0.1.0 `test` will be invoked for all resources in the supplied configuration. +Type Version Methods Requires Description +--------------------------------------------------------------------------------------------------------------------------------------- +DSC/AssertionGroup 0.1.0 get, set, test `test` will be invoked for all resources in the supplied configuration. +DSC/Group 0.1.0 get, set, test All resources in the supplied configuration is treated as a group. +DSC/ParallelGroup 0.1.0 get, set, test All resources in the supplied configuration run concurrently. +DSC/PowerShellGroup 0.1.0 get, set, test, export Resource provider to classic DSC Powershell resources. ``` ### Example 4 - List resources with a matching description @@ -99,11 +103,11 @@ dsc resource list --description 'supplied configuration' ``` ```Output -Type Version Requires Description --------------------------------------------------------------------------------------------------------------- -DSC/ParallelGroup 0.1.0 All resources in the supplied configuration run concurrently. -DSC/AssertionGroup 0.1.0 `test` will be invoked for all resources in the supplied configuration. -DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. +Type Version Methods Requires Description +------------------------------------------------------------------------------------------------------------------------------ +DSC/AssertionGroup 0.1.0 get, set, test `test` will be invoked for all resources in the supplied configuration. +DSC/Group 0.1.0 get, set, test All resources in the supplied configuration is treated as a group. +DSC/ParallelGroup 0.1.0 get, set, test All resources in the supplied configuration run concurrently. ``` ### Example 5 - List resources with matching tags @@ -116,10 +120,10 @@ dsc resource list --tags Windows --tags Linux ``` ```output -Type Version Requires Description -------------------------------------------------------------------------------------------------------- -Microsoft.Windows/Registry 0.1.0 Registry configuration provider for the Windows Registry -Microsoft/OSInfo 0.1.0 Returns information about the operating system. +Type Version Methods Requires Description +----------------------------------------------------------------------------------------------------------------------- +Microsoft.Windows/Registry 0.1.0 get, set, test Registry configuration provider for the Windows Registry +Microsoft/OSInfo 0.1.0 get, export Returns information about the operating system. ``` ## Arguments @@ -170,7 +174,9 @@ Mandatory: false ### -f, --format The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. +redirected or captured as a variable, the output is always a series of JSON Lines representing each +returned resource. When this option isn't specified, the output for the command shows a table +representing a summary of the returned resources. For more information, see [Output](#output). ```yaml Type: String @@ -195,5 +201,21 @@ This command returns a JSON object for each resource that includes the resource' manifest settings, and other metadata. For more information, see [dsc resource list result schema][02]. +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 resources. The summary table includes the following columns, +displayed in the listed order: + +- **Type** - The fully qualified type name of the resource. +- **Version** - The semantic version of the resource. +- **Methods** - A comma-separated list of the implemented methods for the resource. Valid methods + are `get`, `set`, `test`, and `export`. Resources that don't implement `test` rely on DSC's + synthetic test functionality. +- **Requires** - The fully qualified type name of the provider resource that DSC uses to invoke the + returned resource. +- **Description** - The short description of the resource's purpose and usage. + +To display the output objects as either JSON or YAML objects in the console, use the +[--format](#-f---format) option. + [01]: ../dsc.md#environment-variables [02]: ../../schemas/outputs/resource/list.md diff --git a/docs/reference/schemas/config/functions/concat.md b/docs/reference/schemas/config/functions/concat.md index 82184801..438123a0 100644 --- a/docs/reference/schemas/config/functions/concat.md +++ b/docs/reference/schemas/config/functions/concat.md @@ -24,22 +24,23 @@ string. Separate each value with a comma. The `concat()` function is variadic. Y least two values to the function. The function can accept any number of arguments. The function concatenates the input values without any joining character. It accepts only strings -and integers as input values. +or arrays of strings as input values. The input values must be of the same type. If you pass a +string and an array to the same function, the function raises an error. ## Examples ### Example 1 - Concatenate strings -The configuration uses the `concat()` function to join the string `abc` and the integer `123` +The configuration uses the `concat()` function to join the strings `abc` and `def` ```yaml # concat.example.1.dsc.config.yaml $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json resources: - - name: Echo 'abc123' + - name: Echo 'abcdef' type: Test/Echo properties: - text: "[concat('abc', 123)]" + output: "[concat('abc', 'def')]" ``` ```bash @@ -48,11 +49,11 @@ dsc --input-file concat.example.1.dsc.config.yaml config get ```yaml results: -- name: Echo 'abc123' +- name: Echo 'abcdef' type: Test/Echo result: actualState: - text: abc123 + output: abcdef messages: [] hadErrors: false ``` @@ -61,11 +62,11 @@ hadErrors: false ### inputValue -A value to concatenate. Each value must be either a string or an integer. The values are added to -the output string in the same order you pass them to the function. +A value to concatenate. Each value must be either a string or an array of strings. The strings are +are added to the output string in the same order you pass them to the function. ```yaml -Type: [string, integer] +Type: [string, array] Required: true MinimumCount: 2 MaximumCount: 18446744073709551615 diff --git a/docs/reference/schemas/config/functions/envvar.md b/docs/reference/schemas/config/functions/envvar.md new file mode 100644 index 00000000..5613ccb2 --- /dev/null +++ b/docs/reference/schemas/config/functions/envvar.md @@ -0,0 +1,85 @@ +--- +description: Reference for the 'envvar' DSC configuration document function +ms.date: 03/01/2024 +ms.topic: reference +title: envvar +--- + +# envvar + +## Synopsis + +Returns the value of an environment variable. + +## Syntax + +```Syntax +envvar() +``` + +## Description + +The `envvar()` function returns the value of an environment variable as a string. If the +environment variable doesn't exist, the function returns an empty string. + +## Examples + +### Example 1 - Reference DSCConfigRoot in a configuration + +When you use the `--path` option to specify a configuration document for any of the `dsc config *` +commands, DSC automatically creates the `DSCConfigRoot` environment variable and sets the value to +the parent folder of the specified configuration document. For more information, see +[dsc config command reference][01]. + +This configuration echoes that folder with the `Test/Echo` resource. + +```yaml +# ./examples/envvar.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +resources: + - name: Echo 'DSCConfigRoot' in envvar + type: Test/Echo + properties: + output: "[envvar('DSCConfigRoot')]" +``` + +```bash +dsc config get --path ~/dsc/examples/envvar.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo DSCConfigRoot + type: Test/Echo + result: + actualState: + output: ~/dsc/examples +messages: [] +hadErrors: false +``` + +## Parameters + +### variableName + +The value must be a single string representing the name of the environment variable to use. If +the value isn't a string, DSC raises an error when validating the configuration document. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The output of the function is the value of the environment variable specified with the +**variableName** parameter. If the environment variable doesn't exist, the function returns an +empty string. + +```yaml +Type: string +``` + +[01]: ../../../cli/config/command.md#environment-variables diff --git a/docs/reference/schemas/outputs/config/set.md b/docs/reference/schemas/outputs/config/set.md index 81b9effc..d902f4e0 100644 --- a/docs/reference/schemas/outputs/config/set.md +++ b/docs/reference/schemas/outputs/config/set.md @@ -70,8 +70,8 @@ Required: true #### result -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 set` command. For more +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][02]. ### messages diff --git a/docs/reference/schemas/outputs/config/test.md b/docs/reference/schemas/outputs/config/test.md index 0faa28e9..2a81a1bd 100644 --- a/docs/reference/schemas/outputs/config/test.md +++ b/docs/reference/schemas/outputs/config/test.md @@ -70,9 +70,9 @@ Required: true #### result -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 test` command. For more -information, see [dsc resource test result schema reference][02]. +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][02]. ### messages diff --git a/docs/reference/schemas/outputs/resource/get.md b/docs/reference/schemas/outputs/resource/get.md index 552d49b4..34624493 100644 --- a/docs/reference/schemas/outputs/resource/get.md +++ b/docs/reference/schemas/outputs/resource/get.md @@ -21,18 +21,33 @@ Type: object ## Description -The output from the `dsc resource get` command includes the actual state for the specified resource -instance. +Describes the return data for a DSC Resource instance from the `dsc resource get` command. The +return data is either a single object that describes the actual state of a non-nested instance or +an array of objects that describe the actual state of the nested instances for a group or adapter +resource. -## Required properties +DSC returns a [simple get response](#simple-get-response) when the instance isn't a group resource, +adapter resource, or nested inside a group or adapter resource. + +When the retrieved instance is for group resource, adapter resource, or nested inside a group or +adapter resource, DSC returns a [full get result](#full-get-result), which also includes the +resource type and instance name. + +## Simple get response + +Describes the return data for a single DSC Resource instance from the `dsc resource get` command. +This data is returned for instances that aren't group resources, adapter resources, or nested +inside a group or adapter resource. + +### Required properties The output always includes these properties: - [actualState](#actualstate) -## Properties +### Properties -### actualState +#### actualState The `actualState` property always includes the state of the instance returned when DSC invokes the resource's get operation. DSC validates this property's value against the resource's instance @@ -42,3 +57,55 @@ schema. Type: object Required: true ``` + +## Full get result + +Describes the return data for the full result of the `get` operation for a resource instance. This +data is returned: + +- For every instance in a configuration document when you use the `dsc config get` command. +- For nested instances of a group or adapter resource when you use the `dsc resource get` command. + +### Required properties + +- [name](#name) +- [type](#type) +- [result](#result) + +### Properties + +#### 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][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +The `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### result + +The `result` property includes the actual state for the resource. This value is either: + +- The [simple get response](#simple-get-response) for the instance +- An array of full get result objects for each nested instance, if the resource is a group or + adapter resource. + +```yaml +Type: [object, array] +Required: true +``` + +[01]: ../../definitions/resourceType.md diff --git a/docs/reference/schemas/outputs/resource/set.md b/docs/reference/schemas/outputs/resource/set.md index c7ab0cf8..5448938f 100644 --- a/docs/reference/schemas/outputs/resource/set.md +++ b/docs/reference/schemas/outputs/resource/set.md @@ -21,10 +21,26 @@ Type: object ## Description -The output from the `dsc resource set` command includes the state of the resource instance before -and after the set operation, and the list of properties the operation changed. +Describes the return data for a DSC Resource instance from the `dsc resource set` command. The +return data is either a single object that describes the enforced state of a non-nested instance or +an array of objects that describe the enforced state of the nested instances for a group or adapter +resource. -## Required properties +DSC returns a [simple set response](#simple-set-response) when the instance isn't a group resource, +adapter resource, or nested inside a group or adapter resource. + +When the retrieved instance is for group resource, adapter resource, or nested inside a group or +adapter resource, DSC returns a [full set result](#full-set-result), which also includes the +resource type and instance name. + +## Simple set response + +Describes the return data for a DSC Resource instance from the `dsc resource set` command. The +return data is either a single object that describes the enforced state of a non-nested instance or +an array of objects that describe the enforced state of the nested instances for a group or adapter +resource. + +### Required properties The output always includes these properties: @@ -32,9 +48,9 @@ The output always includes these properties: - [afterState](#afterstate) - [changedProperties](#changedproperties) -## Properties +### Properties -### beforeState +#### beforeState Represents the state of the instance returned before the set operation. DSC validates this property's value against the resource's instance schema. @@ -44,7 +60,7 @@ Type: object Required: true ``` -### afterState +#### afterState Represents the state of the instance returned after the set operation. DSC validates this property's value against the resource's instance schema. @@ -54,7 +70,7 @@ Type: object Required: true ``` -### changedProperties +#### 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. @@ -64,3 +80,55 @@ Type: array Required: true ItemsType: string ``` + +## Full set result + +Describes the return data for the full result of the `set` operation for a resource instance. This +data is returned: + +- For every instance in a configuration document when you use the `dsc config set` command. +- For nested instances of a group or adapter resource when you use the `dsc resource set` command. + +### Required properties + +- [name](#name) +- [type](#type) +- [result](#result) + +### Properties + +#### 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][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +The `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### result + +The `result` property includes the enforced state for the resource. This value is either: + +- The [simple set response](#simple-set-response) for the instance +- An array of full set result objects for each nested instance, if the resource is a group or + adapter resource. + +```yaml +Type: [object, array] +Required: true +``` + +[01]: ../../definitions/resourceType.md diff --git a/docs/reference/schemas/outputs/resource/test.md b/docs/reference/schemas/outputs/resource/test.md index 4df67392..2ef67f5f 100644 --- a/docs/reference/schemas/outputs/resource/test.md +++ b/docs/reference/schemas/outputs/resource/test.md @@ -21,18 +21,29 @@ Type: object ## Description -The output from the `dsc resource test` command includes the actual state for the specified -resource instance. +Describes the return data for a DSC Resource instance from the `dsc resource get` 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. -## Required properties +DSC returns a [simple test response](#simple-test-response) when the instance isn't a group +resource, adapter resource, or nested inside a group or adapter resource. + +When the retrieved instance is for group resource, adapter resource, or nested inside a group or +adapter resource, DSC returns a [full test result](#full-test-result), which also includes the +resource type and instance name. + +## Simple test response + +### Required properties The output always includes these properties: - [desiredState](#desiredstate) -## Properties +### Properties -### desiredState +#### desiredState Represents the desired state of the resource instance. DSC validates this property's value against the resource's instance schema. @@ -42,7 +53,7 @@ Type: object Required: true ``` -### actualState +#### actualState Represents the actual state of the resource instance. DSC validates this property's value against the resource's instance schema. @@ -52,7 +63,7 @@ Type: object Required: true ``` -### inDesiredState +#### inDesiredState Indicates whether the resource instance's properties are in the desired state. This value is `true` if every property is in the desired state and otherwise `false`. @@ -62,7 +73,7 @@ Type: boolean Required: true ``` -### differingProperties +#### differingProperties Defines the names of the properties that aren't in the desired state. If this value is an empty array, the instance's properties are in the desired state. @@ -72,3 +83,55 @@ Type: array Required: true ItemsType: string ``` + +## Full test result + +Describes the return data for the full result of the `test` operation for a resource instance. This +data is returned: + +- For every instance in a configuration document when you use the `dsc config test` command. +- For nested instances of a group or adapter resource when you use the `dsc resource test` command. + +### Required properties + +- [name](#name) +- [type](#type) +- [result](#result) + +### Properties + +#### 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][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +The `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### 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 + adapter resource. + +```yaml +Type: [object, array] +Required: true +``` + +[01]: ../../definitions/resourceType.md diff --git a/schemas/2023/10/bundled/outputs/config/get.json b/schemas/2023/10/bundled/outputs/config/get.json index fc58b8db..2582b395 100644 --- a/schemas/2023/10/bundled/outputs/config/get.json +++ b/schemas/2023/10/bundled/outputs/config/get.json @@ -15,24 +15,7 @@ "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", "type": "array", "items": { - "title": "Get Result", - "type": "object", - "required": [ - "name", - "type", - "result" - ], - "properties": { - "name": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" - }, - "type": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" - }, - "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json" - } - } + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.full.json" } }, "messages": { @@ -43,6 +26,46 @@ } }, "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.full.json", + "title": "dsc resource get result (full)", + "description": "Describes the return data for the full result of the `get` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config get` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource get` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json", @@ -64,7 +87,24 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json", "title": "dsc resource get result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command. The return data is either a single object that describes the actual state of a non-nested instance or an array of objects that describe the actual state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.full.json" + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.simple.json", + "title": "dsc resource get result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource get` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource get` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", "type": "object", "required": [ "actualState" @@ -77,23 +117,6 @@ } } }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json", - "title": "Messages", - "description": "A list of structured messages emitted by the DSC Resources during an operation.", - "type": "array", - "items": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/message.json" - } - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json", - "title": "Had Errors", - "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", - "type": "boolean" - }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/message.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/message.json", diff --git a/schemas/2023/10/bundled/outputs/config/set.json b/schemas/2023/10/bundled/outputs/config/set.json index ba0beff0..fe18510c 100644 --- a/schemas/2023/10/bundled/outputs/config/set.json +++ b/schemas/2023/10/bundled/outputs/config/set.json @@ -15,24 +15,7 @@ "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", "type": "array", "items": { - "title": "Set Result", - "type": "object", - "required": [ - "name", - "type", - "result" - ], - "properties": { - "name": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" - }, - "type": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" - }, - "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json" - } - } + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.full.json" } }, "messages": { @@ -43,6 +26,46 @@ } }, "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.full.json", + "title": "dsc resource set result (full)", + "description": "Describes the return data for the full result of the `set` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config set` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource set` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json", @@ -64,7 +87,24 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json", "title": "dsc resource set result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. The return data is either a single object that describes the enforced state of a non-nested instance or an array of objects that describe the enforced state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.full.json" + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.simple.json", + "title": "dsc resource set result (simple)", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource set` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", "type": "object", "required": [ "beforeState", @@ -93,23 +133,6 @@ } } }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json", - "title": "Messages", - "description": "A list of structured messages emitted by the DSC Resources during an operation.", - "type": "array", - "items": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/message.json" - } - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json", - "title": "Had Errors", - "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", - "type": "boolean" - }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/message.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/message.json", diff --git a/schemas/2023/10/bundled/outputs/config/test.json b/schemas/2023/10/bundled/outputs/config/test.json index 1403791b..6ff02e54 100644 --- a/schemas/2023/10/bundled/outputs/config/test.json +++ b/schemas/2023/10/bundled/outputs/config/test.json @@ -15,24 +15,7 @@ "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", "type": "array", "items": { - "title": "Test Result", - "type": "object", - "required": [ - "name", - "type", - "result" - ], - "properties": { - "name": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" - }, - "type": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" - }, - "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json" - } - } + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.full.json" } }, "messages": { @@ -43,6 +26,46 @@ } }, "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.full.json", + "title": "dsc resource test result (full)", + "description": "Describes the return data for the full result of the `test` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config test` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource test` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json", @@ -64,7 +87,24 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json", "title": "dsc resource test result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` 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.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.full.json" + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.simple.json", + "title": "dsc resource test result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource test` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource test` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", "type": "object", "required": [ "desiredState", @@ -99,23 +139,6 @@ } } }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/messages.json", - "title": "Messages", - "description": "A list of structured messages emitted by the DSC Resources during an operation.", - "type": "array", - "items": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/message.json" - } - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/hadErrors.json", - "title": "Had Errors", - "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", - "type": "boolean" - }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/message.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/message.json", diff --git a/schemas/2023/10/bundled/outputs/resource/get.json b/schemas/2023/10/bundled/outputs/resource/get.json index 050ea04c..97f19ff2 100644 --- a/schemas/2023/10/bundled/outputs/resource/get.json +++ b/schemas/2023/10/bundled/outputs/resource/get.json @@ -2,17 +2,92 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json", "title": "dsc resource get result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", - "type": "object", - "required": [ - "actualState" + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command. The return data is either a single object that describes the actual state of a non-nested instance or an array of objects that describe the actual state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.full.json" + } + } ], - "properties": { - "actualState": { - "title": "Actual state", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", - "type": "object" + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.simple.json", + "title": "dsc resource get result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource get` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource get` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "type": "object", + "required": [ + "actualState" + ], + "properties": { + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.full.json", + "title": "dsc resource get result (full)", + "description": "Describes the return data for the full result of the `get` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config get` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource get` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "pattern": "^[a-zA-Z0-9 ]+$", + "minLength": 1 + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json", + "title": "dsc resource get result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command. The return data is either a single object that describes the actual state of a non-nested instance or an array of objects that describe the actual state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.full.json" + } + } + ] } - }, - "$defs": {} + } } diff --git a/schemas/2023/10/bundled/outputs/resource/set.json b/schemas/2023/10/bundled/outputs/resource/set.json index cd199275..b3c7515f 100644 --- a/schemas/2023/10/bundled/outputs/resource/set.json +++ b/schemas/2023/10/bundled/outputs/resource/set.json @@ -2,33 +2,108 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json", "title": "dsc resource set result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", - "type": "object", - "required": [ - "beforeState", - "afterState", - "changedProperties" - ], - "properties": { - "beforeState": { - "title": "State before enforcing", - "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - }, - "afterState": { - "title": "State after enforcing", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", - "type": "object" + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. The return data is either a single object that describes the enforced state of a non-nested instance or an array of objects that describe the enforced state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.simple.json" }, - "changedProperties": { - "title": "Changed properties", - "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + { "type": "array", - "default": [], "items": { - "type": "string" + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.full.json" + } + } + ], + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.simple.json", + "title": "dsc resource set result (simple)", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource set` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "type": "object", + "required": [ + "beforeState", + "afterState", + "changedProperties" + ], + "properties": { + "beforeState": { + "title": "State before enforcing", + "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "afterState": { + "title": "State after enforcing", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "changedProperties": { + "title": "Changed properties", + "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.full.json", + "title": "dsc resource set result (full)", + "description": "Describes the return data for the full result of the `set` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config set` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource set` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "pattern": "^[a-zA-Z0-9 ]+$", + "minLength": 1 + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json", + "title": "dsc resource set result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. The return data is either a single object that describes the enforced state of a non-nested instance or an array of objects that describe the enforced state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.full.json" + } + } + ] } - }, - "$defs": {} + } } diff --git a/schemas/2023/10/bundled/outputs/resource/test.json b/schemas/2023/10/bundled/outputs/resource/test.json index fb88f4a4..c3750582 100644 --- a/schemas/2023/10/bundled/outputs/resource/test.json +++ b/schemas/2023/10/bundled/outputs/resource/test.json @@ -2,39 +2,114 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json", "title": "dsc resource test result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", - "type": "object", - "required": [ - "desiredState", - "actualState", - "inDesiredState", - "differingProperties" - ], - "properties": { - "desiredState": { - "title": "Desired state", - "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", - "type": "object" - }, - "actualState": { - "title": "Actual state", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - }, - "inDesiredState": { - "title": "Instance is in the desired state", - "description": "This property indicates whether the instance is in the desired state.", - "type": "boolean" + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` 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.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.simple.json" }, - "differingProperties": { - "title": "Differing properties", - "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + { "type": "array", - "default": [], "items": { - "type": "string" + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.full.json" + } + } + ], + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.simple.json", + "title": "dsc resource test result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource test` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource test` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "type": "object", + "required": [ + "desiredState", + "actualState", + "inDesiredState", + "differingProperties" + ], + "properties": { + "desiredState": { + "title": "Desired state", + "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", + "type": "object" + }, + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "inDesiredState": { + "title": "Instance is in the desired state", + "description": "This property indicates whether the instance is in the desired state.", + "type": "boolean" + }, + "differingProperties": { + "title": "Differing properties", + "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.full.json", + "title": "dsc resource test result (full)", + "description": "Describes the return data for the full result of the `test` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config test` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource test` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "pattern": "^[a-zA-Z0-9 ]+$", + "minLength": 1 + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` 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.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.full.json" + } + } + ] } - }, - "$defs": {} + } } diff --git a/schemas/2023/10/outputs/config/get.json b/schemas/2023/10/outputs/config/get.json index fc0c2083..bf3da9de 100644 --- a/schemas/2023/10/outputs/config/get.json +++ b/schemas/2023/10/outputs/config/get.json @@ -15,24 +15,7 @@ "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", "type": "array", "items": { - "title": "Get Result", - "type": "object", - "required": [ - "name", - "type", - "result" - ], - "properties": { - "name": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" - }, - "type": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" - }, - "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json" - } - } + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.full.json" } }, "messages": { diff --git a/schemas/2023/10/outputs/config/set.json b/schemas/2023/10/outputs/config/set.json index 3ebbc0db..3bee3521 100644 --- a/schemas/2023/10/outputs/config/set.json +++ b/schemas/2023/10/outputs/config/set.json @@ -15,24 +15,7 @@ "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", "type": "array", "items": { - "title": "Set Result", - "type": "object", - "required": [ - "name", - "type", - "result" - ], - "properties": { - "name": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" - }, - "type": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" - }, - "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json" - } - } + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.full.json" } }, "messages": { diff --git a/schemas/2023/10/outputs/config/test.json b/schemas/2023/10/outputs/config/test.json index 3a0c55e1..60427a95 100644 --- a/schemas/2023/10/outputs/config/test.json +++ b/schemas/2023/10/outputs/config/test.json @@ -15,24 +15,7 @@ "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", "type": "array", "items": { - "title": "Test Result", - "type": "object", - "required": [ - "name", - "type", - "result" - ], - "properties": { - "name": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" - }, - "type": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" - }, - "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json" - } - } + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.full.json" } }, "messages": { diff --git a/schemas/2023/10/outputs/resource/get.full.json b/schemas/2023/10/outputs/resource/get.full.json new file mode 100644 index 00000000..9105fdf7 --- /dev/null +++ b/schemas/2023/10/outputs/resource/get.full.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.full.json", + "title": "dsc resource get result (full)", + "description": "Describes the return data for the full result of the `get` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config get` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource get` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json" + } + } +} diff --git a/schemas/2023/10/outputs/resource/get.json b/schemas/2023/10/outputs/resource/get.json index d569b21c..e32129d3 100644 --- a/schemas/2023/10/outputs/resource/get.json +++ b/schemas/2023/10/outputs/resource/get.json @@ -2,16 +2,16 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json", "title": "dsc resource get result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", - "type": "object", - "required": [ - "actualState" - ], - "properties": { - "actualState": { - "title": "Actual state", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", - "type": "object" + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command. The return data is either a single object that describes the actual state of a non-nested instance or an array of objects that describe the actual state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.full.json" + } } - } + ] } diff --git a/schemas/2023/10/outputs/resource/get.simple.json b/schemas/2023/10/outputs/resource/get.simple.json new file mode 100644 index 00000000..edf0501c --- /dev/null +++ b/schemas/2023/10/outputs/resource/get.simple.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.simple.json", + "title": "dsc resource get result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource get` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource get` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "type": "object", + "required": [ + "actualState" + ], + "properties": { + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + } + } +} diff --git a/schemas/2023/10/outputs/resource/set.full.json b/schemas/2023/10/outputs/resource/set.full.json new file mode 100644 index 00000000..e7e71f27 --- /dev/null +++ b/schemas/2023/10/outputs/resource/set.full.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.full.json", + "title": "dsc resource set result (full)", + "description": "Describes the return data for the full result of the `set` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config set` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource set` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json" + } + } +} diff --git a/schemas/2023/10/outputs/resource/set.json b/schemas/2023/10/outputs/resource/set.json index 389f8353..5658c099 100644 --- a/schemas/2023/10/outputs/resource/set.json +++ b/schemas/2023/10/outputs/resource/set.json @@ -2,32 +2,16 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json", "title": "dsc resource set result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", - "type": "object", - "required": [ - "beforeState", - "afterState", - "changedProperties" - ], - "properties": { - "beforeState": { - "title": "State before enforcing", - "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", - "type": "object" + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. The return data is either a single object that describes the enforced state of a non-nested instance or an array of objects that describe the enforced state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.simple.json" }, - "afterState": { - "title": "State after enforcing", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - }, - "changedProperties": { - "title": "Changed properties", - "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + { "type": "array", - "default": [], "items": { - "type": "string" + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.full.json" } } - } + ] } diff --git a/schemas/2023/10/outputs/resource/set.simple.json b/schemas/2023/10/outputs/resource/set.simple.json new file mode 100644 index 00000000..bb0d895d --- /dev/null +++ b/schemas/2023/10/outputs/resource/set.simple.json @@ -0,0 +1,33 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.simple.json", + "title": "dsc resource set result (simple)", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource set` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "type": "object", + "required": [ + "beforeState", + "afterState", + "changedProperties" + ], + "properties": { + "beforeState": { + "title": "State before enforcing", + "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "afterState": { + "title": "State after enforcing", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "changedProperties": { + "title": "Changed properties", + "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } +} diff --git a/schemas/2023/10/outputs/resource/test.full.json b/schemas/2023/10/outputs/resource/test.full.json new file mode 100644 index 00000000..b2cd568d --- /dev/null +++ b/schemas/2023/10/outputs/resource/test.full.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.full.json", + "title": "dsc resource test result (full)", + "description": "Describes the return data for the full result of the `test` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config test` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource test` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json" + } + } +} diff --git a/schemas/2023/10/outputs/resource/test.json b/schemas/2023/10/outputs/resource/test.json index 90789482..a940171c 100644 --- a/schemas/2023/10/outputs/resource/test.json +++ b/schemas/2023/10/outputs/resource/test.json @@ -2,38 +2,16 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json", "title": "dsc resource test result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", - "type": "object", - "required": [ - "desiredState", - "actualState", - "inDesiredState", - "differingProperties" - ], - "properties": { - "desiredState": { - "title": "Desired state", - "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", - "type": "object" + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` 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.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.simple.json" }, - "actualState": { - "title": "Actual state", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - }, - "inDesiredState": { - "title": "Instance is in the desired state", - "description": "This property indicates whether the instance is in the desired state.", - "type": "boolean" - }, - "differingProperties": { - "title": "Differing properties", - "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + { "type": "array", - "default": [], "items": { - "type": "string" + "$ref": "/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.full.json" } } - } + ] } diff --git a/schemas/2023/10/outputs/resource/test.simple.json b/schemas/2023/10/outputs/resource/test.simple.json new file mode 100644 index 00000000..9a5221a2 --- /dev/null +++ b/schemas/2023/10/outputs/resource/test.simple.json @@ -0,0 +1,39 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.simple.json", + "title": "dsc resource test result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource test` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource test` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "type": "object", + "required": [ + "desiredState", + "actualState", + "inDesiredState", + "differingProperties" + ], + "properties": { + "desiredState": { + "title": "Desired state", + "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", + "type": "object" + }, + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "inDesiredState": { + "title": "Instance is in the desired state", + "description": "This property indicates whether the instance is in the desired state.", + "type": "boolean" + }, + "differingProperties": { + "title": "Differing properties", + "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } +} diff --git a/schemas/build.ps1 b/schemas/build.ps1 index 1b11a870..75e3d06a 100644 --- a/schemas/build.ps1 +++ b/schemas/build.ps1 @@ -21,7 +21,10 @@ param( 'JsonVSCode' 'Yaml' 'YamlVSCode' - ) + ), + + [switch] + $NoBundle ) begin { @@ -202,7 +205,11 @@ begin { [Object[]] $SchemaList, - [LocalJsonSchemaRegistry] $SchemaRegistry + [LocalJsonSchemaRegistry] + $SchemaRegistry, + + [Generic.List[string]] + $ResolvedReferences = [Generic.List[string]]::new() ) begin { @@ -212,18 +219,34 @@ begin { $References.Add($_) } } + $AddResolvedReference = { + if ($_ -notin $ResolvedReferences) { + $ResolvedReferences.Add($_) + } + } } process { if ($PSCmdlet.ParameterSetName -eq 'SchemaObject') { + # Save the schema ID for later comparison + $id = $Schema.'$id' + $Schema.GetEnumerator().ForEach({ if ($_.Key -eq '$ref' -and $_.Value -notin $References) { $References.Add($_.Value) } elseif ($_.Value -is [Object[]]) { - $NestedReferences = Get-JsonSchemaReference -SchemaList $_.Value + $RecursiveParameters = @{ + ResolvedReferences = $ResolvedReferences + SchemaList = $_.Value + } + $NestedReferences = Get-JsonSchemaReference @RecursiveParameters $NestedReferences.ForEach($AddNestedReference) } elseif ($_.Value -is [Specialized.OrderedDictionary]) { - $NestedReferences = Get-JsonSchemaReference -Schema $_.Value + $RecursiveParameters = @{ + ResolvedReferences = $ResolvedReferences + Schema = $_.Value + } + $NestedReferences = Get-JsonSchemaReference @RecursiveParameters $NestedReferences.ForEach($AddNestedReference) } }) @@ -243,13 +266,25 @@ begin { if ($null -ne $SchemaRegistry -and $References.Count -gt 0) { foreach ($Reference in $References.Clone()) { + # Avoid infinite recursion + if ($Reference -eq $id -or $Reference -in $ResolvedReferences) { + continue + } + if ($Reference -in $SchemaRegistry.Map.Keys) { + # Add current reference to the resolved list to avoid infinite recursion + $ResolvedReferences.Add($Reference) + # Resolve nested references with the schema registry $Resolving = @{ - Schema = $SchemaRegistry.Map.$Reference - SchemaRegistry = $SchemaRegistry + Schema = $SchemaRegistry.Map.$Reference + SchemaRegistry = $SchemaRegistry + ResolvedReferences = $ResolvedReferences } $NestedReferences = Get-JsonSchemaReference @Resolving + # Add resolved references to the lists of returning references $NestedReferences.ForEach($AddNestedReference) + # Also to resolved, to avoid re-resolving + $NestedReferences.ForEach($AddResolvedReference) } } } @@ -592,9 +627,11 @@ process { } if (-not (Test-Path -Path $OutputDirectory)) { + Write-Verbose "Creating a new folder for schema version: $($Config.version)" $null = New-Item -Path $OutputDirectory -ItemType Directory -Force } + Write-Verbose "Converting source schemas to JSON with interpolated values..." Get-ChildItem -Path $PSScriptRoot/src -Filter *.yaml -Recurse | ForEach-Object -Process { $SchemaContent = Get-Content -Path $_.FullName -Raw $SchemaContent = $SchemaContent -replace '', $Config.host @@ -615,6 +652,7 @@ process { | Out-File -FilePath ($SchemaPath -replace '\.yaml$', '.json') -Force } + Write-Verbose "Building schema registry..." $RegistryParameters = @{ SchemaDirectories = @( "$OutputDirectory/config" @@ -632,6 +670,10 @@ process { $SchemaRegistry + if ($NoBundle) { + return + } + $Bundles = $Config.bundle_schemas | ForEach-Object -Process { [hashtable]$Bundle = $_ $Bundle.ConfigFilePath = "$OutputDirectory/$($Bundle.ConfigFilePath)" @@ -645,6 +687,7 @@ process { ) } + Write-Verbose "Processing schema bundles: $($Bundles | ConvertTo-Json -Depth 99)" foreach ($BundleToExport in $Bundles) { if ($null -eq $BundleToExport.OutputDirectory) { $BundleToExport.OutputDirectory = "$OutputDirectory/bundled" @@ -654,21 +697,11 @@ process { if ($null -eq $BundleToExport.OutputFormat) { $BundleToExport.OutputFormat = $OutputFormat } - Write-Verbose "Exporting: $($BundleToExport | ConvertTo-Json)" + Write-Verbose "Exporting bundled schema: $($BundleToExport | ConvertTo-Json)" Export-MergedJsonSchema @BundleToExport -SchemaRegistry $SchemaRegistry -ErrorAction Stop } - # Remove VS Code keywords from non-bundled schemas - # $SchemaRegistry.FileMap.GetEnumerator() | ForEach-Object -Process { - # $SchemaPath = $_.Key - # $SchemaData = $_.Value - - # $SchemaData - # | ConvertTo-Json -Depth 99 - # | ForEach-Object { $_ -replace '\r\n', "`n" } - # | Out-File -FilePath $SchemaPath -Force - # } - + Write-Verbose "Removing VS Code keywords from non-bundled schemas..." $SchemaRegistry.FileMap.GetEnumerator() | ForEach-Object -Process { $SchemaPath = $_.Key $SchemaData = $_.Value diff --git a/schemas/src/outputs/config/get.yaml b/schemas/src/outputs/config/get.yaml index 6e731a7b..4415bf17 100644 --- a/schemas/src/outputs/config/get.yaml +++ b/schemas/src/outputs/config/get.yaml @@ -19,19 +19,7 @@ properties: DSC Configuration Document with the instance's name and type. type: array items: - title: Get Result - type: object - required: - - name - - type - - result - properties: - name: - $ref: ///definitions/instanceName.yaml - type: - $ref: ///definitions/resourceType.yaml - result: - $ref: ///outputs/resource/get.yaml + $ref: ///outputs/resource/get.full.yaml messages: $ref: ///definitions/messages.yaml hadErrors: diff --git a/schemas/src/outputs/config/set.yaml b/schemas/src/outputs/config/set.yaml index 653c1115..62b71b72 100644 --- a/schemas/src/outputs/config/set.yaml +++ b/schemas/src/outputs/config/set.yaml @@ -19,19 +19,7 @@ properties: DSC Configuration Document with the instance's name and type. type: array items: - title: Set Result - type: object - required: - - name - - type - - result - properties: - name: - $ref: ///definitions/instanceName.yaml - type: - $ref: ///definitions/resourceType.yaml - result: - $ref: ///outputs/resource/set.yaml + $ref: ///outputs/resource/set.full.yaml messages: $ref: ///definitions/messages.yaml hadErrors: diff --git a/schemas/src/outputs/config/test.yaml b/schemas/src/outputs/config/test.yaml index 28201af9..12a888e9 100644 --- a/schemas/src/outputs/config/test.yaml +++ b/schemas/src/outputs/config/test.yaml @@ -19,19 +19,7 @@ properties: DSC Configuration Document with the instance's name and type. type: array items: - title: Test Result - type: object - required: - - name - - type - - result - properties: - name: - $ref: ///definitions/instanceName.yaml - type: - $ref: ///definitions/resourceType.yaml - result: - $ref: ///outputs/resource/test.yaml + $ref: ///outputs/resource/test.full.yaml messages: $ref: ///definitions/messages.yaml hadErrors: diff --git a/schemas/src/outputs/resource/get.full.yaml b/schemas/src/outputs/resource/get.full.yaml new file mode 100644 index 00000000..4e8607c1 --- /dev/null +++ b/schemas/src/outputs/resource/get.full.yaml @@ -0,0 +1,26 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/resource/get.full.yaml + +title: dsc resource get result (full) +description: |- + Describes the return data for the full result of the `get` operation for a + resource instance. This data is returned: + + - For every instance in a configuration document when you use the + `dsc config get` command. + + - For nested instances of a group or adapter resource when you use the + `dsc resource get` command. + +type: object +required: + - name + - result + - type +properties: + name: + $ref: ///definitions/instanceName.yaml + type: + $ref: ///definitions/resourceType.yaml + result: + $ref: ///outputs/resource/get.yaml \ No newline at end of file diff --git a/schemas/src/outputs/resource/get.simple.yaml b/schemas/src/outputs/resource/get.simple.yaml new file mode 100644 index 00000000..5dd357a9 --- /dev/null +++ b/schemas/src/outputs/resource/get.simple.yaml @@ -0,0 +1,25 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/resource/get.simple.yaml + +title: dsc resource get result (simple) +description: >- + Describes the return data for a single DSC Resource instance from the + `dsc resource get` command. This data is returned for instances that aren't + group resources, adapter resources, or nested inside a group or adapter + resource. + + When you use `dsc resource get` for a group or adapter resource, the command + returns an array of full test result objects that include the name and + type for the nested instances. + +type: object +required: + - actualState +properties: + actualState: + title: Actual state + description: >- + This property always represents the current state of the DSC Resource + instance as returned by its `get` method. DSC validates this return value + against the DSC Resource's schema. + type: object \ No newline at end of file diff --git a/schemas/src/outputs/resource/get.yaml b/schemas/src/outputs/resource/get.yaml index 83104385..79d12d46 100644 --- a/schemas/src/outputs/resource/get.yaml +++ b/schemas/src/outputs/resource/get.yaml @@ -5,16 +5,13 @@ $id: ///outputs/resource/get.yaml title: dsc resource get result description: >- Describes the return data for a DSC Resource instance from the - `dsc resource get` command. + `dsc resource get` command. The return data is either a single object that + describes the actual state of a non-nested instance or an array of objects + that describe the actual state of the nested instances for a group or adapter + resource. -type: object -required: - - actualState -properties: - actualState: - title: Actual state - description: >- - This property always represents the current state of the DSC Resource - instance as returned by its `get` method. DSC validates this return value - against the DSC Resource's schema. - type: object +anyOf: + - $ref: ///outputs/resource/get.simple.yaml + - type: array + items: + $ref: ///outputs/resource/get.full.yaml diff --git a/schemas/src/outputs/resource/set.full.yaml b/schemas/src/outputs/resource/set.full.yaml new file mode 100644 index 00000000..a270409f --- /dev/null +++ b/schemas/src/outputs/resource/set.full.yaml @@ -0,0 +1,26 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/resource/set.full.yaml + +title: dsc resource set result (full) +description: |- + Describes the return data for the full result of the `set` operation for a + resource instance. This data is returned: + + - For every instance in a configuration document when you use the + `dsc config set` command. + + - For nested instances of a group or adapter resource when you use the + `dsc resource set` command. + +type: object +required: + - name + - result + - type +properties: + name: + $ref: ///definitions/instanceName.yaml + type: + $ref: ///definitions/resourceType.yaml + result: + $ref: ///outputs/resource/set.yaml \ No newline at end of file diff --git a/schemas/src/outputs/resource/set.simple.yaml b/schemas/src/outputs/resource/set.simple.yaml new file mode 100644 index 00000000..46ddccf1 --- /dev/null +++ b/schemas/src/outputs/resource/set.simple.yaml @@ -0,0 +1,46 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/resource/set.simple.yaml + +title: dsc resource set result (simple) +description: >- + Describes the return data for a DSC Resource instance from the + `dsc resource set` command. This data is returned for instances that aren't + group resources, adapter resources, or nested inside a group or adapter + resource. + + When you use `dsc resource set` for a group or adapter resource, the command + returns an array of full test result objects that include the name and + type for the nested instances. + +type: object +required: + - beforeState + - afterState + - changedProperties +properties: + beforeState: + title: State before enforcing + description: >- + This property always represents the desired state of the DSC Resource + instance before the `set` method runs. DSC validates this return value + against the DSC Resource's schema. + type: object + afterState: + title: State after enforcing + description: >- + This property always represents the current state of the DSC Resource + instance as returned by its `set` method after enforcing the desired + state. DSC validates this return value against the DSC Resource's schema. + type: object + changedProperties: + title: Changed properties + description: >- + This property always represents the list of property names for the DSC + Resource instance that the `set` method modified. When this value is an + empty array, the `set` method didn't enforce any properties for the + instance. + type: array + default: [] + items: + type: string diff --git a/schemas/src/outputs/resource/set.yaml b/schemas/src/outputs/resource/set.yaml index 1e4751a9..5bed8c7e 100644 --- a/schemas/src/outputs/resource/set.yaml +++ b/schemas/src/outputs/resource/set.yaml @@ -5,36 +5,13 @@ $id: ///outputs/resource/set.yaml title: dsc resource set result description: >- Describes the return data for a DSC Resource instance from the - `dsc resource set` command. + `dsc resource set` command. The return data is either a single object that + describes the enforced state of a non-nested instance or an array of objects + that describe the enforced state of the nested instances for a group or + adapter resource. -type: object -required: - - beforeState - - afterState - - changedProperties -properties: - beforeState: - title: State before enforcing - description: >- - This property always represents the desired state of the DSC Resource - instance before the `set` method runs. DSC validates this return value - against the DSC Resource's schema. - type: object - afterState: - title: State after enforcing - description: >- - This property always represents the current state of the DSC Resource - instance as returned by its `set` method after enforcing the desired - state. DSC validates this return value against the DSC Resource's schema. - type: object - changedProperties: - title: Changed properties - description: >- - This property always represents the list of property names for the DSC - Resource instance that the `set` method modified. When this value is an - empty array, the `set` method didn't enforce any properties for the - instance. - type: array - default: [] +anyOf: + - $ref: ///outputs/resource/set.simple.yaml + - type: array items: - type: string + $ref: ///outputs/resource/set.full.yaml diff --git a/schemas/src/outputs/resource/test.full.yaml b/schemas/src/outputs/resource/test.full.yaml new file mode 100644 index 00000000..8f6befaa --- /dev/null +++ b/schemas/src/outputs/resource/test.full.yaml @@ -0,0 +1,26 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/resource/test.full.yaml + +title: dsc resource test result (full) +description: |- + Describes the return data for the full result of the `test` operation for a + resource instance. This data is returned: + + - For every instance in a configuration document when you use the + `dsc config test` command. + + - For nested instances of a group or adapter resource when you use the + `dsc resource test` command. + +type: object +required: + - name + - result + - type +properties: + name: + $ref: ///definitions/instanceName.yaml + type: + $ref: ///definitions/resourceType.yaml + result: + $ref: ///outputs/resource/test.yaml \ No newline at end of file diff --git a/schemas/src/outputs/resource/test.simple.yaml b/schemas/src/outputs/resource/test.simple.yaml new file mode 100644 index 00000000..717d3084 --- /dev/null +++ b/schemas/src/outputs/resource/test.simple.yaml @@ -0,0 +1,51 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/resource/test.simple.yaml + +title: dsc resource test result (simple) +description: >- + Describes the return data for a single DSC Resource instance from the + `dsc resource test` command. This data is returned for instances that aren't + group resources, adapter resources, or nested inside a group or adapter + resource. + + When you use `dsc resource test` for a group or adapter resource, the command + returns an array of full test result objects that include the name and + type for the nested instances. + +type: object +required: + - desiredState + - actualState + - inDesiredState + - differingProperties +properties: + desiredState: + title: Desired state + description: >- + This property always represents the desired state of the DSC Resource + instance as specified to DSC. + type: object + actualState: + title: Actual state + description: >- + This property always represents the current state of the DSC Resource + instance as returned by its `test` method or, if the DSC Resource doesn't + define the `test` method, by its `get` method. DSC validates this return + value against the DSC Resource's schema. + type: object + inDesiredState: + title: Instance is in the desired state + description: >- + This property indicates whether the instance is in the desired state. + type: boolean + differingProperties: + title: Differing properties + description: >- + This property always represents the list of property names for the DSC + Resource instance that aren't in the desired state. When this property + is an empty array, the instance is in the desired state. + type: array + default: [] + items: + type: string diff --git a/schemas/src/outputs/resource/test.yaml b/schemas/src/outputs/resource/test.yaml index de0cb550..34317d1e 100644 --- a/schemas/src/outputs/resource/test.yaml +++ b/schemas/src/outputs/resource/test.yaml @@ -5,41 +5,13 @@ $id: ///outputs/resource/test.yaml title: dsc resource test result description: >- Describes the return data for a DSC Resource instance from the - `dsc resource test` command. + `dsc resource get` 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. -type: object -required: - - desiredState - - actualState - - inDesiredState - - differingProperties -properties: - desiredState: - title: Desired state - description: >- - This property always represents the desired state of the DSC Resource - instance as specified to DSC. - type: object - actualState: - title: Actual state - description: >- - This property always represents the current state of the DSC Resource - instance as returned by its `test` method or, if the DSC Resource doesn't - define the `test` method, by its `get` method. DSC validates this return - value against the DSC Resource's schema. - type: object - inDesiredState: - title: Instance is in the desired state - description: >- - This property indicates whether the instance is in the desired state. - type: boolean - differingProperties: - title: Differing properties - description: >- - This property always represents the list of property names for the DSC - Resource instance that aren't in the desired state. When this property - is an empty array, the instance is in the desired state. - type: array - default: [] +anyOf: + - $ref: ///outputs/resource/test.simple.yaml + - type: array items: - type: string + $ref: ///outputs/resource/test.full.yaml \ No newline at end of file