Skip to content

Commit df9c4cc

Browse files
michaeltlombardimichaeltlombardi
authored
(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
1 parent 3150cba commit df9c4cc

File tree

16 files changed

+887
-112
lines changed

16 files changed

+887
-112
lines changed

‎dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceCapabilities.md

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
description: JSON schema reference for resource capabilities
3+
ms.date: 08/21/2025
4+
ms.topic: reference
5+
title: DSC Resource capabilities schema reference
6+
---
7+
8+
# DSC Resource capabilities schema reference
9+
10+
## Synopsis
11+
12+
Defines the operations you can invoke for a resource and how the resource behaves when invoked.
13+
14+
## Metadata
15+
16+
```yaml
17+
SchemaDialect: https://json-schema.org/draft/2020-12/schema
18+
SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/definitions/resourceKind.json
19+
Type: array
20+
Required: true
21+
ItemsMustBeUnique: true
22+
ItemsType: string
23+
ItemsValidValues: [
24+
get,
25+
set,
26+
setHandlesExist,
27+
whatIf,
28+
test,
29+
delete,
30+
export,
31+
resolve
32+
]
33+
```
34+
35+
## Description
36+
37+
DSC resources always have at least one capability. Resource capabilities define the operations you
38+
can invoke for a resource and how the resource behaves when invoked.
39+
40+
DSC resources may have the following capabilities:
41+
42+
- `get` - The resource can retrieve the current state of an instance.
43+
- `set` - The resource can enforce the desired state for an instance.
44+
- `setHandlesExist` - The resource handles deleting an instance during a **Set** operation.
45+
- `whatIf` - The resource can report how it would change state for an instance during a **Set**
46+
operation.
47+
- `test` - The resource implements the **Test** operation and doesn't rely on synthetic testing.
48+
- `delete` - The resource can remove an instance.
49+
- `export` - The resource can enumerate every instance.
50+
- `resolve` - The resource can resolve nested instances from an external source.
51+
52+
For more information about resource capabilities, see [DSC resource capabilities][01]. For more
53+
information about the operations you can invoke for a resource, see [DSC resource operations][02].
54+
55+
[01]: ../../../concepts/resources/capabilities.md
56+
[02]: ../../../concepts/resources/operations.md

‎dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md

Lines changed: 26 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: JSON schema reference for resource kind
3-
ms.date: 07/03/2025
3+
ms.date: 08/21/2025
44
ms.topic: reference
55
title: DSC Resource kind schema reference
66
---
@@ -9,7 +9,8 @@ title: DSC Resource kind schema reference
99

1010
## Synopsis
1111

12-
Identifies whether a resource is an adapter resource, a group resource, or a normal resource.
12+
Identifies whether a resource is an adapter resource, a group resource, an importer resource, an
13+
exporter resource, or a normal resource.
1314

1415
## Metadata
1516

@@ -22,22 +23,21 @@ ValidValues: [resource, adapter, group, importer, exporter]
2223
2324
## Description
2425
25-
DSC supports several kinds of command-based DSC Resources:
26+
DSC supports several kinds of command resources:
2627
27-
- `resource` - Indicates that the manifest isn't for a group or adapter resource.
28+
- `resource` - Indicates that the manifest is for a typical resource.
2829
- `group` - Indicates that the manifest is for a [group resource](#group-resources).
2930
- `adapter` - Indicates that the manifest is for an [adapter resource](#adapter-resources).
3031
- `importer` - Indicates that the manifest is for an [importer resource](#importer-resources).
3132
- `exporter` - Indicates that the manifest is for an [exporter resource](#exporter-resources).
3233

33-
When `kind` isn't defined in the resource manifest, DSC infers the value for the property. If the
34-
`adapter` property is defined in the resource manifest, DSC infers the value of `kind` as
35-
`adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as `resource`.
36-
DSC can't infer whether a manifest is for a group or importer resource.
34+
When `kind` isn't defined in the resource manifest for a command resource, DSC infers the value for
35+
the property. If the `adapter` property is defined in the resource manifest, DSC infers the value
36+
of `kind` as `adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as
37+
`resource`. DSC can't infer whether a manifest is for a group, importer, or exporter resource.
3738

38-
When defining a group resource, always explicitly define the `kind` property in the manifest as
39-
`group`. When defining an importer resource, always explicitly define the `kind` property in the
40-
manifest as `importer`.
39+
When defining a group, importer, or exporter resource with a resource manifest, always explicitly
40+
define `kind`.
4141

4242
### Adapter resources
4343

@@ -174,10 +174,10 @@ The following examples show valid and invalid references and dependencies. The e
174174
This example configuration defines several valid references and dependencies. It also defines two
175175
instances of the `Microsoft.DSC/Group` resource, one nested inside the other.
176176

177-
The top level instance of the `Microsoft.DSC.Debug/Echo` resource references and depends on the top-level instance
178-
of the `Microsoft/OSInfo` resource. The top-level instances of the `Microsoft.DSC.Debug/Echo` and
179-
`Microsoft/OSInfo` resources both depend on the top-level instance of the `Microsoft.DSC/Group`
180-
resource.
177+
The top level instance of the `Microsoft.DSC.Debug/Echo` resource references and depends on the
178+
top-level instance of the `Microsoft/OSInfo` resource. The top-level instances of the
179+
`Microsoft.DSC.Debug/Echo` and `Microsoft/OSInfo` resources both depend on the top-level instance
180+
of the `Microsoft.DSC/Group` resource.
181181

182182
```yaml
183183
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
@@ -206,9 +206,9 @@ resources:
206206
```
207207

208208
The top-level instance of `Microsoft.DSC/Group` defines three nested resource instances:
209-
`Microsoft.DSC.Debug/Echo`, `Microsoft/OSInfo`, and `Microsoft.DSC/Group`. As at the top-level, the `Microsoft.DSC.Debug/Echo`
210-
instance references and depends on the adjacent nested`Microsoft/OSInfo` instance and that instance
211-
depends on the adjacent nested `Microsoft.DSC/Group` instance.
209+
`Microsoft.DSC.Debug/Echo`, `Microsoft/OSInfo`, and `Microsoft.DSC/Group`. As at the top-level, the
210+
`Microsoft.DSC.Debug/Echo` instance references and depends on the adjacent nested`Microsoft/OSInfo`
211+
instance and that instance depends on the adjacent nested `Microsoft.DSC/Group` instance.
212212

213213
```yaml
214214
# Other top-level instances snipped for brevity
@@ -237,8 +237,8 @@ depends on the adjacent nested `Microsoft.DSC/Group` instance.
237237
```
238238

239239
Finally, the nested instance of `Microsoft.DSC/Group` defines two nested instances. The deeply
240-
nested instance of `Microsoft.DSC.Debug/Echo` references and depends on the deeply nested instance of
241-
`Microsoft/OSInfo`.
240+
nested instance of `Microsoft.DSC.Debug/Echo` references and depends on the deeply nested instance
241+
of `Microsoft/OSInfo`.
242242

243243
```yaml
244244
- name: Top level group
@@ -338,9 +338,9 @@ resources:
338338

339339
#### Example 2 - Invalid reference and dependency on a nested instance
340340

341-
This example configuration is invalid, because the top-level instance of the `Microsoft.DSC.Debug/Echo` resource
342-
references and depends on the nested `Microsoft/OSInfo` instance. The nested instance is external
343-
to the top-level instance, not adjacent.
341+
This example configuration is invalid, because the top-level instance of the
342+
`Microsoft.DSC.Debug/Echo` resource references and depends on the nested `Microsoft/OSInfo`
343+
instance. The nested instance is external to the top-level instance, not adjacent.
344344

345345
```yaml
346346
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
@@ -367,9 +367,9 @@ resources:
367367

368368
#### Example 3 - Invalid reference and dependency on an external instance
369369

370-
This example configuration is invalid, because the nested instance of the `Microsoft.DSC.Debug/Echo` resource
371-
references and depends on the top-level `Microsoft/OSInfo` instance. The top-level instance is
372-
external to the nested instance, not adjacent.
370+
This example configuration is invalid, because the nested instance of the
371+
`Microsoft.DSC.Debug/Echo` resource references and depends on the top-level `Microsoft/OSInfo`
372+
instance. The top-level instance is external to the nested instance, not adjacent.
373373

374374
```yaml
375375
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json

‎dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md

Lines changed: 22 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: JSON schema reference for the data returned by the 'dsc resource list' command.
3-
ms.date: 07/03/2025
3+
ms.date: 08/21/2025
44
ms.topic: reference
55
title: dsc resource list result schema reference
66
---
@@ -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
7979

8080
### capabilities
8181

82-
Defines the operations and behaviors the resource is implemented to support. This property is an
83-
array of capabilities. Resources always have the `Get` capability, but the other capabilities are
84-
optional and depend on the resource.
85-
86-
The following list describes the available capabilities for a resource:
87-
88-
- <a id="capability-get" ></a> `get` - The resource supports retrieving the current state of an
89-
instance. All DSC Resources must have this capability. A resource has this capability when it
90-
defines the mandatory [get][07] property in its resource manifest.
91-
- <a id="capability-set" ></a> `set` - The resource supports enforcing the desired state of an
92-
instance. A resource has this capability when it defines the [set][08] property in its resource
93-
manifest. Resources without this capability can't be used with the [dsc resource set][09] or
94-
[dsc config set][10] commands unless they're in a Microsoft.DSC/Assertion group as a nested
95-
instance.
96-
- <a id="capability-sethandlesexist" ></a> `setHandlesExist` - The resource supports the
97-
[_exist property][11] directly. A resource has this capability when it defines the
98-
[handlesExist][12] property as `true` in the definition of the [set][08] command property in its
99-
resource manifest.
100-
101-
When a resource has this capability, the `_exist` property is part of the resource's instance
102-
schema and the resource handles deleting instances of the resource in its `set` command.
103-
104-
When a resource doesn't have this capability, when DSC finds an instance of the resource with
105-
`_exist` set to `false`, it handles calling the [delete][13] operation for the resource.
106-
107-
If the resource doesn't have this capability or the `delete` capability, DSC raises an error when
108-
an instance defines `_exist` as `false`.
109-
- <a id="capability-whatif" ></a> `whatIf` - The resource supports returning explicit information
110-
about how it will modify state when a user calls [dsc config set][10] with the [--what-if][14]
111-
option. A resource has this capability when it defines the [What-if operation][15] in its
112-
resource manifest.
113-
114-
When a resource has this capability, DSC calls the defined command with its arguments when a
115-
user executes the `dsc config set` command with the `--what-if` option.
116-
117-
When a resource doesn't have this capability, DSC synthesizes how the resource will change and
118-
instance by converting the `Test` result for the instance into a `Set` result. The synthetic
119-
operation can't indicate potential issues or changes that can't be determined by comparing the
120-
result of the `Test` operation against the resource's desired state. For example, the credentials
121-
used to test a resource might be valid for that operation, but not have permissions to actually
122-
modify the system state. Only a resource with this capability can fully report whether and how
123-
the resource will change system state.
124-
- <a id="capability-test" ></a> `test` - The resource supports validating the desired state of an
125-
instance against the current state of the instance. A resource has this capability when it
126-
defines the [test][16] property in its resource manifest.
127-
128-
If a resource doesn't have the `test` capability, DSC uses a synthetic test for instances of the
129-
resource. The synthetic test compares each property for the desired state of an instance against
130-
the actual state. The synthetic test uses strict, case-sensitive equivalence. If the desired
131-
state for a property and the actual state aren't the same, DSC marks the property as out of the
132-
desired state.
133-
- <a id="capability-delete" ></a> `delete` - The resource supports removing an instance. A resource
134-
has this capability when it defines the [delete][13] property in its resource manifest. This
135-
capability isn't mutually exclusive with the `setHandlesExist` property. A resource can handle
136-
the `_exist` property in set operations and be called directly with [dsc resource delete][17] to
137-
remove an instance.
138-
- <a id="capability-export" ></a> `export` - The resource supports enumerating every instance of
139-
the resource. A resource has this capability when it defines the [export][18] property in its
140-
resource manifest. Only resources with this capability are usable with the
141-
[dsc resource export][19] and [dsc config export][20] commands.
142-
- <a id="capability-resolve" ></a> `resolve` - The resource supports resolving nested resource
143-
instances from an external source. A resource has this capability when it defines the
144-
[resolve][21] property in its resource manifest. This functionality is primarily used by
145-
[importer resources][22].
82+
DSC resources always have at least one capability. Resource capabilities define the operations you
83+
can invoke for a resource and how the resource behaves when invoked.
84+
85+
DSC resources may have the following capabilities:
86+
87+
- `get` - The resource can retrieve the current state of an instance.
88+
- `set` - The resource can enforce the desired state for an instance.
89+
- `setHandlesExist` - The resource handles deleting an instance during a **Set** operation.
90+
- `whatIf` - The resource can report how it would change state for an instance during a **Set**
91+
operation.
92+
- `test` - The resource implements the **Test** operation and doesn't rely on synthetic testing.
93+
- `delete` - The resource can remove an instance.
94+
- `export` - The resource can enumerate every instance.
95+
- `resolve` - The resource can resolve nested instances from an external source.
96+
97+
For more information about resource capabilities, see [DSC resource capabilities][07]. For more
98+
information about the operations you can invoke for a resource, see [DSC resource operations][08].
14699

147100
```yaml
148101
Type: array
@@ -239,7 +192,7 @@ Required: true
239192

240193
Represents the values defined in the resource's manifest. This value is `null` for resources that
241194
aren't command-based. For more information on the value for this property, see
242-
[Command-based DSC Resource manifest schema reference][23].
195+
[Command-based DSC Resource manifest schema reference][09].
243196

244197
```yaml
245198
Type: [object, 'null']
@@ -253,20 +206,6 @@ Required: true
253206
[04]: ../../definitions/resourceKind.md#group-resources
254207
[05]: ../../resource/manifest/root.md#kind
255208
[06]: ../../definitions/resourceKind.md
256-
[07]: ../../resource/manifest/get.md
257-
[08]: ../../resource/manifest/set.md
258-
[09]: ../../../cli/resource/set.md
259-
[10]: ../../../cli/config/set.md
260-
[11]: ../../resource/properties/exist.md
261-
[12]: ../../resource/manifest/set.md#handlesexist
262-
[13]: ../../resource/manifest/delete.md
263-
[14]: ../../../cli/config/set.md#--what-if
264-
[15]: ../../resource/manifest/whatif.md
265-
[16]: ../../resource/manifest/test.md
266-
[17]: ../../../cli/resource/delete.md
267-
[18]: ../../resource/manifest/export.md
268-
[19]: ../../../cli/resource/export.md
269-
[20]: ../../../cli/config/export.md
270-
[21]: ../../resource/manifest/resolve.md
271-
[22]: ../../definitions/resourceKind.md#importer-resources
272-
[23]: ../../resource/manifest/root.md
209+
[07]: ../../../../concepts/resources/capabilities.md
210+
[08]: ../../../../concepts/resources/operations.md
211+
[09]: ../../resource/manifest/root.md

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
description: JSON schema reference for a DSC Resource manifest
3-
ms.date: 07/03/2025
3+
ms.date: 08/21/2025
44
ms.topic: reference
55
title: Command-based DSC Resource manifest schema reference
66
---
@@ -38,6 +38,7 @@ The manifest must include these properties:
3838
- [$schema](#schema)
3939
- [type](#type)
4040
- [version](#version)
41+
- [get](#get)
4142

4243
## Properties
4344

@@ -166,12 +167,12 @@ Required: false
166167
### kind
167168

168169
The `kind` property defines how DSC should handle the resource. DSC supports several kinds
169-
ofcommand-based DSC Resources: `resource`, `group`, `adapter`, `importer`, and `exporter`.
170+
of DSC resources: `resource`, `group`, `adapter`, `importer`, and `exporter`.
170171

171172
When `kind` isn't defined in the resource manifest, DSC infers the value for the property. If the
172173
`adapter` property is defined in the resource manifest, DSC infers the value of `kind` as
173174
`adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as `resource`.
174-
DSC can't infer whether a manifest is for a group` or importer resource.
175+
DSC can't infer whether a manifest is for a `group` or `importer` resource.
175176

176177
When defining a group resource, always explicitly define the `kind` property in the manifest as
177178
`group`. When defining an importer resource, always explicitly define the `kind` property in the

‎dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/stdout/delete.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
description: JSON schema reference for the expected stdout from the delete resource operation
3+
ms.date: 08/21/2025
4+
ms.topic: reference
5+
title: DSC resource delete operation stdout schema reference
6+
---
7+
8+
# DSC resource delete operation stdout schema reference
9+
10+
## Synopsis
11+
12+
DSC doesn't expect the **Delete** operation for a resource to return any JSON to stdout.
13+
14+
## Metadata
15+
16+
```yaml
17+
SchemaDialect: https://json-schema.org/draft/2020-12/schema
18+
SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/delete.json
19+
Type: 'null'
20+
```
21+
22+
## Description
23+
24+
DSC resources that implement the **Delete** operation shouldn't emit any data to stdout. DSC
25+
doesn't expect any output for the **Delete** operation and ignores any data emitted to stdout when
26+
invoking the operation.

0 commit comments

Comments
 (0)