Skip to content

Commit 9903df4

Browse files
SteveL-MSFTSteveL-MSFT
authored
Merge pull request #890 from michaeltlombardi/schema/main/v3.1.0
(SCHEMA) Update schemas for v3.1.0 release
2 parents b7ad7ec + e741bae commit 9903df4

File tree

502 files changed

+68336
-192
lines changed

Some content is hidden

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

502 files changed

+68336
-192
lines changed

‎schemas/build.ps1

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -675,6 +675,7 @@ process {
675675
"$OutputDirectory/config"
676676
"$OutputDirectory/metadata"
677677
"$OutputDirectory/definitions"
678+
"$OutputDirectory/extension"
678679
"$OutputDirectory/outputs"
679680
"$OutputDirectory/resource"
680681
)

‎schemas/schemas.config.yaml

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,15 @@
11
host: https://raw.githubusercontent.com
22
prefix: PowerShell/DSC/main/schemas
3-
version: v3.0
3+
version: v3.1.0
44
docs_base_url: https://learn.microsoft.com/powershell/dsc
55
docs_version_pin: view=dsc-3.0&preserve-view=true
66
bundle_schemas:
7+
# Resource manifest bundle
8+
- ConfigFilePath: extension/manifest.json
9+
Name: manifest
10+
OutputDirectory: bundled/extension
11+
OutputFormat: ['Json', 'JsonVSCode']
12+
713
# Resource manifest bundle
814
- ConfigFilePath: resource/manifest.json
915
Name: manifest
@@ -37,6 +43,11 @@ bundle_schemas:
3743
OutputDirectory: bundled/outputs/config
3844
OutputFormat: ['Json', 'JsonVSCode']
3945

46+
- ConfigFilePath: outputs/extension/list.json
47+
Name: list
48+
OutputDirectory: bundled/outputs/extension
49+
OutputFormat: ['Json', 'JsonVSCode']
50+
4051
- ConfigFilePath: outputs/resource/get.json
4152
Name: get
4253
OutputDirectory: bundled/outputs/resource
@@ -61,3 +72,59 @@ bundle_schemas:
6172
Name: test
6273
OutputDirectory: bundled/outputs/resource
6374
OutputFormat: ['Json', 'JsonVSCode']
75+
76+
# stdout schema bundles
77+
- ConfigFilePath: extension/stdout/discover.json
78+
Name: discover
79+
OutputDirectory: bundled/extension/stdout
80+
OutputFormat: ['Json', 'JsonVSCode']
81+
82+
- ConfigFilePath: resource/stdout/delete.json
83+
Name: delete
84+
OutputDirectory: bundled/resource/stdout
85+
OutputFormat: ['Json', 'JsonVSCode']
86+
87+
- ConfigFilePath: resource/stdout/export.json
88+
Name: export
89+
OutputDirectory: bundled/resource/stdout
90+
OutputFormat: ['Json', 'JsonVSCode']
91+
92+
- ConfigFilePath: resource/stdout/get.json
93+
Name: get
94+
OutputDirectory: bundled/resource/stdout
95+
OutputFormat: ['Json', 'JsonVSCode']
96+
97+
- ConfigFilePath: resource/stdout/list.json
98+
Name: list
99+
OutputDirectory: bundled/resource/stdout
100+
OutputFormat: ['Json', 'JsonVSCode']
101+
102+
- ConfigFilePath: resource/stdout/resolve.json
103+
Name: resolve
104+
OutputDirectory: bundled/resource/stdout
105+
OutputFormat: ['Json', 'JsonVSCode']
106+
107+
- ConfigFilePath: resource/stdout/schema.json
108+
Name: schema
109+
OutputDirectory: bundled/resource/stdout
110+
OutputFormat: ['Json', 'JsonVSCode']
111+
112+
- ConfigFilePath: resource/stdout/set.json
113+
Name: set
114+
OutputDirectory: bundled/resource/stdout
115+
OutputFormat: ['Json', 'JsonVSCode']
116+
117+
- ConfigFilePath: resource/stdout/test.json
118+
Name: test
119+
OutputDirectory: bundled/resource/stdout
120+
OutputFormat: ['Json', 'JsonVSCode']
121+
122+
- ConfigFilePath: resource/stdout/validate.json
123+
Name: validate
124+
OutputDirectory: bundled/resource/stdout
125+
OutputFormat: ['Json', 'JsonVSCode']
126+
127+
- ConfigFilePath: resource/stdout/whatIf.json
128+
Name: whatIf
129+
OutputDirectory: bundled/resource/stdout
130+
OutputFormat: ['Json', 'JsonVSCode']

‎schemas/src/config/document.yaml

Lines changed: 414 additions & 0 deletions
Large diffs are not rendered by default.

‎schemas/src/definitions/extensionCapabilities.yaml

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema
2+
$schema: https://json-schema.org/draft/2020-12/schema
3+
$id: <HOST>/<PREFIX>/<VERSION>/definitions/extensionCapabilities.yaml
4+
5+
title: Resource capabilities
6+
description: >-
7+
Define the operations DSC can invoke for an extension and how the extension behaves when invoked.
8+
9+
markdownDescription: |-
10+
***
11+
[_Online Documentation_][00]
12+
***
13+
14+
DSC extensions always have at least one capability. Extension capabilities define the operations
15+
DSC can invoke for an extension and how the extension behaves when invoked.
16+
17+
<!-- Link reference definitions -->
18+
[00]: <DOCS_BASE_URL>/reference/schemas/definitions/extensionCapabilities?<DOCS_VERSION_PIN>
19+
20+
type: array
21+
items:
22+
type: string
23+
enum:
24+
- discover
25+
markdownEnumDescriptions:
26+
- |- # discover
27+
***
28+
[_Online Documentation_][00]
29+
***
30+
31+
An extension with the `discover` capability supports retrieving the path to DSC resource
32+
manifests that aren't included in the `PATH` or `DSC_RESOURCE_PATH`, like manifests for
33+
software installed as AppX packages.
34+
35+
An extension has this capability when its manifest defines the [discover][02]
36+
property.
37+
38+
<!-- Link reference definitions -->
39+
[00]: <DOCS_BASE_URL>/reference/schemas/definitions/extensionCapabilities?<DOCS_VERSION_PIN>#discover
40+
[02]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/discover?<DOCS_VERSION_PIN>

‎schemas/src/definitions/extensionType.yaml

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema
2+
$schema: https://json-schema.org/draft/2020-12/schema
3+
$id: <HOST>/<PREFIX>/<VERSION>/definitions/extensionType.yaml
4+
5+
title: DSC extension fully qualified type name
6+
description: |
7+
The namespaced name of the DSC extension, using the syntax:
8+
9+
<owner>[.<group>][.<area>][.<subarea>]/<name>
10+
11+
For example:
12+
13+
- Microsoft/Example
14+
- Microsoft.DSC/Docs
15+
- Microsoft.Windows.Appx/Discover
16+
17+
type: string
18+
pattern: ^\w+(\.\w+){0,3}\/\w+$
19+
20+
# VS Code only
21+
markdownDescription: |
22+
***
23+
[_Online Documentation_][01]
24+
***
25+
26+
The namespaced name of the DSC extension, using the syntax:
27+
28+
```yaml
29+
owner[{.namespace}]/name
30+
```
31+
32+
For example:
33+
34+
- `Microsoft/Example`
35+
- `Microsoft.DSC/Docs`
36+
- `Microsoft.Windows.Appx/Discover`
37+
38+
[01]: <DOCS_BASE_URL>/reference/schemas/definitions/extensiontype?<DOCS_VERSION_PIN>
39+
patternErrorMessage: |
40+
Invalid type name. Valid extension type names always define an owner and a name separated by a
41+
slash, like `Microsoft/Example`. Type names may optionally include the group, area, and subarea
42+
segments to namespace the resource under the owner, like `Microsoft.Windows.Appx/Discover`.

‎schemas/src/definitions/resourceKind.yaml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ enum:
1313
- adapter
1414
- group
1515
- importer
16+
- exporter
1617

1718
# VS Code only
1819

@@ -56,3 +57,12 @@ markdownEnumDescriptions:
5657
Indicates that the manifest is for a resource that resolves an external source to DSC
5758
resource instances. DSC processes the resolved instances as nested instances for the importer
5859
resource.
60+
- | # exporter
61+
<!-- force a line break -->
62+
63+
Indicates that the manifest is for a resource that only implements the **Export** operation
64+
to use for inventory and fact-gathering scenarios. For exporter resources, DSC expects the
65+
resource to return one or more resource definitions to recursively export, rather than the
66+
actual state of instances.
67+
68+
For more information about the expected output, see [Export resource operation stdout][02].

‎schemas/src/definitions/resourceType.yaml

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,16 @@ title: DSC resource fully qualified type name
66
description: |
77
The namespaced name of the DSC resource, using the syntax:
88
9-
owner[.group][.area]/name
9+
<owner>[.<group>][.<area>][.<subarea>]/<name>
1010
1111
For example:
1212
13-
- Microsoft.SqlServer/Database
14-
- Microsoft.SqlServer.Database/User
13+
- Microsoft/OSInfo
14+
- Microsoft.SqlServer/Database
15+
- Microsoft.SqlServer.Database/User
1516
1617
type: string
17-
pattern: ^\w+(\.\w+){0,2}\/\w+$
18+
pattern: ^\w+(\.\w+){0,3}\/\w+$
1819

1920
# VS Code only
2021
markdownDescription: |
@@ -25,16 +26,17 @@ markdownDescription: |
2526
The namespaced name of the DSC resource, using the syntax:
2627
2728
```yaml
28-
owner[.group][.area]/name
29+
<owner>[.<group>][.<area>][.<subarea>]/<name>
2930
```
3031
3132
For example:
3233
34+
- `Microsoft/OSInfo`
3335
- `Microsoft.SqlServer/Database`
3436
- `Microsoft.SqlServer.Database/User`
3537
3638
[01]: <DOCS_BASE_URL>/reference/schemas/definitions/resourcetype?<DOCS_VERSION_PIN>
3739
patternErrorMessage: |
3840
Invalid type name. Valid resource type names always define an owner and a name separated by a
39-
slash, like `Microsoft/OSInfo`. Type names may optionally include a group and area to namespace
40-
the resource under the owner, like `Microsoft.Windows/Registry`.
41+
slash, like `Microsoft/OSInfo`. Type names may optionally include the group, area, and subarea
42+
segments to namespace the resource under the owner, like `Microsoft.Windows/Registry`.

‎schemas/src/extension/manifest.discover.yaml

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema
2+
$schema: https://json-schema.org/draft/2020-12/schema
3+
$id: <HOST>/<PREFIX>/<VERSION>/extension/manifest.discover.yaml
4+
5+
title: Discover operation command
6+
description: >-
7+
Defines how DSC must call the DSC extension to discover the paths to resource manifests.
8+
markdownDescription: | # VS Code only
9+
***
10+
[_Online Documentation_][00]
11+
***
12+
13+
Defines how DSC must call the DSC extension to discover the paths to resource manifests. An
14+
extension that defines this field in its manifest has the `discover` capability.
15+
16+
By default, DSC only discovers resource manifests in the `PATH` environment variable. If the
17+
`DSC_RESOURCE_PATH` environment variable is defined, DSC searches those paths for resource
18+
manifests instead.
19+
20+
If initial discovery finds any extension manifests that have the `discover` capability, DSC uses
21+
those extensions to discover resources that aren't available in `PATH` or `DSC_RESOURCE_PATH`.
22+
23+
For more information about the output DSC expects the extension to emit for this command, see
24+
[Discover extension operation stdout][01].
25+
26+
[00]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/discover?<DOCS_VERSION_PIN>
27+
[00]: <DOCS_BASE_URL>/reference/schemas/extension/stdout/discover?<DOCS_VERSION_PIN>
28+
29+
type: object
30+
required:
31+
- executable
32+
properties:
33+
executable:
34+
$ref: /<PREFIX>/<VERSION>/definitions/commandExecutable.yaml
35+
markdownDescription: |
36+
***
37+
[_Online Documentation_][01]
38+
***
39+
40+
Defines the name of the command to run. The value must be the name of a command discoverable
41+
in the system's `PATH` environment variable or the full path to the command. A file extension
42+
is only required when the command isn't recognizable by the operating system as an
43+
executable.
44+
45+
[01]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/discover?<DOCS_VERSION_PIN>#executable
46+
args:
47+
$ref: /<PREFIX>/<VERSION>/definitions/commandArgs.yaml
48+
markdownDescription: |
49+
***
50+
[_Online Documentation_][01]
51+
***
52+
53+
Defines an array of strings to pass as arguments to the command. DSC passes the arguments to
54+
the command in the order they're specified.
55+
56+
For example, the given the following definition:
57+
58+
```json
59+
{
60+
"executable": "myextension",
61+
"args": ["discover", "--all"],
62+
}
63+
```
64+
65+
DSC invokes the command for the resource as:
66+
67+
```bash
68+
myextension discover --all
69+
```
70+
71+
[01]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/discover?<DOCS_VERSION_PIN>#args
72+
73+
defaultSnippets: # VS Code only
74+
- label: ' Define without arguments'
75+
markdownDescription: |
76+
Define the `discover` command for the extension when no arguments are required.
77+
body:
78+
executable: ${2:executable_name}
79+
- label: ' Define with arguments'
80+
markdownDescription: |-
81+
Define the `discover` command for the extension when at least one argument is required.
82+
body:
83+
executable: ${2:executable_name}
84+
args:
85+
- ${3:--first-argument}

0 commit comments

Comments
 (0)