(GH-1563) Enhance the PSScript resources

[Mikey Lombardi (He/Him) (michaeltlombardi)]

PR Summary

This change:

1. Canonicalizes the JSON Schema for the transitional PowerShell script resources by

   • Adding the title and description keywords for every property.
   • Embedding the canonical property definition for _inDesiredState and referencing it instead of redefining it.
   • Using a shared subschema for the script properties that ensures they are strings with a minimum length of 1 and indicates that the expected content is PowerShell script code in with the contentMediaType keyword.
   • Adding constraints to verify the shape of an instance for input (requiring one or more script property) and output (requiring an empty object, an object with output, or an object with _inDesiredState).
   • Allowing users to pass non-integer numbers for input and forbidding passing null

2. Updates the emitted data for output. Prior to this change, the output property was always an array. This change checks whether the resource emitted any output and:

• Emits an empty object when the script doesn't emit any data.
• Emits an object with output defined as a scalar value when the script only emitted a single item.
• Emits an object with output defined as an array when the script emitted two or more items.

1. Updates the version of the resource to reflect the changes in schema and behavior.

PR Context

Addresses issues with the schema and implementation of the PSScript resources and fixes #1563.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (5)

resources/PSScript/psscript.dsc.resource.json:163

• The schema embeds a canonical definition for _inDesiredState in $defs, but _inDesiredState currently $refs the remote URL instead. This contradicts the PR description (embed + reference) and can introduce an unnecessary network dependency during schema resolution.

                "_inDesiredState": {
                    "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/inDesiredState.json"
                }
            },
            "$defs": {
                "powershellScript": {
                    "writeOnly": true,
                    "type": "string",
                    "minLength": 1,
                    "contentMediaType": "text/vnd.microsoft.powershell"
                },
                "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/inDesiredState.json": {
                    "$schema": "https://json-schema.org/draft/2020-12/schema",

resources/PSScript/winpsscript.dsc.resource.json:162

• The schema embeds a canonical definition for _inDesiredState in $defs, but _inDesiredState currently $refs the remote URL instead. This contradicts the PR description (embed + reference) and can introduce an unnecessary network dependency during schema resolution.

                "_inDesiredState": {
                    "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/inDesiredState.json"
                }
            },
            "$defs": {
                "powershellScript": {
                    "writeOnly": true,
                    "type": "string",
                    "minLength": 1,
                    "contentMediaType": "text/vnd.microsoft.powershell"
                },
                "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/inDesiredState.json": {
                    "$schema": "https://json-schema.org/draft/2020-12/schema",

resources/PSScript/psscript.ps1:207

• ConvertTo-Json -EnumsAsStrings is gated only by $PSVersionTable.PSVersion -ge 6.0, but the safer check is whether the running ConvertTo-Json actually supports the parameter. This avoids runtime failures on pwsh builds that don’t include -EnumsAsStrings (and naturally disables it on Windows PowerShell).

    if ($PSVersionTable.PSVersion -ge [Version]'6.0') {
        $toJsonParams['EnumsAsStrings'] = $true
    }

resources/PSScript/psscript.dsc.resource.json:78

• This description says the empty-object return shape is only for operations with an undefined script, but psscript.ps1 now also emits an empty object when a script runs and produces no output. Updating the description avoids misleading schema docs.

This issue also appears on line 151 of the same file.

                            "description": "Defines the return data as an empty object for operations with an undefined script.",
                            "minProperties": 0,
                            "maxProperties": 0
                        },

resources/PSScript/winpsscript.dsc.resource.json:77

• This description says the empty-object return shape is only for operations with an undefined script, but psscript.ps1 now also emits an empty object when a script runs and produces no output. Updating the description avoids misleading schema docs.

This issue also appears on line 150 of the same file.

                            "description": "Defines the return data as an empty object for operations with an undefined script.",
                            "minProperties": 0,
                            "maxProperties": 0
                        },