diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md index f91e8b1..9210f18 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md @@ -327,12 +327,12 @@ For more information about the formatting of the output data, see the [02]: https://jsonlines.org/ [03]: ../../schemas/outputs/resource/list.md [04]: ../../schemas/definitions/resourceKind.md -[05]: ../../schemas/outputs/resource/list.md#capabilities -[06]: ../../schemas/outputs/resource/list.md#capability-get -[07]: ../../schemas/outputs/resource/list.md#capability-set -[08]: ../../schemas/outputs/resource/list.md#capability-sethandlesexist -[09]: ../../schemas/outputs/resource/list.md#capability-whatif -[10]: ../../schemas/outputs/resource/list.md#capability-test -[11]: ../../schemas/outputs/resource/list.md#capability-delete -[12]: ../../schemas/outputs/resource/list.md#capability-export -[13]: ../../schemas/outputs/resource/list.md#capability-resolve +[05]: ../../schemas/definitions/resourceCapabilities.md +[06]: ../../schemas/definitions/resourceCapabilities.md#get +[07]: ../../schemas/definitions/resourceCapabilities.md#set +[08]: ../../schemas/definitions/resourceCapabilities.md#setHandlesExist +[09]: ../../schemas/definitions/resourceCapabilities.md#whatIf +[10]: ../../schemas/definitions/resourceCapabilities.md#test +[11]: ../../schemas/definitions/resourceCapabilities.md#delete +[12]: ../../schemas/definitions/resourceCapabilities.md#export +[13]: ../../schemas/definitions/resourceCapabilities.md#resolve diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceCapabilities.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceCapabilities.md new file mode 100644 index 0000000..6867e76 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceCapabilities.md @@ -0,0 +1,59 @@ +--- +description: JSON schema reference for resource capabilities +ms.date: 08/21/2025 +ms.topic: reference +title: DSC Resource capabilities schema reference +--- + +# DSC Resource capabilities schema reference + +## Synopsis + +Defines the operations you can invoke for a resource and how the resource behaves when invoked. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/definitions/resourceKind.json +Type: array +Required: true +ItemsMustBeUnique: true +ItemsType: string +ItemsValidValues: [ + get, + set, + setHandlesExist, + whatIf, + test, + delete, + export, + resolve + ] +``` + +## Description + +DSC resources always have at least one capability. Resource capabilities define the operations you +can invoke for a resource and how the resource behaves when invoked. + +DSC resources may have the following capabilities: + +- `get` - The resource can retrieve the current state of an instance. +- `set` - The resource can enforce the desired state for an instance. +- `setHandlesExist` - The resource handles deleting an instance during + a **Set** operation. +- `whatIf` - The resource can report how it would change state for an instance + during a **Set** operation. +- `test` - The resource implements the **Test** operation and doesn't rely on + synthetic testing. +- `delete` - The resource can remove an instance. +- `export` - The resource can enumerate every instance. +- `resolve` - The resource can resolve nested instances from an external + source. + +For more information about resource capabilities, see [DSC resource capabilities][01]. For more +information about the operations you can invoke for a resource, see [DSC resource operations][02]. + +[01]: ../../../concepts/resources/capabilities.md +[02]: ../../../concepts/resources/operations.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md index bcd429c..4b3d216 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for resource kind -ms.date: 07/03/2025 +ms.date: 08/21/2025 ms.topic: reference title: DSC Resource kind schema reference --- @@ -9,7 +9,8 @@ title: DSC Resource kind schema reference ## Synopsis -Identifies whether a resource is an adapter resource, a group resource, or a normal resource. +Identifies whether a resource is an adapter resource, a group resource, an importer resource, an +exporter resource, or a normal resource. ## Metadata @@ -22,22 +23,21 @@ ValidValues: [resource, adapter, group, importer, exporter] ## Description -DSC supports several kinds of command-based DSC Resources: +DSC supports several kinds of command resources: -- `resource` - Indicates that the manifest isn't for a group or adapter resource. +- `resource` - Indicates that the manifest is for a typical resource. - `group` - Indicates that the manifest is for a [group resource](#group-resources). - `adapter` - Indicates that the manifest is for an [adapter resource](#adapter-resources). - `importer` - Indicates that the manifest is for an [importer resource](#importer-resources). - `exporter` - Indicates that the manifest is for an [exporter resource](#exporter-resources). -When `kind` isn't defined in the resource manifest, DSC infers the value for the property. If the -`adapter` property is defined in the resource manifest, DSC infers the value of `kind` as -`adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as `resource`. -DSC can't infer whether a manifest is for a group or importer resource. +When `kind` isn't defined in the resource manifest for a command resource, DSC infers the value for +the property. If the `adapter` property is defined in the resource manifest, DSC infers the value +of `kind` as `adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as +`resource`. DSC can't infer whether a manifest is for a group, importer, or exporter resource. -When defining a group resource, always explicitly define the `kind` property in the manifest as -`group`. When defining an importer resource, always explicitly define the `kind` property in the -manifest as `importer`. +When defining a group, importer, or exporter resource with a resource manifest, always explicitly +define `kind`. ### Adapter resources @@ -174,10 +174,10 @@ The following examples show valid and invalid references and dependencies. The e This example configuration defines several valid references and dependencies. It also defines two instances of the `Microsoft.DSC/Group` resource, one nested inside the other. -The top level instance of the `Microsoft.DSC.Debug/Echo` resource references and depends on the top-level instance -of the `Microsoft/OSInfo` resource. The top-level instances of the `Microsoft.DSC.Debug/Echo` and -`Microsoft/OSInfo` resources both depend on the top-level instance of the `Microsoft.DSC/Group` -resource. +The top level instance of the `Microsoft.DSC.Debug/Echo` resource references and depends on the +top-level instance of the `Microsoft/OSInfo` resource. The top-level instances of the +`Microsoft.DSC.Debug/Echo` and `Microsoft/OSInfo` resources both depend on the top-level instance +of the `Microsoft.DSC/Group` resource. ```yaml # yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json @@ -206,9 +206,9 @@ resources: ``` The top-level instance of `Microsoft.DSC/Group` defines three nested resource instances: -`Microsoft.DSC.Debug/Echo`, `Microsoft/OSInfo`, and `Microsoft.DSC/Group`. As at the top-level, the `Microsoft.DSC.Debug/Echo` -instance references and depends on the adjacent nested`Microsoft/OSInfo` instance and that instance -depends on the adjacent nested `Microsoft.DSC/Group` instance. +`Microsoft.DSC.Debug/Echo`, `Microsoft/OSInfo`, and `Microsoft.DSC/Group`. As at the top-level, the +`Microsoft.DSC.Debug/Echo` instance references and depends on the adjacent nested`Microsoft/OSInfo` +instance and that instance depends on the adjacent nested `Microsoft.DSC/Group` instance. ```yaml # Other top-level instances snipped for brevity @@ -237,8 +237,8 @@ depends on the adjacent nested `Microsoft.DSC/Group` instance. ``` Finally, the nested instance of `Microsoft.DSC/Group` defines two nested instances. The deeply -nested instance of `Microsoft.DSC.Debug/Echo` references and depends on the deeply nested instance of -`Microsoft/OSInfo`. +nested instance of `Microsoft.DSC.Debug/Echo` references and depends on the deeply nested instance +of `Microsoft/OSInfo`. ```yaml - name: Top level group @@ -338,9 +338,9 @@ resources: #### Example 2 - Invalid reference and dependency on a nested instance -This example configuration is invalid, because the top-level instance of the `Microsoft.DSC.Debug/Echo` resource -references and depends on the nested `Microsoft/OSInfo` instance. The nested instance is external -to the top-level instance, not adjacent. +This example configuration is invalid, because the top-level instance of the +`Microsoft.DSC.Debug/Echo` resource references and depends on the nested `Microsoft/OSInfo` +instance. The nested instance is external to the top-level instance, not adjacent. ```yaml # yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json @@ -367,9 +367,9 @@ resources: #### Example 3 - Invalid reference and dependency on an external instance -This example configuration is invalid, because the nested instance of the `Microsoft.DSC.Debug/Echo` resource -references and depends on the top-level `Microsoft/OSInfo` instance. The top-level instance is -external to the nested instance, not adjacent. +This example configuration is invalid, because the nested instance of the +`Microsoft.DSC.Debug/Echo` resource references and depends on the top-level `Microsoft/OSInfo` +instance. The top-level instance is external to the nested instance, not adjacent. ```yaml # yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/metadata/Microsoft.DSC/properties.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/metadata/Microsoft.DSC/properties.md index 827f309..ecd32e4 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/metadata/Microsoft.DSC/properties.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/metadata/Microsoft.DSC/properties.md @@ -13,7 +13,19 @@ Metadata properties used and returned by DSC for configuration and resource oper ## Description -Blah +The `Microsoft.DSC` metadata object captures execution details that DSC adds to +command output and, when applicable, to resource results. It describes what +operation ran, when it started and finished, how long it took, the security +context DSC ran under, and the DSC version that produced the output. These +properties are informational and help with diagnostics, auditing, and tooling. + +Not every property is present for every operation. For example, `executionType` +is only meaningful for `Set` (and is `WhatIf` when you invoke DSC with +`--whatIf`), while `operation` is always provided. Timestamps use RFC 3339 +`date-time` format, and durations use the ISO 8601 `duration` format. + +Consumers should tolerate additional, future metadata fields. Producers should +preserve unknown metadata they do not interpret. ## Properties diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md index 30f082c..0299dfd 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource list' command. -ms.date: 07/03/2025 +ms.date: 08/21/2025 ms.topic: reference title: dsc resource list result schema reference --- @@ -79,70 +79,23 @@ Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z ### capabilities -Defines the operations and behaviors the resource is implemented to support. This property is an -array of capabilities. Resources always have the `Get` capability, but the other capabilities are -optional and depend on the resource. - -The following list describes the available capabilities for a resource: - -- `get` - The resource supports retrieving the current state of an - instance. All DSC Resources must have this capability. A resource has this capability when it - defines the mandatory [get][07] property in its resource manifest. -- `set` - The resource supports enforcing the desired state of an - instance. A resource has this capability when it defines the [set][08] property in its resource - manifest. Resources without this capability can't be used with the [dsc resource set][09] or - [dsc config set][10] commands unless they're in a Microsoft.DSC/Assertion group as a nested - instance. -- `setHandlesExist` - The resource supports the - [_exist property][11] directly. A resource has this capability when it defines the - [handlesExist][12] property as `true` in the definition of the [set][08] command property in its - resource manifest. - - When a resource has this capability, the `_exist` property is part of the resource's instance - schema and the resource handles deleting instances of the resource in its `set` command. - - When a resource doesn't have this capability, when DSC finds an instance of the resource with - `_exist` set to `false`, it handles calling the [delete][13] operation for the resource. - - If the resource doesn't have this capability or the `delete` capability, DSC raises an error when - an instance defines `_exist` as `false`. -- `whatIf` - The resource supports returning explicit information - about how it will modify state when a user calls [dsc config set][10] with the [--what-if][14] - option. A resource has this capability when it defines the [What-if operation][15] in its - resource manifest. - - When a resource has this capability, DSC calls the defined command with its arguments when a - user executes the `dsc config set` command with the `--what-if` option. - - When a resource doesn't have this capability, DSC synthesizes how the resource will change and - instance by converting the `Test` result for the instance into a `Set` result. The synthetic - operation can't indicate potential issues or changes that can't be determined by comparing the - result of the `Test` operation against the resource's desired state. For example, the credentials - used to test a resource might be valid for that operation, but not have permissions to actually - modify the system state. Only a resource with this capability can fully report whether and how - the resource will change system state. -- `test` - The resource supports validating the desired state of an - instance against the current state of the instance. A resource has this capability when it - defines the [test][16] property in its resource manifest. - - If a resource doesn't have the `test` capability, DSC uses a synthetic test for instances of the - resource. The synthetic test compares each property for the desired state of an instance against - the actual state. The synthetic test uses strict, case-sensitive equivalence. If the desired - state for a property and the actual state aren't the same, DSC marks the property as out of the - desired state. -- `delete` - The resource supports removing an instance. A resource - has this capability when it defines the [delete][13] property in its resource manifest. This - capability isn't mutually exclusive with the `setHandlesExist` property. A resource can handle - the `_exist` property in set operations and be called directly with [dsc resource delete][17] to - remove an instance. -- `export` - The resource supports enumerating every instance of - the resource. A resource has this capability when it defines the [export][18] property in its - resource manifest. Only resources with this capability are usable with the - [dsc resource export][19] and [dsc config export][20] commands. -- `resolve` - The resource supports resolving nested resource - instances from an external source. A resource has this capability when it defines the - [resolve][21] property in its resource manifest. This functionality is primarily used by - [importer resources][22]. +DSC resources always have at least one capability. Resource capabilities define the operations you +can invoke for a resource and how the resource behaves when invoked. + +DSC resources may have the following capabilities: + +- `get` - The resource can retrieve the current state of an instance. +- `set` - The resource can enforce the desired state for an instance. +- `setHandlesExist` - The resource handles deleting an instance during a **Set** operation. +- `whatIf` - The resource can report how it would change state for an instance during a **Set** + operation. +- `test` - The resource implements the **Test** operation and doesn't rely on synthetic testing. +- `delete` - The resource can remove an instance. +- `export` - The resource can enumerate every instance. +- `resolve` - The resource can resolve nested instances from an external source. + +For more information about resource capabilities, see [DSC resource capabilities][07]. For more +information about the operations you can invoke for a resource, see [DSC resource operations][08]. ```yaml Type: array @@ -239,7 +192,7 @@ Required: true Represents the values defined in the resource's manifest. This value is `null` for resources that aren't command-based. For more information on the value for this property, see -[Command-based DSC Resource manifest schema reference][23]. +[Command-based DSC Resource manifest schema reference][09]. ```yaml Type: [object, 'null'] @@ -253,20 +206,6 @@ Required: true [04]: ../../definitions/resourceKind.md#group-resources [05]: ../../resource/manifest/root.md#kind [06]: ../../definitions/resourceKind.md -[07]: ../../resource/manifest/get.md -[08]: ../../resource/manifest/set.md -[09]: ../../../cli/resource/set.md -[10]: ../../../cli/config/set.md -[11]: ../../resource/properties/exist.md -[12]: ../../resource/manifest/set.md#handlesexist -[13]: ../../resource/manifest/delete.md -[14]: ../../../cli/config/set.md#--what-if -[15]: ../../resource/manifest/whatif.md -[16]: ../../resource/manifest/test.md -[17]: ../../../cli/resource/delete.md -[18]: ../../resource/manifest/export.md -[19]: ../../../cli/resource/export.md -[20]: ../../../cli/config/export.md -[21]: ../../resource/manifest/resolve.md -[22]: ../../definitions/resourceKind.md#importer-resources -[23]: ../../resource/manifest/root.md +[07]: ../../../../concepts/resources/capabilities.md +[08]: ../../../../concepts/resources/operations.md +[09]: ../../resource/manifest/root.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md index 1c7628d..2d6ebf9 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a DSC Resource manifest -ms.date: 07/03/2025 +ms.date: 08/21/2025 ms.topic: reference title: Command-based DSC Resource manifest schema reference --- @@ -38,6 +38,7 @@ The manifest must include these properties: - [$schema](#schema) - [type](#type) - [version](#version) +- [get](#get) ## Properties @@ -166,12 +167,12 @@ Required: false ### kind The `kind` property defines how DSC should handle the resource. DSC supports several kinds -ofcommand-based DSC Resources: `resource`, `group`, `adapter`, `importer`, and `exporter`. +of DSC resources: `resource`, `group`, `adapter`, `importer`, and `exporter`. When `kind` isn't defined in the resource manifest, DSC infers the value for the property. If the `adapter` property is defined in the resource manifest, DSC infers the value of `kind` as `adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as `resource`. -DSC can't infer whether a manifest is for a group` or importer resource. +DSC can't infer whether a manifest is for a `group` or `importer` resource. When defining a group resource, always explicitly define the `kind` property in the manifest as `group`. When defining an importer resource, always explicitly define the `kind` property in the diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md index 7a0f9e4..cd451c2 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md @@ -256,6 +256,6 @@ ValidValues: [state, stateAndDiff] [01]: ../properties/exist.md [02]: ./root.md#schema-1 -[03]: ../../outputs/resource/list.md#capability-sethandlesexist -[04]: ../../outputs/resource/list.md#capabilities +[03]: ../../definitions/resourceCapabilities.md#setHandlesExist +[04]: ../../definitions/resourceCapabilities.md [05]: ./delete.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md index 404806d..003ac47 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/whatif.md @@ -278,6 +278,6 @@ ValidValues: [state, stateAndDiff] [03]: ./set.md [04]: ../properties/exist.md [05]: ./root.md#schema-1 -[06]: ../../outputs/resource/list.md#capability-sethandlesexist -[07]: ../../outputs/resource/list.md#capabilities +[06]: ../../definitions/resourceCapabilities.md#setHandlesExist +[07]: ../../definitions/resourceCapabilities.md [08]: ./delete.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/delete.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/delete.md new file mode 100644 index 0000000..a759e98 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/delete.md @@ -0,0 +1,26 @@ +--- +description: JSON schema reference for the expected stdout from the delete resource operation +ms.date: 08/21/2025 +ms.topic: reference +title: DSC resource delete operation stdout schema reference +--- + +# DSC resource delete operation stdout schema reference + +## Synopsis + +DSC doesn't expect the **Delete** operation for a resource to return any JSON to stdout. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/delete.json +Type: 'null' +``` + +## Description + +DSC resources that implement the **Delete** operation shouldn't emit any data to stdout. DSC +doesn't expect any output for the **Delete** operation and ignores any data emitted to stdout when +invoking the operation. diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/export.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/export.md new file mode 100644 index 0000000..dc43ab0 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/export.md @@ -0,0 +1,73 @@ +--- +description: JSON schema reference for the expected stdout from the export resource operation +ms.date: 08/21/2025 +ms.topic: reference +title: DSC resource export operation stdout schema reference +--- + +# DSC resource export operation stdout schema reference + +## Synopsis + +Represents the actual state of a resource instance in DSC. DSC expects every JSON Line emitted to +stdout for the **Export** operation to adhere to this schema. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/export.json +Type: object +``` + +## Description + +DSC expects a resource implementing the **Export** operation to return a series of JSON Lines. + +The data that DSC expects depends on whether the resource kind is defined as `exporter`: + +- When the resource kind is `exporter`, DSC expects the resource to return JSON Lines representing + DSC resource instance definitions to recursively export. +- When the resource kind isn't `exporter`, DSC expects the resource to return JSON Lines + representing the actual state of every instance of the resource on the system. + +## Typical resource expected output + +DSC expects a typical resource implementing the **Export** operation to return a series of JSON +Lines. + +Each JSON Line represents the actual state of a resource instance in DSC. DSC expects every JSON +Line emitted to stdout for the **Export** operation to adhere to this schema. + +The output must be a JSON object. The object must be a valid representation of an instance of the +resource. + +Command resources define their instance schema with the [schema.command][01] or +[schema.embedded][02] fields in their resource manifest. If a command resource returns JSON that is +invalid against the resource instance schema, DSC raises an error. + +Adapted resource instances are validated by their adapter when the adapter invokes them. + +## Exporter resource expected output + +DSC expects an exporter resource (one with the [kind][03] field in its manifest set to `exporter`) +to return a series of JSON Lines. + +Each JSON Line represents a DSC resource instance definition to recursively invoke the **Export** +operation for. DSC expects every JSON Line emitted to stdout for the **Export** operation to adhere +to this schema. + +The output must be a JSON object adhering to [DSC resource instance][04] schema, rather than the +instance schema for a specific resource. DSC expects the object to define at least the [name][05] +and [type][06] fields. If the object defines the [properties][07] field, DSC passes those +properties to the resource when recursively exporting it so that the resource may filter the +exported instance results. + + +[01]: ../manifest/schema/property.md +[02]: ../manifest/schema/embedded.md +[03]: ../manifest/root.md#kind +[04]: ../../config/resource.md +[05]: ../../config/resource.md#name +[06]: ../../config/resource.md#type +[07]: ../../config/resource.md#properties-1 diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/get.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/get.md new file mode 100644 index 0000000..5af4a3f --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/get.md @@ -0,0 +1,39 @@ +--- +description: JSON schema reference for the expected stdout from the get resource operation +ms.date: 08/21/2025 +ms.topic: reference +title: DSC resource get operation stdout schema reference +--- + +# DSC resource get operation stdout schema reference + +## Synopsis + +Represents the actual state of a resource instance in DSC. DSC expects the JSON Line emitted to +stdout for the **Get** operation to adhere to this schema. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/get.json +Type: object +``` + +## Description + +Represents the actual state of a resource instance in DSC. DSC expects the JSON Line emitted to +stdout for the **Get** operation to adhere to this schema. + +The output must be a JSON object. The object must be a valid representation of an instance of the +resource. + +Command resources define their instance schema with the [schema.command][01] or +[schema.embedded][02] fields in their resource manifest. If a command resource returns JSON that is +invalid against the resource instance schema, DSC raises an error. + +Adapted resource instances are validated by their adapter when the adapter invokes them. + + +[01]: ../manifest/schema/property.md +[02]: ../manifest/schema/embedded.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/index.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/index.md new file mode 100644 index 0000000..c953d1f --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/index.md @@ -0,0 +1,25 @@ +--- +description: Overview for the JSON Schemas defining expected stdout for DSC Resource operations. +ms.date: 08/21/2025 +ms.topic: reference +title: Overview of DSC resource operation stdout schemas +--- + +# Overview of DSC resource operation stdout schemas + +DSC is designed around strong contracts and data models to define how resources integrate into DSC +and the wider ecosystem. As part of this contract, DSC defines JSON Schemas for the expected text +resources emit to stdout for each resource operation. + +The following schemas describe the expected output for each operation and how DSC validates the +data a resource emits: + +- [DSC resource delete operation stdout schema reference](./delete.md) +- [DSC resource export operation stdout schema reference](./export.md) +- [DSC resource get operation stdout schema reference](./get.md) +- [DSC resource list operation stdout schema reference](./list.md) +- [DSC resource resolve operation stdout schema reference](./resolve.md) +- [DSC resource schema operation stdout schema reference](./schema.md) +- [DSC resource test operation stdout schema reference](./test.md) +- [DSC resource validate operation stdout schema reference](./validate.md) +- [DSC resource what-if operation stdout schema reference](./whatIf.md) diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/list.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/list.md new file mode 100644 index 0000000..2d64a35 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/list.md @@ -0,0 +1,195 @@ +--- +description: JSON schema reference for the expected stdout from the list resource operation +ms.date: 08/21/2025 +ms.topic: reference +title: DSC resource list operation stdout schema reference +--- + +# DSC resource list operation stdout schema reference + +## Synopsis + +Defines the representation of an adapted resource in DSC. DSC expects every JSON Line emitted to +stdout for the **List** operation to adhere to this schema. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/list.json +Type: object +``` + +## Description + +Defines the representation of an adapted resource in DSC. DSC expects every JSON Line emitted to +stdout for the **List** operation to adhere to this schema. + +DSC includes the following adapter resources: + +- [Microsoft.DSC/PowerShell][01] run PowerShell and enables you to use PowerShell DSC (PSDSC) +resources implemented as PowerShell classes in DSC. +- [Microsoft.Windows/WindowsPowerShell][02] runs Windows PowerShell and enables you to use any +available PSDSC resources in DSC. This adapter is only available when you install DSC on +Windows. +- [Microsoft.Windows/WMI][03] enables you to use WMI classes as resources in DSC. This adapter is +only available when you install DSC on Windows. + +## Required Properties + +The output for the `discover` operation must include these properties: + +- [type](#type) +- [kind](#kind) +- [version](#version) +- [capabilities](#capabilities) +- [path](#path) +- [directory](#directory) +- [implementedAs](#implementedas) +- [properties](#properties-1) +- [requireAdapter](#requireadapter) + +## Properties + +### type + +The `type` property represents the fully qualified type name of the resource. It's used to specify +the resource in configuration documents and as the value of the `--resource` flag when using the +`dsc resource *` commands. For more information about resource type names, see +[DSC Resource fully qualified type name schema reference][04]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### kind + +The `kind` property defines how DSC should handle the adapted resource. DSC supports several kinds +of resources: `resource`, `group`, `adapter`, `importer`, and `exporter`. + +For more information, see [DSC resource kinds][05]. + +```yaml +Type: string +Required: false +ValidValues: [resource, adapter, group, importer, exporter] +``` + +### version + +The `version` property represents the current version of the adapted resource as a valid semantic +version (semver) string. The version applies to the adapted resource, not the software it manages. + +```yaml +Type: string +Required: true +Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +``` + +### capabilities + +Defines the list of capabilities for the adapted resource. DSC resources always have at least one +capability. Resource capabilities define the operations you can invoke for a resource and how the +resource behaves when invoked. + +DSC resources may have the following capabilities: + +- `get` - The resource can retrieve the current state of an instance. +- `set` - The resource can enforce the desired state for an instance. +- `setHandlesExist` - The resource handles deleting an instance during a **Set** operation. +- `whatIf` - The resource can report how it would change state for an instance during a **Set** operation. +- `test` - The resource implements the **Test** operation and doesn't rely on synthetic testing. +- `delete` - The resource can remove an instance. +- `export` - The resource can enumerate every instance. +- `resolve` - The resource can resolve nested instances from an external source. + +For more information about resource capabilities, see [DSC resource capabilities][06]. For more +information about the operations you can invoke for a resource, see [DSC resource operations][07]. + +```yaml +Type: array +Required: true +ItemsMustBeUnique: true +ItemsType: string +ItemsValidValues: [ + get, + set, + setHandlesExist, + whatIf, + test, + delete, + export, + resolve + ] +``` + +### path + +Indicates the path to the adapted resource on the file system. + +```yaml +Type: string +Required: true +``` + +### directory + +Indicates the path to the folder containing the adapted resource on the file system. + +```yaml +Type: string +Required: true +``` + +### implementedAs + +Indicates that the adapted resource uses a custom implementation. The name can be used to +distinguish between different implementations for the adapted resources. + +```yaml +Type: string +Required: true +``` + +### author + +Indicates the name of the person or organization that developed and maintains the adapted Resource. + +```yaml +Type: [string, 'null'] +Required: false +Pattern: ^\w+( \w+)* +``` + +### properties + +Defines the adapted resource's property names. + +```yaml +Type: array +Required: false +ItemsType: string +ItemsPattern: ^\w+$ +``` + +### requireAdapter + +Defines the fully qualified type name of the adapter that the adapted resource depends on. An +adapter should always set this value to its own fully qualified resource type name. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + + +[01]: ../../../resources/Microsoft/DSC/PowerShell/index.md +[02]: ../../../resources/Microsoft/Windows/WindowsPowerShell/index.md +[03]: ../../../resources/Microsoft/Windows/WMI/index.md +[04]: ../../definitions/resourceType.md +[05]: ../../../../concepts/resources/kinds.md +[06]: ../../../../concepts/resources/capabilities.md +[07]: ../../../../concepts/resources/operations.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/resolve.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/resolve.md new file mode 100644 index 0000000..7c19b0f --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/resolve.md @@ -0,0 +1,64 @@ +--- +description: JSON schema reference for the expected stdout from the resolve resource operation +ms.date: 08/21/2025 +ms.topic: reference +title: DSC resource resolve operation stdout schema reference +--- + +# DSC resource resolve operation stdout schema reference + +## Synopsis + +Defines the representation of a resolved configuration document. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/resolve.json +Type: object +``` + +## Description + +Defines the representation of a resolved configuration document. DSC expects the JSON Line emitted +to stdout for the **Resolve** operation to adhere to this schema. + +## Required Properties + +The output object for the **Resolve** operation must include these properties: + +- [configuration](#configuration) + +## Properties + +### configuration + +Defines the resolved configuration document. If the configuration document defines any parameters, +values for those parameters may be retrieved from the `parameters` property of the **Resolve** +operation output. + +For more information, see [DSC Configuration document schema reference][01] + +```yaml +Type: object +Required: true +``` + +### parameters + +The `parameters` property defines the set of resolved parameter values for the resolved +configuration document. If the `parameters` property is omitted from the output for the **Resolve** +operation, DSC doesn't pass any parameters to the resolved configuration when invoking operations +on it. + +Each property of this object represents a different resolved parameter. The property name +identifies the name of a parameter. The property value is the resolved value for the parameter. + +```yaml +Type: object +Required: false +``` + + +[01]: ../../config/document.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/schema.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/schema.md new file mode 100644 index 0000000..f7278d3 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/schema.md @@ -0,0 +1,34 @@ +--- +description: JSON schema reference for the expected stdout from the schema resource command +ms.date: 08/21/2025 +ms.topic: reference +title: DSC resource schema command stdout schema reference +--- + +# DSC resource schema command stdout schema reference + +## Synopsis + +Represents the JSON Schema that validates instances of the resource. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/schema.json +Type: object +``` + +## Description + +Represents the JSON Schema that validates instances of the resource. DSC expects a resource that +defines the [`schema.command`][01] field in its resource manifest to return this value for that +command. + +The output must be a JSON object. The object must be a valid JSON Schema. For more information +about what DSC expects for resource instance JSON Schemas, see +[DSC Resource manifest embedded schema reference][02], which describes the expectations in full. + + +[01]: ../manifest/schema/property.md +[02]: ../manifest/schema/embedded.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/set.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/set.md new file mode 100644 index 0000000..21b92d2 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/set.md @@ -0,0 +1,93 @@ +--- +description: JSON schema reference for the expected stdout from the set resource operation +ms.date: 08/21/2025 +ms.topic: reference +title: DSC resource set operation stdout schema reference +--- + +# DSC resource set operation stdout schema reference + +## Synopsis + +Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/set.json +``` + +## Description + +Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation. + +DSC expects this output for both actual **Set** operations and **Set** operations in `whatIf` mode. +If the resource has the `whatIf` capability, the output should be the same for both modes. + +DSC expects different output from the command resource depending on the definition of +[set.return][01] in the resource manifest: + +- If the field isn't defined, DSC doesn't expect the resource to return any JSON to stdout. + Instead, DSC invokes the **Get** operation on the resource after the **Set** operation concludes + and synthesizes the **Set** result, including the after state of the resource and the list of + changed properties. +- If the field is defined as `state`, DSC expects the resource to emit a JSON Line to stdout + representing the actual state of the resource instance after the **Set** operation changes the + system. +- If the field is defined as `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The + first JSON Line should be an object representing the actual state of the resource after the + **Set** operation. The second JSON Line should be an array representing the names of the resource + properties that the operation changed on the system. + +## Null output + +When a command resource doesn't define [set.return][01] in its resource manifest, DSC doesn't +expect the resource to emit any JSON to stdout for the **Set** operation. + +```yaml +type: 'null' +``` + +## state output + +When a command resource defines [set.return][01] in its manifest as `state` or `stateAndDiff`, DSC +expects the resource to emit a JSON Line to stdout representing the actual state of the resource +instance after the **Set** operation changes the system. + +The output must be a JSON object. The object must be a valid representation of an instance of the +resource. + +Command resources define their instance schema with the [schema.command][02] or +[schema.embedded][03] fields in their resource manifest. If a command resource returns JSON that is +invalid against the resource instance schema, DSC raises an error. + +Adapted resource instances are validated by their adapter when the adapter invokes them. + +```yaml +type: object +``` + +## diff output + +When a command resource defines [set.return][01] in its manifest as `stateAndDiff`, DSC expects the +resource to emit a second JSON Line to stdout representing the names of the resource properties +that the operation changed on the system. + +This output must be emitted after the JSON Line representing the state of the resource instance +after the operation changes the system. + +The output must be a JSON array. The array may be empty, or it may contain one or more strings. +Each string in the array must be the name of one of the resource's properties. Each string in the +array must be unique. + +```yaml +Type: array +ItemsMustBeUnique: true +ItemsType: string +``` + + +[01]: ../manifest/set.md#return +[02]: ../manifest/schema/property.md +[03]: ../manifest/schema/embedded.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/test.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/test.md new file mode 100644 index 0000000..faee898 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/test.md @@ -0,0 +1,69 @@ +--- +description: JSON schema reference for the expected stdout from the test resource operation +ms.date: 08/21/2025 +ms.topic: reference +title: DSC resource test operation stdout schema reference +--- + +# DSC resource test operation stdout schema reference + +## Synopsis + +Defines the JSON DSC expects a resource to emit to stdout for the **Test** operation. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/test.json +``` + +## Description + +Defines the JSON DSC expects a resource to emit to stdout for the **Test** operation. + +DSC expects different output from the command resource depending on the definition of +[test.return][01] in the resource manifest: + +- If the field is omitted or defined as `state` (the default value), DSC expects the resource to + emit a JSON Line to stdout representing the actual state of the resource instance with the + [_inDesiredState][02] canonical resource property included in the returned object. +- If the field is defined as `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The + first JSON Line should be an object representing the actual state of the resource instance with + the `_inDesiredState` included in the returned object. The second JSON Line should be an array + representing the names of the resource properties that aren't in the desired state. + +## state output + +For the **Test** operation, DSC always expects the resource to emit a JSON Line to stdout +representing the actual state of the resource instance with the [_inDesiredState][02] canonical +resource property included in the returned object. + +The output must be a JSON object. The object must be a valid representation of an instance of the +resource. + +Command resources define their instance schema with the [schema.command][03] or +[schema.embedded][04] fields in their resource manifest. If a command resource returns JSON that is +invalid against the resource instance schema, DSC raises an error. + +Adapted resource instances are validated by their adapter when the adapter invokes them. + +## diff output + +When a command resource defines [test.return][01] in its manifest as `stateAndDiff`, DSC expects +the resource to emit a second JSON Line to stdout representing the names of the resource properties +that aren't in the desired state. + +This output must be emitted after the JSON Line representing the actual state of the resource +instance with the [_inDesiredState][02] canonical resource property included in the returned +object. + +The output must be a JSON array. The array may be empty, or it may contain one or more strings. +Each string in the array must be the name of one of the resource's properties. Each string in the +array must be unique. The array should never include the `_inDesiredState` property. + + +[01]: ../manifest/test.md#return +[02]: ../properties/inDesiredState.md +[03]: ../manifest/schema/property.md +[04]: ../manifest/schema/embedded.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/validate.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/validate.md new file mode 100644 index 0000000..c7896e1 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/validate.md @@ -0,0 +1,58 @@ +--- +description: JSON schema reference for the expected stdout from the validate resource operation +ms.date: 08/21/2025 +ms.topic: reference +title: DSC resource validate operation stdout schema reference +--- + +# DSC resource validate operation stdout schema reference + +## Synopsis + +Defines the JSON DSC expects a resource to emit to stdout for the **Validate** operation. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/validate.json +Type: object +``` + +## Description + +Defines the JSON DSC expects a resource to emit to stdout for the **Validate** operation. + +DSC expects the resource to return a JSON object that indicates whether the instance is valid and +optionally a string indicating how the resource is invalid. + +## Required properties + +The output object for the **Validate** operation must include these properties: + +- [valid](#valid) + +## Properties + +### valid + +Indicates whether the instance is valid for the resource. When the value is `true`, the instance is +valid for the resource. + +```yaml +Type: boolean +Required: true +``` + +### reason + +Describes how and why the instance is invalid for the resource. Always define this property in the +output object when `valid` is `false`. Don't define this property in the output object when `valid` +is `true`. + +```yaml +Type: string +Required: false +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/whatIf.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/whatIf.md new file mode 100644 index 0000000..919b897 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/whatIf.md @@ -0,0 +1,79 @@ +--- +description: JSON schema reference for the expected stdout from the set resource operation in what-if mode +ms.date: 08/21/2025 +ms.topic: reference +title: DSC resource what-if operation stdout schema reference +--- + +# DSC resource what-if operation stdout schema reference + +## Synopsis + +Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation in what-if +mode. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/whatIf.json +``` + +## Description + +Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation in what-if +mode. + +DSC expects different output from the command resource depending on the definition of +[whatIf.return][01] in the resource manifest: + +- If the field is defined as `state`, DSC expects the resource to emit a JSON Line to stdout + representing the actual state of the resource instance after the **Set** operation changes the + system. +- If the field is defined as `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The + first JSON Line should be an object representing the actual state of the resource after the + **Set** operation. The second JSON Line should be an array representing the names of the resource + properties that the operation changed on the system. + +## state output + +When a command resource defines [whatIf.return][01] in its manifest as `state` or `stateAndDiff`, +DSC expects the resource to emit a JSON Line to stdout representing the expected actual state of +the resource instance after the **Set** operation changes the system. + +The output must be a JSON object. The object must be a valid representation of an instance of the +resource. + +Command resources define their instance schema with the [schema.command][02] or +[schema.embedded][03] fields in their resource manifest. If a command resource returns JSON that is +invalid against the resource instance schema, DSC raises an error. + +Adapted resource instances are validated by their adapter when the adapter invokes them. + +```yaml +type: object +``` + +## diff output + +When a command resource defines [whatIf.return][01] in its manifest as `stateAndDiff`, DSC expects +the resource to emit a second JSON Line to stdout representing the names of the resource properties +that the operation changed on the system. + +This output must be emitted after the JSON Line representing the state of the resource instance +after the operation changes the system. + +The output must be a JSON array. The array may be empty, or it may contain one or more strings. +Each string in the array must be the name of one of the resource's properties. Each string in the +array must be unique. + +```yaml +Type: array +ItemsMustBeUnique: true +ItemsType: string +``` + + +[01]: ../manifest/whatif.md#return +[02]: ../manifest/schema/property.md +[03]: ../manifest/schema/embedded.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml b/dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml index de60218..b654aee 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/toc.yml @@ -135,6 +135,30 @@ items: href: resource/properties/purge.md - name: _rebootRequested href: resource/properties/rebootRequested.md + - name: Resource operation stdout schemas + items: + - name: Overview + href: resource/stdout/index.md + - name: delete operation stdout + href: resource/stdout/delete.md + - name: export operation stdout + href: resource/stdout/export.md + - name: get operation stdout + href: resource/stdout/get.md + - name: list operation stdout + href: resource/stdout/list.md + - name: resolve operation stdout + href: resource/stdout/resolve.md + - name: schema operation stdout + href: resource/stdout/schema.md + - name: set operation stdout + href: resource/stdout/set.md + - name: test operation stdout + href: resource/stdout/test.md + - name: validate operation stdout + href: resource/stdout/validate.md + - name: what-if operation stdout + href: resource/stdout/whatIf.md - name: Metadata items: - name: Microsoft.DSC properties