diff --git a/docs/reference/schemas/definitions/resourceCapabilities.md b/docs/reference/schemas/definitions/resourceCapabilities.md new file mode 100644 index 000000000..4e671e3bd --- /dev/null +++ b/docs/reference/schemas/definitions/resourceCapabilities.md @@ -0,0 +1,55 @@ +--- +description: JSON schema reference for resource capabilities +ms.date: 07/03/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/docs/reference/schemas/definitions/resourceKind.md b/docs/reference/schemas/definitions/resourceKind.md index d368e4d69..2589bdc17 100644 --- a/docs/reference/schemas/definitions/resourceKind.md +++ b/docs/reference/schemas/definitions/resourceKind.md @@ -9,7 +9,7 @@ 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 @@ -17,27 +17,25 @@ Identifies whether a resource is an adapter resource, a group resource, or a nor 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: string -ValidValues: [resource, adapter, group, importer] +ValidValues: [resource, adapter, group, importer, exporter] ``` ## Description -DSC supports three 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 diff --git a/docs/reference/schemas/outputs/resource/list.md b/docs/reference/schemas/outputs/resource/list.md index bff9b9635..c0ff3173c 100644 --- a/docs/reference/schemas/outputs/resource/list.md +++ b/docs/reference/schemas/outputs/resource/list.md @@ -79,70 +79,22 @@ 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 +191,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 +205,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#-w---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/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md index bcb47e1e4..3814a84ef 100644 --- a/docs/reference/schemas/resource/manifest/root.md +++ b/docs/reference/schemas/resource/manifest/root.md @@ -166,23 +166,24 @@ Required: false ### kind -The `kind` property defines how DSC should handle the resource. DSC supports three kinds of -command-based DSC Resources: `Resource`, `Group`, and `Adapter`. +The `kind` property defines how DSC should handle the resource. DSC supports several kinds +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 resource. +`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 defining a group resource, always explicitly define the `kind` property in the manifest as -`Group`. +`group`. When defining an importer resource, always explicitly define the `kind` property in the +manifest as `importer`. For more information, see [DSC Resource kind schema reference][02]. ```yaml Type: string Required: false -ValidValues: [Resource, Adapter, Group] +ValidValues: [resource, adapter, group, importer, exporter] ``` ### tags diff --git a/docs/reference/schemas/resource/stdout/delete.md b/docs/reference/schemas/resource/stdout/delete.md new file mode 100644 index 000000000..86e1c25b4 --- /dev/null +++ b/docs/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: 02/28/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/docs/reference/schemas/resource/stdout/export.md b/docs/reference/schemas/resource/stdout/export.md new file mode 100644 index 000000000..034405872 --- /dev/null +++ b/docs/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: 07/29/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/docs/reference/schemas/resource/stdout/get.md b/docs/reference/schemas/resource/stdout/get.md new file mode 100644 index 000000000..7d168fe55 --- /dev/null +++ b/docs/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: 07/29/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/docs/reference/schemas/resource/stdout/list.md b/docs/reference/schemas/resource/stdout/list.md new file mode 100644 index 000000000..871c1e025 --- /dev/null +++ b/docs/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: 07/29/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/docs/reference/schemas/resource/stdout/resolve.md b/docs/reference/schemas/resource/stdout/resolve.md new file mode 100644 index 000000000..6c8ace149 --- /dev/null +++ b/docs/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: 07/29/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/docs/reference/schemas/resource/stdout/schema.md b/docs/reference/schemas/resource/stdout/schema.md new file mode 100644 index 000000000..5a040e9b9 --- /dev/null +++ b/docs/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: 07/29/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/docs/reference/schemas/resource/stdout/set.md b/docs/reference/schemas/resource/stdout/set.md new file mode 100644 index 000000000..7fb917962 --- /dev/null +++ b/docs/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: 07/29/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/docs/reference/schemas/resource/stdout/test.md b/docs/reference/schemas/resource/stdout/test.md new file mode 100644 index 000000000..7536bab48 --- /dev/null +++ b/docs/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: 07/29/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/docs/reference/schemas/resource/stdout/validate.md b/docs/reference/schemas/resource/stdout/validate.md new file mode 100644 index 000000000..e2031bb40 --- /dev/null +++ b/docs/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: 07/29/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/docs/reference/schemas/resource/stdout/whatIf.md b/docs/reference/schemas/resource/stdout/whatIf.md new file mode 100644 index 000000000..9fc08cc77 --- /dev/null +++ b/docs/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: 07/29/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