Skip to content

Commit 660f61d

Browse files
michaeltlombardimichaeltlombardi
committed
(SCHEMA) Update for JSON input arguments
This change updates the definition of the command arguments from an array of strings to an array that can include strings and a single object representing a JSON input argument, as implemented in #385. The shared definition includes default snippets to simplify adding arguments to an `args` list, but not validation for the maximum number of JSON input arguments. It updates the definition for the schema command and adapter list command to expect arrays of strings instead of the shared definition for the command arguments, as those commands never get JSON data for input and their struct definition in Rust expects an optional vector of strings, not command arguments. It updates the definition for the `delete`, `export`, `get`, `set`, `test`, and `validate` commands to: 1. Make `input` optional, if it was required before, because that matches the struct definitions and DSC no longer requires the `input` kind when `args` includes a JSON input argument. 1. Add validation using three branches of the `oneOf` keyword, to handle mixed support for the `contains`, `minContains`, and `maxContains` keywords across the JSON and YAML support in VS Code. It raises specific error messages now when: - `input` isn't defined and `args` doesn't include a JSON input argument, or includes more than one JSON input argument. - `input` is defined and `args` includes more than one JSON input argument. 1. Update the default snippets to enable users to quickly define the command without any arguments, with only string arguments, and with a JSON input argument. 1. Update the in-editor help and clarify that the command must define `input`, a JSON input argument in `args`, or both. This change updates both the source and composed schemas.
1 parent 2359ded commit 660f61d

21 files changed

+2250
-364
lines changed

‎schemas/2024/04/bundled/outputs/resource/list.json‎

Lines changed: 307 additions & 49 deletions
Large diffs are not rendered by default.

‎schemas/2024/04/bundled/resource/manifest.json‎

Lines changed: 307 additions & 49 deletions
Large diffs are not rendered by default.

‎schemas/2024/04/bundled/resource/manifest.vscode.json‎

Lines changed: 477 additions & 101 deletions
Large diffs are not rendered by default.

‎schemas/2024/04/definitions/commandArgs.json‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,37 @@
22
"$schema": "https://json-schema.org/draft/2020-12/schema",
33
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json",
44
"title": "Executable Command Arguments",
5-
"description": "The list of arguments to pass to the command.",
5+
"description": "The list of arguments to pass to the command. The arguments can be any number of strings. If you want to pass the JSON object representing the property bag for the resource to an argument, you can define a single item in the array as a JSON object, indicating the name of the argument with the `jsonInputArg` string property and whether the argument is mandatory for the command with the `mandatory` boolean property.",
66
"type": "array",
77
"items": {
8-
"type": "string"
8+
"oneOf": [
9+
{
10+
"type": "string",
11+
"title": "String argument",
12+
"description": "Any item in the argument array can be a string representing a static argument to pass to the command."
13+
},
14+
{
15+
"type": "object",
16+
"title": "JSON input argument",
17+
"description": "Defines an argument for the command that accepts the JSON input object as a string. DSC passes the JSON input to the named argument when available. You can define the `mandatory` property to indicate whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the JSON input argument. You can only define one JSON input argument per arguments array.",
18+
"required": [
19+
"jsonInputArg"
20+
],
21+
"unevaluatedProperties": false,
22+
"properties": {
23+
"jsonInputArg": {
24+
"title": "JSON input argument name",
25+
"description": "Defines the argument that accepts the JSON property bag for the resource as input.",
26+
"type": "string"
27+
},
28+
"mandatory": {
29+
"title": "Mandatory argument",
30+
"description": "Defines whether the argument is mandatory. If this property is set to `true`, DSC passes an empty string when no JSON input is provided. The default value is `false`.",
31+
"type": "boolean",
32+
"default": false
33+
}
34+
}
35+
}
36+
]
937
}
1038
}

‎schemas/2024/04/resource/manifest.adapter.json‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,12 @@
2121
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json"
2222
},
2323
"args": {
24-
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json"
24+
"type": "array",
25+
"items": {
26+
"type": "string"
27+
},
28+
"title": "Command arguments",
29+
"description": "Defines the list of arguments to pass to the command to return the list of supported DSC Resources."
2530
}
2631
}
2732
},

‎schemas/2024/04/resource/manifest.delete.json‎

Lines changed: 42 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,7 @@
55
"description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.",
66
"type": "object",
77
"required": [
8-
"executable",
9-
"input"
8+
"executable"
109
],
1110
"properties": {
1211
"executable": {
@@ -19,17 +18,49 @@
1918
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json"
2019
}
2120
},
22-
"examples": [
21+
"oneOf": [
2322
{
24-
"executable": "registry",
25-
"args": [
26-
"config",
27-
"delete",
28-
"--input",
29-
"{json}"
23+
"required": [
24+
"input"
3025
],
31-
"input": {
32-
"arg": "{json}"
26+
"not": {
27+
"properties": {
28+
"args": {
29+
"contains": {
30+
"type": "object"
31+
}
32+
}
33+
}
34+
}
35+
},
36+
{
37+
"not": {
38+
"required": [
39+
"input"
40+
]
41+
},
42+
"properties": {
43+
"args": {
44+
"contains": {
45+
"type": "object"
46+
},
47+
"minContains": 1,
48+
"maxContains": 1
49+
}
50+
}
51+
},
52+
{
53+
"required": [
54+
"input"
55+
],
56+
"properties": {
57+
"args": {
58+
"contains": {
59+
"type": "object"
60+
},
61+
"minContains": 1,
62+
"maxContains": 1
63+
}
3364
}
3465
}
3566
]

‎schemas/2024/04/resource/manifest.export.json‎

Lines changed: 51 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"$schema": "https://json-schema.org/draft/2020-12/schema",
33
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json",
4-
"title": "Get Method",
4+
"title": "Export Method",
55
"description": "Defines how DSC must call the DSC Resource to get the current state of every instance.",
66
"type": "object",
77
"required": [
@@ -13,6 +13,55 @@
1313
},
1414
"args": {
1515
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json"
16+
},
17+
"input": {
18+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json"
19+
}
20+
},
21+
"oneOf": [
22+
{
23+
"required": [
24+
"input"
25+
],
26+
"not": {
27+
"properties": {
28+
"args": {
29+
"contains": {
30+
"type": "object"
31+
}
32+
}
33+
}
34+
}
35+
},
36+
{
37+
"not": {
38+
"required": [
39+
"input"
40+
]
41+
},
42+
"properties": {
43+
"args": {
44+
"contains": {
45+
"type": "object"
46+
},
47+
"minContains": 1,
48+
"maxContains": 1
49+
}
50+
}
51+
},
52+
{
53+
"required": [
54+
"input"
55+
],
56+
"properties": {
57+
"args": {
58+
"contains": {
59+
"type": "object"
60+
},
61+
"minContains": 1,
62+
"maxContains": 1
63+
}
64+
}
1665
}
17-
}
66+
]
1867
}

‎schemas/2024/04/resource/manifest.get.json‎

Lines changed: 40 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,17 +18,50 @@
1818
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json"
1919
}
2020
},
21-
"examples": [
21+
"oneOf": [
2222
{
23-
"executable": "registry",
24-
"args": [
25-
"config",
26-
"get"
23+
"required": [
24+
"input"
2725
],
28-
"input": "stdin"
26+
"not": {
27+
"properties": {
28+
"args": {
29+
"contains": {
30+
"type": "object"
31+
}
32+
}
33+
}
34+
}
2935
},
3036
{
31-
"executable": "osinfo"
37+
"not": {
38+
"required": [
39+
"input"
40+
]
41+
},
42+
"properties": {
43+
"args": {
44+
"contains": {
45+
"type": "object"
46+
},
47+
"minContains": 1,
48+
"maxContains": 1
49+
}
50+
}
51+
},
52+
{
53+
"required": [
54+
"input"
55+
],
56+
"properties": {
57+
"args": {
58+
"contains": {
59+
"type": "object"
60+
},
61+
"minContains": 1,
62+
"maxContains": 1
63+
}
64+
}
3265
}
3366
]
3467
}

‎schemas/2024/04/resource/manifest.schema.json‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,12 @@
2929
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json"
3030
},
3131
"args": {
32-
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json"
32+
"type": "array",
33+
"items": {
34+
"type": "string"
35+
},
36+
"title": "Command arguments",
37+
"description": "Defines the list of arguments to pass to the command to return the JSON Schema for the resource."
3338
}
3439
}
3540
},

‎schemas/2024/04/resource/manifest.set.json‎

Lines changed: 43 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,7 @@
55
"description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.",
66
"type": "object",
77
"required": [
8-
"executable",
9-
"input"
8+
"executable"
109
],
1110
"properties": {
1211
"executable": {
@@ -35,16 +34,50 @@
3534
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json"
3635
}
3736
},
38-
"examples": [
37+
"oneOf": [
3938
{
40-
"executable": "registry",
41-
"args": [
42-
"config",
43-
"set"
39+
"required": [
40+
"input"
4441
],
45-
"input": "stdin",
46-
"implementsPretest": true,
47-
"return": "state"
42+
"not": {
43+
"properties": {
44+
"args": {
45+
"contains": {
46+
"type": "object"
47+
}
48+
}
49+
}
50+
}
51+
},
52+
{
53+
"not": {
54+
"required": [
55+
"input"
56+
]
57+
},
58+
"properties": {
59+
"args": {
60+
"contains": {
61+
"type": "object"
62+
},
63+
"minContains": 1,
64+
"maxContains": 1
65+
}
66+
}
67+
},
68+
{
69+
"required": [
70+
"input"
71+
],
72+
"properties": {
73+
"args": {
74+
"contains": {
75+
"type": "object"
76+
},
77+
"minContains": 1,
78+
"maxContains": 1
79+
}
80+
}
4881
}
4982
]
5083
}

0 commit comments

Comments
 (0)