Skip to content

Commit 135837e

Browse files
michaeltlombardimichaeltlombardi
committed
(SCHEMA) Decompose capabilities into separate schema for reuse
This change breaks out the capabilities schema from the `dsc resource list` output schema into a separate definition file. This enables us to reference the schema without using a JSON Pointer and provides us with a page for documenting the capabilities directly. This is a required precursor for a future change that defines stdout schemas for resource operations.
1 parent 9f36ab4 commit 135837e

File tree

2 files changed

+245
-18
lines changed

2 files changed

+245
-18
lines changed

‎schemas/src/definitions/resourceCapabilities.yaml

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema
2+
$schema: https://json-schema.org/draft/2020-12/schema
3+
$id: <HOST>/<PREFIX>/<VERSION>/definitions/resourceCapabilities.yaml
4+
5+
title: Resource capabilities
6+
description: >-
7+
Define the operations you can invoke for a resource and how the resource behaves when invoked.
8+
9+
markdownDescription: |-
10+
***
11+
[_Online Documentation_][00]
12+
***
13+
14+
DSC resources always have at least one capability. Resource capabilities define the operations
15+
you can invoke for a resource and how the resource behaves when invoked.
16+
17+
For more information about the operations you can invoke for a resource, see
18+
[DSC resource operations][01].
19+
20+
<!-- Link reference definitions -->
21+
[00]: <DOCS_BASE_URL>/reference/schemas/definitions/resourceCapabilities?<DOCS_VERSION_PIN>
22+
[00]: <DOCS_BASE_URL>/concepts/resources/operations?<DOCS_VERSION_PIN>
23+
24+
type: array
25+
items:
26+
type: string
27+
enum:
28+
- get
29+
- set
30+
- setHandlesExist
31+
- whatIf
32+
- test
33+
- delete
34+
- export
35+
- resolve
36+
markdownEnumDescriptions:
37+
- |- # get
38+
***
39+
[_Online Documentation_][00]
40+
***
41+
42+
A resource with the `get` capability supports retrieving the current state of an instance
43+
with the [Get][01] operation.
44+
45+
A command resource has this capability when its resource manifest defines the [get][02]
46+
property.
47+
48+
<!-- Link reference definitions -->
49+
[00]: <DOCS_BASE_URL>/reference/schemas/definitions/resourceCapabilities?<DOCS_VERSION_PIN>#get
50+
[01]: <DOCS_BASE_URL>/concepts/resources/operations?<DOCS_VERSION_PIN>#get-operation
51+
[02]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/get?<DOCS_VERSION_PIN>
52+
53+
- |- # set
54+
***
55+
[_Online Documentation_][00]
56+
***
57+
58+
A resource with the `set` capability supports enforcing the desired state of an instance with
59+
the [Set][01] operation. Resources without this capability can't be used with the
60+
[dsc resource set][02] or [dsc config set][03] commands unless they're defined in a
61+
`Microsoft.DSC/Assertion` group as a nested instance.
62+
63+
A command resource has this capability when its resource manifest defines the [set][04]
64+
property.
65+
66+
<!-- Link reference definitions -->
67+
[00]: <DOCS_BASE_URL>/reference/schemas/definitions/resourceCapabilities?<DOCS_VERSION_PIN>#set
68+
[01]: <DOCS_BASE_URL>/concepts/resources/operations?<DOCS_VERSION_PIN>#set-operation
69+
[02]: <DOCS_BASE_URL>/reference/cli/resource/set?<DOCS_VERSION_PIN>
70+
[03]: <DOCS_BASE_URL>/reference/cli/config/set?<DOCS_VERSION_PIN>
71+
[04]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>
72+
73+
- |- # setHandlesExist
74+
***
75+
[_Online Documentation_][00]
76+
***
77+
78+
A resource with the `setHandlesExist` capability indicates that you can use the [Set][01]
79+
operation to delete an instance. Resources with this capability must have the [_exist][02]
80+
canonical resource property. Resources that don't have the `_exist` property never have this
81+
capability.
82+
83+
When a resource has the `_exist` property but not the `setHandlesExist` capability:
84+
85+
- If the resource has the `delete` capability, DSC invokes the [Delete][03] operation instead
86+
of **Set** when the desired state for an instance defines `_exist` as false.
87+
- If the resource doesn't have the `delete` capability, DSC raises an error during a **Set**
88+
operation when the desired state for an instance defines `_exist` as false.
89+
90+
A command resource has this capability when its resource manifest defines the
91+
[set.handlesExist][04] subproperty as `true`.
92+
93+
<!-- Link reference definitions -->
94+
[00]: <DOCS_BASE_URL>/reference/schemas/definitions/resourceCapabilities?<DOCS_VERSION_PIN>#sethandlesexist
95+
[01]: <DOCS_BASE_URL>/concepts/resources/operations<DOCS_VERSION_PIN>#set-operation
96+
[02]: <DOCS_BASE_URL>/reference/schemas/resource/properties/exist<DOCS_VERSION_PIN>
97+
[03]: <DOCS_BASE_URL>/concepts/resources/operations<DOCS_VERSION_PIN>#delete-operation
98+
[04]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set<DOCS_VERSION_PIN>#handlesexist
99+
100+
- |- # whatIf
101+
***
102+
[_Online Documentation_][00]
103+
***
104+
105+
A resource with the `whatIf` capability indicates that you can use the [Set][01] operation in
106+
what-if mode to have the resource return explicit information about how it would modify state
107+
in an actual **Set** operation.
108+
109+
When a resource doesn't have this capability, DSC synthesizes how the resource would change
110+
an instance by converting the **Test** result for the instance into a **Set** result. The
111+
synthetic operation can't indicate potential issues or changes that can't be determined by
112+
comparing the result of the **Test** operation against the resource's desired state. For
113+
example, the credentials used to test a resource might be valid for that operation, but not
114+
have permissions to actually modify the system state. Only a resource with this capability
115+
can fully report whether and how the resource would change system state.
116+
117+
A resource has this capability when it defines the [whatIf][02] property.
118+
119+
<!-- Link reference definitions -->
120+
[00]: <DOCS_BASE_URL>/reference/schemas/definitions/resourceCapabilities?<DOCS_VERSION_PIN>#whatif
121+
[01]: <DOCS_BASE_URL>/concepts/resources/operations?<DOCS_VERSION_PIN>#set-operation
122+
[02]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>
123+
124+
- |- # test
125+
***
126+
[_Online Documentation_][00]
127+
***
128+
129+
A resource with the `test` capability indicates that it implements the [Test][01] operation
130+
directly. Resources with this capability must have the [_inDesiredState][02] canonical
131+
resource property. Resources that don't have the `_inDesiredState` property never have this
132+
capability.
133+
134+
When a resource doesn't have this capability, DSC uses a synthetic test for instances of the
135+
resource. DSC performs the synthetic test by:
136+
137+
1. Invoking the **Get** operation on the resource to retrieve the actual state of the
138+
instance.
139+
1. Synthetically testing each property for the desired state of an instance against the
140+
actual state returned. The synthetic test uses strict, case-sensitive equivalence.
141+
1. If the desired state for a property and the actual state aren't the same, DSC marks the
142+
property as out of the desired state.
143+
1. If any properties are out of the desired state, DSC reports the entire instance as not
144+
being in the desired state.
145+
146+
Synthetic testing can't account for all resource behaviors. For example, if a package
147+
resource allows users to define a version range for the package, the **Get** operation
148+
returns the actual version of the package, like `1.2.3`. If the user specified the version
149+
range `~1` (NPM syntax indicating the package should be latest released semantic version with
150+
major version `1`), DSC would compare the desired state `~1` against the actual state `1.2.3`
151+
and consider the package to be in the incorrect state, even if `1.2.3` is actually the latest
152+
release matching the version pin.
153+
154+
Any resource that has properties which can't use a strict case-sensitive comparison check
155+
should have this capability.
156+
157+
A command resource has this capability when its resource manifest defines the [test][03]
158+
property.
159+
160+
<!-- Link reference definitions -->
161+
[00]: <DOCS_BASE_URL>/reference/schemas/definitions/resourceCapabilities?<DOCS_VERSION_PIN>#test
162+
[01]: <DOCS_BASE_URL>/concepts/resources/operations?<DOCS_VERSION_PIN>#test-operation
163+
[02]: <DOCS_BASE_URL>/reference/schemas/resource/properties/inDesiredState?<DOCS_VERSION_PIN>
164+
[03]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/test?<DOCS_VERSION_PIN>
165+
166+
- |- # delete
167+
***
168+
[_Online Documentation_][00]
169+
***
170+
171+
A resource with the `delete` capability supports removing an instance with the [Delete][01]
172+
operation and the [dsc resource delete][02] command.
173+
174+
This capability isn't mutually exclusive with the `setHandlesExist` property. A resource can handle
175+
the `_exist` property in **Set** operations and be called directly with `dsc resource delete` to
176+
remove an instance.
177+
178+
For resources with the `delete` capability and the [_exist][03] canonical resource property:
179+
180+
- If the resource doesn't have the `setHandlesExist` capability, DSC invokes the **Delete**
181+
operation for the resource instead of **Set** when the desired state defines `_exist` as
182+
`false`.
183+
- If the resource does have the `setHandlesExist` capability, DSC invokes the **Set** operation for
184+
the resource when the desired state defines `_exist` as `false`.
185+
186+
Resources with the `delete` capability that don't have the `_exist` canonical resource property
187+
must implement their **Set** operation to handle removing instances. DSC can't infer existence
188+
semantics without the `_exist` property.
189+
190+
A command resource has this capability when its resource manifest defines the [delete][04]
191+
property.
192+
193+
<!-- Link reference definitions -->
194+
[00]: <DOCS_BASE_URL>/reference/schemas/definitions/resourceCapabilities?<DOCS_VERSION_PIN>#delete
195+
[01]: <DOCS_BASE_URL>/concepts/resources/operations?<DOCS_VERSION_PIN>#delete-operation
196+
[02]: <DOCS_BASE_URL>/reference/cli/resource/delete?<DOCS_VERSION_PIN>
197+
[03]: <DOCS_BASE_URL>/reference/schemas/resource/properties/exist?<DOCS_VERSION_PIN>
198+
[04]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/delete?<DOCS_VERSION_PIN>
199+
200+
201+
- |- # export
202+
***
203+
[_Online Documentation_][00]
204+
***
205+
206+
A resource with the `export` capability supports enumerating every instance of the resource
207+
with the [Export][01] operation.
208+
209+
You can use resources with this capability with the following commands:
210+
211+
- [dsc config export][02] to return a configuration document representing the actual state
212+
for every instance of each resource defined in the input document.
213+
- [dsc resource export][03] to return a configuration document representing the actual state
214+
for every instance of the input resource.
215+
- `dsc resource get` with the [--all][04] option to return the actual state of every instance
216+
of the input resource.
217+
218+
A command resource has this capability when its resource manifest defines the [export][05]
219+
property.
220+
221+
<!-- Link reference definitions -->
222+
[00]: <DOCS_BASE_URL>/reference/schemas/definitions/resourceCapabilities?<DOCS_VERSION_PIN>#export
223+
[01]: <DOCS_BASE_URL>/concepts/resources/operations<DOCS_VERSION_PIN>#export-operation
224+
[02]: <DOCS_BASE_URL>/reference/cli/config/export?<DOCS_VERSION_PIN>
225+
[03]: <DOCS_BASE_URL>/reference/cli/resource/export?<DOCS_VERSION_PIN>
226+
[04]: <DOCS_BASE_URL>/reference/cli/resource/get?<DOCS_VERSION_PIN>#--all
227+
[05]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/export?<DOCS_VERSION_PIN>
228+
229+
- |- # resolve
230+
***
231+
[_Online Documentation_][00]
232+
***
233+
234+
A resource with the `resolve` capability supports resolving nested resource instances from an
235+
external source. This capability is primarily used by [importer resources][01] to enable users to
236+
compose configuration documents.
237+
238+
A command resource has this capability when its resource manifest defines the [resolve][0220]
239+
property.
240+
241+
<!-- Link reference definitions -->
242+
[00]: <DOCS_BASE_URL>/reference/schemas/definitions/resourceCapabilities?<DOCS_VERSION_PIN>#resolve
243+
[01]: <DOCS_BASE_URL>/concepts/resources/kinds?<DOCS_VERSION_PIN>#importer-resources
244+
[02]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/resolve?<DOCS_VERSION_PIN>

‎schemas/src/outputs/resource/list.yaml

Lines changed: 1 addition & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -21,24 +21,7 @@ properties:
2121
# Only the Test* resources seem to have this field populated.
2222
$ref: /<PREFIX>/<VERSION>/definitions/semver.yaml
2323
capabilities:
24-
title: Resource capabilities
25-
description: >-
26-
Defines the list of DSC operations the resource is compatible with. If the resource doesn't
27-
list a given operation, like `set` or `export`, the resource can't be used for those
28-
operations. The exception to this is `test` - DSC uses synthetic testing for resources that
29-
don't have the `test` capability.
30-
type: array
31-
items:
32-
type: string
33-
enum:
34-
- get
35-
- set
36-
- setHandlesExist
37-
- whatIf
38-
- test
39-
- delete
40-
- export
41-
- resolve
24+
$ref: /<PREFIX>/<VERSION>/definitions/resourceCapabilities.yaml
4225
description:
4326
title: Resource description
4427
description: >-

0 commit comments

Comments
 (0)