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>/resource/stdout/set.yaml
4+
5+ title : Set resource operation stdout
6+ description : >-
7+ Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation.
8+
9+ markdownDescription : | # VS Code only
10+ ***
11+ [_Online Documentation_][00]
12+ ***
13+
14+ Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation.
15+
16+ DSC expects this output for both actual **Set** operations and **Set** operations in `whatIf`
17+ mode. If the resource has the `whatIf` capability, the output should be the same for both modes.
18+
19+ DSC expects different output from the command resource depending on the definition of
20+ [set.return][01] in the resource manifest:
21+
22+ - If the field isn't defined, DSC doesn't expect the resource to return any JSON to stdout.
23+ Instead, DSC invokes the **Get** operation on the resource after the **Set** operation
24+ concludes and synthesizes the **Set** result, including the after state of the resource and
25+ the list of changed properties.
26+ - If the field is defined as `state`, DSC expects the resource to emit a JSON Line to stdout
27+ representing the actual state of the resource instance after the **Set** operation changes the
28+ system.
29+ - If the field is defined as `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The
30+ first JSON Line should be an object representing the actual state of the resource after the
31+ **Set** operation. The second JSON Line should be an array representing the names of the
32+ resource properties that the operation changed on the system.
33+
34+ [00]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/set?<DOCS_VERSION_PIN>
35+ [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>#return
36+
37+ oneOf :
38+ - title : Null output
39+ description : >-
40+ When a command resource doesn't define `set.return` in its resource manifest, DSC doesn't
41+ expect the resource to emit any JSON to stdout for the **Set** operation.
42+ markdownDescription : |-
43+ ***
44+ [_Online Documentation_][00]
45+ ***
46+
47+ When a command resource doesn't define [set.return][01] in its resource manifest, DSC doesn't expect
48+ the resource to emit any JSON to stdout for the **Set** operation.
49+
50+ [00]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/set?<DOCS_VERSION_PIN>#null-output
51+ [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>#return
52+ type : ' null'
53+ - title : state output
54+ description : >-
55+ When a resource defines `set.return` in its manifest as `state` or `stateAndDiff`, DSC
56+ expects the resource to emit a JSON Line to stdout representing the actual state of the
57+ resource instance after the **Set** operation changes the system.
58+ markdownDescription : |-
59+ ***
60+ [_Online Documentation_][00]
61+ ***
62+
63+ When a command resource defines [set.return][01] in its manifest as `state` or
64+ `stateAndDiff`, DSC expects the resource to emit a JSON Line to stdout representing the
65+ actual state of the resource instance after the **Set** operation changes the system.
66+
67+ The output must be a JSON object. The object must be a valid representation of an instance of
68+ the resource.
69+
70+ Command resources define their instance schema with the [schema.command][02] or
71+ [schema.embedded][03] fields in their resource manifest. If a command resource returns JSON
72+ that is invalid against the resource instance schema, DSC raises an error.
73+
74+ Adapted resource instances are validated by their adapter when the adapter invokes them.
75+
76+ [00]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/set?<DOCS_VERSION_PIN>#state-output
77+ [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>#return
78+ [02]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/command?<DOCS_VERSION_PIN>
79+ [03]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/embedded?<DOCS_VERSION_PIN>
80+ type : object
81+ - title : diff output
82+ description : >-
83+ When a command resource defines `set.return` in its manifest as `stateAndDiff`, DSC expects
84+ the resource to emit a second JSON Line to stdout representing the names of the resource
85+ properties that the operation changed on the system.
86+ markdownDescription : |-
87+ ***
88+ [_Online Documentation_][00]
89+ ***
90+
91+ When a command resource defines [set.return][01] in its manifest as `stateAndDiff`, DSC
92+ expects the resource to emit a second JSON Line to stdout representing the names of the
93+ resource properties that the operation changed on the system.
94+
95+ This output must be emitted after the JSON Line representing the state of the resource
96+ instance after the operation changes the system.
97+
98+ The output must be a JSON array. The array may be empty, or it may contain one or more
99+ strings. Each string in the array must be the name of one of the resource's properties. Each
100+ string in the array must be unique.
101+
102+ [00]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/set?<DOCS_VERSION_PIN>#diff-output
103+ [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>#return
104+ type : array
105+ uniqueItems : true
106+ items :
107+ type : string
0 commit comments