(SCHEMAS) FIx/update for v3.0.0 release #734
Draft
Conversation
This file contains 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
This change updates casing and terms to match the glossary. These changes are colocated to make reviewing actual schema changes simpler.
This change sets the `minItems` keyword to `0` for the `resources` property of a configuration document. Prior to this change, the schema specified a value of `1`, which was inaccurate. This change fixes PowerShell#717
Prior to this change, the enums in the schema source for the `kind` property of a DSC resource wasn't updated to reflect the change for camelCasing and naming. This change updates the enumeration values and the associated documentation keywords and fixes PowerShell#708.
This change breaks out the capabilities schema from the `dsc resource list` output schema into a separate definition file. This enables us to reference the schema without using a JSON Pointer and provides us with a page for documenting the capabilities directly. This is a required precursor for a future change that defines stdout schemas for resource operations.
Prior to this change, the `returnKind` shared definition set a default value. This was inaccurate, because `set.return` has different behavior when `return` isn't defined - DSC invokes the **Get** operation to construct the result after the **Set** operation for the resource concludes. This change removes the default from the shared definition, adds it to the `test.return` property, and clarifies the behavior for the `set.return` property. Finally, this change also makes `whatIf.return` mandatory, as the synthetic after-state doesn't make sense for this operation, even if DSC will technically accept it.
Prior to this change, the instructions and information about how resources should return data to DSC for any given operation was somewhat vague and not always helpful. This change defines a new set of schemas for the various operations, so resource authors can review their implementations and validate them against these schemas.
This change updates the documentation keywords for the various resource commands to point to the newly defined stdout JSON Schemas. This change was kept separate from the implementation of those schemas to simplify review.
Prior to this change, the schemas erroneously included URIs for the preview schemas and didn't include URIs for the various version folders or `aka.ms` short link options. This change corrects the enumeration values and accompanying documentation keywords.
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 change set includes updates to the schema source files for various issues with the canonically published schemas, including:
minItemskeyword forresourcesproperty of coniguration documentkindreturnKindforset, requiring updating shared definition,set.return,whatIf.return,test.return, and related documentation keywords.$schemaproperty in both configuration document and resource manifest schemasThis change also adds JSON schemas for the expected
stdoutJSON for various resource operations. This should help resource authors understand and validate their resource implementations.TODO:
PR Context
Needed to address issues with the published schemas for the
v3.0.0release. These changes and the technical review of them are required for completing the regeneration and documentation efforts.