docs: Update resource schema reference - #1708
Open
Gijs Reijn (Gijsreyn) wants to merge 1 commit into
Open
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Multiple schema-reference pages now describe behavior/fields that conflict with their stated SchemaID versions (notably v3.1.0), making the documentation internally inconsistent with the repo’s published schemas.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR syncs and restructures DSC schema reference documentation (primarily resource manifest and stdout schema pages) based on updated schema groupings from Microsoft Learn.
Changes:
- Expanded and clarified what-if behavior and method return-shape guidance across
set,test,whatIf, anddeletestdout schema docs. - Updated manifest schema docs to reflect newer manifest capabilities/arguments (e.g., what-if args, adapter input kinds) and refreshed cross-links.
- Refreshed canonical property docs (dates, added
_restartRequiredoverview text, removed TODO stubs).
File summaries
| File | Description |
|---|---|
| docs/reference/schemas/resource/stdout/whatIf.md | Expands what-if stdout semantics and link targets. |
| docs/reference/schemas/resource/stdout/test.md | Updates test stdout behavior documentation and return semantics. |
| docs/reference/schemas/resource/stdout/set.md | Clarifies set vs what-if stdout expectations and adds cross-links. |
| docs/reference/schemas/resource/stdout/list.md | Broadens list stdout documentation and adds/updates fields and links. |
| docs/reference/schemas/resource/stdout/delete.md | Reworks delete stdout docs to describe what-if output behavior. |
| docs/reference/schemas/resource/properties/purge.md | Refreshes metadata and removes TODO footer. |
| docs/reference/schemas/resource/properties/overview.md | Updates canonical properties overview and adds _restartRequired section/link. |
| docs/reference/schemas/resource/properties/inDesiredState.md | Refreshes metadata and updates link footer. |
| docs/reference/schemas/resource/properties/exist.md | Refreshes metadata and removes TODO footer. |
| docs/reference/schemas/resource/properties/ensure.md | Refreshes metadata and clarifies _ensure legacy status. |
| docs/reference/schemas/resource/manifest/whatif.md | Documents deprecation guidance and what-if argument approach. |
| docs/reference/schemas/resource/manifest/validate.md | Broadens validate description beyond group resources and updates examples. |
| docs/reference/schemas/resource/manifest/test.md | Updates test manifest semantics, args kinds, and return/security context docs. |
| docs/reference/schemas/resource/manifest/set.md | Updates set manifest semantics, adds what-if argument guidance and fields. |
| docs/reference/schemas/resource/manifest/schema/property.md | Updates schema property guidance and adds adapter-oriented examples. |
| docs/reference/schemas/resource/manifest/schema/embedded.md | Minor corrections/updates to embedded schema guidance and links. |
| docs/reference/schemas/resource/manifest/root.md | Expands root manifest docs (schema URLs list, properties, capabilities, metadata). |
| docs/reference/schemas/resource/manifest/resolve.md | Updates resolve docs for importer kind and args kinds. |
| docs/reference/schemas/resource/manifest/get.md | Updates get docs for optional input behavior and adds adapter argument example. |
| docs/reference/schemas/resource/manifest/export.md | Updates export docs (capability, filtering validation, args kinds, new fields). |
| docs/reference/schemas/resource/manifest/delete.md | Updates delete docs including what-if argument/capability and new fields. |
| docs/reference/schemas/resource/manifest/adapter.md | Updates adapter docs to inputKind model and new examples/links. |
Review details
- Files reviewed: 22/22 changed files
- Comments generated: 4
- 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
+104
to
109
| ## Required properties | ||
|
|
||
| The `adapter` definition must include these properties: | ||
|
|
||
| - [config](#config) | ||
| - [list](#list) | ||
| - [inputKind](#inputkind) | ||
|
|
Comment on lines
183
to
195
| The `type` property represents the fully qualified type name of the resource. It's used to specify | ||
| the resource in configuration documents and as the value of the `--resource` flag when using the | ||
| `dsc resource *` commands. For more information about resource type names, see | ||
| `dsc resource *` commands. The type name must define an owner segment, any number of optional | ||
| namespace segments separated by periods (`.`), and a name segment separated from the preceding | ||
| segments by a forward slash (`/`), like `Microsoft.Windows/Registry`. Each segment must contain | ||
| only alphanumeric characters and underscores. For more information about resource type names, see | ||
| [DSC Resource fully qualified type name schema reference][01]. | ||
|
|
||
| ```yaml | ||
| Type: string | ||
| Required: true | ||
| Pattern: ^\w+(\.\w+){0,2}\/\w+$ | ||
| Pattern: ^\w+(\.\w+)*\/\w+$ | ||
| ``` |
Comment on lines
16
to
20
| ```yaml | ||
| SchemaDialect: https://json-schema.org/draft/2020-12/schema | ||
| SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/resource/stdout/delete.json | ||
| Type: 'null' | ||
| Type: ['null', object] | ||
| ``` |
Comment on lines
+45
to
56
| ## Required properties | ||
|
|
||
| The output for the `discover` operation must include these properties: | ||
| The output for the **List** operation must include these properties: | ||
|
|
||
| - [type](#type) | ||
| - [kind](#kind) | ||
| - [version](#version) | ||
| - [capabilities](#capabilities) | ||
| - [path](#path) | ||
| - [directory](#directory) | ||
| - [implementedAs](#implementedas) | ||
| - [properties](#properties-1) | ||
| - [requireAdapter](#requireadapter) | ||
|
|
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