Skip to content

docs: Update shared definitions and Microsoft.DSC metadata reference #1704

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.

Sign up for GitHub

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

Open
Gijs Reijn (Gijsreyn) wants to merge 1 commit into
base: main
Choose a base branch
from
+214 −103
Open

docs: Update shared definitions and Microsoft.DSC metadata reference #1704

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 21 additions & 14 deletions docs/reference/schemas/definitions/functions/builtin/dataTypes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
description: JSON schema reference for the data types that DSC functions operate on.
ms.date: 07/03/2025
ms.date: 09/01/2026
ms.topic: reference
title: Function data types schema reference
---
Expand All @@ -14,24 +14,28 @@ Defines the available data types that DSC functions operate on.
## Metadata

```yaml
SchemaDialect : https://json-schema.org/draft/2020-12/schema
SchemaID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.2.0/definitions/functions/builtin/dataTypes.json
Type : string
ValidValues : [
'array'
'boolean'
'lambda'
'null'
'number'
'object'
'string'
]
SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/definitions/functions/builtin/argKind.json
Type: string
ValidValues: [
array,
boolean,
lambda,
null,
number,
object,
string
]
```

## Description

Functions in DSC only support a subset of possible data types for input arguments and output
values. The supported data types are:
values. The `dsc function list` command reports these data types in the `acceptedArgOrderedTypes`,
`remainingArgAcceptedTypes`, and `returnTypes` properties for each function. For more information,
see [dsc function list result schema reference][01].

The supported data types are:

- `array` - A collection of items
- `boolean` - Either `true` or `false`
Expand All @@ -40,3 +44,6 @@ values. The supported data types are:
- `number` - A 64-bit integer
- `object` - A collection of key-value pairs
- `string` - UTF-8 text

<!-- Link reference definitions -->
[01]: ../../../outputs/function/list.md
9 changes: 7 additions & 2 deletions docs/reference/schemas/definitions/message.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
description: JSON schema reference for a structured message returned from a 'dsc config' command.
ms.date: 07/03/2025
ms.date: 09/01/2026
ms.topic: reference
title: Structured message schema reference
---
Expand All @@ -21,6 +21,11 @@ Type: object

## Description

When DSC invokes a resource during a `dsc config` command, it captures any messages the resource
emits and returns them in the `messages` array of the command's output. Each message is an object
that identifies the resource instance the message came from, the text of the message, and its
severity.

## Required properties

Every message must be an object that defines these properties:
Expand Down Expand Up @@ -50,7 +55,7 @@ type names, see [DSC Resource fully qualified type name schema reference][01].
```yaml
Type: string
Required: true
Pattern: ^\w+(\.\w+){0,2}\/\w+$
Pattern: ^\w+(\.\w+)*\/\w+$
```

### message
Expand Down
15 changes: 9 additions & 6 deletions docs/reference/schemas/definitions/parameters/dataTypes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
description: JSON schema reference for valid parameter data types in a configuration document.
ms.date: 07/03/2025
ms.date: 09/01/2026
ms.topic: reference
title: DSC configuration parameter data type schema reference
---
Expand All @@ -17,7 +17,7 @@ Defines valid data types for a DSC configuration parameter
SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/definitions/parameters/dataTypes.json
Type: string
ValidValues: [array, bool, int, object, string, secureobject, securestring]
ValidValues: [array, bool, int, object, string, secureObject, secureString]
```

## Description
Expand All @@ -31,8 +31,11 @@ The valid data types for a parameter are:
- `int` for integers
- `object` for objects
- `string` for strings
- `secureobject` for secure objects
- `securestring` for secure strings
- `secureObject` for secure objects
- `secureString` for secure strings

The data type names are case-sensitive. For example, DSC raises an error for a parameter that
defines its `type` as `securestring` instead of `secureString`.

Access parameters in a configuration using this syntax:

Expand Down Expand Up @@ -244,9 +247,9 @@ secure object parameters.
```yaml
parameters:
password:
type: securestring
type: secureString
sensitiveOptions:
type: secureobject
type: secureObject
```

[01]: ../../config/document.md
63 changes: 48 additions & 15 deletions docs/reference/schemas/definitions/resourceCapabilities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
description: JSON schema reference for resource capabilities
ms.date: 07/03/2025
ms.date: 09/01/2026
ms.topic: reference
title: DSC Resource capabilities schema reference
---
Expand All @@ -15,7 +15,7 @@ Defines the operations you can invoke for a resource and how the resource behave

```yaml
SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/definitions/resourceKind.json
SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/definitions/resourceCapabilities.json
Type: array
Required: true
ItemsMustBeUnique: true
Expand All @@ -24,9 +24,10 @@ ItemsValidValues: [
get,
set,
setHandlesExist,
whatIf,
setWhatIf,
test,
delete,
deleteWhatIf,
Comment on lines 26 to +30
export,
resolve
]
Expand All @@ -35,21 +36,53 @@ ItemsValidValues: [
## Description

DSC resources always have at least one capability. Resource capabilities define the operations you
can invoke for a resource and how the resource behaves when invoked.
can invoke for a resource and how the resource behaves when invoked. DSC reports the capabilities
of every discovered resource in the output of the `dsc resource list` command.

DSC resources may have the following capabilities:

- `get` - The resource can retrieve the current state of an instance.
- `set` - The resource can enforce the desired state for an instance.
- `setHandlesExist` - The resource handles deleting an instance during a **Set** operation.
- `whatIf` - The resource can report how it would change state for an instance during a **Set** operation.
- `get` - The resource supports retrieving the current state of an instance.
- `set` - The resource supports enforcing the desired state for an instance.
- `setHandlesExist` - The resource handles the `_exist` canonical property directly during a
**Set** operation, including removing an instance when `_exist` is `false`.
- `setWhatIf` - The resource supports simulating the **Set** operation directly, reporting how it
would change the state of an instance without changing it. This capability was added in DSC
version 3.3.0. Through DSC version 3.2.x, this capability was reported as `whatIf`.
- `test` - The resource implements the **Test** operation and doesn't rely on synthetic testing.
- `delete` - The resource can remove an instance.
- `export` - The resource can enumerate every instance.
- `resolve` - The resource can resolve nested instances from an external source.
- `delete` - The resource supports removing an instance.
- `deleteWhatIf` - The resource supports simulating the **Delete** operation directly, reporting
how it would remove an instance without removing it. This capability was added in DSC version
3.3.0.
- `export` - The resource supports enumerating every instance.
- `resolve` - The resource supports resolving nested instances from an external source.

For more information about resource capabilities, see [DSC resource capabilities][01]. For more
information about the operations you can invoke for a resource, see [DSC resource operations][02].
### Capabilities for command resources

[01]: ../../../concepts/resources/capabilities.md
[02]: ../../../concepts/resources/operations.md
DSC infers the capabilities of a command resource from the properties defined in its resource
manifest:

| Capability | Manifest properties |
|:------------------|:---------------------------------------------------------------------|
| `get` | [get][01] |
| `set` | [set][02] |
| `setHandlesExist` | [set][02] with `handlesExist` set to `true` |
| `setWhatIf` | [set][02] with a `whatIfArg` item in `args`, or [whatIf][03] |
| `test` | [test][04] |
| `delete` | [delete][05] |
| `deleteWhatIf` | [delete][05] with a `whatIfArg` item in `args` |
| `export` | [export][06] |
| `resolve` | [resolve][07] |

For more information about resource capabilities, see [DSC resource capabilities][08]. For more
information about the operations you can invoke for a resource, see [DSC resource operations][09].

<!-- Link reference definitions -->
[01]: ../resource/manifest/get.md
[02]: ../resource/manifest/set.md
[03]: ../resource/manifest/whatif.md
[04]: ../resource/manifest/test.md
[05]: ../resource/manifest/delete.md
[06]: ../resource/manifest/export.md
[07]: ../resource/manifest/resolve.md
[08]: ../../../concepts/resources/capabilities.md
[09]: ../../../concepts/resources/operations.md
51 changes: 27 additions & 24 deletions docs/reference/schemas/definitions/resourceKind.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
description: JSON schema reference for resource kind
ms.date: 07/03/2025
ms.date: 09/01/2026
ms.topic: reference
title: DSC Resource kind schema reference
---
Expand All @@ -9,7 +9,8 @@ title: DSC Resource kind schema reference

## Synopsis

Identifies whether a resource is an adapter resource, a group resource, an importer resource, an exporter resource, or a normal resource.
Identifies whether a resource is an adapter resource, a group resource, an importer resource, an
exporter resource, or a normal resource.

## Metadata

Expand All @@ -35,7 +36,8 @@ the property. If the `adapter` property is defined in the resource manifest, DSC
of `kind` as `adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as
`resource`. DSC can't infer whether a manifest is for a group, importer, or exporter resource.

When defining a group, importer, or exporter resource with a resource manifest, always explicitly define `kind`.
When defining a group, importer, or exporter resource with a resource manifest, always explicitly
define `kind`.

### Adapter resources

Expand Down Expand Up @@ -172,13 +174,13 @@ The following examples show valid and invalid references and dependencies. The e
This example configuration defines several valid references and dependencies. It also defines two
instances of the `Microsoft.DSC/Group` resource, one nested inside the other.

The top level instance of the `Microsoft.DSC.Debug/Echo` resource references and depends on the top-level instance
of the `Microsoft/OSInfo` resource. The top-level instances of the `Microsoft.DSC.Debug/Echo` and
`Microsoft/OSInfo` resources both depend on the top-level instance of the `Microsoft.DSC/Group`
resource.
The top level instance of the `Microsoft.DSC.Debug/Echo` resource references and depends on the
top-level instance of the `Microsoft/OSInfo` resource. The top-level instances of the
`Microsoft.DSC.Debug/Echo` and `Microsoft/OSInfo` resources both depend on the top-level instance
of the `Microsoft.DSC/Group` resource.

```yaml
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
resources:
# The top level echo references and depends on the top-level OSInfo.
# It also depends on the top-level Group.
Expand All @@ -204,9 +206,10 @@ resources:
```

The top-level instance of `Microsoft.DSC/Group` defines three nested resource instances:
`Microsoft.DSC.Debug/Echo`, `Microsoft/OSInfo`, and `Microsoft.DSC/Group`. As at the top-level, the `Microsoft.DSC.Debug/Echo`
instance references and depends on the adjacent nested`Microsoft/OSInfo` instance and that instance
depends on the adjacent nested `Microsoft.DSC/Group` instance.
`Microsoft.DSC.Debug/Echo`, `Microsoft/OSInfo`, and `Microsoft.DSC/Group`. As at the top-level, the
`Microsoft.DSC.Debug/Echo` instance references and depends on the adjacent nested
`Microsoft/OSInfo` instance and that instance depends on the adjacent nested `Microsoft.DSC/Group`
instance.

```yaml
# Other top-level instances snipped for brevity
Expand Down Expand Up @@ -235,8 +238,8 @@ depends on the adjacent nested `Microsoft.DSC/Group` instance.
```

Finally, the nested instance of `Microsoft.DSC/Group` defines two nested instances. The deeply
nested instance of `Microsoft.DSC.Debug/Echo` references and depends on the deeply nested instance of
`Microsoft/OSInfo`.
nested instance of `Microsoft.DSC.Debug/Echo` references and depends on the deeply nested instance
of `Microsoft/OSInfo`.

```yaml
- name: Top level group
Expand All @@ -262,7 +265,7 @@ nested instance of `Microsoft.DSC.Debug/Echo` references and depends on the deep
dependsOn:
- "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]"
- name: Deeply nested OSInfo
type: Microsoft.OSInfo
type: Microsoft/OSInfo
properties: {}
```

Expand All @@ -275,7 +278,7 @@ nested instances in the same group.
Putting the configuration together, you get this full document:

```yaml
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
# The top level echo references and depends on the top-level OSInfo.
Expand Down Expand Up @@ -330,18 +333,18 @@ resources:
dependsOn:
- "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]"
- name: Deeply nested OSInfo
type: Microsoft.OSInfo
type: Microsoft/OSInfo
properties: {}
```

#### Example 2 - Invalid reference and dependency on a nested instance

This example configuration is invalid, because the top-level instance of the `Microsoft.DSC.Debug/Echo` resource
references and depends on the nested `Microsoft/OSInfo` instance. The nested instance is external
to the top-level instance, not adjacent.
This example configuration is invalid, because the top-level instance of the
`Microsoft.DSC.Debug/Echo` resource references and depends on the nested `Microsoft/OSInfo`
instance. The nested instance is external to the top-level instance, not adjacent.

```yaml
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Top level echo
Expand All @@ -365,12 +368,12 @@ resources:

#### Example 3 - Invalid reference and dependency on an external instance

This example configuration is invalid, because the nested instance of the `Microsoft.DSC.Debug/Echo` resource
references and depends on the top-level `Microsoft/OSInfo` instance. The top-level instance is
external to the nested instance, not adjacent.
This example configuration is invalid, because the nested instance of the
`Microsoft.DSC.Debug/Echo` resource references and depends on the top-level `Microsoft/OSInfo`
instance. The top-level instance is external to the nested instance, not adjacent.

```yaml
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Top level OSInfo
Expand Down
Loading