-
Notifications
You must be signed in to change notification settings - Fork 44
(DOCS) Define decomposed schemas #94
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
SteveL-MSFT
merged 11 commits into
PowerShell:main
from
michaeltlombardi:docs/decomposed-schemas
Aug 4, 2023
Merged
Changes from all commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
d57c824
(DOCS) Define decomposed schemas
michaeltlombardi 14ad588
(MAINT) Improve embedded schema definition
michaeltlombardi 3fb3209
(MAINT) Reorganize parameter definition schemas
michaeltlombardi d7d109a
(MAINT) Add build script for bundling schemas
michaeltlombardi e423498
(MAINT) Simplify decomposed schemas
michaeltlombardi 3979ecf
(DOCS) Document resource and config schemas
michaeltlombardi abea7b7
(DOCS) Update schemas and docs for schema changes
michaeltlombardi ecdd9ba
(DOCS) Document CLI output schemas
michaeltlombardi 5a68b02
(MAINT) Rework schemas for GitHub hosting
michaeltlombardi 5e273ae
Apply suggestions from review
michaeltlombardi 0ee8248
Apply suggestions from review
michaeltlombardi File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,130 @@ | ||
# DSC Configuration document schema reference | ||
|
||
## Synopsis | ||
|
||
The YAML or JSON file that defines a DSC Configuration. | ||
|
||
## Metadata | ||
|
||
```yaml | ||
Schema Dialect : https://json-schema.org/draft/2020-12/schema | ||
Schema ID : https://github.com/raw/PowerShell/DSC/main/schemas/2023/08/config/document.json | ||
Type : object | ||
``` | ||
|
||
## Description | ||
|
||
DSC Configurations enable users to define state by combining different DSC Resources. A | ||
configuration document uses parameters and variables to pass to a set of one or more resources that | ||
define a desired state. | ||
|
||
A configuration document can be defined as either YAML or JSON. For ease of authoring, Microsoft | ||
recommends drafting configuration documents in YAML. | ||
|
||
For DSC's authoring tools to recognize a file as a DSC Configuration document, the filename must | ||
end with `.dsc.config.json` or `.dsc.config.yaml`. | ||
|
||
For more information, see [DSC Configurations overview][01] | ||
|
||
The rest of this document describes the schema DSC uses to validation configuration documents. | ||
|
||
## Examples | ||
|
||
<!-- To-Do --> | ||
|
||
## Required Properties | ||
|
||
Every configuration document must include these properties: | ||
|
||
- [$schema] | ||
- [resources] | ||
|
||
## Properties | ||
|
||
### $schema | ||
|
||
The `$schema` property indicates the canonical URI for the version of this schema that the document | ||
adheres to. DSC uses this property when validating the configuration document before any | ||
configuration operations. | ||
|
||
```yaml | ||
Type: string | ||
Required: true | ||
Format: URI | ||
Valid Values: | ||
- https://github.com/raw/PowerShell/DSC/main/schemas/2023/08/config/document.json | ||
``` | ||
|
||
### metadata | ||
|
||
The `metadata` property defines a set of key-value pairs as annotations for the configuration. DSC | ||
doesn't validate the metadata. A configuration can include any arbitrary information in this | ||
property. | ||
|
||
```yaml | ||
Type: object | ||
Required: false | ||
``` | ||
|
||
### parameters | ||
|
||
The `parameters` property defines a set of runtime options for the configuration. Each parameter is | ||
defined as key-value pair. The key for each pair defines the name of the parameter. The value for | ||
each pair must be an object that defines the `type` keyword to indicate how DSC should process the | ||
parameter. | ||
|
||
Parameters may be overridden at run-time, enabling re-use of the same configuration document for | ||
different contexts. | ||
|
||
For more information about defining parameters in a configuration, see | ||
[DSC Configuration document parameter schema][02]. For more information about using parameters in a | ||
configuration, see [DSC Configuration parameters][03] | ||
|
||
```yaml | ||
Type: object | ||
Required: false | ||
Valid Property Schema: https://github.com/raw/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json | ||
``` | ||
|
||
### variables | ||
|
||
The `variables` property defines a set of reusable values for the resources in the document as | ||
key-value pairs. The key for each pair defines the name of the variable. Resources that reference | ||
the variable by name can access the variable's value. | ||
|
||
This can help reduce the amount of copied values and options for resources in the configuration, | ||
which makes the document easier to read and maintain. Unlike parameters, variables can only be | ||
defined in the configuration and can't be overridden at run-time. | ||
|
||
For more information about using variables in a configuration, see | ||
[DSC Configuration variables][04]. | ||
|
||
```yaml | ||
Type: object | ||
Required: false | ||
``` | ||
|
||
### resources | ||
|
||
The `resources` property defines a list of DSC Resource instances that the configuration manages. | ||
Every instance in the list must be unique, but instances may share the same DSC Resource type. | ||
|
||
For more information about defining a valid resource instance in a configuration, see | ||
[DSC Configuration document resource schema][05]. For more information about how DSC uses resources | ||
in a configuration, see [DSC Configuration resources][06] and | ||
[DSC Configuration resource groups][07]. | ||
michaeltlombardi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
```yaml | ||
Type: array | ||
Required: true | ||
Minimum Item Count: 1 | ||
Valid Item Schema: https://github.com/raw/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json | ||
``` | ||
|
||
[01]: ../../../configurations/overview.md | ||
[02]: parameter.md | ||
[03]: ../../../configurations/parameters.md | ||
[04]: ../../../configurations/variables.md | ||
[05]: resource.md | ||
[06]: ../../../configurations/resources.md | ||
[07]: ../../../configurations/resource-groups.md |
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,185 @@ | ||
# DSC Configuration document parameter schema | ||
|
||
## Synopsis | ||
|
||
Defines runtime options for a configuration. | ||
|
||
## Metadata | ||
|
||
```yaml | ||
Schema Dialect : https://json-schema.org/draft/2020-12/schema | ||
Schema ID : https://github.com/raw/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json | ||
Type : object | ||
``` | ||
|
||
## Description | ||
|
||
DSC Configuration documents can include parameters, which users can override at runtime. Parameters | ||
enable separating secrets from configuration definitions and enable users to write configurations | ||
that can apply to multiple contexts. | ||
|
||
Parameters are defined as key-value pairs in the `parameters` property of a configuration document. | ||
The key is the parameter's name, which is used to reference the parameter in the [resources][01] | ||
property of the configuration document. The value is an object that defines the parameter. | ||
|
||
Every parameter defines its data type. Parameters may also define a default value, validation | ||
checks, a description of their purpose, and arbitrary metadata. | ||
|
||
## Required Properties | ||
|
||
- [type](#type) | ||
|
||
## Properties | ||
|
||
### description | ||
|
||
Parameters may define a short explanation of their purpose and usage with the `description` | ||
property. To define a longer explanation in YAML, use the folded block syntax or literal block | ||
syntax. | ||
|
||
```yaml | ||
Type: string | ||
Required: false | ||
``` | ||
|
||
### metadata | ||
|
||
The `metadata` property defines a set of key-value pairs as annotations for the parameter. DSC | ||
doesn't validate the metadata. A parameter can include any arbitrary information in this property. | ||
|
||
```yaml | ||
Type: object | ||
Required: false | ||
``` | ||
|
||
### type | ||
|
||
Every parameter must define the data type that it expects as the `type` property. DSC validates the | ||
data type for every passed parameter before executing a configuration operation. | ||
|
||
The `secure*` data types indicate that DSC and integrating tools shouldn't log or record the | ||
values. If a secure data type parameter is used for a resource instance property that doesn't | ||
expect a secure value, the resource may still log or record the value. If the resource has | ||
independent logging or recording that isn't handled by DSC, the value may be stored insecurely. | ||
|
||
Use secure strings for passwords and secrets. | ||
|
||
For more information about data types, see | ||
[DSC configuration parameter data type schema reference][02]. | ||
|
||
```yaml | ||
Type: string | ||
Required: true | ||
Valid Values: | ||
- string | ||
- securestring | ||
- int | ||
- bool | ||
- object | ||
- secureobject | ||
- array | ||
``` | ||
|
||
### defaultValue | ||
|
||
Parameters may define a default value with the `defaultValue` property. If the parameter isn't | ||
passed at runtime, DSC uses the default value for the parameter. If the parameter isn't passed at | ||
runtime and no default value is defined, DSC raises an error. The value must be valid for the | ||
parameter's `type`. | ||
|
||
```yaml | ||
Required: false | ||
Valid JSON Types: | ||
- string | ||
- integer | ||
- object | ||
- array | ||
- boolean | ||
``` | ||
|
||
### allowedValues | ||
|
||
Parameters may limit the set of valid values for the parameter by defining the `allowedValues` | ||
property. DSC validates parameters passed at runtime and defined as `defaultValue` against this | ||
list of values. If any of the values is invalid, DSC raises an error. | ||
|
||
This property is always an array. If this property is defined, it must include at least one item in | ||
the list of values. | ||
|
||
```yaml | ||
Type: array | ||
Required: false | ||
Valid Item JSON Types: | ||
- string | ||
- integer | ||
- object | ||
- array | ||
- boolean | ||
``` | ||
|
||
### minLength | ||
|
||
The `minLength` property defines a validation option for array and string parameters. The length of | ||
a string is its character count. The length of an array is its item count. | ||
|
||
If the default value or runtime value for the parameter is shorter than this property, DSC raises | ||
an error. If this property is defined for parameters whose `type` isn't `array`, `string`, or | ||
`securestring`, DSC raises an error. | ||
|
||
If this property is defined with the `maxLength` property, this property must be less than | ||
`maxLength`. If it isn't, DSC raises an error. | ||
|
||
```yaml | ||
Type: int | ||
Required: false | ||
Minimum Value: 0 | ||
``` | ||
|
||
### maxLength | ||
|
||
The `maxLength` property defines a validation option for array and string parameters. The length of | ||
a string is its character count. The length of an array is its item count. | ||
|
||
If the default value or runtime value for the parameter is longer than this property, DSC raises an | ||
error. If this property is defined for parameters whose `type` isn't `array`, `string`, or | ||
`securestring`, DSC raises an error. | ||
|
||
If this property is defined with the `minLength` property, this property must be greater than | ||
`minLength`. If it isn't, DSC raises an error. | ||
|
||
```yaml | ||
Type: int | ||
Required: false | ||
Minimum Value: 0 | ||
``` | ||
|
||
### minValue | ||
|
||
The `minValue` property defines a validation option for integer parameters. If the default value or | ||
runtime value for the parameter is less than this property, DSC raises an error. If this property | ||
is defined for parameters whose `type` isn't `int`, DSC raises an error. | ||
|
||
If this property is defined with the `maxValue` property, this property must be less than | ||
`maxValue`. If it isn't, DSC raises an error. | ||
|
||
```yaml | ||
Type: int | ||
Required: false | ||
``` | ||
|
||
### maxValue | ||
|
||
The `maxValue` property defines a validation option for integer parameters. If the default value or | ||
runtime value for the parameter is greater than this property, DSC raises an error. If this | ||
property is defined for parameters whose `type` isn't `int`, DSC raises an error. | ||
|
||
If this property is defined with the `minValue` property, this property must be greater than | ||
`minValue`. If it isn't, DSC raises an error. | ||
|
||
```yaml | ||
Type: int | ||
Required: false | ||
``` | ||
|
||
[01]: resources.md | ||
[02]: ../definitions/parameters/dataTypes.md |
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.