Skip to content

Commit 473b174

Browse files
SteveL-MSFTSteveL-MSFT
authored
Merge pull request #94 from michaeltlombardi/docs/decomposed-schemas
(DOCS) Define decomposed schemas
2 parents c6eb4b0 + 0ee8248 commit 473b174

File tree

113 files changed

+8106
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

113 files changed

+8106
-0
lines changed

‎docs/reference/schemas/config/document.md

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# DSC Configuration document schema reference
2+
3+
## Synopsis
4+
5+
The YAML or JSON file that defines a DSC Configuration.
6+
7+
## Metadata
8+
9+
```yaml
10+
Schema Dialect : https://json-schema.org/draft/2020-12/schema
11+
Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
12+
Type : object
13+
```
14+
15+
## Description
16+
17+
DSC Configurations enable users to define state by combining different DSC Resources. A
18+
configuration document uses parameters and variables to pass to a set of one or more resources that
19+
define a desired state.
20+
21+
A configuration document can be defined as either YAML or JSON. For ease of authoring, Microsoft
22+
recommends drafting configuration documents in YAML.
23+
24+
For DSC's authoring tools to recognize a file as a DSC Configuration document, the filename must
25+
end with `.dsc.config.json` or `.dsc.config.yaml`.
26+
27+
For more information, see [DSC Configurations overview][01]
28+
29+
The rest of this document describes the schema DSC uses to validation configuration documents.
30+
31+
## Examples
32+
33+
<!-- To-Do -->
34+
35+
## Required Properties
36+
37+
Every configuration document must include these properties:
38+
39+
- [$schema]
40+
- [resources]
41+
42+
## Properties
43+
44+
### $schema
45+
46+
The `$schema` property indicates the canonical URI for the version of this schema that the document
47+
adheres to. DSC uses this property when validating the configuration document before any
48+
configuration operations.
49+
50+
```yaml
51+
Type: string
52+
Required: true
53+
Format: URI
54+
Valid Values:
55+
- https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
56+
```
57+
58+
### metadata
59+
60+
The `metadata` property defines a set of key-value pairs as annotations for the configuration. DSC
61+
doesn't validate the metadata. A configuration can include any arbitrary information in this
62+
property.
63+
64+
```yaml
65+
Type: object
66+
Required: false
67+
```
68+
69+
### parameters
70+
71+
The `parameters` property defines a set of runtime options for the configuration. Each parameter is
72+
defined as key-value pair. The key for each pair defines the name of the parameter. The value for
73+
each pair must be an object that defines the `type` keyword to indicate how DSC should process the
74+
parameter.
75+
76+
Parameters may be overridden at run-time, enabling re-use of the same configuration document for
77+
different contexts.
78+
79+
For more information about defining parameters in a configuration, see
80+
[DSC Configuration document parameter schema][02]. For more information about using parameters in a
81+
configuration, see [DSC Configuration parameters][03]
82+
83+
```yaml
84+
Type: object
85+
Required: false
86+
Valid Property Schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json
87+
```
88+
89+
### variables
90+
91+
The `variables` property defines a set of reusable values for the resources in the document as
92+
key-value pairs. The key for each pair defines the name of the variable. Resources that reference
93+
the variable by name can access the variable's value.
94+
95+
This can help reduce the amount of copied values and options for resources in the configuration,
96+
which makes the document easier to read and maintain. Unlike parameters, variables can only be
97+
defined in the configuration and can't be overridden at run-time.
98+
99+
For more information about using variables in a configuration, see
100+
[DSC Configuration variables][04].
101+
102+
```yaml
103+
Type: object
104+
Required: false
105+
```
106+
107+
### resources
108+
109+
The `resources` property defines a list of DSC Resource instances that the configuration manages.
110+
Every instance in the list must be unique, but instances may share the same DSC Resource type.
111+
112+
For more information about defining a valid resource instance in a configuration, see
113+
[DSC Configuration document resource schema][05]. For more information about how DSC uses resources
114+
in a configuration, see [DSC Configuration resources][06] and
115+
[DSC Configuration resource groups][07].
116+
117+
```yaml
118+
Type: array
119+
Required: true
120+
Minimum Item Count: 1
121+
Valid Item Schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json
122+
```
123+
124+
[01]: ../../../configurations/overview.md
125+
[02]: parameter.md
126+
[03]: ../../../configurations/parameters.md
127+
[04]: ../../../configurations/variables.md
128+
[05]: resource.md
129+
[06]: ../../../configurations/resources.md
130+
[07]: ../../../configurations/resource-groups.md

‎docs/reference/schemas/config/parameter.md

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# DSC Configuration document parameter schema
2+
3+
## Synopsis
4+
5+
Defines runtime options for a configuration.
6+
7+
## Metadata
8+
9+
```yaml
10+
Schema Dialect : https://json-schema.org/draft/2020-12/schema
11+
Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json
12+
Type : object
13+
```
14+
15+
## Description
16+
17+
DSC Configuration documents can include parameters, which users can override at runtime. Parameters
18+
enable separating secrets from configuration definitions and enable users to write configurations
19+
that can apply to multiple contexts.
20+
21+
Parameters are defined as key-value pairs in the `parameters` property of a configuration document.
22+
The key is the parameter's name, which is used to reference the parameter in the [resources][01]
23+
property of the configuration document. The value is an object that defines the parameter.
24+
25+
Every parameter defines its data type. Parameters may also define a default value, validation
26+
checks, a description of their purpose, and arbitrary metadata.
27+
28+
## Required Properties
29+
30+
- [type](#type)
31+
32+
## Properties
33+
34+
### description
35+
36+
Parameters may define a short explanation of their purpose and usage with the `description`
37+
property. To define a longer explanation in YAML, use the folded block syntax or literal block
38+
syntax.
39+
40+
```yaml
41+
Type: string
42+
Required: false
43+
```
44+
45+
### metadata
46+
47+
The `metadata` property defines a set of key-value pairs as annotations for the parameter. DSC
48+
doesn't validate the metadata. A parameter can include any arbitrary information in this property.
49+
50+
```yaml
51+
Type: object
52+
Required: false
53+
```
54+
55+
### type
56+
57+
Every parameter must define the data type that it expects as the `type` property. DSC validates the
58+
data type for every passed parameter before executing a configuration operation.
59+
60+
The `secure*` data types indicate that DSC and integrating tools shouldn't log or record the
61+
values. If a secure data type parameter is used for a resource instance property that doesn't
62+
expect a secure value, the resource may still log or record the value. If the resource has
63+
independent logging or recording that isn't handled by DSC, the value may be stored insecurely.
64+
65+
Use secure strings for passwords and secrets.
66+
67+
For more information about data types, see
68+
[DSC configuration parameter data type schema reference][02].
69+
70+
```yaml
71+
Type: string
72+
Required: true
73+
Valid Values:
74+
- string
75+
- securestring
76+
- int
77+
- bool
78+
- object
79+
- secureobject
80+
- array
81+
```
82+
83+
### defaultValue
84+
85+
Parameters may define a default value with the `defaultValue` property. If the parameter isn't
86+
passed at runtime, DSC uses the default value for the parameter. If the parameter isn't passed at
87+
runtime and no default value is defined, DSC raises an error. The value must be valid for the
88+
parameter's `type`.
89+
90+
```yaml
91+
Required: false
92+
Valid JSON Types:
93+
- string
94+
- integer
95+
- object
96+
- array
97+
- boolean
98+
```
99+
100+
### allowedValues
101+
102+
Parameters may limit the set of valid values for the parameter by defining the `allowedValues`
103+
property. DSC validates parameters passed at runtime and defined as `defaultValue` against this
104+
list of values. If any of the values is invalid, DSC raises an error.
105+
106+
This property is always an array. If this property is defined, it must include at least one item in
107+
the list of values.
108+
109+
```yaml
110+
Type: array
111+
Required: false
112+
Valid Item JSON Types:
113+
- string
114+
- integer
115+
- object
116+
- array
117+
- boolean
118+
```
119+
120+
### minLength
121+
122+
The `minLength` property defines a validation option for array and string parameters. The length of
123+
a string is its character count. The length of an array is its item count.
124+
125+
If the default value or runtime value for the parameter is shorter than this property, DSC raises
126+
an error. If this property is defined for parameters whose `type` isn't `array`, `string`, or
127+
`securestring`, DSC raises an error.
128+
129+
If this property is defined with the `maxLength` property, this property must be less than
130+
`maxLength`. If it isn't, DSC raises an error.
131+
132+
```yaml
133+
Type: int
134+
Required: false
135+
Minimum Value: 0
136+
```
137+
138+
### maxLength
139+
140+
The `maxLength` property defines a validation option for array and string parameters. The length of
141+
a string is its character count. The length of an array is its item count.
142+
143+
If the default value or runtime value for the parameter is longer than this property, DSC raises an
144+
error. If this property is defined for parameters whose `type` isn't `array`, `string`, or
145+
`securestring`, DSC raises an error.
146+
147+
If this property is defined with the `minLength` property, this property must be greater than
148+
`minLength`. If it isn't, DSC raises an error.
149+
150+
```yaml
151+
Type: int
152+
Required: false
153+
Minimum Value: 0
154+
```
155+
156+
### minValue
157+
158+
The `minValue` property defines a validation option for integer parameters. If the default value or
159+
runtime value for the parameter is less than this property, DSC raises an error. If this property
160+
is defined for parameters whose `type` isn't `int`, DSC raises an error.
161+
162+
If this property is defined with the `maxValue` property, this property must be less than
163+
`maxValue`. If it isn't, DSC raises an error.
164+
165+
```yaml
166+
Type: int
167+
Required: false
168+
```
169+
170+
### maxValue
171+
172+
The `maxValue` property defines a validation option for integer parameters. If the default value or
173+
runtime value for the parameter is greater than this property, DSC raises an error. If this
174+
property is defined for parameters whose `type` isn't `int`, DSC raises an error.
175+
176+
If this property is defined with the `minValue` property, this property must be greater than
177+
`minValue`. If it isn't, DSC raises an error.
178+
179+
```yaml
180+
Type: int
181+
Required: false
182+
```
183+
184+
[01]: resources.md
185+
[02]: ../definitions/parameters/dataTypes.md

0 commit comments

Comments
 (0)