(GH-1563) Enhance the PSScript resources - #1657
Draft
Mikey Lombardi (He/Him) (michaeltlombardi) wants to merge 6 commits into
Draft
(GH-1563) Enhance the PSScript resources#1657Mikey Lombardi (He/Him) (michaeltlombardi) wants to merge 6 commits into
Mikey Lombardi (He/Him) (michaeltlombardi) wants to merge 6 commits into
Conversation
Prior to this change, the PSScript resource manifests embedded a schema that minimally defined the `_inDesiredState` canonical property instead of referencing the canonical schema for that property. This change updates the embedded schemas to reference the canonical schema and adds the embedded schema by ID to the `$defs` keyword.
Prior to this change, the embedded schemas in the manifests for the
transitional PowerShell script resources defined the script properties
with a minimal schema allowing the value to be any string or null. They
didn't include any other keywords.
This change:
1. Defines a shared subschema for the script properties, which they now
reference instead of redefining the constraints for each property.
1. Removed `null` from the allowed types, since defining a script
property as `null` isn't valid but _not_ specifying the property at
all _is_ valid.
1. Added the `writeOnly` keyword to the script properties, since
they're only used for input and not output.
1. Added the `contentMediaType` keyword to the script properties to
clearly indicate---but not validate---that the value is expected to
be a PowerShell script.
1. Added the `minLength` keyword to the script properties to ensure that
an empty string isn't used as a script value.
1. Adds the `title` and `description` keywords to the script properties
to provide more context for each property in the schema.
Prior to this change, the `input` property for the PSScript resource schemas defined the valid types with two problems: 1. It allowed `null` as a valid type, which caused failures when the resource invoked the scripts. 1. It didn't allow non-integer numbers, erroneously preventing users from defining input values like `3.14`, even though `[3.14]` was accepted. This change: 1. Removes `null` from the valid types for `input`. 1. Adds `number` to the valid types for `input`, allowing non-integer numbers to be used as input values. 1. Adds the `title` and `description` keywords to the `input` property, providing better documentation for users.
Prior to this change, the embedded schemas for the PSScript resources didn't require any properties to be defined. For input, a user should always define at least one script property. For output, the resource should always return one of three value shapes: 1. For `test` operations, the resource should always define the `inDesiredState` property. 1. For implemented `get` and `set` operations, the resource should define the `output` property when the script emits any output to the success stream. 1. When `get` and `set` operations aren't implemented or don't emit any output, the resource should return an empty object. This change adds constraints to the embedded schemas with the `oneOf` keyword and nested `oneOf`/`anyOf` keywords to enforce these rules.
Prior to this change, the embedded schema for the PSScript resources didn't define the `title` or `description` keywords. This change: 1. Adds `title` and `description` keywords to the embedded schema for the PSScript resources to provide some documentation for them. 1. Defines the `$schema` keyword explicitly.
Prior to this change, the PSScript resources: 1. Always returned an array of output objects, even if there was only one object. 1. Didn't ensure that enums in script output were serialized as strings, causing enums to emit as integers, which is likely not what the user intended and makes review more difficult. This change: 1. Ensures that if a script returns a single object, it's serialized as that object instead of nested in an array. 1. Adds the `-EnumAsString` parameter to the `ConvertTo-Json` call for emitting script output when invoked through PowerShell to ensure that enums are serialized as strings. This enhancement doesn't affect Windows PowerShell, which doesn't support the `-EnumAsString` parameter. 1. Updates the tests to reflect the new behavior of returning a single object instead of an array. 1. Fixes the tests to use correct casing for the script properties, now that the schema validation checks for those properties.
Mikey Lombardi (He/Him) (michaeltlombardi)
requested a lite review from Copilot
August 6, 2026 18:46
Mikey Lombardi (He/Him) (michaeltlombardi)
requested a lite review from Copilot
August 6, 2026 19:45
Copilot started reviewing on behalf of
Mikey Lombardi (He/Him) (michaeltlombardi)
August 6, 2026 23:20
View session
Copilot started reviewing on behalf of
Mikey Lombardi (He/Him) (michaeltlombardi)
August 6, 2026 23:24
View session
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Summary
This change:
Canonicalizes the JSON Schema for the transitional PowerShell script resources by
titleanddescriptionkeywords for every property._inDesiredStateand referencing it instead of redefining it.contentMediaTypekeyword.output, or an object with_inDesiredState).inputand forbidding passingnullUpdates the emitted data for
output. Prior to this change, theoutputproperty was always an array. This change checks whether the resource emitted any output and:outputdefined as a scalar value when the script only emitted a single item.outputdefined as an array when the script emitted two or more items.PR Context
Addresses issues with the schema and implementation of the PSScript resources and fixes #1563.