(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 PowerShell#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.

schemas/2024/04/definitions/commandArgs.json

@@ -2,9 +2,37 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json",
   "title": "Executable Command Arguments",
-  "description": "The list of arguments to pass to the command.",
+  "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.",
   "type": "array",
   "items": {
-    "type": "string"
+    "oneOf": [
+      {
+        "type": "string",
+        "title": "String argument",
+        "description": "Any item in the argument array can be a string representing a static argument to pass to the command."
+      },
+      {
+        "type": "object",
+        "title": "JSON input argument",
+        "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.",
+        "required": [
+          "jsonInputArg"
+        ],
+        "unevaluatedProperties": false,
+        "properties": {
+          "jsonInputArg": {
+            "title": "JSON input argument name",
+            "description": "Defines the argument that accepts the JSON property bag for the resource as input.",
+            "type": "string"
+          },
+          "mandatory": {
+            "title": "Mandatory argument",
+            "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`.",
+            "type": "boolean",
+            "default": false
+          }
+        }
+      }
+    ]
   }
 }

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

@@ -21,7 +21,12 @@
           "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json"
         },
         "args": {
-          "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json"
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "title": "Command arguments",
+          "description": "Defines the list of arguments to pass to the command to return the list of supported DSC Resources."
         }
       }
     },

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

@@ -5,8 +5,7 @@
   "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.",
   "type": "object",
   "required": [
-    "executable",
-    "input"
+    "executable"
   ],
   "properties": {
     "executable": {
@@ -19,17 +18,49 @@
       "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json"
     }
   },
-  "examples": [
+  "oneOf": [
     {
-      "executable": "registry",
-      "args": [
-        "config",
-        "delete",
-        "--input",
-        "{json}"
+      "required": [
+        "input"
       ],
-      "input": {
-        "arg": "{json}"
+      "not": {
+        "properties": {
+          "args": {
+            "contains": {
+              "type": "object"
+            }
+          }
+        }
+      }
+    },
+    {
+      "not": {
+        "required": [
+          "input"
+        ]
+      },
+      "properties": {
+        "args": {
+          "contains": {
+            "type": "object"
+          },
+          "minContains": 1,
+          "maxContains": 1
+        }
+      }
+    },
+    {
+      "required": [
+        "input"
+      ],
+      "properties": {
+        "args": {
+          "contains": {
+            "type": "object"
+          },
+          "minContains": 1,
+          "maxContains": 1
+        }
       }
     }
   ]

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json",
-  "title": "Get Method",
+  "title": "Export Method",
   "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.",
   "type": "object",
   "required": [
@@ -13,6 +13,55 @@
     },
     "args": {
       "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json"
+    },
+    "input": {
+      "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json"
+    }
+  },
+  "oneOf": [
+    {
+      "required": [
+        "input"
+      ],
+      "not": {
+        "properties": {
+          "args": {
+            "contains": {
+              "type": "object"
+            }
+          }
+        }
+      }
+    },
+    {
+      "not": {
+        "required": [
+          "input"
+        ]
+      },
+      "properties": {
+        "args": {
+          "contains": {
+            "type": "object"
+          },
+          "minContains": 1,
+          "maxContains": 1
+        }
+      }
+    },
+    {
+      "required": [
+        "input"
+      ],
+      "properties": {
+        "args": {
+          "contains": {
+            "type": "object"
+          },
+          "minContains": 1,
+          "maxContains": 1
+        }
+      }
     }
-  }
+  ]
 }

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

@@ -18,17 +18,50 @@
       "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json"
     }
   },
-  "examples": [
+  "oneOf": [
     {
-      "executable": "registry",
-      "args": [
-        "config",
-        "get"
+      "required": [
+        "input"
       ],
-      "input": "stdin"
+      "not": {
+        "properties": {
+          "args": {
+            "contains": {
+              "type": "object"
+            }
+          }
+        }
+      }
     },
     {
-      "executable": "osinfo"
+      "not": {
+        "required": [
+          "input"
+        ]
+      },
+      "properties": {
+        "args": {
+          "contains": {
+            "type": "object"
+          },
+          "minContains": 1,
+          "maxContains": 1
+        }
+      }
+    },
+    {
+      "required": [
+        "input"
+      ],
+      "properties": {
+        "args": {
+          "contains": {
+            "type": "object"
+          },
+          "minContains": 1,
+          "maxContains": 1
+        }
+      }
     }
   ]
 }

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

@@ -29,7 +29,12 @@
           "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json"
         },
         "args": {
-          "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json"
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "title": "Command arguments",
+          "description": "Defines the list of arguments to pass to the command to return the JSON Schema for the resource."
         }
       }
     },

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

@@ -5,8 +5,7 @@
   "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.",
   "type": "object",
   "required": [
-    "executable",
-    "input"
+    "executable"
   ],
   "properties": {
     "executable": {
@@ -35,16 +34,50 @@
       "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json"
     }
   },
-  "examples": [
+  "oneOf": [
     {
-      "executable": "registry",
-      "args": [
-        "config",
-        "set"
+      "required": [
+        "input"
       ],
-      "input": "stdin",
-      "implementsPretest": true,
-      "return": "state"
+      "not": {
+        "properties": {
+          "args": {
+            "contains": {
+              "type": "object"
+            }
+          }
+        }
+      }
+    },
+    {
+      "not": {
+        "required": [
+          "input"
+        ]
+      },
+      "properties": {
+        "args": {
+          "contains": {
+            "type": "object"
+          },
+          "minContains": 1,
+          "maxContains": 1
+        }
+      }
+    },
+    {
+      "required": [
+        "input"
+      ],
+      "properties": {
+        "args": {
+          "contains": {
+            "type": "object"
+          },
+          "minContains": 1,
+          "maxContains": 1
+        }
+      }
     }
   ]
 }

schemas/2024/04/resource/manifest.test.json

@@ -5,8 +5,7 @@
   "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.",
   "type": "object",
   "required": [
-    "executable",
-    "input"
+    "executable"
   ],
   "properties": {
     "executable": {
@@ -24,15 +23,50 @@
       "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json"
     }
   },
-  "examples": [
+  "oneOf": [
     {
-      "executable": "registry",
-      "args": [
-        "config",
-        "test"
+      "required": [
+        "input"
       ],
-      "input": "stdin",
-      "return": "state"
+      "not": {
+        "properties": {
+          "args": {
+            "contains": {
+              "type": "object"
+            }
+          }
+        }
+      }
+    },
+    {
+      "not": {
+        "required": [
+          "input"
+        ]
+      },
+      "properties": {
+        "args": {
+          "contains": {
+            "type": "object"
+          },
+          "minContains": 1,
+          "maxContains": 1
+        }
+      }
+    },
+    {
+      "required": [
+        "input"
+      ],
+      "properties": {
+        "args": {
+          "contains": {
+            "type": "object"
+          },
+          "minContains": 1,
+          "maxContains": 1
+        }
+      }
     }
   ]
 }