docs: Update extension schema reference - #1706
Open
Gijs Reijn (Gijsreyn) wants to merge 1 commit into
Open
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The updated docs materially diverge from the schemas currently checked into this repo (including documenting schema versions and properties/argument forms that aren’t present), which is likely to mislead users and break validation expectations.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Updates the DSC extension schema reference documentation (synced from Microsoft Learn) to reflect newer/expanded extension manifest and discover output behaviors, including additional capabilities and revised schema URI guidance.
Changes:
- Expanded extension discover stdout documentation to describe
manifestPathvsmanifestContentoutputs and related discovery behavior. - Expanded extension manifest root documentation with capability descriptions, additional manifest properties, and a much larger set of
$schemaURI examples. - Updated extension manifest discover documentation to describe a newer argument shape for
discover.args(including anextensionsArgobject) and added an example.
File summaries
| File | Description |
|---|---|
| docs/reference/schemas/extension/stdout/discover.md | Updates the documented stdout schema/behavior for extension discovery output. |
| docs/reference/schemas/extension/manifest/root.md | Updates the documented extension manifest root schema, including $schema URI options and additional properties/capabilities. |
| docs/reference/schemas/extension/manifest/discover.md | Updates the documented discover manifest property schema and examples, including argument semantics. |
Review details
- Files reviewed: 3/3 changed files
- Comments generated: 5
- 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
76
to
82
| ### args | ||
|
|
||
| The `args` property defines the list of arguments to pass to the command. The arguments can be any | ||
| number of strings. If you want to pass the JSON object representing the property bag for the | ||
| extension input to an argument, you can define a single item in the array as a | ||
| [JSON object](#json-input-argument), indicating the name of the argument with the `jsonInputArg` | ||
| string property and whether the argument is mandatory for the command with the `mandatory` boolean | ||
| property. | ||
| The `args` property defines the list of arguments to pass to the command. Each item in the array | ||
| can be a string representing a static argument or an | ||
| [extensions argument](#extensions-argument) object that receives the list of file extensions DSC | ||
| recognizes for manifests. | ||
|
|
| Type: string | ||
| Required: true | ||
| Pattern: ^\w+(\.\w+){0,3}\/\w+$ | ||
| Pattern: ^\w+(\.\w+)*\/\w+$ |
| Type: string | ||
| Required: true | ||
| Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ | ||
| Pattern: ^(?<major>(?:0|[1-9]\d*))\.(?<minor>(?:0|[1-9]\d*))\.(?<patch>(?:0|[1-9]\d*))(?:-(?<prerelease>(?:(?:0|[1-9]\d*)|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:(?:0|[1-9]\d*)|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ |
Comment on lines
+212
to
+216
| ### condition | ||
|
|
||
| The `condition` property defines a DSC configuration expression that DSC evaluates during | ||
| discovery to determine whether the extension is usable on the system. If the expression evaluates | ||
| to `false`, DSC discards the extension during discovery and writes a debug message indicating that |
Comment on lines
+24
to
+29
| Represents a DSC manifest that the extension discovered, either as the absolute path to the | ||
| manifest file on the system or as the content of the manifest. DSC expects every JSON Line emitted | ||
| to stdout for the **Discover** operation to adhere to this schema. | ||
|
|
||
| The output must be a JSON object. The object must define the full path to the discovered manifest. | ||
| If an extension returns JSON that is invalid against this schema, DSC raises an error. | ||
| The output must be a JSON object. The object must define exactly one of the [manifestPath][01] or | ||
| [manifestContent][02] properties. If an extension returns JSON that is invalid against this schema, |
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