Publish to live (#375)

* Add description to Microsoft.DSC metadata (#371)

* (SYNC) Draft reference for expected resource stdout JSON Schemas (#373)

This change:

- Adds reference documentation for the expected output
  for resource operations
- Mirrors the PR in the code repository (PowerShell/DSC#1016)
- Fixes #367
- Fixes #368
- Fixes #369

* (MAINT) Fix bookmark links (#374)

---------

Co-authored-by: Gijs Reijn <[email protected]>
Co-authored-by: Mikey Lombardi (He/Him) <[email protected]>

Author: 3 people

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

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` - <a id="get"></a> The resource can retrieve the current state of an instance.
+- `set` - <a id="set"></a> The resource can enforce the desired state for an instance.
+- `setHandlesExist` - <a id="setHandlesExist"></a> The resource handles deleting an instance during
+  a **Set** operation.
+- `whatIf` - <a id="whatIf"></a> The resource can report how it would change state for an instance
+  during a **Set** operation.
+- `test` - <a id="test"></a> The resource implements the **Test** operation and doesn't rely on
+  synthetic testing.
+- `delete` - <a id="delete"></a> The resource can remove an instance.
+- `export` - <a id="export"></a> The resource can enumerate every instance.
+- `resolve` - <a id="resolve"></a> 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

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

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
 

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:
-
-- <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 +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

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

dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md

@@ -256,6 +256,6 @@ ValidValues: [state, stateAndDiff]
 <!-- Reference link definitions -->
 [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

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