Skip to content

Commit 2c5c4bb

Browse files
michaeltlombardimichaeltlombardi
committed
(SCHEMA) Regenerate schemas
This change regenerates the schemas with the updated definitions for the `whatIf` property and `WhatIf` resource capability.
1 parent fb82b79 commit 2c5c4bb

File tree

7 files changed

+539
-0
lines changed

7 files changed

+539
-0
lines changed

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

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
"Get",
2525
"Set",
2626
"SetHandlesExist",
27+
"WhatIf",
2728
"Test",
2829
"Delete",
2930
"Export",
@@ -200,6 +201,9 @@
200201
"set": {
201202
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json"
202203
},
204+
"whatIf": {
205+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.whatIf.json"
206+
},
203207
"test": {
204208
"$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json"
205209
},
@@ -441,6 +445,89 @@
441445
}
442446
]
443447
},
448+
"https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.whatIf.json": {
449+
"$schema": "https://json-schema.org/draft/2020-12/schema",
450+
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.whatIf.json",
451+
"title": "What-if method",
452+
"description": "Defines how DSC must call the DSC Resource to indicate whether and how the set command will modify an instance and how to process the output from the DSC Resource.",
453+
"type": "object",
454+
"required": [
455+
"executable"
456+
],
457+
"properties": {
458+
"executable": {
459+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json"
460+
},
461+
"args": {
462+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json"
463+
},
464+
"input": {
465+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json"
466+
},
467+
"implementsPretest": {
468+
"title": "Resource Performs Pre-Test",
469+
"description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set --what-if` command. Set this value to `true` if the DSC Resource tests input before processing how it will modify system state.",
470+
"type": "boolean",
471+
"default": false
472+
},
473+
"handlesExist": {
474+
"title": "Resource handles _exist property",
475+
"description": "Defines whether the DSC Resource has its own built-in handling for the `_exist` common property. Set this value to `true` if the DSC Resource handles instance deletion internally when receiving a `set --what-if` command where the instance defines the `_exist` property as `false`.",
476+
"type": "boolean",
477+
"default": false
478+
},
479+
"return": {
480+
"description": "Defines whether the command returns a JSON blob of the DSC Resource's expected state after a set operation in what-if mode or the state and an array of the properties the DSC Resource would modify.",
481+
"$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json"
482+
}
483+
},
484+
"oneOf": [
485+
{
486+
"required": [
487+
"input"
488+
],
489+
"not": {
490+
"properties": {
491+
"args": {
492+
"contains": {
493+
"type": "object"
494+
}
495+
}
496+
}
497+
}
498+
},
499+
{
500+
"not": {
501+
"required": [
502+
"input"
503+
]
504+
},
505+
"properties": {
506+
"args": {
507+
"contains": {
508+
"type": "object"
509+
},
510+
"minContains": 1,
511+
"maxContains": 1
512+
}
513+
}
514+
},
515+
{
516+
"required": [
517+
"input"
518+
],
519+
"properties": {
520+
"args": {
521+
"contains": {
522+
"type": "object"
523+
},
524+
"minContains": 1,
525+
"maxContains": 1
526+
}
527+
}
528+
}
529+
]
530+
},
444531
"https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json": {
445532
"$schema": "https://json-schema.org/draft/2020-12/schema",
446533
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json",

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

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
"Get",
2525
"Set",
2626
"SetHandlesExist",
27+
"WhatIf",
2728
"Test",
2829
"Delete",
2930
"Export",
@@ -548,6 +549,9 @@
548549
"set": {
549550
"$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json"
550551
},
552+
"whatIf": {
553+
"$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.whatIf.json"
554+
},
551555
"test": {
552556
"$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json"
553557
},
@@ -895,6 +899,142 @@
895899
}
896900
]
897901
},
902+
"manifest.whatIf.json": {
903+
"$schema": "https://json-schema.org/draft/2020-12/schema",
904+
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.whatIf.json",
905+
"title": "What-if method",
906+
"description": "Defines how DSC must call the DSC Resource to indicate whether and how the set command will modify an instance and how to process the output from the DSC Resource.",
907+
"markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to indicate whether and how the set command will\nmodify an instance and how to process the output from the DSC Resource. If a resource doesn't\ndefine this method in the manifest, DSC synthesizes this behavior by converting the result of\nthe test operation for the resource into the [set result][02].\n\nThis method definition has the same structure as the [set method][03] in the resource manifest.\n\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/whatif?view=dsc-3.0&preserve-view=true\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/outputs/resource/set?view=dsc-3.0&preserve-view=true\n[03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true\n",
908+
"type": "object",
909+
"required": [
910+
"executable"
911+
],
912+
"properties": {
913+
"executable": {
914+
"$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json",
915+
"markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/whatif?view=dsc-3.0&preserve-view=true#executable\n"
916+
},
917+
"args": {
918+
"$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json",
919+
"markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"myresource\",\n \"args\": [\"config\", \"set\", \"--what-if\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config set --what-if\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property.` When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"set\",\n \"--what-if\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config set --what-if --properties <JSON string of instance properties>\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/whatif?view=dsc-3.0&preserve-view=true#args\n"
920+
},
921+
"input": {
922+
"$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json",
923+
"markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/whatif?view=dsc-3.0&preserve-view=true#input\n"
924+
},
925+
"implementsPretest": {
926+
"title": "Resource Performs Pre-Test",
927+
"description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set --what-if` command. Set this value to `true` if the DSC Resource tests input before processing how it will modify system state.",
928+
"type": "boolean",
929+
"default": false,
930+
"markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the DSC Resource performs its own test to ensure idempotency when calling the\n`set --what-if` command . Set this value to `true` if the DSC Resource tests input before\nprocessing how it will modify system state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/whatif?view=dsc-3.0&preserve-view=true#implementspretest\n"
931+
},
932+
"handlesExist": {
933+
"title": "Resource handles _exist property",
934+
"description": "Defines whether the DSC Resource has its own built-in handling for the `_exist` common property. Set this value to `true` if the DSC Resource handles instance deletion internally when receiving a `set --what-if` command where the instance defines the `_exist` property as `false`.",
935+
"type": "boolean",
936+
"default": false,
937+
"markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the DSC Resource has its own built-in handling for the [`_exist`][02] common\nproperty. Set this value to `true` if the DSC Resource handles instance deletion internally\nwhen receiving a `set --what-if` command where the instance defines the `_exist` property as\n`false`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/whatif?view=dsc-3.0&preserve-view=true#handlesExist\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?view=dsc-3.0&preserve-view=true\n"
938+
},
939+
"return": {
940+
"description": "Defines whether the command returns a JSON blob of the DSC Resource's expected state after a set operation in what-if mode or the state and an array of the properties the DSC Resource would modify.",
941+
"$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json",
942+
"markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the command returns a JSON blob of the DSC Resource's expected state after a\nset operation in what-if mode or the state and an array of the properties the DSC Resource\nwould modify.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/whatif?view=dsc-3.0&preserve-view=true#return\n",
943+
"markdownEnumDescriptions": [
944+
"_Final state only_\n\n> Indicates that the resource returns only the instance's expected final state after the\n> set operation as a JSON blob.\n",
945+
"_Final state and changed properties_\n\n> Indicates that the resource returns the instance's expected final state and an array of\n> property names that the resource would modify.\n"
946+
]
947+
}
948+
},
949+
"oneOf": [
950+
{
951+
"required": [
952+
"input"
953+
],
954+
"not": {
955+
"properties": {
956+
"args": {
957+
"contains": {
958+
"type": "object"
959+
}
960+
}
961+
}
962+
}
963+
},
964+
{
965+
"not": {
966+
"required": [
967+
"input"
968+
]
969+
},
970+
"properties": {
971+
"args": {
972+
"errorMessage": "The `whatIf` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/whatif?view=dsc-3.0&preserve-view=true",
973+
"contains": {
974+
"type": "object"
975+
},
976+
"minContains": 1,
977+
"maxContains": 1
978+
}
979+
}
980+
},
981+
{
982+
"required": [
983+
"input"
984+
],
985+
"properties": {
986+
"args": {
987+
"errorMessage": "You can only specify one JSON input argument for the `whatIf` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/whatif?view=dsc-3.0&preserve-view=true",
988+
"contains": {
989+
"type": "object"
990+
},
991+
"minContains": 1,
992+
"maxContains": 1
993+
}
994+
}
995+
}
996+
],
997+
"defaultSnippets": [
998+
{
999+
"label": " Define without arguments",
1000+
"markdownDescription": "Define the `whatIf` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n",
1001+
"body": {
1002+
"input": "${1|stdin,env|}",
1003+
"implementsPretest": "^${2|true,false|}",
1004+
"return": "${3|state,stateAndDiff|}",
1005+
"executable": "${4:executable_name}"
1006+
}
1007+
},
1008+
{
1009+
"label": " Define with string arguments",
1010+
"markdownDescription": "Define the `whatIf` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.",
1011+
"body": {
1012+
"input": "${1|stdin,env|}",
1013+
"implementsPretest": "^${2|true,false|}",
1014+
"return": "${3|state,stateAndDiff|}",
1015+
"executable": "${4:executable_name}",
1016+
"args": [
1017+
"${5:--first-argument}"
1018+
]
1019+
}
1020+
},
1021+
{
1022+
"label": " Define with a JSON input argument",
1023+
"markdownDescription": "Define the `whatIf` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.",
1024+
"body": {
1025+
"implementsPretest": "^${1|true,false|}",
1026+
"return": "${2|state,stateAndDiff|}",
1027+
"executable": "${3:executable_name}",
1028+
"args": [
1029+
{
1030+
"jsonInputArg": "${4:argument_name}",
1031+
"mandatory": "^$5"
1032+
}
1033+
]
1034+
}
1035+
}
1036+
]
1037+
},
8981038
"manifest.test.json": {
8991039
"$schema": "https://json-schema.org/draft/2020-12/schema",
9001040
"$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json",

0 commit comments

Comments
 (0)