(SCHEMA) Add extension secret to schema source #1083
+356
−0
Conversation
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
michaeltlombardi
previously approved these changes
Aug 28, 2025
|
@SteveL-MSFT - this looks correct to me from a docs perspective, just want the technical details double-checked. |
SteveL-MSFT
previously requested changes
Aug 29, 2025
Gijsreyn
force-pushed
the
add-secret-schema
branch
from
d0b4549 to
5229401
Compare
|
Added your remark Mikey, thanks for the rewritten version :) |
|
@Gijsreyn - I'm going to adopt this PR to make some changes to the argument definitions. Adding them as review comments will be more confusing/difficult than updating in place, but I'll sync with you to explain these changes. |
…st schema This change makes some corrections to the documentation for the `secret` field in the extension manifest schema: - Moves the documentation about the capability contract from `secret.executable` up to `secret`. - Redefines the documentation for `secret.executable` to indicate defining the path to an executable file. - Rewrites the documentation for `secret.args` to clarify the requirement to define a secret name input argument exactly once and the implications of not defining the vault input argument. The new documentation also shows examples of manifest snippets and the effective invocation. - Adds annotation keywords to document the various valid argument types. This change makes enhancements to the validation for the `secret` field: - It makes `args` required, even though it isn't required in the schema for the struct, because there's no functional way to pass the name of a secret to the extension without defining a secret name input argument. In `process_secret_args`, DSC considers it valid to define `secret` without any arguments and without the secret name input argument, but doing so means the extension is never sent the name of the secret to retrieve. The same is true for manifests that don't define the vault input argument, though conceivably an extension could be implemented without support for retrieving secrets from a named vault. https://github.com/PowerShell/DSC/blob/4750f779ecb27eb480f7ab37b8e8a526ed5054f5/dsc_lib/src/extensions/secret.rs#L108-L134 - It changes the `anyOf` in `secret.args.items` to `oneOf`, which is more strictly correct. An item must be _either_ a string argument _or_ a secret name input argument _or_ a vault input argument. - It ensures that the minimum length for a defined argument is `1`, preventing the accidental defining of an empty string. Arguably, we should also use the `pattern` keyword to forbid spacing characters, but this change doesn't add that stricter validation. - Replaces usage of `additionalProperties` with `unevaluatedProperties` to better support integrating tools and schema extensions. - Adds the `allOf` keyword to the top level of `secret` to provide validation for defining the correct number of secret name input arguments and vault name input arguments. The author must define exactly one secret name input argument in `secret.args` and zero or one vault input argument. The subschemas use the VS Code extended vocabulary keyword `errorMessage` to provide specific messaging when an author defines too few or too many of the secret name input argument and too many of the vault input argument. Finally, this change also updates the default snippets to remove the invalid snippets, which didn't define the secret name input argument, and to reword the documentation for those snippets. It also corrects the numbering of the snippet placeholders.
This change updates and extends the `markdownDescription` keyword for the `secret` operation stdout schema, clarifying the expected output conditions and validation.
michaeltlombardi
dismissed stale reviews from SteveL-MSFT and themself
Addressed in updates.
|
This PR should be ready for review again. |
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 changeset only adds the extension secret schema.
PR Context
Partially addresses #1082