Repository navigation
(DSC) Idiomaticize resource schemas - #2040
Mikey Lombardi (He/Him) (michaeltlombardi) wants to merge 4 commits into
Conversation
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
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.
| } catch { | ||
| Write-Trace -level error -message "Failed to get PSResources for '$Scope' scope: $_" | ||
| @() | ||
| } |
|
Mikey Lombardi (He/Him) (@michaeltlombardi) - again, well done on the work you did here! I did a quick review, and yes, I agree with the direction. I checked the branch against what the DSC engine (v3.3.0) actually enforces and found a few things worth fixing before merging. Also, a small heads-up: it might need a rebase after a couple of PRs land in
Requiring "required": ["name"],
"allOf": [
{
"if": { "properties": { "_exist": { "const": true } }, "required": ["_exist"] },
"then": { "required": ["uri"] }
}
]
Minor:** for a repository that does not exist, |
|
Mikey Lombardi (He/Him) (@michaeltlombardi) - Can you rebase the PR, lot of changes have been merged in the DSC resource since. |
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.
c5bd5cb to
af94cc1
Compare
A few thoughts: Regarding the requirement for URI, I think the more correct implementation and schema is to always require While it's not convenient to require It's worse, in my opinion, to define a resource instance that works for some operaations but not all operations. Consider the following snippet for the properties of a resource instance describing a repository that isn't currently registered: name: MikeyModules
trusted: true
priority: 1The following would work:
But We could leave When we have to make tradeoffs for friction/clarity, I think we should prefer requiring users to define the instance in a way that functions for typical operations (get/set/test) without requiring any munging. Or we should raise warnings/errors to help the user understand how their definition will be invalid for set when they call what-if. It's preferable to require a more-explicit resource instance over surprising runtime failures where we enabled convenience for get/test at the cost of breaking set operations. Further, given that "allOf": [
{
"if": { // If name is PSGallery (case-insensitive)
"properties": {
"name": { "pattern": "(?i)^PSGallery$" }
}
},
"then": { // Then uri must not be defined
"not": { "required": ["uri"] }
},
"else": { // else if name is not PSGallery
"if": { // And exist is `true` or undefined
"properties": {
"_exist": { "const": true }
}
}, // Then uri must be defined
"then": { "required": ["uri"] }
}
}
]I think we need to choose between:
|
|
Aditya Patwardhan (@adityapatwardhan) is there a quick way to force the tests to run for the resource in CI? I had some issues getting the local testing to work and I would definitely prefer to have my local stuff checked by CI before merge where possible. |
|
Running tests from a fork is not supported. Let me push this commit to upstream and create a branch. |
|
Mikey Lombardi (He/Him) (@michaeltlombardi) - please look at - #2069 |
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.