(DSC) Idiomaticize resource schemas - #2040
Open
Mikey Lombardi (He/Him) (michaeltlombardi) wants to merge 3 commits into
Open
Mikey Lombardi (He/Him) (michaeltlombardi) wants to merge 3 commits into
Mikey Lombardi (He/Him) (michaeltlombardi) wants to merge 3 commits into
Conversation
Prior to this change, there were a few issues with the DSC resource schemas regarding the idiomatic definitions and semantics of JSON schema: 1. Optional properties should not define the `type` keyword with `null` as a valid data type unless `null` is an explicitly modeled state for the property. In JSON Schema, the absence of a property in an object is semantically distinct from a property explicitly set to `null`. Instead, we control the optionality of properties through the `required` or `dependentRequired` keywords. 1. The schema for `Microsoft.PowerShell.PSResourceGet/Repository` didn't define `required` at the top-level. Instead, it used the `allOf` keyword to indicate whether the `name` and `uri` properties are required or just `name`. When a property is always required, we should hoist it to the top-level `required` keyword array. We can still use the `allOf` to conditionally extend the schema as needed. Parsing a JSON Schema is difficult for consumers, moreso when it requires unrolling schema composition. We should surface as much information to the consumer in the simplest form possible. To address these issues, this change: 1. Removes `null` from the `type` keyword for optional properties that don't explicitly model `null` as a valid state. 1. Updates the `Microsoft.PowerShell.PSResourceGet/Repository` schema to define `required` at the top-level to indicate that `name` is always required and simplifies the `allOf` keyword for the remaining case (when `_exist` is `true` then `uri` is required).
Prior to this change, the resource script serialized the data by just
converting the instances to JSON (stripping `_inDesiredState` for
non-test operations).
This caused the resource to serialize `null` for properties that
weren't defined on the instance, causing a mismatch with the idiomatic
schema.
This change updates the serialization logic to omit undefined optional
fields from the serialized output by:
1. Defining the `ToData` method to convert instances to a data
representation that omits undefined optional fields while preserving
property order for predictable serialization.
The method defines two overloads:
- `ToData([bool$forTest)`: Converts the instance to a data
representation, omitting undefined optional fields. If `$forTest`
is `$false`, the method doesn't insert `_inDesiredState`.
- `ToData()`: Convenience overload to call `ToData($false)`.
1. Standardizing the serialization trace messaging and extracting into
reusable methods.
Prior to this change, the `PSResourceList` resource would fail during `export` operations when a scope had no installed resources because it would emit an empty/invalid item. The non-terminating error for no resources in a scope was also erroneously emitted. This change: 1. Defines the `GetAllPsResourcesInScope` function as a wrapper around `Get-PsResource` to retrieve all resources in a given scope, returning an empty array if no resources are found and erroring if the command fails for any other reason. 1. Updates `PopulatePSResourceListObject` to handle empty resource arrays gracefully, emitting an info message instead of invalid data.
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
Copilot started reviewing on behalf of
Mikey Lombardi (He/Him) (michaeltlombardi)
September 14, 2026 21:41
View session
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved critical and moderate export and schema-validation issues remain.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
This PR updates DSC schemas and PSResource serialization/export behavior.
Changes:
- Removes unnecessary nullable types.
- Simplifies repository schema requirements.
- Refactors serialization and empty-scope export handling.
File summaries
| File | Summary and final review comments |
|---|---|
src/dsc/repository.dsc.resource.json |
Refines repository requirements. Moderate (1 vote): Require _exist inside the if schema so absent _exist does not trigger the then branch. |
src/dsc/psresourcelist.dsc.resource.json |
Removes unnecessary nullable property types. |
src/dsc/psresourceget.ps1 |
Updates serialization and export behavior. Critical (3 votes): Single-resource scopes are incorrectly treated as empty at lines 913 and 927. Moderate (3 votes): Empty repositoryName omits a required property. Moderate (3 votes): Catch-all exception handling hides failures as empty results. Nit (1 vote): Add tests for empty scopes and unexpected query failures. |
Review details
Suppressed comments (3)
src/dsc/psresourceget.ps1:927
- When a scope contains exactly one resource,
.Countis 1, so this branch treats the scope as empty and omits that resource from the export. Test for a non-empty collection instead.
if ($currentUserPSResources.count -gt 1) {
src/dsc/psresourceget.ps1:863
- The new empty-scope and error-handling branches are not exercised by the DSC tests: the existing export test installs
testmodule99and only asserts a non-empty exported list. Add coverage for a scope with no installed resources (and for an unexpected query failure) so the new fallback cannot regress into invalid or silently incomplete export output.
try {
Get-PSResource -Scope $Scope -ErrorAction Stop
} catch [Microsoft.PowerShell.PSResourceGet.UtilClasses.ResourceNotFoundException] {
# Everything is fine, there's just no installed resources
@()
} catch {
Write-Trace -level error -message "Failed to get PSResources for '$Scope' scope: $_"
@()
}
src/dsc/repository.dsc.resource.json:83
- Because
ifonly hasproperties, it also evaluates true when_existis absent (propertiesdoes not require the property). Thethenbranch therefore requiresurifor inputs such as{ "name": "repo" }, even though the condition is supposed to apply only when_existis true. Addrequired: ["_exist"]inside theifschema.
"const": true
- Files reviewed: 3/3 changed files
- Comments generated: 3
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| $_.Repository, | ||
| $_.PreRelease ? $true : $false | ||
| ) | ||
| if ($allUsersPSResources.count -gt 1) { |
Comment on lines
+207
to
+209
| if (-not [string]::IsNullOrEmpty($this.repositoryName)) { | ||
| $data['repositoryName'] = $this.repositoryName | ||
| } |
Comment on lines
+860
to
+863
| } catch { | ||
| Write-Trace -level error -message "Failed to get PSResources for '$Scope' scope: $_" | ||
| @() | ||
| } |
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:
nullfrom thetypekeyword for optional resource properties that don't explicitly modelnullas a valid state.Microsoft.PowerShell.PSResourceGet/Repositoryschema to definerequiredat the top-level to indicate thatnameis always required and simplifies theallOfkeyword for the remaining case (when_exististruethenuriis required).exportfunctionality to gracefully handle cases where a scope has zero installed PSResources instead of emitting an unhandled (non-terminating) error and returning invalid data that fails schema validation in DSC.PR Context
Prior to this change, there were a few issues with the DSC resource schemas regarding the idiomatic definitions and semantics of JSON schema:
Optional properties should not define the
typekeyword withnullas a valid data type unlessnullis an explicitly modeled state for the property.In JSON Schema, the absence of a property in an object is semantically distinct from a property explicitly set to
null.Instead, we control the optionality of properties through the
requiredordependentRequiredkeywords.The schema for
Microsoft.PowerShell.PSResourceGet/Repositorydidn't definerequiredat the top-level. Instead, it used theallOfkeyword to indicate whether thenameanduriproperties are required or justname.When a property is always required, we should hoist it to the top-level
requiredkeyword array. We can still use theallOfto conditionally extend the schema as needed.Parsing a JSON Schema is difficult for consumers, moreso when it requires unrolling schema composition. We should surface as much information to the consumer in the simplest form possible.
PR Checklist
.h,.cpp,.cs,.ps1and.psm1files have the correct copyright headerWIP:or[ WIP ]to the beginning of the title (theWIPbot will keep its status check atPendingwhile the prefix is present) and remove the prefix when the PR is ready.