Merge pull request #1016 from michaeltlombardi/docs/main/output-docs

(DOCS) Add reference docs for expected resource operations stdout

Author: SteveL-MSFT

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

docs/reference/schemas/definitions/resourceKind.md

@@ -9,35 +9,33 @@ 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
 
 ```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:          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
 

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:
-
-- <a id="capability-get" ></a> `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.
-- <a id="capability-set" ></a> `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.
-- <a id="capability-sethandlesexist" ></a> `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`.
-- <a id="capability-whatif" ></a> `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.
-- <a id="capability-test" ></a> `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.
-- <a id="capability-delete" ></a> `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.
-- <a id="capability-export" ></a> `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.
-- <a id="capability-resolve" ></a> `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

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

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.

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.
+
+<!-- Reference link definitions -->
+[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

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.
+
+<!-- Reference link definitions -->
+[01]: ../manifest/schema/property.md
+[02]: ../manifest/schema/embedded.md