docs: Update configuration document schema reference - #1707
Open
Gijs Reijn (Gijsreyn) wants to merge 1 commit into
Open
docs: Update configuration document schema reference#1707Gijs Reijn (Gijsreyn) wants to merge 1 commit into
Gijs Reijn (Gijsreyn) wants to merge 1 commit into
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Several documentation updates conflict with the referenced v3.1.0 JSON schemas (including documenting unsupported properties and listing schema versions/URLs that do not exist in-repo), which would mislead users.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates the DSC configuration schema reference documentation (synced from Microsoft Learn) under docs/reference/schemas/config/, expanding and reorganizing schema reference content and refreshing metadata dates.
Changes:
- Updated the resource instance schema reference with new/expanded properties and revised constraints.
- Updated the configuration document schema reference with additional
$schemaURL variants and new documented top-level properties. - Updated parameter schema type value casing (for
secureString/secureObject) and aligned related wording.
File summaries
| File | Description |
|---|---|
| docs/reference/schemas/config/resource.md | Updates the resource instance schema reference content, including required properties and constraints. |
| docs/reference/schemas/config/parameter.md | Updates parameter type ValidValues casing and related explanatory text. |
| docs/reference/schemas/config/metadata.md | Updates metadata guidance and securityContext value casing to align with current schema expectations. |
| docs/reference/schemas/config/document.md | Expands $schema ValidValues list and documents additional configuration document properties/directives. |
Review details
Suppressed comments (4)
docs/reference/schemas/config/resource.md:45
conditionis documented as part of the resource instance schema, but the referenced schema file (schemas/v3.1.0/config/document.resource.json) does not define aconditionproperty; documenting it here will mislead users and validators unless the schema is updated or this page is explicitly scoped to a newer schema version.
### condition
The `condition` property defines an expression that DSC evaluates before invoking the instance. If
the expression evaluates to `true`, DSC invokes the instance as normal. If it evaluates to any other
value, DSC skips the instance and doesn't include it in the results for the operation.
docs/reference/schemas/config/resource.md:76
- The
typeregex pattern here is broader than the referenced schema constraint.schemas/v3.1.0/definitions/resourceType.jsonlimits dot-separated segments to{0,3}; using*suggests unlimited segments and doesn't match validation behavior.
Pattern: ^\w+(\.\w+)*\/\w+$
docs/reference/schemas/config/resource.md:123
- Inside the
nameschema block, the property is marked optional with a default empty string, but the referenced schema (schemas/v3.1.0/config/document.resource.json + definitions/instanceName.json) requiresnameand enforces minLength/pattern constraints. This block should reflect the schema’s required/constraint settings.
Type: string
Required: false
Default: ""
docs/reference/schemas/config/resource.md:245
- The
dependsOnschema block currently implies any string is allowed, but the referenced JSON schema constrains items to resourceId()-expression strings and intends uniqueness. Please restore the item constraints to match schema validation.
Type: array
Required: false
ItemsType: string
- Files reviewed: 4/4 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.
Comment on lines
+197
to
+201
| ### contentVersion | ||
|
|
||
| The `contentVersion` property defines a version string for the configuration document. You can use | ||
| this property to track revisions of the document. DSC doesn't validate or use this value when | ||
| processing a configuration document. The document that the `dsc config export` command returns |
Comment on lines
35
to
37
| Every resource instance must be an object that defines these properties: | ||
|
|
||
| - [name](#name) | ||
| - [type](#type) |
Comment on lines
79
to
83
| ```yaml | ||
| Type: string | ||
| Required: true | ||
| ValidValues: [string, securestring, int, bool, object, secureobject, array] | ||
| ValidValues: [string, secureString, int, bool, object, secureObject, array] | ||
| ``` |
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
As requested, shortened the number of files and updated them based on separate schema groups.
PR context
Synced docs from Microsoft Learn: MicrosoftDocs/PowerShell-Docs-DSC#414