diff --git a/docs/schemas/resource/manifest.md b/docs/schemas/resource/manifest.md new file mode 100644 index 000000000..bad8055c4 --- /dev/null +++ b/docs/schemas/resource/manifest.md @@ -0,0 +1,198 @@ +# Command-based DSC Resource manifest schema reference + +Every command-based DSC Resource must have a DSC Resource manifest. The manifest must: + +1. Be discoverable in the `PATH` environment variable. +1. Follow the naming convention `.resource.json`. +1. Be valid for the schema described in this document. + +The rest of this document describes the DSC Resource manifest schema. + +## Metadata + +| Metadata Key | Metadata Value | +|:------------:|:----------------------------------------------------| +| `$schema` | `https://json-schema.org/draft/2020-12/schema` | +| `$id` | `https://aka.ms/dsc/schemas/resource/manifest.yaml` | +| `type` | `object` | + +## Required Properties + +The manifest must include these properties: + +- [manifestVersion](#manifestversion) +- [type](#type) +- [version](#version) +- [get](#get) + +## Properties + +### manifestVersion + +The `manifestVersion` property indicates the semantic version (semver) of the DSC Resource manifest +schema that the DSC Resource manifest validates against. This property is mandatory. DSC uses this +value to validate the manifest against the correct JSON schema. + +```yaml +Type: string +Required: true +Valid Values: + - '1.0' +``` + +### type + +The `type` property represents the fully qualified the name of the DSC Resource in its namespace. +It's used to specify the DSC Resource in configuration documents and as the value of the +`--resource` flag when using the `dsc resource *` commands. This value must use the following +syntax: + +```text +`[.][.]/` +``` + +Each component must be string of alphanumeric characters and underscores. No other characters are +permitted. Every DSC Resource must define an `owner` and a `name`. Use the `group` and `area` +components to organize DSC Resources into related namespaces. For example: + +- `Microsoft.SqlServer/Database` +- `Microsoft.SqlServer.Database/Role` +- `Microsoft.SqlServer.Database/User` +- `Microsoft.SqlServer/Endpoint` +- `Microsoft.SqlServer.Endpoint/Permission` +- `Microsoft.SqlServer/Login` +- `Microsoft.SqlServer/MaxDop` + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### version + +The `version` property must be the current version of the DSC Resource as a valid semantic +version string. The version applies to the DSC Resource, not the software it manages. + +```yaml +Type: string +Required: true +``` + +### description + +The `description` property defines a synopsis for the DSC Resource's purpose. The value for this +property must be a short string. + +```yaml +Type: string +Required: false +``` + +### tags + +The `tags` property defines a list of searchable terms for the DSC Resource. The value of this +property must be an array of strings. Each tag must contain only alphanumeric characters and +underscores. No other characters are permitted. + +```yaml +Type: array +Required: false +Valid Items: + Type: string + Pattern: ^\w+$ +``` + +### get + +The `get` property defines how to call the DSC Resource to get the current state of an instance. +This property is mandatory for all DSC Resources. + +The value of this property must be an object. The object's `executable` property, defining the name +of the command to call, is mandatory. The `args` and `input` properties are optional. For more +information, see [DSC Resource manifest get property schema reference][01]. + +```yaml +Type: object +Required: true +``` + +### set + +The `set` property defines how to call the DSC Resource to set the desired state of an instance. It +also defines how to process the output from the DSC Resource for this method. When this property +isn't defined, the DSC can't manage instances of the DSC Resource. It can only get their current +state and test whether the instance is in the desired state. + +The value of this property must be an object. The `executable` property, defining the name of the +command to call, is mandatory. The `args` `input`, `preTest`, and `returns` properties are +optional. For more information, see [DSC Resource manifest set property schema reference][02]. + +### test + +The `test` property defines how to call the DSC Resource to test whether an instance is in the +desired state. It also defines how to process the output from the DSC Resource for this method. +When this property isn't defined, DSC performs a basic synthetic test for instances of the DSC +Resource. + +The value of this property must be an object. The object's `executable` property, defining the name +of the command to call, is mandatory. The `args` `input`, and `returns` properties are optional. +For more information, see [DSC Resource manifest test property schema reference][03]. + +### validate + +The `validate` property defines how to call a DSC Group Resource to validate its instances. This +property is mandatory for DSC Group Resources. DSC ignores this property for all other DSC +Resources. + +The value of this property must be an object. The object's `executable` property, defining the name +of the command to call, is mandatory. The `args` property is optional. For more information, see +[DSC Resource manifest validate property schema reference][04]. + +### provider + +When specified, the `provider` property defines the DSC Resource as a DSC Resource Provider. + +For more information, see the [DSC Resource manifest provider property schema reference][05]. + +### exitCodes + +The `exitCodes` property defines a set of valid exit codes for the DSC Resource and their meaning. +Define this property as a set of key-value pairs where: + +- The key is an integer that maps to a known exit code for the DSC Resource. +- The value is a string describing the semantic meaning of that exit code for a human reader. + +DSC always interprets exit code `0` as a successful operation and any other exit code as an error. + +```yaml +Type: object +Required: false +Valid Properties: + Name Pattern: ^[0-9]+# + Value Type: string +``` + +### schema + +The `schema` property defines how DSC should get the JSON schema to validate an instance of the DSC +Resource. This property must always be an object that defines one of the following properties: + +- `command` - When you specify the `command` property, DSC calls the defined command to get the + JSON schema. +- `embedded` - When you specify the `embedded` property, DSC uses the defined value as the JSON + schema. + +For more information, see [DSC Resource manifest schema property reference][06]. + +```yaml +Type: object +Required: true +``` + +[01]: ./methods/get.md +[02]: ./methods/set.md +[03]: ./methods/test.md +[04]: ./methods/validate.md +[05]: ./provider-property.md +[06]: ./schema-property.md diff --git a/docs/schemas/resource/manifest.yaml b/docs/schemas/resource/manifest.yaml new file mode 100644 index 000000000..a7d7e85c3 --- /dev/null +++ b/docs/schemas/resource/manifest.yaml @@ -0,0 +1,376 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://aka.ms/dsc/schemas/resource/manifest.yaml + +title: Command-based DSC Resource Manifest +description: >- + Defines a valid command-based DSC Resource. + +type: object +required: + - manifestVersion + - type + - version + - get +properties: + manifestVersion: + title: Manifest Version + description: >- + The semver of the DSC Resource manifest schema to validate this manifest + with. + $ref: "#/$defs/semver" + enums: + - '1.0' + + type: + title: Resource Type + description: >- + The namespaced name of the DSC Resource, like using the syntax: + `[.][.]/`, like `Microsoft.SqlServer/Database` + or `Microsoft.SqlServer.Database/User`. + type: string + pattern: ^\w+(\.\w+){0,2}\/\w+$ + + version: + title: Resource Semantic Version + description: >- + The semantic version (semver) of the DSC Resource. This version + identifies the DSC Resource, not the version of the application it + manages. + $ref: "#/$defs/semver" + + description: + title: Resource Description + description: >- + A short synopsis of the DSC Resource's purpose. + type: string + # Should this include a maximum length or a pattern that forbids newlines? + + tags: + title: Tags + description: >- + An array of short strings used to search for DSC Resources. + type: array + items: + type: string + pattern: ^\w+$ + + get: + title: Get Method + description: >- + Defines how DSC must call the DSC Resource to get the current state of an + instance. + type: object + required: + - executable + properties: + executable: + $ref: "#/$defs/executable" + args: + $ref: "#/$defs/args" + input: + $ref: "#/$defs/input" + examples: + - executable: registry + args: + - config + - get + input: stdin + - executable: osinfo + + set: + title: Set Method + description: >- + Defines how DSC must call the DSC Resource to set the desired state of + an instance and how to process the output from the DSC Resource. + type: object + required: + - executable + - input + properties: + executable: + $ref: "#/$defs/executable" + args: + $ref: "#/$defs/args" + input: + $ref: "#/$defs/input" + preTest: + title: Resource Performs Pre-Test + description: >- + Defines whether the DSC Resource performs its own test to ensure + idempotency when calling the `set` command. Set this value to `true` + if the DSC Resource tests input before modifying system state. + type: boolean + default: false + return: + title: Set Command Return Type + description: >- + Defines whether the command returns a JSON blob of the DSC Resource's + state after the set operation or the state and an array of the + properties the DSC Resource modified. + $ref: "#/$defs/return" + examples: + - executable: registry + args: + - config + - set + input: stdin + preTest: true + return: state + + test: + title: Test Method + description: >- + Defines how DSC must call the DSC Resource to test if an instance is in + the desired state and how to process the output from the DSC Resource. + type: object + required: + - executable + - input + properties: + executable: + $ref: "#/$defs/executable" + args: + $ref: "#/$defs/args" + input: + $ref: "#/$defs/input" + return: + title: Test Command Return Type + description: >- + Defines whether the command returns a JSON blob of the DSC Resource's + current state or the state and an array of the properties that are + out of the desired state. + $ref: "#/$defs/return" + examples: + - executable: registry + args: + - config + - test + input: stdin + return: state + + validate: + title: Validate Method + description: >- + Defines how DSC must call the DSC Resource to validate the state of an + instance. This method is mandatory for DSC Group Resources. It's ignored + for all other DSC Resources. + type: object + required: + - executable + properties: + executable: + $ref: "#/$defs/executable" + args: + $ref: "#/$defs/args" + + examples: + - executable: dsc + args: + - config + - validate + + # I'm not clear on how this works in practice + provider: + title: Provider + description: >- + Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider + enables users to manage resources that don't have their own manifests with + DSC. + type: object + required: + - list + - config + properties: + list: + title: List Command + description: >- + Defines how DSC must call the DSC Resource Provider to list its supported + DSC Resources. + type: object + required: + - executable + properties: + executable: + $ref: "#/$defs/executable" + args: + $ref: "#/$defs/args" + config: + title: Expected Configuration + description: >- + Defines whether the provider expects to receive a full and unprocessed + configuration as a single JSON blob over stdin or a sequence of JSON + Lines for each child resource's configurations. + type: string + enum: + - full + - sequence + examples: + - config: full + list: + executable: pwsh + args: + - -NoLogo + - -NonInteractive + - -NoProfile + - -Command + - ./powershellgroup.resource.ps1 List + + + # This setting in the root of the schema implies exit codes must have the same + # meaning across all executions. What about implementations that support + # multiple executables? Should exitCodes be a key that exists on + # command/method objects too? + exitCodes: + title: Exit Codes + description: >- + This property defines a map of valid exit codes for the DSC Resource. + DSC always interprets exit code `0` as a successful operation and any + other exit code as an error. Use this property to indicate human-readable + semantic meanings for the DSC Resource's exit codes. + type: object + propertyNames: + pattern: "^[0-9]+$" + patternProperties: + "^[0-9]+$": + type: string + examples: + - exitCodes: + "0": Success + "1": Invalid parameter + "2": Invalid input + "3": Registry error + "4": JSON serialization failed + + # While the current implementation is somewhat confusing in the schema, I + # think it's actually easier to document. Mainly, the complexity comes from + # the expected object having exactly one property with exclusive key names. + # If a DSC Resource could specify a combination of these values, the schema + # would be less complex. + schema: + title: Instance Schema + description: >- + Defines how DSC must validate a JSON blob representing an instance of the + DSC Resource. + type: object + oneOf: + - required: [command] + - required: [embedded] + properties: + command: + title: Instance Schema Command + description: >- + Defines how DSC must call the DSC Resource to get the JSON Schema for + validating a JSON blob representing an instance of the DSC Resource. + type: object + required: executable + properties: + executable: + $ref: "#/$defs/executable" + args: + $ref: "#/$defs/args" + embedded: + title: Embedded Instance Schema + description: >- + Defines the JSON Schema DSC must use to validate a JSON blob + representing an instance of the DSC Resource. + type: object + minProperties: 1 + url: + title: Instance Schema URL + description: >- + Defines the URL to the DSC Resource's JSON schema for integrating + tools. + type: string + format: uri + examples: + - command: + executable: registry + args: + - schema + - embedded: + $schema: http://json-schema.org/draft-07/schema# + title: OSInfo + type: object + required: [] + properties: + $id: + type: string + architecture: + type: [string, "null"] + bitness: + $ref: "#/definitions/Bitness" + codename: + type: [string, "null"] + edition: + type: [string, "null"] + family: + $ref: "#/definitions/Family" + version: + type: string + additionalProperties: false + definitions: + Bitness: + type: string + enum: ["32", "64", "unknown"] + Family: + type: string + enum: [Linux, macOS, Windows] + - url: https://json.schemastore.org/rust-toolchain.json + +$defs: + args: + title: Executable Command Arguments + description: >- + The list of arguments to pass to the command. + type: array + items: + type: string + executable: + title: Executable Command Name + description: >- + The name of the command to run. + type: string + input: + title: Executable Command Input Type + description: >- + Defines how DSC should pass input to the command, either as arguments or + JSON over stdin. + type: string + enum: + - args + - stdin + default: args + return: + type: string + enum: + - state + - stateAndDiff + default: state + semver: + title: Semantic Version + description: >- + A valid semantic version (semver) string. For reference, see https://semver.org/ + type: string + pattern: >- + ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ + $comment: | + This pattern was taken from the semver website's FAQ: + + https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string + + It's the suggested regex pattern for JavaScript. + + This is the same pattern, made multi-line for easier readability. + + ``` + ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*) + (?:-( + (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*) + (?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)) + *))? + (?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ + ``` + + The first line matches the `major.minor.patch` components of the version. The middle lines match + the pre-release components. The last line matches the build metadata component. diff --git a/docs/schemas/resource/methods/get.md b/docs/schemas/resource/methods/get.md new file mode 100644 index 000000000..bf8a5db2e --- /dev/null +++ b/docs/schemas/resource/methods/get.md @@ -0,0 +1,112 @@ +# DSC Resource manifest get property schema reference + +Every command-based DSC Resource must define the `get` property in its DSC Resource manifest. This +property defines how DSC can get the current state of an instance of the DSC Resource. + +This document describes the schema for the property. + +## Metadata + +| Metadata Key | Metadata Value | +|:------------:|:--------------------------------------------------------------------| +| `$schema` | `https://json-schema.org/draft/2020-12/schema` | +| `$id` | `https://aka.ms/dsc/schemas/resource/manifest.yaml#/properties/get` | +| `type` | `object` | + +## Examples + +### Example 1 - Minimal definition + +This example is from the `Microsoft/OSInfo` DSC Resource. + +```json +"get": { + "executable": "osinfo" +} +``` + +It only defines the `executable` property. When a manifest doesn't define `args`, DSC passes no +arguments to the command. When a manifest doesn't define `input`, the default behavior is to send a +JSON blob to the command over `stdin`. + +With this definition, DSC calls the `get` method for this DSC Resource by running: + +```sh +{ ... } | osinfo +``` + +### Example 2 - Full definition + +This example is from the `Microsoft.Windows/Registry` DSC Resource. + +```json +"get": { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" +} +``` + +It defines `executable` as `registry`, rather than `registry.exe`. The extension isn't required +when the operating system recognizes the application as an executable. + +The manifest defines two arguments, `config` and `get`. The `input` property indicates that the +`get` command expects its input as a JSON blob from `stdin`. + +Combined with the value for `executable`, DSC calls the get method for this DSC Resource by +running: + +```sh +{ ... } | registry config get +``` + +## Required Properties + +- [executable](#executable) + +## Properties + +### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the +application. A file extension is only required when the executable isn't recognizable by the +operating system as an executable. + +```yaml +Type: string +Required: true +``` + +### args + +The `args` property defines an array of strings to pass as arguments to the command. DSC passes the +arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` + +### input + +The `input` property defines how to pass input to the DSC Resource. The value of this property must +be one of the following strings: + +- `args` - Indicates that the DSC Resource expects the properties of an instance to be specified + with command line arguments. +- `stdin` - Indicates that the DSC Resource expects a JSON blob representing an instance from + `stdin`. + +```yaml +Type: string +Required: false +Default: stdin +Valid Values: + - args + - stdin +``` diff --git a/docs/schemas/resource/methods/set.md b/docs/schemas/resource/methods/set.md new file mode 100644 index 000000000..5ae80d777 --- /dev/null +++ b/docs/schemas/resource/methods/set.md @@ -0,0 +1,140 @@ +# DSC Resource manifest set property schema reference + +To manage an instance with DSC, a DSC Resource must define the `set` property in its DSC Resource +manifest. This property defines how DSC can enforce the current state of an instance of the DSC +Resource. + +When this property isn't defined, the DSC Resource can only be used to get the current state of an +instance and test whether it's in the desired state. It can't enforce desired state. + +This document describes the schema for the property. + +## Metadata + +| Metadata Key | Metadata Value | +|:------------:|:--------------------------------------------------------------------| +| `$schema` | `https://json-schema.org/draft/2020-12/schema` | +| `$id` | `https://aka.ms/dsc/schemas/resource/manifest.yaml#/properties/set` | +| `type` | `object` | + +## Examples + +### Example 1 - Full definition + +This example is from the `Microsoft.Windows/Registry` DSC Resource. + +```json +"set": { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "preTest": true, + "return": "state" +} +``` + +It defines `executable` as `registry`, rather than `registry.exe`. The extension isn't required +when the operating system recognizes the application as an executable. + +The manifest defines two arguments, `config` and `set`. The value of the `input` property indicates +that the `set` command expects its input as a JSON blob from `stdin`. + +Combined with the value for `executable`, DSC calls the set method for this DSC Resource by +running: + +```sh +{ ... } | registry config set +``` + +Because the manifest defines `preTest` as `true`, DSC won't call the `test` method for the resource +before calling `set`. This setting indicates that the DSC Resource itself tests instances before +enforcing their desired state. + +The manifest defines `return` as `state`, indicating that it only returns the final state of the +DSC Resource after the `set` method runs. DSC compares the desired state to the return data of this +DSC Resource to identify which of the DSC Resource's properties the `set` method enforced, if any. + +## Required Properties + +- [executable](#executable) + +## Properties + +### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the +application. A file extension is only required when the executable isn't recognizable by the +operating system as an executable. + +```yaml +Type: string +Required: true +``` + +### args + +The `args` property defines an array of strings to pass as arguments to the command. DSC passes the +arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` + +### input + +The `input` property defines how to pass input to the DSC Resource. The value of this property must +be one of the following strings: + +- `args` - Indicates that the DSC Resource expects the properties of an instance to be specified + with command line arguments. +- `stdin` - Indicates that the DSC Resource expects a JSON blob representing an instance from + `stdin`. + +```yaml +Type: string +Required: false +Default: stdin +Valid Values: + - args + - stdin +``` + +### preTest + +The `preTest` property defines whether the DSC Resource tests the instance internally before +enforcing the desired state. Set this property to `true` when the DSC Resource tests the instance. +Set this property to `false` to ensure DSC determines tests the instance instead. The default value +is `false`. + +```yaml +Type: boolean +Required: false +Default: false +``` + +### return + +The `return` property defines how DSC should process the output for this method. The value of this +property must be one of the following strings: + +- `state` - Indicates that the DSC Resource returns only the instance's final state after the set + operation as a JSON blob. +- `stateAndDiff` - Indicates that the DSC Resource returns the instance's final state and an array + of property names that the DSC Resource modified. + +The default value is `state`. + +```yaml +Type: string +Required: false +Default: state +Valid Values: + - state + - stateAndDiff +``` diff --git a/docs/schemas/resource/methods/test.md b/docs/schemas/resource/methods/test.md new file mode 100644 index 000000000..6fd66d10d --- /dev/null +++ b/docs/schemas/resource/methods/test.md @@ -0,0 +1,134 @@ +# DSC Resource manifest test property schema reference + +If a DSC Resource implements its own logic for determining whether an instance is in the desired +state, it must define the `test` property in its DSC Resource manifest. This property defines how +DSC can call the DSC Resource to test whether an instance is in the desired state. + +When this property isn't defined, DSC uses a synthetic test method for the DSC Resource. The +synthetic test method: + +1. Gets the actual state of the instance using the DSC Resource's `get` method. +1. Compares every defined property of the instance's desired state to the actual state. +1. If the desired state of a property isn't equal to the actual state of that property, DSC reports + that the instance isn't in the desired state. + +Because the synthetic test only checks for equivalency, it can't accurately test DSC Resources with +properties that can't be evaluated with equivalency alone. For example, if a DSC Resource manages +package versions and allows setting the version to `latest`, DSC would report an instance with a +version of `3.1.0` as being out of the desired state, even if `3.1.0` is the latest version of the +package. + +For DSC Resources with properties that can't be evaluated by equivalency alone, always define the +`test` property in the DSC Resource manifest. + +This document describes the schema for the `test` property. + +## Metadata + +| Metadata Key | Metadata Value | +|:------------:|:---------------------------------------------------------------------| +| `$schema` | `https://json-schema.org/draft/2020-12/schema` | +| `$id` | `https://aka.ms/dsc/schemas/resource/manifest.yaml#/properties/test` | +| `type` | `object` | + +## Examples + +### Example 1 - Full definition + +This example is from the `Microsoft.Windows/Registry` DSC Resource. + +```json +"test": { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" +} +``` + +It defines `executable` as `registry`, rather than `registry.exe`. The extension isn't required +when the operating system recognizes the application as an executable. + +The manifest defines two arguments, `config` and `test`. The value of the `input` property +indicates that the `test` command expects its input as a JSON blob from `stdin`. + +Combined with the value for `executable`, DSC calls the `test` method for this DSC Resource by +running: + +```sh +{ ... } | registry config test +``` + +The manifest defines `return` as `state`, indicating that it only returns the actual state of the +DSC Resource when the `test` method runs. + +## Required Properties + +- [executable](#executable) + +## Properties + +### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the +application. A file extension is only required when the executable isn't recognizable by the +operating system as an executable. + +```yaml +Type: string +Required: true +``` + +### args + +The `args` property defines an array of strings to pass as arguments to the command. DSC passes the +arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` + +### input + +The `input` property defines how to pass input to the DSC Resource. The value of this property must +be one of the following strings: + +- `args` - Indicates that the DSC Resource expects the properties of an instance to be specified + with command line arguments. +- `stdin` - Indicates that the DSC Resource expects a JSON blob representing an instance from + `stdin`. + +```yaml +Type: string +Required: false +Default: stdin +Valid Values: + - args + - stdin +``` + +### return + +The `return` property defines how DSC should process the output for this method. The value of this +property must be one of the following strings: + +- `state` - Indicates that the DSC Resource returns only the instance's actual state. +- `stateAndDiff` - Indicates that the DSC Resource returns the instance's actual state and an array + of property names that are out of the desired state. + +The default value is `state`. + +```yaml +Type: string +Required: false +Default: state +Valid Values: + - state + - stateAndDiff +``` diff --git a/docs/schemas/resource/methods/validate.md b/docs/schemas/resource/methods/validate.md new file mode 100644 index 000000000..658162342 --- /dev/null +++ b/docs/schemas/resource/methods/validate.md @@ -0,0 +1,71 @@ +# DSC Resource manifest validate property schema reference + +DSC Group Resources must define the `validate` property in their DSC Resource manifest. This +property defines how DSC can call the DSC Group Resource to test whether instances in the group +have valid definitions. + +Always define the `validate` property for DSC Group Resources in the DSC Resource manifest. + +This document describes the schema for the `validate` property. + +## Metadata + +| Metadata Key | Metadata Value | +|:------------:|:-------------------------------------------------------------------------| +| `$schema` | `https://json-schema.org/draft/2020-12/schema` | +| `$id` | `https://aka.ms/dsc/schemas/resource/manifest.yaml#/properties/validate` | +| `type` | `object` | + +## Examples + +### Example 1 - Full definition + +This example is from the `DSC/AssertionGroup` DSC Group Resource. + +```json +"validate": { + "executable": "dsc", + "args": [ + "config", + "validate" + ] +} +``` + +It defines the executable as `dsc` with the arguments `config` and `validate`. The `validate` +method always sends the method's input as a JSON blob over `stdin`. + +With this definition, DSC calls the `validate` method for this DSC Group Resource by running: + +```sh +{ ... } | dsc config validate +``` + +## Required Properties + +- [executable](#executable) + +## Properties + +### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the +application. A file extension is only required when the executable isn't recognizable by the +operating system as an executable. + +```yaml +Type: string +Required: true +``` + +### args + +The `args` property defines an array of strings to pass as arguments to the command. DSC passes the +arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` diff --git a/docs/schemas/resource/provider-property.md b/docs/schemas/resource/provider-property.md new file mode 100644 index 000000000..188c8df0d --- /dev/null +++ b/docs/schemas/resource/provider-property.md @@ -0,0 +1,114 @@ +# DSC Resource manifest provider property schema reference + +DSC Resource Providers must define the `provider` property in their DSC Resource manifest. DSC uses +this property to determine which command-based DSC Resources are DSC Resource providers. The +`provider` property defines how DSC should call the DSC Resource Provider. + +## Metadata + +| Metadata Key | Metadata Value | +|:------------:|:-------------------------------------------------------------------------| +| `$schema` | `https://json-schema.org/draft/2020-12/schema` | +| `$id` | `https://aka.ms/dsc/schemas/resource/manifest.yaml#/properties/provider` | +| `type` | `object` | + +## Examples + +### Example 1 - DSC/PowerShellGroup + +This example is from the `DSC/PowerShellGroup` DSC Resource Provider. + +```json +"provider": { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo" + "-NonInteractive" + "-NoProfile" + "-Command" + "./powershellgroup.resource.ps1 List" + ] + } +} +``` + +The manifest sets `config` to `full`, indicating that it expects a JSON blob representing the full +and unprocessed configuration from `stdin`. + +It defines `list.executable` as `pwsh`. The arguments defined in `list.args` ensure that DSC runs +PowerShell: + +- Without the logo banner +- In non-interactive mode +- Without loading any profile scripts +- To invoke the `powershellgroup.resource.ps1` executable in the same folder as the `dsc` + executable and pass the `List` argument. + +With this definition, DSC calls the `list` method for this DSC Resource provider by running: + +```sh +pwsh -NoLogo -NonInteractive -NoProfile -Command "./powershellgroup.resource.ps1 List" +``` + +## Required Properties + +The `provider` definition must include these properties: + +- [config](#config) +- [list](#list) + +## Properties + +### config + +The `config` property defines how the DSC Resource Provider expects to receive resource +configurations. The value must be one of the following options: + +- `full` - Indicates that the DSC Resource Provider expects a JSON blob containing the full and + unprocessed configuration as a single JSON blob over `stdin`. +- `sequence` - Indicates that the DSC Resource Provider expects each resource's configuration as + a JSON Line over `stdin`. + +```yaml +Type: string +Valid Values: + - full + - sequence +``` + +### list + +The `list` property defines how DSC must call the DSC Resource Provider to list the DSC Resources +it supports. The value of this property must be an object and define the `executable` property. + +```yaml +Type: object +Required: true +Required Properties: + - executable +``` + +#### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the +application. A file extension is only required when the executable isn't recognizable by the +operating system as an executable. + +```yaml +Type: string +Required: true +``` + +#### args + +The `args` property defines an array of strings to pass as arguments to the command. DSC passes the +arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` diff --git a/docs/schemas/resource/schema-property.md b/docs/schemas/resource/schema-property.md new file mode 100644 index 000000000..61b899b07 --- /dev/null +++ b/docs/schemas/resource/schema-property.md @@ -0,0 +1,138 @@ +# DSC Resource manifest schema property reference + +Every command-based DSC Resource must define the `schema` property in its DSC Resource manifest. +This property defines how DSC can get the JSON schema it needs to validate instances of the DSC +Resource. + +This document describes the schema for the property. + +## Metadata + +| Metadata Key | Metadata Value | +|:------------:|:-----------------------------------------------------------------------| +| `$schema` | `https://json-schema.org/draft/2020-12/schema` | +| `$id` | `https://aka.ms/dsc/schemas/resource/manifest.yaml#/properties/schema` | +| `type` | `object` | + +## Examples + +### Example 1 - Get JSON schema with a command + +This example is from the `Microsoft.Windows/Registry` DSC Resource. + +```json +"schema": { + "command": { + "executable": "registry", + "args": ["schema"] + } +} +``` + +With the `command` property defined, DSC gets the JSON schema to validate instances of this DSC +Resource with the following command: + +```sh +registry schema +``` + +### Example 2 - Embedded JSON schema + +This example is from the `Microsoft/OSInfo` DSC Resource. It defines an embedded JSON schema that +DSC uses to validate an instance of the DSC Resource. + +```json +"schema": { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { "type": "string" }, + "architecture": { "type": ["string","null"] }, + "bitness": { "$ref": "#/definitions/Bitness" }, + "codename": { "type": ["string","null"] }, + "edition": { "type": ["string","null"] }, + "family": { "$ref": "#/definitions/Family" }, + "version": { "type": "string" } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { "type": "string", "enum": ["32","64","unknown"] }, + "Family": { "type": "string", "enum": ["Linux","macOS","Windows"] } + } + } +} +``` + +## Required Properties + +The `provider` definition must include exactly one of these properties: + +- [command](#command) +- [embedded](#embedded) + +## Properties + +### command + +The `command` property defines how DSC must call the DSC Resource to get the JSON schema that +validates its instances. The value of this property must be an object and define the `executable` +property. + +When you specify the `command` property, you should also publish the JSON schema to a publicly +available URI so authoring tools and other integrating applications can validate instances without +running the command locally. When you do, use the `url` property to indicate the public URI of the +schema for integrating tools. + +```yaml +Type: object +Required Properties: + - executable +``` + +#### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the +application. A file extension is only required when the executable isn't recognizable by the +operating system as an executable. + +```yaml +Type: string +Required: true +``` + +#### args + +The `args` property defines an array of strings to pass as arguments to the command. DSC passes the +arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` + +### embedded + +The `embedded` property defines the full JSON schema for DSC to validate instances of the DSC +Resource. The value for this property must be a valid JSON schema. + +```yaml +Type: object +Minimum Property Count: 1 +``` + +### url + +The `url` property defines the URL to the DSC Resource's JSON schema. It's used by integrating +tools for DSC Resources that define the `command` property instead of the `embedded` property. + + + +```yaml +Type: string +Format: uri +```