diff --git a/docs/reference/schemas/config/document.md b/docs/reference/schemas/config/document.md new file mode 100644 index 000000000..7905cde11 --- /dev/null +++ b/docs/reference/schemas/config/document.md @@ -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://raw.githubusercontent.com/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 + + + +## 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://raw.githubusercontent.com/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://raw.githubusercontent.com/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]. + +```yaml +Type: array +Required: true +Minimum Item Count: 1 +Valid Item Schema: https://raw.githubusercontent.com/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 diff --git a/docs/reference/schemas/config/parameter.md b/docs/reference/schemas/config/parameter.md new file mode 100644 index 000000000..178fc55bc --- /dev/null +++ b/docs/reference/schemas/config/parameter.md @@ -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://raw.githubusercontent.com/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 diff --git a/docs/reference/schemas/config/resource.md b/docs/reference/schemas/config/resource.md new file mode 100644 index 000000000..0f3fb0b81 --- /dev/null +++ b/docs/reference/schemas/config/resource.md @@ -0,0 +1,102 @@ +# DSC Configuration document resource instance schema + +## Synopsis + +Defines a DSC Resource instance in a configuration document. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json +Type : object +``` + +## Description + +The `resources` property of a DSC Configuration document always includes at least one DSC Resource +instance. Together, the instances in a configuration define the desired state that DSC can get, +test, and set on a machine. + +This document describes the JSON schema for a valid DSC Resource instance in a configuration +document. + +For more information about DSC Resources, see [Anatomy of a command-based DSC Resource][01]. + +## Required Properties + +Every resource instance must be an object that defines these properties: + +- [name](#name) +- [type](#type) + +## Properties + +### name + +The `name` property of a resource instance defines the short, human-readable name for a DSC +Resource instance. This property must be unique within a DSC Configuration document. If any +resource instances share the same name, DSC raises an error. + +```yaml +Type: string +Required: true +``` + +### type + +The `type` property identifies the instance's DSC Resource. The value for this property must be the +valid fully qualified type name for the resource. For more information about type names, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### properties + +The `properties` of a resource instance define its desired state. The value of this property must +be an object. For [assertion resources][02], the value may be an empty object (`{}`). DSC uses the +DSC Resource's instance schema to validate the defined properties. + +For more information about instance schemas in DSC, see [DSC Resource instance schemas][03]. + +```yaml +Type: object +Required: true +``` + +### dependsOn + +To declare that a resource instance is dependent on another instance in the configuration, define +the `dependsOn` property. + +This property must be an array of dependency declarations. Each dependency must use this +syntax: + +```yaml +"[]" +``` + +In the dependency syntax, `` is the `type` property of the dependent resource +and `` is the dependency's `name` property. + +Multiple instances can depend on the same instance, but every dependency for an instance must be +unique in that instance's `dependsOn` property. + +For more information, see [Configuration resource dependencies][04]. + +```yaml +Type: array +Required: false +Items Must be Unique: true +Valid Items Type: string +Valid Items Pattern: ^\[\w+(\.\w+){0,2}\/\w+\].+$ +``` + +[01]: ../definitions/resourceType.md +[02]: ../../../resources/concepts/assertion-resources.md +[03]: ../../../resources/concepts/schemas.md +[04]: ../../../configurations/concepts/dependencies.md diff --git a/docs/reference/schemas/definitions/message.md b/docs/reference/schemas/definitions/message.md new file mode 100644 index 000000000..c64c5d88d --- /dev/null +++ b/docs/reference/schemas/definitions/message.md @@ -0,0 +1,71 @@ +# Structured message schema reference + +## Synopsis + +A message emitted by a DSC Resource with associated metadata. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json +Type : object +``` + +## Description + +## Required properties + +Every message must be an object that defines these properties: + +- [name](#name) +- [type](#type) +- [message](#message) +- [level](#level) + +## Properties + +### name + +Identifies the instance by its short, unique, human-readable name as defined in the configuration +document. + +```yaml +Type: string +Required: true +``` + +### type + +Identifies the instance's DSC Resource by its fully qualified type name. For more information about +type names, see [DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### message + +The actual content of the message as emitted by the DSC Resource. + +```yaml +Type: string +Required: true +``` + +### level + +Indicates the severity of the message. + +```yaml +Type: string +Required: true +Valid Values: + - Error + - Warning + - Information +``` + +[01]: resourceType.md diff --git a/docs/reference/schemas/definitions/parameters/dataTypes.md b/docs/reference/schemas/definitions/parameters/dataTypes.md new file mode 100644 index 000000000..f8fcb981c --- /dev/null +++ b/docs/reference/schemas/definitions/parameters/dataTypes.md @@ -0,0 +1,252 @@ +# DSC configuration parameter data type schema reference + +## Synopsis + +Defines valid data types for a DSC configuration parameter + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json +Type : string +Valid Values: + - array + - bool + - int + - object + - string + - secureobject + - securestring +``` + +## Description + +Parameters in a [DSC Configuration document][01] must be a valid data type. + +The valid data types for a parameter are: + +- `array` for arrays +- `bool` for booleans +- `int` for integers +- `object` for objects +- `string` for strings +- `secureobject` for secure objects +- `securestring` for secure strings + +Access parameters in a configuration using this syntax: + +```yaml +"[parameter('')]" +``` + +In YAML, the parameter syntax needs to be enclosed in double-quotes when used as an inline value. +If the syntax isn't quoted, YAML interprets the syntax as an array. + +```yaml +valid: "[parameter('example')]" +# This unquoted syntax: +invalid: [parameter('example')] +# Evaluates to this YAML: +invalid: + - parameter('example') +``` + +## Arrays + +Arrays are a list of one or more values. The values in the array can be any valid data type. Values +in the array can be the same type or different types. + +```yaml +parameters: + exampleIntArray: + type: array + defaultValue: + - 1 + - 2 + - 3 + exampleMixedArray: + type: array + defaultValue: + - 1 + - true + - example string +``` + +Access items in an array can by their index. The first item in an array is index `0`. Use this +syntax to access an index in an array parameter: + +```yaml +"[parameter('')[]]" +``` + +```yaml +parameters: + members: + type: array + defaultValue: + - first + - second + - third +resources: + # Use the entire array as the value for a resource property + - name: Operators Group + type: Example.Security/Group + properties: + groupName: operators + members: "[parameter('members')]" + # Use a single item in the array as the value for a resource property + - name: Admin Group + type: Example.Security/Group + properties: + groupName: admins + members: + - "[parameter('members')[0]]" +``` + +## Booleans + +Boolean values are either `true` or `false`. + +```yaml +parameters: + exampleBool: + type: bool + defaultValue: true +``` + +## Integers + +Integer values are numbers without a fractional part. Integer values may be limited by integrating +tools or the DSC Resources they're used with. DSC itself supports integer values between +`-9223372036854775808` and `9223372036854775807`. + +```yaml +parameters: + exampleInt: + type: int + defaultValue: 12 +``` + +## Objects + +Objects define a set of key-value pairs. The value for each key can be any valid data type. The +values can be the same type or different types. + +```yaml +parameters: + exampleObject: + type: object + defaultValue: + scope: machine + updateAutomatically: true + updatefrequency: 30 +``` + +Access keys in the object using dot-notation. Dot-notation uses this syntax: + +```yaml +"[parameters('').] +``` + +```yaml +parameters: + tstoy: + type: object + defaultValue: + scope: machine + updateAutomatically: true + updatefrequency: 30 + registryKeys: + type: object + defaultValue: + productName: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: ProductName + systemRoot: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: SystemRoot +resources: + # Use the base object for the property definition + - name: TSToy + type: TSToy.Example/gotstoy + properties: "[parameter('tstoy')]" + # Use dot-notation for the property definition + - name: Windows Product Name + type: Microsoft.Windows/Registry + properties: "[parameter('registryKeys').productName]" + # Use dot-notation for each value in the property definition + - name: Windows System Root + type: Microsoft.Windows/Registry + properties: + keyPath: "[parameters('registryKeys').systemRoot.keyPath]" + valueName: "[parameters('registryKeys').systemRoot.valueName]" +``` + +## Strings + +Strings are an arbitrary set of text. + +```yaml +parameters: + exampleString: + type: string + defaultValue: This example includes spaces and 'quoted' "text." +``` + +To define a long string without newlines in YAML, use the folded block syntax by adding a `>` and a +line break after the key. Then, indent the next line. Every line in the string must start at the +same level of indentation. The lines are combined with a single space instead of newlines. To trim +trailing whitespace, use `>-` instead of `>`. + +```yaml +parameters: + foldedBlockExample: + type: string + defaultValue: >- + This example spans multiple lines + in the definition, but the lines are + joined with spaces instead of newlines. +``` + +To define a long string with newlines in YAML, use the literal block syntax by adding a `|` and a +line break after the key. Then, indent the next line. Every line in the string must start at the +same level of indentation or higher. The lines are interpreted literally, but with the leading +indentation removed. If any lines after the first line are indented more than the first line, only +the extra indentation is preserved. To trim trailing whitespace, use `|-` instead of `|`. + +```yaml +parameters: + literalBlockExample: + type: string + defaultValue: |- + This example spans multiple lines + in the definition. + + It can even include paragraphs. + + When a line is indented further + than the first line, that extra + indentation is preserved. +``` + +## Secure strings and objects + +Secure strings use the same format as strings and secure objects use the same format as objects. +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. Never define a default value for secure string or +secure object parameters. + +```yaml +parameters: + password: + type: securestring + sensitiveOptions: + type: secureobject +``` + +[01]: ../../config/document.md diff --git a/docs/reference/schemas/definitions/resourceType.md b/docs/reference/schemas/definitions/resourceType.md new file mode 100644 index 000000000..72526d715 --- /dev/null +++ b/docs/reference/schemas/definitions/resourceType.md @@ -0,0 +1,65 @@ +# DSC Resource fully qualified type name schema reference + +## Synopsis + +Identifies a DSC Resource. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json +Type : string +Pattern : ^\w+(\.\w+){0,2}\/\w+$ +``` + +## Description + +DSC Resources are identified by their fully qualified type name. Values of this type are used to +specify a resource in configuration documents and as the value of the `--resource` flag when +using the `dsc resource *` commands. + +The fully qualified type name of a resource uses the following syntax: + +```text +`[.][.]/` +``` + +Each segment must be string of alphanumeric characters and underscores. No other characters are +permitted. Every resource must define an `owner` and a `name`. Use the `group` and `area` +components to organize 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` + +## Type name segments + +### Owner + +The owner segment of the type name is mandatory. It identifies the person or organization that +owns, develops and maintains the resource. + +### Group + +The group segment of the type name is optional. It defines a logical grouping for a collection of +resources. For example, resources that manage SQL Server might use the `SqlServer` group in their +type name. + +### Area + +The area segment of the type name is optional. It defines a grouping for a collection of resources +by purpose or higher-level component. For example, resources that manage components of a SQL Server +database might use the `Database` area in their type name. + +### Name + +The name segment of the type name is mandatory. It identifies the component that the resource +manages. This segment should be a singular noun unless the resource always manages a list of +components in a single resource instance. In that case, the resource name should be the plural form +of the noun it manages or the singular form of the noun followed by the word `List`, like +`JeaRoleCapabilities` or `JeaRoleCapabilityList`. diff --git a/docs/reference/schemas/outputs/config/get.md b/docs/reference/schemas/outputs/config/get.md new file mode 100644 index 000000000..bc78fee06 --- /dev/null +++ b/docs/reference/schemas/outputs/config/get.md @@ -0,0 +1,91 @@ +# dsc config get result schema reference + +## Synopsis + +The result output from the `dsc config get` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/get.json +Type : object +``` + +## Description + +The output from the `dsc config get` command includes the actual state for every resource instance +in the configuration document. + +## Required properties + +The output always includes these properties: + +- [results](#results) +- [messages](#messages) +- [hadErrors](#haderrors) + +## Properties + +### results + +Defines the list of results for the `get` operation invoked against every instance in the +configuration document. Every entry in the list includes the resource's type name, instance name, +and the result data for an instance. + +```yaml +Type: array +Required: true +Items Type: object +``` + +#### type + +An item's `type` property identifies the instance's DSC Resource by its fully qualified type name. +For more information about type names, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +An item's `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### result + +An item's `result` property includes the actual state for the resource instance. The value for this +property adheres to the same schema as the output for the `dsc resource get` command. For more +information, see [dsc resource get result schema reference][02]. + +### messages + +Defines the list of structured messages emitted by resources during the get operation. For more +information, see [Structured message schema reference][03]. + +```yaml +Type: array +Required: true +``` + +### hadErrors + +Indicates whether the operation encountered any errors. This value is `true` if the configuration +document failed validation or any resource exited with an exit code other than `0`. + +```yaml +Type: boolean +Required: true +``` + +[01]: ../../definitions/resourceType.md +[02]: ../resource/get.md +[03]: ../../definitions/message.md diff --git a/docs/reference/schemas/outputs/config/set.md b/docs/reference/schemas/outputs/config/set.md new file mode 100644 index 000000000..24dc5c34f --- /dev/null +++ b/docs/reference/schemas/outputs/config/set.md @@ -0,0 +1,92 @@ +# dsc config set result schema reference + +## Synopsis + +The result output from the `dsc config set` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/set.json +Type : object +``` + +## Description + +The output from the `dsc config set` command includes the state of every resource instance in the +configuration before and after the set operation, and the list of properties the operation changed +for each instance. + +## Required properties + +The output always includes these properties: + +- [results](#results) +- [messages](#messages) +- [hadErrors](#haderrors) + +## Properties + +### results + +Defines the list of results for the `set` operation invoked against every instance in the +configuration document. Every entry in the list includes the resource's type name, instance name, +and the result data for an instance. + +```yaml +Type: array +Required: true +Items Type: object +``` + +#### type + +An item's `type` property identifies the instance's DSC Resource by its fully qualified type name. +For more information about type names, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +An item's `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### result + +An item's `result` property includes the actual state for the resource instance. The value for this +property adheres to the same schema as the output for the `dsc resource set` command. For more +information, see [dsc resource set result schema reference][02]. + +### messages + +Defines the list of structured messages emitted by resources during the set operation. For more +information, see [Structured message schema reference][03]. + +```yaml +Type: array +Required: true +``` + +### hadErrors + +Indicates whether the operation encountered any errors. This value is `true` if the configuration +document failed validation or any resource exited with an exit code other than `0`. + +```yaml +Type: boolean +Required: true +``` + +[01]: ../../definitions/resourceType.md +[02]: ../resource/set.md +[03]: ../../definitions/message.md diff --git a/docs/reference/schemas/outputs/config/test.md b/docs/reference/schemas/outputs/config/test.md new file mode 100644 index 000000000..61e8593cd --- /dev/null +++ b/docs/reference/schemas/outputs/config/test.md @@ -0,0 +1,92 @@ +# dsc config test result schema reference + +## Synopsis + +The result output from the `dsc config test` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/test.json +Type : object +``` + +## Description + +The output from the `dsc config test` command includes the state of every resource instance in the +configuration before and after the test operation, and the list of properties the operation changed +for each instance. + +## Required properties + +The output always includes these properties: + +- [results](#results) +- [messages](#messages) +- [hadErrors](#haderrors) + +## Properties + +### results + +Defines the list of results for the `test` operation invoked against every instance in the +configuration document. Every entry in the list includes the resource's type name, instance name, +and the result data for an instance. + +```yaml +Type: array +Required: true +Items Type: object +``` + +#### type + +An item's `type` property identifies the instance's DSC Resource by its fully qualified type name. +For more information about type names, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +An item's `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### result + +An item's `result` property includes the actual state for the resource instance. The value for this +property adheres to the same schema as the output for the `dsc resource test` command. For more +information, see [dsc resource test result schema reference][02]. + +### messages + +Defines the list of structured messages emitted by resources during the test operation. For more +information, see [Structured message schema reference][03]. + +```yaml +Type: array +Required: true +``` + +### hadErrors + +Indicates whether the operation encountered any errors. This value is `true` if the configuration +document failed validation or any resource exited with an exit code other than `0`. + +```yaml +Type: boolean +Required: true +``` + +[01]: ../../definitions/resourceType.md +[02]: ../resource/test.md +[03]: ../../definitions/message.md diff --git a/docs/reference/schemas/outputs/resource/get.md b/docs/reference/schemas/outputs/resource/get.md new file mode 100644 index 000000000..85eebee3a --- /dev/null +++ b/docs/reference/schemas/outputs/resource/get.md @@ -0,0 +1,37 @@ +# dsc resource get result schema reference + +## Synopsis + +The result output from the `dsc resource get` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json +Type : object +``` + +## Description + +The output from the `dsc resource get` command includes the actual state for the specified resource +instance. + +## Required properties + +The output always includes these properties: + +- [actualState](#actualstate) + +## Properties + +### actualState + +The `actualState` property always includes the state of the instance returned when DSC invokes the +resource's get operation. DSC validates this property's value against the resource's instance +schema. + +```yaml +Type: object +Required: true +``` diff --git a/docs/reference/schemas/outputs/resource/list.md b/docs/reference/schemas/outputs/resource/list.md new file mode 100644 index 000000000..8e06b5177 --- /dev/null +++ b/docs/reference/schemas/outputs/resource/list.md @@ -0,0 +1,158 @@ +# dsc resource list result schema reference + +## Synopsis + +The result output from the `dsc resource list` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/list.json +Type : object +``` + +## Description + +The output from the `dsc resource list` command includes a representation of discovered DSC +Resources as a series of [JSON Lines][01]. This schema describes the JSON object returned for each +resource. + +## Required properties + +Each resource in the output always includes these properties: + +- [type](#type) +- [version](#version) +- [path](#path) +- [directory](#directory) +- [implementedAs](#implementedas) +- [author](#author) +- [properties](#properties) +- [requires](#requires) +- [manifest](#manifest) + +## Properties + +### type + +Identifies the fully qualified type name of the resource. It's used to specify the resource in +configuration documents and as the value of the `--resource` flag when using the `dsc resource *` +commands. For more information about resource type names, see +[DSC Resource fully qualified type name schema reference][02]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### version + +Represents the current version of the resource as a valid semantic version (semver) string. The +version applies to the resource, not the software it manages. + +```yaml +Type: string +Required: true +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-]+)*))?$ +``` + +### description + +Defines a synopsis for the resource's purpose as a short string. If the resource doesn't have a +description, this property is `null`. + +```yaml +Type: [string, 'null'] +Required: true +``` + +### path + +Represents the path to the resource's manifest on the machine. For resources made available through +a provider, this property identifies the path to the file that defines the resource instead. + +```yaml +Type: string +Required: true +``` + +### directory + +Represents the path to the folder containing the resource's manifest on the machine. For resources +made available through a provider, this property identifies the path to the folder containing the +file that defines the resource instead. + +```yaml +Type: string +Required: true +``` + +### implementedAs + +Indicates how the DSC Resource was implemented. For command-based resources, this value is always +`Command`. + + + +### author + +Indicates the name of the person or organization that developed and maintains the DSC Resource. If +this property is `null`, the author is unknown. + + + +```yaml +Type: [string, 'null'] +Required: true +``` + +### properties + +Defines the property names for resources made available through a provider resource. For other +resources, this property is an empty array. + + + +```yaml +Type: array +Required: true +Items Type: string +Items Pattern: ^\w+$ +``` + +### requires + +Defines the fully qualified type name of the provider resource that this resource is made available +through. + +```yaml +Type: [string, 'null'] +Required: true +``` + +### manifest + +Represents the values defined in the resource's manifest. This value is `null` for resources that +aren't command-based. For more information on the value for this property, see +[Command-based DSC Resource manifest schema reference][03]. + +```yaml +Type: [object, 'null'] +Required: true +``` + +[01]: https://jsonlines.org/ +[02]: ../../definitions/resourceType.md +[03]: ../../resource/manifest/root.md diff --git a/docs/reference/schemas/outputs/resource/set.md b/docs/reference/schemas/outputs/resource/set.md new file mode 100644 index 000000000..8dfab0f2e --- /dev/null +++ b/docs/reference/schemas/outputs/resource/set.md @@ -0,0 +1,59 @@ +# dsc resource set result schema reference + +## Synopsis + +The result output from the `dsc resource set` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json +Type : object +``` + +## Description + +The output from the `dsc resource set` command includes the state of the resource instance before +and after the set operation, and the list of properties the operation changed. + +## Required properties + +The output always includes these properties: + +- [beforeState](#beforestate) +- [afterState](#afterstate) +- [changedProperties](#changedproperties) + +## Properties + +### beforeState + +Represents the state of the instance returned before the set operation. DSC validates this +property's value against the resource's instance schema. + +```yaml +Type: object +Required: true +``` + +### afterState + +Represents the state of the instance returned after the set operation. DSC validates this +property's value against the resource's instance schema. + +```yaml +Type: object +Required: true +``` + +### changedProperties + +Defines the names of the properties the set operation enforced. If this value is an empty array, +the resource made no changes during the set operation. + +```yaml +Type: array +Required: true +Items Type: string +``` diff --git a/docs/reference/schemas/outputs/resource/test.md b/docs/reference/schemas/outputs/resource/test.md new file mode 100644 index 000000000..8f4e2de4d --- /dev/null +++ b/docs/reference/schemas/outputs/resource/test.md @@ -0,0 +1,67 @@ +# dsc resource test result schema reference + +## Synopsis + +The result output from the `dsc resource test` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json +Type : object +``` + +## Description + +The output from the `dsc resource test` command includes the actual state for the specified +resource instance. + +## Required properties + +The output always includes these properties: + +- [desiredState](#desiredstate) + +## Properties + +### desiredState + +Represents the desired state of the resource instance. DSC validates this property's value against +the resource's instance schema. + +```yaml +Type: object +Required: true +``` + +### actualState + +Represents the actual state of the resource instance. DSC validates this property's value against +the resource's instance schema. + +```yaml +Type: object +Required: true +``` + +### inDesiredState + +Indicates whether the resource instance's properties are in the desired state. This value is `true` +if every property is in the desired state and otherwise `false`. + +```yaml +Type: boolean +Required: true +``` + +### differingProperties + +Defines the names of the properties that aren't in the desired state. If this value is an empty +array, the instance's properties are in the desired state. + +```yaml +Type: array +Required: true +Items Type: string +``` diff --git a/docs/reference/schemas/resource/manifest/get.md b/docs/reference/schemas/resource/manifest/get.md new file mode 100644 index 000000000..938837cbc --- /dev/null +++ b/docs/reference/schemas/resource/manifest/get.md @@ -0,0 +1,114 @@ +# Command-based DSC Resource manifest schema reference + +## Synopsis + +Defines how to retrieve a DSC Resource instance. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json +Type : object +``` + +## Description + +Every command-based DSC Resource must define the `get` property in its manifest. This property +defines how DSC can get the current state of a resource instance. + +## 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 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 command 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 resource by running: + +```sh +{ ... } | registry config get +``` + +## Required Properties + +The `get` definition must include these 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 command. A +file extension is only required when the command 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 resource. The value of this property must +be one of the following strings: + +- `args` - Indicates that the resource expects the properties of an instance to be specified with + command line arguments. This option isn't implemented yet. +- `stdin` - Indicates that the 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/reference/schemas/resource/manifest/provider.md b/docs/reference/schemas/resource/manifest/provider.md new file mode 100644 index 000000000..cf0fbe1b8 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/provider.md @@ -0,0 +1,122 @@ +# DSC Resource manifest provider property schema reference + +## Synopsis + +Defines a DSC Resource as a DSC Resource Provider. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json +Type : object +``` + +## Description + +DSC Resource Providers must define the `provider` property in their manifest. This property +identifies the resource as a provider and defines how DSC can call the provider to get the +resources the provider supports and how to pass resource instances to the provider. + +## 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 the provider 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` script in the same folder as the `dsc` command and + pass the `List` argument. + +With this definition, DSC calls the `list` method for this 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 provider expects to receive resource configurations. The +value must be one of the following options: + +- `full` - Indicates that the provider expects a JSON blob containing the full and + unprocessed configuration as a single JSON blob over `stdin`. +- `sequence` - Indicates that the provider expects each resource's configuration as + a [JSON Line][01] over `stdin`. + +```yaml +Type: string +Valid Values: + - full + - sequence +``` + +### list + +The `list` property defines how to call the provider to list the resources it supports. The value +of this property must be an object and define the `executable` subproperty. + +```yaml +Type: object +Required: true +Required Properties: + - executable +``` + +#### executable + +The `executable` subproperty 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 command. +A file extension is only required when the command isn't recognizable by the operating system as an +executable. + +```yaml +Type: string +Required: true +``` + +#### args + +The `args` subproperty 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: [] +``` + +[01]: https://jsonlines.org/ diff --git a/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md new file mode 100644 index 000000000..113d9c092 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/root.md @@ -0,0 +1,208 @@ +# Command-based DSC Resource manifest schema reference + +## Synopsis + +The JSON file that defines a command-based DSC Resource. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json +Type : object +``` + +## Description + +Every command-based DSC Resource must have a manifest. The manifest file must: + +1. Be discoverable in the `PATH` environment variable. +1. Follow the naming convention `.dsc.resource.json`. +1. Be valid for the schema described in this document. + +The rest of this document describes the manifest's schema. + +## 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 this schema that the +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 +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-]+)*))?$ +Valid Values: + - '1.0' +``` + +### type + +The `type` property represents the fully qualified type name of the resource. It's used to specify +the resource in configuration documents and as the value of the `--resource` flag when using the +`dsc resource *` commands. For more information about resource type names, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### version + +The `version` property must be the current version of the resource as a valid semantic version +(semver) string. The version applies to the resource, not the software it manages. + +```yaml +Type: string +Required: true +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-]+)*))?$ +``` + +### description + +The `description` property defines a synopsis for the 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 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. Each tag must be unique. + +```yaml +Type: array +Required: false +Valid Items: + Type: string + Pattern: ^\w+$ + Unique: true +``` + +### get + +The `get` property defines how to call the resource to get the current state of an instance. This +property is mandatory for all 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][02]. + +```yaml +Type: object +Required: true +``` + +### set + +The `set` property defines how to call the resource to set the desired state of an instance. It +also defines how to process the output from the resource for this method. When this property isn't +defined, the DSC can't manage instances of the 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][03]. + +```yaml +Type: object +Required: false +``` + +### test + +The `test` property defines how to call the resource to test whether an instance is in the desired +state. It also defines how to process the output from the 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][04]. + +```yaml +Type: object +Required: false +``` + +### 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 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][05]. + +```yaml +Type: object +Required: false +``` + +### provider + +When specified, the `provider` property defines the resource as a DSC Resource Provider. + +The value of this property must be an object. The object's `list` and `config` properties are +mandatory. The `list` property defines how to call the provider to return the resources that the +provider can manage. The `config` property defines how the provider expects input. For more +information, see the [DSC Resource manifest provider property schema reference][06]. + +### exitCodes + +The `exitCodes` property defines a set of valid exit codes for the resource and their meaning. +Define this property as a set of key-value pairs where: + +- The key is a string containing an integer that maps to a known exit code for the resource. +- The value is a string describing the semantic meaning of that exit code for a human reader. + +DSC 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 to get the JSON schema that validates an instance of the +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][07]. + +```yaml +Type: object +Required: true +``` + +[01]: ../../definitions/resourceType.md +[02]: get.md +[03]: set.md +[04]: test.md +[05]: validate.md +[06]: provider.md +[07]: schema.md diff --git a/docs/reference/schemas/resource/manifest/schema/embedded.md b/docs/reference/schemas/resource/manifest/schema/embedded.md new file mode 100644 index 000000000..5951d09d8 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/schema/embedded.md @@ -0,0 +1,161 @@ +# DSC Resource manifest embedded schema reference + +## Synopsis + +Defines a JSON Schema that validates a DSC Resource instance. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json#/properties/embedded +Type : object +``` + +## Description + +The `embedded` subproperty defines a full JSON schema for a DSC Resource's instances. DSC uses the +JSON schema to validate every instance of the resource before calling the resource's commands and +after receiving an instance as output from the resource. + +Embedded JSON schemas are also used by integrating and authoring tools like VS Code to validate +resource instances and provide IntelliSense. + +## Required keywordds + +The `embedded` definition must include these keywords: + +- [$schema](#schema) +- [type](#type) +- [properties](#properties) + +## Keywords + +### $schema + +The `$schema` keyword defines the dialect of JSON Schema the resource's instance schema uses. DSC +uses this keyword when processing the schema. The dialect defines which keywords are available and +how to interpret them. + +DSC only supports JSON Schema Draft 07 and later. + +```yaml +Type: string +Required: true +Format: uri-reference +Valid Values: + - https://json-schema.org/draft/2020-12/schema + - https://json-schema.org/draft/2019-09/schema + - http://json-schema.org/draft-07/schema# +``` + +### $id + +The `$id` keyword defines the unique ID for the instance schema. If the instance schema is published +to its own public URI, set this keyword to that URI. + +```yaml +Type: string +Required: false +Format: uri-reference +``` + +### type + +The `type` keyword defines what kind of value the instance is. Instances must be objects. Set this +keyword to `object`. + +```yaml +Type: string +Required: true +Valid Value: object +``` + +### properties + +The `properties` keyword defines the properties that DSC can retrieve and manage for the resource's +instances. This keyword must define at least one property as a key-value pair. The key is the +property's name. The value is a subschema that validates the property. + +Resources can define any properties they need for managing instances. DSC defines shared schemas +for well-known properties. Some well-known properties enable a DSC Resource to use built-in +processing. The well-known properties always start with an underscore (`_`) and DSC Resources that +use these properties may not override or extend them. If a resource specifies a well-known property +in the embedded schema, the schema _must_ define the property as a reference. + +- [_ensure](#_ensure) +- [_inDesiredState](#_indesiredstate) +- [_purge](#_purge) +- [_rebootRequested](#_rebootrequested) + +#### _ensure + +The `_ensure` property indicates that the resource can enforce whether instances exist using the +shared present and absent semantics. If a resource must distinguish between states beyond whether +an instance is present or absent, the resource should define its own `ensure` property without the +leading underscore. This property provides shared semantics for DSC Resources and integrating +tools, but doesn't enable any additional built-in processing with DSC. + +If defined, this property must be a reference to the schema for the well-known property: + +```json +"_ensure": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" +} +``` + +For more information, see [DSC Resource _ensure property schema][01]. + +#### _inDesiredState + +The read-only `_inDesiredState` property indicates whether a resource instance is in the desired +state. This property is mandatory for command-based DSC Resources that define the [test][02] +property. + +If defined, this property must be a reference to the schema for the well-known property: + +```json +"_inDesiredState": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" +} +``` + +For more information, see [DSC Resource _inDesiredState property schema][03]. + +#### _purge + +Resources that need to distinguish between whether unmanaged entries in a list are valid or must be +removed can define the write-only `_purge` property. This property provides shared semantics for +DSC Resources and integrating tools, but doesn't enable any built-in processing with DSC. + +If defined, this property must be a reference to the schema for the well-known property: + +```json +"_inDesiredState": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" +} +``` + +For more information, see [DSC Resource _purge property schema][04]. + +#### _rebootRequested + +The read-only `_rebootRequested` property indicates whether a resource instance requires a reboot +after a set operation. To use DSC's built-in reboot notification processing, resources must define +this property in their manifest. + +If defined, this property must be a reference to the schema for the well-known property: + +```json +"_rebootRequested": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" +} +``` + +For more information, see [DSC Resource _rebootRequested property schema][05] + +[01]: ../../properties/ensure.md +[02]: ../test.md +[03]: ../../properties/inDesiredState.md +[04]: ../../properties/purge.md +[05]: ../../properties/rebootRequested.md diff --git a/docs/reference/schemas/resource/manifest/schema/property.md b/docs/reference/schemas/resource/manifest/schema/property.md new file mode 100644 index 000000000..9eca4c2c3 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/schema/property.md @@ -0,0 +1,154 @@ +# DSC Resource manifest schema property reference + +## Synopsis + +Defines how to retrieve the JSON Schema that validates a DSC Resource instance. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json +Type : object +``` + +## Description + +Every command-based DSC Resource must define the `schema` property in its manifest. This property +defines how DSC can get the JSON schema it needs to validate instances of the resource. + +The JSON schema can be defined dynamically with the [command](#command) property or statically with +the [embedded](#embedded) property. + +For development purposes, it can be more convenient to use the `command` property and avoid needing +to adjust both the code and the schema. + +Microsoft recommends using the `embedded` property when publishing a resource publicly. When the +manifest declares the schema with the `command` property, DSC calls the command at the beginning of +any operation using the resource, possibly impacting performance. The schema is also unavailable to +integrating tools when the resource isn't installed locally. When the schema is embedded in the +manifest, DSC and integrating tools only need the manifest itself. + +## 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 +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 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 `schema` definition must include exactly one of these properties: + +- [command](#command) +- [embedded](#embedded) + +## Properties + +### command + +The `command` property defines how DSC must call the 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 publishing a manifest with the `command` property, Microsoft recommends publishing the JSON +schema to a publicly available URI and setting the `url` property to that URI. This enables +authoring tools and other integrating applications to validate instances without running the +command locally. + +```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 command. A +file extension is only required when the command 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 that defines the `$schema`, +`type`, and `properties` keywords. + +```yaml +Type: object +Minimum Property Count: 1 +``` + +### url + +The `url` property defines the URL to the resource's published JSON schema. It's used by +integrating tools for resources that define the `command` property instead of the `embedded` +property. + + + +```yaml +Type: string +Format: uri +``` diff --git a/docs/reference/schemas/resource/manifest/set.md b/docs/reference/schemas/resource/manifest/set.md new file mode 100644 index 000000000..30677f954 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/set.md @@ -0,0 +1,145 @@ +# DSC Resource manifest set property schema reference + +## Synopsis + +Defines how to enforce state for a DSC Resource instance. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json +Type : object +``` + +## Description + +To manage an instance with DSC, a DSC Resource must define the `set` property in its manifest. This +property defines how DSC can enforce the current state of an instance. + +When this property isn't defined, DSC can only get the current state of instances and test whether +they're in the desired state. DSC can't enforce desired state for the resource. + +## 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 command 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 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 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 +resource after the `set` method runs. DSC compares the desired state to the return data of this +resource to identify which of the resource's properties the `set` method enforced, if any. + +## Required Properties + +The `set` definition must include these 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 command. A +file extension is only required when the command 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 resource. The value of this property must +be one of the following strings: + +- `args` - Indicates that the resource expects the properties of an instance to be specified + with command line arguments. This option isn't implemented yet. +- `stdin` - Indicates that the 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 resource tests the instance internally before +enforcing the desired state. Set this property to `true` when the resource tests the instance. +Set this property to `false` to ensure DSC tests the instance first 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 resource returns only the instance's final state after the set + operation as a JSON blob. +- `stateAndDiff` - Indicates that the resource returns the instance's final state and an array of + property names that the resource modified. + +The default value is `state`. + +```yaml +Type: string +Required: false +Default: state +Valid Values: + - state + - stateAndDiff +``` diff --git a/docs/reference/schemas/resource/manifest/test.md b/docs/reference/schemas/resource/manifest/test.md new file mode 100644 index 000000000..185f4880d --- /dev/null +++ b/docs/reference/schemas/resource/manifest/test.md @@ -0,0 +1,139 @@ +# DSC Resource manifest test property schema reference + +## Synopsis + +Defines how to test whether a DSC Resource instance is in the desired state. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json +Type : object +``` + +## Description + +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 manifest. This property defines how DSC can call +the 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 resource. The synthetic +test method: + +1. Gets the actual state of the instance using the 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 resources with +properties that can't be evaluated with equivalency alone. For example, if a 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 resources with properties that can't be evaluated by equivalency alone, always define the +`test` property in the manifest. + +## 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 command 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 resource by running: + +```sh +{ ... } | registry config test +``` + +The manifest defines `return` as `state`, indicating that it only returns the actual state of the +resource when the `test` method runs. + +## Required Properties + +The `test` definition must include these 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 command. A +file extension is only required when the command 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 resource. The value of this property must +be one of the following strings: + +- `args` - Indicates that the resource expects the properties of an instance to be specified + with command line arguments. This option isn't implemented yet. +- `stdin` - Indicates that the 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 resource returns only the instance's actual state. +- `stateAndDiff` - Indicates that the 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/reference/schemas/resource/manifest/validate.md b/docs/reference/schemas/resource/manifest/validate.md new file mode 100644 index 000000000..e5304da21 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/validate.md @@ -0,0 +1,77 @@ +# DSC Resource manifest validate property schema reference + +## Synopsis + +This property + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json +Type : object +``` + +## Description + +DSC Group Resources must define the `validate` property in their DSC Resource manifest. This +property defines how DSC can call the group resource to test whether instances in the group +have valid definitions. + +Always define the `validate` property for group resources in the DSC Resource manifest. + +## 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 + +The `validate` definition must include these 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 command. A +file extension is only required when the command 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/reference/schemas/resource/properties/ensure.md b/docs/reference/schemas/resource/properties/ensure.md new file mode 100644 index 000000000..3f373be19 --- /dev/null +++ b/docs/reference/schemas/resource/properties/ensure.md @@ -0,0 +1,49 @@ +# DSC Resource _ensure property schema + +## Synopsis + +Indicates whether an instance should exist. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json +Type : string +Valid Values : [Absent, Present] +``` + +## Description + +The `_ensure` property indicates that the resource can enforce whether instances exist using the +shared present and absent semantics. + +When `_ensure` is set to `Present` for the desired state, the instance is expected to exist. If it +doesn't exist, the resource creates the instance during the set operation. + +When `_ensure` is set to `Absent` for the desired state, the instance is expected to not exist. If +it does exist, the resource removes the instance during the set operation. + +To add this property to a resource's instance schema, define the property with the following +snippet: + +```json +"_ensure": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" +} +``` + +If a resource must distinguish between states beyond whether an instance is present or absent, the +resource should define its own `ensure` property without the leading underscore. + +For example, a resource that manages a file might be designed to ensure whether the file exists, is +specifically a file, or exists as a symlink. In that case, the resource would define its own +`ensure` property, such as with the snippet below. + +```json +"ensure": { + "type": "string", + "enum": ["present", "absent", "file", "symlink"], + "default": "present" +} +``` diff --git a/docs/reference/schemas/resource/properties/inDesiredState.md b/docs/reference/schemas/resource/properties/inDesiredState.md new file mode 100644 index 000000000..98532aff0 --- /dev/null +++ b/docs/reference/schemas/resource/properties/inDesiredState.md @@ -0,0 +1,44 @@ +# DSC Resource _inDesiredState property schema + +## Synopsis + +Indicates whether an instance is in the desired state. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json +Type : [boolean, 'null'] +Read Only : true +``` + +## Description + +The `_inDesiredState` property indicates whether a resource instance is in the desired state. +Whether a resource's instance schema should include this property depends on whether the resource's +[manifest][01] defines the [test][02] property. + +If the resource's manifest doesn't define `test`, the resource relies on DSC's synthetic test. The +resource's instance schema must not include the `_inDesiredState` property. + +If the resource's manifest defines `test`, the instance schema must include the `_inDesiredState` +property. When the resource returns the state of an instance for the get and set operations, +`_inDesiredState` must be `null`. When the resource returns the state of an instance for the test +operation, `_inDesiredState` must be `true` if the instance is in the desired state and otherwise +`false`. + +This property is read-only. The resource returns instances with this property, but the desired +state can't include it. + +To add this property to a resource's instance schema, define the property with the following +snippet: + +```json +"_inDesiredState": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" +} +``` + +[01]: ../manifest/root.md +[02]: ../manifest/test.md diff --git a/docs/reference/schemas/resource/properties/overview.md b/docs/reference/schemas/resource/properties/overview.md new file mode 100644 index 000000000..d8ba9b6e4 --- /dev/null +++ b/docs/reference/schemas/resource/properties/overview.md @@ -0,0 +1,47 @@ +# DSC well-known properties + +DSC has support for several well-known properties. Some well-known properties enable a DSC Resource +to use built-in processing. The well-known properties always start with an underscore (`_`) and DSC +Resources that use these properties may not override or extend them. + +## _ensure + +The `_ensure` property indicates that the resource can enforce whether instances exist using the +shared present and absent semantics. If a resource must distinguish between states beyond whether +an instance is present or absent, the resource should define its own `ensure` property without the +leading underscore. This property provides shared semantics for DSC Resources and integrating +tools, but doesn't enable any additional built-in processing with DSC. + +For more information, see [DSC Resource _ensure property schema][01]. + +## _inDesiredState + +The read-only `_inDesiredState` property indicates whether a resource instance is in the desired +state. This property is mandatory for command-based DSC Resources that define the [test][02] +property in their [manifest][03]. + +For more information, see [DSC Resource _inDesiredState property schema][04]. + +## _purge + +DSC Resources that need to distinguish between whether unmanaged entries in a list are valid or +must be removed can define the write-only `_purge` property. This property provides shared +semantics for DSC Resources and integrating tools, but doesn't enable any built-in processing with +DSC. + +For more information, see [DSC Resource _purge property schema][05]. + +## _rebootRequested + +The read-only `_rebootRequested` property indicates whether a resource instance requires a reboot +after a set operation. To use DSC's built-in reboot notification processing, resources must define +this property in their manifest. + +For more information, see [DSC Resource _rebootRequested property schema][06]. + +[01]: ensure.md +[02]: ../manifest/test.md +[03]: ../manifest/root.md +[04]: inDesiredState.md +[05]: purge.md +[06]: rebootRequested.md diff --git a/docs/reference/schemas/resource/properties/purge.md b/docs/reference/schemas/resource/properties/purge.md new file mode 100644 index 000000000..1d367c686 --- /dev/null +++ b/docs/reference/schemas/resource/properties/purge.md @@ -0,0 +1,42 @@ +# DSC Resource _purge property schema + +## Synopsis + +Indicates that the resource should treat non-defined entries in a list as invalid. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json +Type : [boolean, 'null'] +Write Only : true +``` + +## Description + +DSC Resources that need to distinguish between whether unmanaged entries in a list are valid or +must be removed can define the `_purge` property. + +When a resource's instance schema defines this property, it indicates that the resource changes its +behavior based on the property's value in an instance's desired state: + +- When `_purge` is `true`, the resource removes unmanaged entries. The resource treats any entries + not listed in the instance's desired state as invalid. +- When `_purge` is `false` or not specified, the resource ignores unmanaged entries. + +When a resource defines this property, it should always document which property or properties +`_purge` affects. A resource may define `_purge` as a subproperty for a complex property. + +This property is write-only. A resource that uses the `_purge` property should never return +`_purge` in the instance's output state. A resource must not define `_purge` as a mandatory +property. + +To add this property to a resource's instance schema, define the property with the following +snippet: + +```json +"_inDesiredState": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" +} +``` diff --git a/docs/reference/schemas/resource/properties/rebootRequested.md b/docs/reference/schemas/resource/properties/rebootRequested.md new file mode 100644 index 000000000..0d180617a --- /dev/null +++ b/docs/reference/schemas/resource/properties/rebootRequested.md @@ -0,0 +1,41 @@ +# DSC Resource _rebootRequested property schema + +## Synopsis + +Indicates whether an instance is in the desired state. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json +Type : [boolean, 'null'] +Read Only : true +``` + +## Description + +The `_rebootRequested` property indicates whether a resource instance requires a reboot after a set +operation. + +If the resource determines during a set operation that the node needs to reboot before the state +change takes full effect, it should return the instance's data with the `_rebootRequested` property +set to `true`. If a resource returns an instance from the set operation with the `_rebootRequested` +property set to `true`, DSC generates a reboot notification. + +If the resource returns an instance from the set operation without the `_rebootRequested` property +defined, or if the property value is `false`, DSC doesn't generate a reboot notification. + +Resources must define this property to use DSC's built-in reboot request notifications. + +This property is read-only. The resource returns instances with this property, but the desired +state can't include it. + +To add this property to a resource's instance schema, define the property with the following +snippet: + +```json +"_rebootRequested": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" +} +``` diff --git a/schemas/2023/08/bundled/config/document.json b/schemas/2023/08/bundled/config/document.json new file mode 100644 index 000000000..55b7b4676 --- /dev/null +++ b/schemas/2023/08/bundled/config/document.json @@ -0,0 +1,226 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": "type", + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", + "title": "DSC Resource instance", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + } + } +} diff --git a/schemas/2023/08/bundled/config/document.vscode.json b/schemas/2023/08/bundled/config/document.vscode.json new file mode 100644 index 000000000..1006c4d86 --- /dev/null +++ b/schemas/2023/08/bundled/config/document.vscode.json @@ -0,0 +1,244 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2023": { + "08": { + "config": { + "document.parameter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": "type", + "properties": { + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + ] + }, + "document.resource.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", + "title": "DSC Resource instance", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "name": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } + } + }, + "definitions": { + "parameters": { + "dataTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] + }, + "validValueTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + } + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + } + } + } + } + } + } + } + } + } +} diff --git a/schemas/2023/08/bundled/outputs/config/get.json b/schemas/2023/08/bundled/outputs/config/get.json new file mode 100644 index 000000000..01e7b1b2b --- /dev/null +++ b/schemas/2023/08/bundled/outputs/config/get.json @@ -0,0 +1,118 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/get.json", + "title": "DSC Configuration get command result", + "description": "Represents the data structure returned by the `dsc config get` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Get Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/get.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } +} diff --git a/schemas/2023/08/bundled/outputs/config/set.json b/schemas/2023/08/bundled/outputs/config/set.json new file mode 100644 index 000000000..4cda22cb0 --- /dev/null +++ b/schemas/2023/08/bundled/outputs/config/set.json @@ -0,0 +1,118 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/set.json", + "title": "DSC Configuration set command result", + "description": "Represents the data structure returned by the `dsc config set` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Set Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/set.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } +} diff --git a/schemas/2023/08/bundled/outputs/config/test.json b/schemas/2023/08/bundled/outputs/config/test.json new file mode 100644 index 000000000..6c74c6720 --- /dev/null +++ b/schemas/2023/08/bundled/outputs/config/test.json @@ -0,0 +1,118 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/test.json", + "title": "DSC Configuration test command result", + "description": "Represents the data structure returned by the `dsc config test` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Test Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/test.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } +} diff --git a/schemas/2023/08/bundled/outputs/resource/get.json b/schemas/2023/08/bundled/outputs/resource/get.json new file mode 100644 index 000000000..8ed6684d9 --- /dev/null +++ b/schemas/2023/08/bundled/outputs/resource/get.json @@ -0,0 +1,18 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json", + "title": "dsc resource get result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", + "type": "object", + "required": [ + "actualState" + ], + "properties": { + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + } + }, + "$defs": {} +} diff --git a/schemas/2023/08/bundled/outputs/resource/list.json b/schemas/2023/08/bundled/outputs/resource/list.json new file mode 100644 index 000000000..18cd2107d --- /dev/null +++ b/schemas/2023/08/bundled/outputs/resource/list.json @@ -0,0 +1,518 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/list.json", + "title": "dsc resource list result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource list` command.", + "type": "object", + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "version": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "path": { + "title": "Path", + "description": "Indicates the path to the DSC Resource on the file system.", + "type": "string" + }, + "directory": { + "title": "Directory", + "description": "Indicates the path to the folder containing the DSC Resource on the file system.", + "type": "string" + }, + "implementedAs": { + "title": "Implemented as", + "description": "Indicates how the DSC Resource was implemented.", + "oneOf": [ + { + "title": "Standard implementation", + "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", + "type": "string", + "enum": [ + "Command" + ] + }, + { + "title": "Custom implementation", + "description": "Indicates that the DSC Resource uses a custom implementation.", + "type": "object", + "required": [ + "custom" + ], + "properties": { + "custom": { + "title": "Custom implementation name", + "description": "The name of the custom implementation.", + "type": "string" + } + } + } + ] + }, + "author": { + "title": "Author", + "description": "Indicates the name of the person or organization that developed and maintains the DSC Resource.", + "type": [ + "string", + "null" + ] + }, + "properties": { + "title": "Properties", + "description": "Defines the DSC Resource's property names.", + "type": "array", + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "requires": { + "title": "Required DSC Resource Provider", + "description": "Defines the fully qualified type name of the DSC Resource Provider the DSC Resource depends on.", + "oneOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + { + "type": "null" + } + ] + }, + "manifest": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "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-]+)*))?$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "enums": "1.0" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "An array of short strings used to search for DSC Resources.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json" + }, + "set": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json" + }, + "test": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json" + }, + "validate": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json" + }, + "provider": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json" + }, + "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" + } + } + }, + "schema": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "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": { + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "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" + ] + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "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", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "properties": { + "_ensure": { + "title": "Standard Property: _ensure", + "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "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" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json", + "title": "Ensure Existence", + "description": "Indicates whether the DSC Resource instance should exist.", + "type": "string", + "enum": [ + "Absent", + "Present" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json", + "title": "Instance is in the Desired State", + "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json", + "title": "Purge", + "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", + "type": [ + "boolean", + "null" + ], + "writeOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json", + "title": "Reboot Requested", + "description": "Indicates that the set operation requires a reboot before it's fully complete.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + } + } +} diff --git a/schemas/2023/08/bundled/outputs/resource/schema.json b/schemas/2023/08/bundled/outputs/resource/schema.json new file mode 100644 index 000000000..dbe44ccd9 --- /dev/null +++ b/schemas/2023/08/bundled/outputs/resource/schema.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc resource schema` command. This command always returns the DSC Resource's JSON schema document.", + "type": "object", + "$defs": {} +} diff --git a/schemas/2023/08/bundled/outputs/resource/set.json b/schemas/2023/08/bundled/outputs/resource/set.json new file mode 100644 index 000000000..c6b67bf1a --- /dev/null +++ b/schemas/2023/08/bundled/outputs/resource/set.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json", + "title": "dsc resource set result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", + "type": "object", + "required": [ + "beforeState", + "afterState", + "changedProperties" + ], + "properties": { + "beforeState": { + "title": "State before enforcing", + "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "afterState": { + "title": "State after enforcing", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "changedProperties": { + "title": "Changed properties", + "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + }, + "$defs": {} +} diff --git a/schemas/2023/08/bundled/outputs/resource/test.json b/schemas/2023/08/bundled/outputs/resource/test.json new file mode 100644 index 000000000..6e584bca4 --- /dev/null +++ b/schemas/2023/08/bundled/outputs/resource/test.json @@ -0,0 +1,40 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", + "type": "object", + "required": [ + "desiredState", + "actualState", + "inDesiredState", + "differingProperties" + ], + "properties": { + "desiredState": { + "title": "Desired state", + "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", + "type": "object" + }, + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "inDesiredState": { + "title": "Instance is in the desired state", + "description": "This property indicates whether the instance is in the desired state.", + "type": "boolean" + }, + "differingProperties": { + "title": "Differing properties", + "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + }, + "$defs": {} +} diff --git a/schemas/2023/08/bundled/outputs/schema.json b/schemas/2023/08/bundled/outputs/schema.json new file mode 100644 index 000000000..e5b2d2310 --- /dev/null +++ b/schemas/2023/08/bundled/outputs/schema.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc schema` command. This command always returns a JSON schema document.", + "type": "object", + "$defs": {} +} diff --git a/schemas/2023/08/bundled/resource/manifest.json b/schemas/2023/08/bundled/resource/manifest.json new file mode 100644 index 000000000..6ebcc1d01 --- /dev/null +++ b/schemas/2023/08/bundled/resource/manifest.json @@ -0,0 +1,440 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "enums": [ + "1.0" + ] + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "An array of short strings used to search for DSC Resources.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json" + }, + "set": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json" + }, + "test": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json" + }, + "validate": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json" + }, + "provider": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json" + }, + "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" + } + } + ] + }, + "schema": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "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-]+)*))?$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "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": { + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "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" + ] + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "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", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "properties": { + "_ensure": { + "title": "Standard Property: _ensure", + "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "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" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json", + "title": "Ensure Existence", + "description": "Indicates whether the DSC Resource instance should exist.", + "type": "string", + "enum": [ + "Absent", + "Present" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json", + "title": "Instance is in the Desired State", + "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json", + "title": "Purge", + "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", + "type": [ + "boolean", + "null" + ], + "writeOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json", + "title": "Reboot Requested", + "description": "Indicates that the set operation requires a reboot before it's fully complete.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + } + } +} diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json new file mode 100644 index 000000000..d9e6cdc0f --- /dev/null +++ b/schemas/2023/08/bundled/resource/manifest.vscode.json @@ -0,0 +1,412 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "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/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "enums": [ + "1.0" + ] + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "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/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "An array of short strings used to search for DSC Resources.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json" + }, + "set": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json" + }, + "test": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json" + }, + "validate": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json" + }, + "provider": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json" + }, + "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" + } + } + ] + }, + "schema": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json" + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2023": { + "08": { + "definitions": { + "semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "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-]+)*))?$" + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "commandExecutable.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "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" + }, + "returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state" + } + }, + "resource": { + "manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json", + "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/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + } + } + }, + "manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json", + "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/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "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": { + "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/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json", + "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/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "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/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json", + "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/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "manifest.provider.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json", + "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/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "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" + ] + } + } + }, + "manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json", + "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/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "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", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "properties": { + "_ensure": { + "title": "Standard Property: _ensure", + "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + } + } + } + } + } + } + } + } + } + } +} diff --git a/schemas/2023/08/config/document.json b/schemas/2023/08/config/document.json new file mode 100644 index 000000000..9b9ba5a30 --- /dev/null +++ b/schemas/2023/08/config/document.json @@ -0,0 +1,49 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + } +} diff --git a/schemas/2023/08/config/document.parameter.json b/schemas/2023/08/config/document.parameter.json new file mode 100644 index 000000000..26b606a1e --- /dev/null +++ b/schemas/2023/08/config/document.parameter.json @@ -0,0 +1,102 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + ] +} diff --git a/schemas/2023/08/config/document.resource.json b/schemas/2023/08/config/document.resource.json new file mode 100644 index 000000000..4a0bebb9f --- /dev/null +++ b/schemas/2023/08/config/document.resource.json @@ -0,0 +1,33 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", + "title": "DSC Resource instance", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } +} diff --git a/schemas/2023/08/definitions/commandArgs.json b/schemas/2023/08/definitions/commandArgs.json new file mode 100644 index 000000000..67af70e06 --- /dev/null +++ b/schemas/2023/08/definitions/commandArgs.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } +} diff --git a/schemas/2023/08/definitions/commandExecutable.json b/schemas/2023/08/definitions/commandExecutable.json new file mode 100644 index 000000000..408eb9289 --- /dev/null +++ b/schemas/2023/08/definitions/commandExecutable.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" +} diff --git a/schemas/2023/08/definitions/hadErrors.json b/schemas/2023/08/definitions/hadErrors.json new file mode 100644 index 000000000..6ea65bfec --- /dev/null +++ b/schemas/2023/08/definitions/hadErrors.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" +} diff --git a/schemas/2023/08/definitions/inputKind.json b/schemas/2023/08/definitions/inputKind.json new file mode 100644 index 000000000..c6305bd52 --- /dev/null +++ b/schemas/2023/08/definitions/inputKind.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "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" +} diff --git a/schemas/2023/08/definitions/instanceName.json b/schemas/2023/08/definitions/instanceName.json new file mode 100644 index 000000000..ba86a225a --- /dev/null +++ b/schemas/2023/08/definitions/instanceName.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" +} diff --git a/schemas/2023/08/definitions/message.json b/schemas/2023/08/definitions/message.json new file mode 100644 index 000000000..48be4a2e7 --- /dev/null +++ b/schemas/2023/08/definitions/message.json @@ -0,0 +1,39 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } +} diff --git a/schemas/2023/08/definitions/messages.json b/schemas/2023/08/definitions/messages.json new file mode 100644 index 000000000..a8cf65986 --- /dev/null +++ b/schemas/2023/08/definitions/messages.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/message.json" + } +} diff --git a/schemas/2023/08/definitions/parameters/dataTypes.json b/schemas/2023/08/definitions/parameters/dataTypes.json new file mode 100644 index 000000000..0a3951dc7 --- /dev/null +++ b/schemas/2023/08/definitions/parameters/dataTypes.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] +} diff --git a/schemas/2023/08/definitions/parameters/validValueTypes.json b/schemas/2023/08/definitions/parameters/validValueTypes.json new file mode 100644 index 000000000..ac2f7b14d --- /dev/null +++ b/schemas/2023/08/definitions/parameters/validValueTypes.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. As-written, values must be one of\nthose on this list - the schema definition for dataType excludes `null` and\nnumbers with fractional parts, like `3.5`.\n", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] +} diff --git a/schemas/2023/08/definitions/resourceType.json b/schemas/2023/08/definitions/resourceType.json new file mode 100644 index 000000000..41ae13554 --- /dev/null +++ b/schemas/2023/08/definitions/resourceType.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" +} diff --git a/schemas/2023/08/definitions/returnKind.json b/schemas/2023/08/definitions/returnKind.json new file mode 100644 index 000000000..12de48fa8 --- /dev/null +++ b/schemas/2023/08/definitions/returnKind.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." +} diff --git a/schemas/2023/08/definitions/semver.json b/schemas/2023/08/definitions/semver.json new file mode 100644 index 000000000..6e19aa651 --- /dev/null +++ b/schemas/2023/08/definitions/semver.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "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 comes from the semver website's FAQ:\n\nhttps://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n\nIt's the suggested regex pattern for JavaScript.\n\nThis is the same pattern, made multi-line for easier readability.\n\n```\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n" +} diff --git a/schemas/2023/08/outputs/config/get.json b/schemas/2023/08/outputs/config/get.json new file mode 100644 index 000000000..9c5de7d64 --- /dev/null +++ b/schemas/2023/08/outputs/config/get.json @@ -0,0 +1,45 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/get.json", + "title": "DSC Configuration get command result", + "description": "Represents the data structure returned by the `dsc config get` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Get Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/get.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + } +} diff --git a/schemas/2023/08/outputs/config/set.json b/schemas/2023/08/outputs/config/set.json new file mode 100644 index 000000000..450eb783e --- /dev/null +++ b/schemas/2023/08/outputs/config/set.json @@ -0,0 +1,45 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/set.json", + "title": "DSC Configuration set command result", + "description": "Represents the data structure returned by the `dsc config set` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Set Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/set.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + } +} diff --git a/schemas/2023/08/outputs/config/test.json b/schemas/2023/08/outputs/config/test.json new file mode 100644 index 000000000..964c98fd8 --- /dev/null +++ b/schemas/2023/08/outputs/config/test.json @@ -0,0 +1,45 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/test.json", + "title": "DSC Configuration test command result", + "description": "Represents the data structure returned by the `dsc config test` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Test Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/test.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + } +} diff --git a/schemas/2023/08/outputs/resource/get.json b/schemas/2023/08/outputs/resource/get.json new file mode 100644 index 000000000..00a306026 --- /dev/null +++ b/schemas/2023/08/outputs/resource/get.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json", + "title": "dsc resource get result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", + "type": "object", + "required": [ + "actualState" + ], + "properties": { + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + } + } +} diff --git a/schemas/2023/08/outputs/resource/list.json b/schemas/2023/08/outputs/resource/list.json new file mode 100644 index 000000000..13b4a5094 --- /dev/null +++ b/schemas/2023/08/outputs/resource/list.json @@ -0,0 +1,91 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/list.json", + "title": "dsc resource list result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource list` command.", + "type": "object", + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "version": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "path": { + "title": "Path", + "description": "Indicates the path to the DSC Resource on the file system.", + "type": "string" + }, + "directory": { + "title": "Directory", + "description": "Indicates the path to the folder containing the DSC Resource on the file system.", + "type": "string" + }, + "implementedAs": { + "title": "Implemented as", + "description": "Indicates how the DSC Resource was implemented.", + "oneOf": [ + { + "title": "Standard implementation", + "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", + "type": "string", + "enum": [ + "Command" + ] + }, + { + "title": "Custom implementation", + "description": "Indicates that the DSC Resource uses a custom implementation.", + "type": "object", + "required": [ + "custom" + ], + "properties": { + "custom": { + "title": "Custom implementation name", + "description": "The name of the custom implementation.", + "type": "string" + } + } + } + ] + }, + "author": { + "title": "Author", + "description": "Indicates the name of the person or organization that developed and maintains the DSC Resource.", + "type": [ + "string", + "null" + ] + }, + "properties": { + "title": "Properties", + "description": "Defines the DSC Resource's property names.", + "type": "array", + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "requires": { + "title": "Required DSC Resource Provider", + "description": "Defines the fully qualified type name of the DSC Resource Provider the DSC Resource depends on.", + "oneOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + { + "type": "null" + } + ] + }, + "manifest": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json" + } + } +} diff --git a/schemas/2023/08/outputs/resource/schema.json b/schemas/2023/08/outputs/resource/schema.json new file mode 100644 index 000000000..fd430dd71 --- /dev/null +++ b/schemas/2023/08/outputs/resource/schema.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc resource schema` command. This command always returns the DSC Resource's JSON schema document.", + "type": "object" +} diff --git a/schemas/2023/08/outputs/resource/set.json b/schemas/2023/08/outputs/resource/set.json new file mode 100644 index 000000000..ce8776378 --- /dev/null +++ b/schemas/2023/08/outputs/resource/set.json @@ -0,0 +1,33 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json", + "title": "dsc resource set result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", + "type": "object", + "required": [ + "beforeState", + "afterState", + "changedProperties" + ], + "properties": { + "beforeState": { + "title": "State before enforcing", + "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "afterState": { + "title": "State after enforcing", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "changedProperties": { + "title": "Changed properties", + "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } +} diff --git a/schemas/2023/08/outputs/resource/test.json b/schemas/2023/08/outputs/resource/test.json new file mode 100644 index 000000000..e64a9d5dd --- /dev/null +++ b/schemas/2023/08/outputs/resource/test.json @@ -0,0 +1,39 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", + "type": "object", + "required": [ + "desiredState", + "actualState", + "inDesiredState", + "differingProperties" + ], + "properties": { + "desiredState": { + "title": "Desired state", + "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", + "type": "object" + }, + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "inDesiredState": { + "title": "Instance is in the desired state", + "description": "This property indicates whether the instance is in the desired state.", + "type": "boolean" + }, + "differingProperties": { + "title": "Differing properties", + "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } +} diff --git a/schemas/2023/08/outputs/schema.json b/schemas/2023/08/outputs/schema.json new file mode 100644 index 000000000..f3142e294 --- /dev/null +++ b/schemas/2023/08/outputs/schema.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc schema` command. This command always returns a JSON schema document.", + "type": "object" +} diff --git a/schemas/2023/08/resource/manifest.get.json b/schemas/2023/08/resource/manifest.get.json new file mode 100644 index 000000000..351aa81dd --- /dev/null +++ b/schemas/2023/08/resource/manifest.get.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ] +} diff --git a/schemas/2023/08/resource/manifest.json b/schemas/2023/08/resource/manifest.json new file mode 100644 index 000000000..07f125eb7 --- /dev/null +++ b/schemas/2023/08/resource/manifest.json @@ -0,0 +1,88 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "enums": [ + "1.0" + ] + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "An array of short strings used to search for DSC Resources.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json" + }, + "set": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json" + }, + "test": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json" + }, + "validate": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json" + }, + "provider": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json" + }, + "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" + } + } + ] + }, + "schema": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json" + } + } +} diff --git a/schemas/2023/08/resource/manifest.provider.json b/schemas/2023/08/resource/manifest.provider.json new file mode 100644 index 000000000..efbcbcf3a --- /dev/null +++ b/schemas/2023/08/resource/manifest.provider.json @@ -0,0 +1,53 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "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" + ] + } + } + ] +} diff --git a/schemas/2023/08/resource/manifest.schema.json b/schemas/2023/08/resource/manifest.schema.json new file mode 100644 index 000000000..11145f7ee --- /dev/null +++ b/schemas/2023/08/resource/manifest.schema.json @@ -0,0 +1,195 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "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", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "properties": { + "_ensure": { + "title": "Standard Property: _ensure", + "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "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" + ] + } + } + } + } + ] +} diff --git a/schemas/2023/08/resource/manifest.set.json b/schemas/2023/08/resource/manifest.set.json new file mode 100644 index 000000000..37adb350f --- /dev/null +++ b/schemas/2023/08/resource/manifest.set.json @@ -0,0 +1,44 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "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": { + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "preTest": true, + "return": "state" + } + ] +} diff --git a/schemas/2023/08/resource/manifest.test.json b/schemas/2023/08/resource/manifest.test.json new file mode 100644 index 000000000..c503d5704 --- /dev/null +++ b/schemas/2023/08/resource/manifest.test.json @@ -0,0 +1,38 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] +} diff --git a/schemas/2023/08/resource/manifest.validate.json b/schemas/2023/08/resource/manifest.validate.json new file mode 100644 index 000000000..b646ae487 --- /dev/null +++ b/schemas/2023/08/resource/manifest.validate.json @@ -0,0 +1,27 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json", + "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": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + }, + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] +} diff --git a/schemas/2023/08/resource/properties/ensure.json b/schemas/2023/08/resource/properties/ensure.json new file mode 100644 index 000000000..46575b94f --- /dev/null +++ b/schemas/2023/08/resource/properties/ensure.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json", + "title": "Ensure Existence", + "description": "Indicates whether the DSC Resource instance should exist.", + "type": "string", + "enum": [ + "Absent", + "Present" + ] +} diff --git a/schemas/2023/08/resource/properties/inDesiredState.json b/schemas/2023/08/resource/properties/inDesiredState.json new file mode 100644 index 000000000..dcbb3888f --- /dev/null +++ b/schemas/2023/08/resource/properties/inDesiredState.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json", + "title": "Instance is in the Desired State", + "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", + "type": [ + "boolean", + "null" + ], + "readOnly": true +} diff --git a/schemas/2023/08/resource/properties/purge.json b/schemas/2023/08/resource/properties/purge.json new file mode 100644 index 000000000..d91cd908a --- /dev/null +++ b/schemas/2023/08/resource/properties/purge.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json", + "title": "Purge", + "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", + "type": [ + "boolean", + "null" + ], + "writeOnly": true +} diff --git a/schemas/2023/08/resource/properties/rebootRequested.json b/schemas/2023/08/resource/properties/rebootRequested.json new file mode 100644 index 000000000..3ec4824c4 --- /dev/null +++ b/schemas/2023/08/resource/properties/rebootRequested.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json", + "title": "Reboot Requested", + "description": "Indicates that the set operation requires a reboot before it's fully complete.", + "type": [ + "boolean", + "null" + ], + "readOnly": true +} diff --git a/schemas/build.ps1 b/schemas/build.ps1 new file mode 100644 index 000000000..bd0261a2b --- /dev/null +++ b/schemas/build.ps1 @@ -0,0 +1,597 @@ +#requires -Modules yayaml +using namespace System.Collections + +<# + .SYNOPSIS +#> + +[cmdletbinding(DefaultParameterSetName='ByConfig')] +param( + [string] + $OutputDirectory = "$PSScriptRoot", + + [Parameter(ParameterSetName='ByPath')] + [string[]] + $ConfigFilePath, + + [string[]] + [ValidateSet('Json', 'JsonVSCode', 'Yaml', 'YamlVSCode')] + $OutputFormat = @( + 'Json' + 'JsonVSCode' + 'Yaml' + 'YamlVSCode' + ) +) + +begin { + class LocalJsonSchemaRegistry { + [Specialized.OrderedDictionary] + $Map + + [Generic.List[Specialized.OrderedDictionary]] + $List + + [string]$SchemaHost + [string]$SchemaPrefix + [string]$SchemaVersion + + LocalJsonSchemaRegistry() { + $this.Map = [Specialized.OrderedDictionary]::new() + $this.List = [Generic.List[Specialized.OrderedDictionary]]::new() + } + + LocalJsonSchemaRegistry( + [string]$SchemaHost, + [string]$SchemaPrefix, + [string]$SchemaVersion + ) { + $this.SchemaHost = $SchemaHost + $this.SchemaPrefix = $SchemaPrefix + $this.SchemaVersion = $SchemaVersion + $this.Map = [Specialized.OrderedDictionary]::new() + $this.List = [Generic.List[Specialized.OrderedDictionary]]::new() + } + + } + + function Remove-JsonSchemaKey { + [cmdletbinding(DefaultParameterSetName='SchemaObject')] + [OutputType([Specialized.OrderedDictionary])] + [OutputType([Object[]])] + param( + [parameter(ParameterSetName='SchemaObject')] + [Specialized.OrderedDictionary] + $Schema, + + [parameter(ParameterSetName='SchemaList', DontShow)] + [Object[]] + $SchemaList, + + [string]$KeyName + ) + + process { + if ($PSCmdlet.ParameterSetName -eq 'SchemaObject') { + $MungedSchema = [Specialized.OrderedDictionary]::new() + + $Schema.GetEnumerator().Where({$_.Key -ne $KeyName}).ForEach({ + if ($_.Value -is [Object[]]) { + $MungedKeyValue = Remove-JsonSchemaKey -KeyName $KeyName -SchemaList $_.Value + $MungedSchema.Add($_.Key, $MungedKeyValue) + } elseif ($_.Value -is [Specialized.OrderedDictionary]) { + $MungedKeyValue = Remove-JsonSchemaKey -KeyName $KeyName -Schema $_.Value + $MungedSchema.Add($_.Key, $MungedKeyValue) + } else { + $MungedSchema.Add($_.Key, $_.Value) + } + }) + + return $MungedSchema + } + + if ($PSCmdlet.ParameterSetName -eq 'SchemaList') { + [Object[]]$MungedArrayValue = @() + + $SchemaList.ForEach({ + if ($_ -is [Object[]]) { + $MungedArrayValue += Remove-JsonSchemaKey -KeyName $KeyName -SchemaList $_ + } elseif ($_ -is [Specialized.OrderedDictionary]) { + $MungedArrayValue += Remove-JsonSchemaKey -KeyName $KeyName -Schema $_ + } else { + $MungedArrayValue += $_ + } + }) + + return $MungedArrayValue + } + } + } + + function Get-LocalJsonSchemaRegistry { + [CmdletBinding()] + [OutputType([LocalJsonSchemaRegistry])] + param( + [switch]$WithoutExamples, + [switch]$WithoutComments, + [string[]]$SchemaDirectories = @(), + [string]$SchemaHost = 'https://raw.githubusercontent.com', + [string]$SchemaPrefix = 'PowerShell/DSC/main', + [string]$SchemaVersion = '2023/08' + ) + + begin { + $Info = [LocalJsonSchemaRegistry]::new($SchemaHost, $SchemaPrefix, $SchemaVersion) + } + + process { + Get-ChildItem -Path $SchemaDirectories -Recurse -File + | Where-Object -Property Extension -in -Value @('.json', '.yaml', '.yml') + | ForEach-Object -process { + $Schema = Get-Content $_ -Raw | yayaml\ConvertFrom-Yaml + if ($AddDocsUrl) { + Write-Warning 'Not implemented yet' + } + if ($MakeStrict) { + Write-Warning 'Not implemented yet' + } + if ($WithoutComments) { + $Schema = Remove-JsonSchemaKey -Schema $Schema -KeyName '$comment' + } + if ($WithoutExamples) { + $Schema = Remove-JsonSchemaKey -Schema $Schema -KeyName 'examples' + } + if ($SchemaID = $Schema.'$id') { + $SchemaRefID = $SchemaID -replace $SchemaHost, '' + $Info.List.Add($Schema) + $Info.Map.Add($SchemaID, $Schema) + $Info.Map.Add($SchemaRefID, $Schema) + } + } + + $Info + } + } + + function Get-JsonSchemaReference { + <# + #> + [cmdletbinding(DefaultParameterSetName='SchemaObject')] + [OutputType([Generic.List[string]])] + param( + [parameter(ParameterSetName='SchemaObject')] + [Specialized.OrderedDictionary] + $Schema, + + [parameter(ParameterSetName='SchemaList', DontShow)] + [Object[]] + $SchemaList, + + [LocalJsonSchemaRegistry] $SchemaRegistry + ) + + begin { + $References = [Generic.List[string]]::new() + $AddNestedReference = { + if ($_ -notin $References) { + $References.Add($_) + } + } + } + + process { + if ($PSCmdlet.ParameterSetName -eq 'SchemaObject') { + $Schema.GetEnumerator().ForEach({ + if ($_.Key -eq '$ref' -and $_.Value -notin $References) { + $References.Add($_.Value) + } elseif ($_.Value -is [Object[]]) { + $NestedReferences = Get-JsonSchemaReference -SchemaList $_.Value + $NestedReferences.ForEach($AddNestedReference) + } elseif ($_.Value -is [Specialized.OrderedDictionary]) { + $NestedReferences = Get-JsonSchemaReference -Schema $_.Value + $NestedReferences.ForEach($AddNestedReference) + } + }) + } + + if ($PSCmdlet.ParameterSetName -eq 'SchemaList') { + $SchemaList.ForEach({ + if ($_ -is [Object[]]) { + $NestedReferences = Get-JsonSchemaReference -SchemaList $_ + $NestedReferences.ForEach($AddNestedReference) + } elseif ($_ -is [Specialized.OrderedDictionary]) { + $NestedReferences = Get-JsonSchemaReference -Schema $_ + $NestedReferences.ForEach($AddNestedReference) + } + }) + } + + if ($null -ne $SchemaRegistry -and $References.Count -gt 0) { + foreach ($Reference in $References.Clone()) { + if ($Reference -in $SchemaRegistry.Map.Keys) { + $Resolving = @{ + Schema = $SchemaRegistry.Map.$Reference + SchemaRegistry = $SchemaRegistry + } + $NestedReferences = Get-JsonSchemaReference @Resolving + $NestedReferences.ForEach($AddNestedReference) + } + } + } + + $References + } + } + + function Merge-JsonSchema { + <# + #> + [cmdletbinding(DefaultParameterSetName='FromPreset')] + [OutputType([Specialized.OrderedDictionary])] + param( + [Parameter(ParameterSetName='FromPath', Mandatory)] + [string] + $Path, + + [Parameter(ParameterSetName='FromSchema', Mandatory)] + [Specialized.OrderedDictionary] + $Schema, + + [Parameter(ParameterSetName='FromPreset', Mandatory)] + [ValidateSet('ConfigDocument', 'ResourceManifest')] + [string] + $Preset, + + [LocalJsonSchemaRegistry] $SchemaRegistry, + + [switch]$ForVSCode, + [switch]$WithoutComments, + [switch]$WithoutExamples + ) + + begin { + if ($null -eq $SchemaRegistry) { + $SchemaRegistry = Get-LocalJsonSchemaRegistry + } + + $Schema = [Specialized.OrderedDictionary]::new() + $References = [Generic.List[string]]::new() + $RelativeUriReferencePattern = @( + '(?m)' + '^' + '(?\s+\$ref:\s+)' + '(?/.+)' + '$' + ) -join '' + } + + process { + if ($PSCmdlet.ParameterSetName -eq 'FromPath') { + $Schema = Get-Content -Path $Path -Raw | yayaml\ConvertFrom-Yaml + } + if ($PSCmdlet.ParameterSetName -eq 'FromPreset') { + switch ($Preset) { + 'ConfigDocument' { + $Schema = $SchemaRegistry.Map.'/dsc/2023/07/config/document.yaml' + } + 'ResourceManifest' { + $Schema = $SchemaRegistry.Map.'/dsc/2023/07/resource/manifest.yaml' + } + } + } + + $ID = $Schema.'$id' + + $MergedSchema = $Schema | yayaml\ConvertTo-Yaml -Depth 99 | yayaml\ConvertFrom-Yaml + + $References = Get-JsonSchemaReference -Schema $Schema -SchemaRegistry $SchemaRegistry + + if ($ForVSCode) { + if ('$defs' -notin $MergedSchema.Keys) { + $MergedSchema.Add('$defs', [Specialized.OrderedDictionary]::new()) + } + + foreach ($Reference in $References) { + $ReferenceSchema = $SchemaRegistry.Map.$Reference + if ($null -eq $ReferenceSchema -and $Reference -match '#\/') { + Write-Verbose "$ID`n`tSkipping local reference: '$Reference'" + continue + } + + if ($null -eq $ReferenceSchema -or $Reference -match '^https?:\/\/') { + Write-Verbose "$ID`n`tSkipping apparent remote reference: '$Reference'" + continue + } + + $ReferenceSegments = $Reference.Trim('/') -split '/' + $Working = $MergedSchema.'$defs' + + for ($i = 0; $i -lt $ReferenceSegments.Count; $i++) { + $Segment = $ReferenceSegments[$i] + + # Segment dictionary already exists + if ($Segment -in $Working.Keys) { + $Working = $Working.$Segment + continue + } + + # Add an empty dictionary for non-final segments + if ($i -ne ($ReferenceSegments.Count - 1)) { + $Working.Add($Segment, [Specialized.OrderedDictionary]::new()) + $Working = $Working.$Segment + continue + } + + # Add the referenced schema + $Working.Add($Segment, $ReferenceSchema) + } + + } + + $MungingSchema = $MergedSchema | yayaml\ConvertTo-Yaml -Depth 99 + $MungingSchema + | Select-String -Pattern $RelativeUriReferencePattern -AllMatches + | Select-Object -ExpandProperty Matches + | ForEach-Object -Process { + $Whole = $_.Groups + | Where-Object { $_.Name -eq '0' } + | Select-Object -ExpandProperty Value + $Prefix = $_.Groups + | Where-Object { $_.Name -eq 'Prefix' } + | Select-Object -ExpandProperty Value + $RefUri = $_.Groups + | Where-Object { $_.Name -eq 'Reference' } + | Select-Object -ExpandProperty Value + $NewValue = @( + $Prefix + "'" + '#/$defs' + $RefUri.Trim() + "'" + ) -join '' + $MungingSchema = $MungingSchema -replace [regex]::Escape($Whole), $NewValue + } + $MergedSchema = $MungingSchema | yayaml\ConvertFrom-Yaml + } else { + if ('$defs' -notin $MergedSchema.Keys) { + $MergedSchema.Add('$defs', [Specialized.OrderedDictionary]::new()) + } + + foreach ($Reference in $References) { + $ReferenceSchema = $SchemaRegistry.Map.$Reference + if ($null -eq $ReferenceSchema -and $Reference -match '^#\/') { + Write-Verbose "$ID`n`tSkipping local reference: '$Reference'" + continue + } + + if ($null -eq $ReferenceSchema) { + Write-Verbose "$ID`n`tSkipping apparent remote reference: '$Reference'" + continue + } + + if ($Reference -notin $Schema.'$defs'.Keys) { + Write-Verbose "$ID`n`tAdding reference to `$defs: '$Reference'" + $MergedSchema.'$defs'.Add($ReferenceSchema.'$id', $ReferenceSchema) + } + } + } + + if ($WithoutComments) { + $MergedSchema = Remove-JsonSchemaKey -Schema $MergedSchema -KeyName '$comment' + } + if ($WithoutExamples) { + $MergedSchema = Remove-JsonSchemaKey -Schema $MergedSchema -KeyName 'examples' + } + + $MergedSchema + } + } + + function ConvertTo-MergedAndMungedJson { + [CmdletBinding()] + [OutputType([string])] + param( + [Parameter(Mandatory, ValueFromPipeline)] + [Specialized.OrderedDictionary] + $InputObject + ) + + process { + ($InputObject | ConvertTo-Json -Depth 99) -replace '\b(\w+\.)yaml', '$1json' + } + } + + function Set-BundledSchemaID { + [CmdletBinding()] + [OutputType([Specialized.OrderedDictionary])] + param( + [Parameter(Mandatory, ValueFromPipeline)] + [Specialized.OrderedDictionary] + $InputObject, + [Parameter(Mandatory)] + [string] + $BundledName, + [string] + $SchemaHost = 'https://raw.githubusercontent.com', + [string] + $SchemaPrefix = 'PowerShell/DSC/main' + ) + + begin { + $ReplaceIDPattern = @( + '^' + '(' + [regex]::Escape("$SchemaHost/$SchemaPrefix") + '\d+\/\d+\/' + ')' + '.+\.yaml' + '$' + ) -join '' + $ReplaceIDValue = "`$1bundled/$BundledName.yaml" + } + process { + $ID = $InputObject.'$id' -replace $ReplaceIDPattern, $ReplaceIDValue + $InputObject.'$id' = $ID + $InputObject + } + } + + function Export-MergedJsonSchema { + param ( + [Parameter(Mandatory)] + [string] + $ConfigFilePath, + + [string] + $Name, + + [string] + $OutputDirectory = $PWD, + + [string[]] + [ValidateSet('Json', 'JsonVSCode', 'Yaml', 'YamlVSCode')] + $OutputFormat = @( + 'Json' + ), + + [LocalJsonSchemaRegistry] $SchemaRegistry + ) + + begin { + $MergeForNormal = $OutputFormat.Where({$_ -notmatch 'VSCode'}).Count -gt 0 + $MergeForVSCode = $OutputFormat.Where({$_ -match 'VSCode'}).Count -gt 0 + if (-not (Test-Path -Path $OutputDirectory)) { + $null = New-Item -Path $OutputDirectory -ItemType Directory -Force + } + } + + process { + if ([string]::IsNullOrEmpty($Name)) { + $ConfigFileInfo = Get-Item -Path $ConfigFilePath + $Name = $ConfigFileInfo.BaseName + } + + $OutputPathPrefix = "$OutputDirectory/$Name" + + $SharedMergeParams = @{ + Path = $ConfigFilePath + SchemaRegistry = $SchemaRegistry + } + + if ($MergeForNormal) { + $Bundled = Merge-JsonSchema @SharedMergeParams + | Set-BundledSchemaID -BundledName $Name + + if ($OutputFormat -contains 'json') { + $Bundled + | ConvertTo-MergedAndMungedJson + | ForEach-Object { $_ -replace '\r\n', "`n" } + | Out-File -FilePath "$OutputPathPrefix.json" + } + + if ($OutputFormat -contains 'yaml') { + $Bundled + | yayaml\ConvertTo-Yaml -Depth 99 + | ForEach-Object { $_ -replace '\r\n', "`n" } + | Out-File -FilePath "$OutputPathPrefix.yaml" + } + } + if ($MergeForVSCode) { + $Bundled = Merge-JsonSchema @SharedMergeParams -ForVSCode + | Set-BundledSchemaID -BundledName $Name + + if ($OutputFormat -contains 'jsonVSCode') { + $Bundled + | ConvertTo-MergedAndMungedJson + | ForEach-Object { $_ -replace '\r\n', "`n" } + | Out-File -FilePath "$OutputPathPrefix.vscode.json" + } + + if ($OutputFormat -contains 'yamlVSCode') { + $Bundled + | yayaml\ConvertTo-Yaml -Depth 99 + | ForEach-Object { $_ -replace '\r\n', "`n" } + | Out-File -FilePath "$OutputPathPrefix.vscode.yaml" -Force:$Force + } + } + } + } +} + +process { + $Config = Get-Content -Path $PSScriptRoot/schemas.config.yaml | yayaml\ConvertFrom-Yaml + + if (-not $PSBoundParameters.ContainsKey('OutputDirectory')) { + $OutputDirectory = "$PSScriptRoot/$($Config.version)" + } + + if (-not (Test-Path -Path $OutputDirectory)) { + $null = New-Item -Path $OutputDirectory -ItemType Directory -Force + } + + Get-ChildItem -Path $PSScriptRoot/src -Filter *.yaml -Recurse | ForEach-Object -Process { + $SchemaContent = Get-Content -Path $_.FullName -Raw + $SchemaContent = $SchemaContent -replace '', $Config.host + $SchemaContent = $SchemaContent -replace '', $Config.prefix + $SchemaContent = $SchemaContent -replace '', $Config.version + $SchemaContent = $SchemaContent -replace '(?m)\.yaml$"?,?', '.json' + $SchemaPath = $_.FullName -replace 'src', $Config.version + $SchemaFolder = Split-Path -Parent $SchemaPath + if (-not (Test-Path -Path ($SchemaFolder))) { + $null = New-Item -Path $SchemaFolder -ItemType Directory -Force + } + + $SchemaContent + | yayaml\ConvertFrom-Yaml + | ConvertTo-Json -Depth 99 + | ForEach-Object { $_ -replace '\r\n', "`n" } + | Out-File -FilePath ($SchemaPath -replace '\.yaml$', '.json') -Force + } + + $RegistryParameters = @{ + SchemaDirectories = @( + "$OutputDirectory/config" + "$OutputDirectory/definitions" + "$OutputDirectory/outputs" + "$OutputDirectory/resource" + ) + SchemaHost = $Config.host + SchemaPrefix = $Config.prefix + SchemaVersion = $Config.version + WithoutExamples = $true + WithoutComments = $true + } + $SchemaRegistry = Get-LocalJsonSchemaRegistry @RegistryParameters + + $SchemaRegistry + + $Bundles = $Config.bundle_schemas | ForEach-Object -Process { + [hashtable]$Bundle = $_ + $Bundle.ConfigFilePath = "$OutputDirectory/$($Bundle.ConfigFilePath)" + $Bundle + } + + if ($Bundles.Count -eq 0) { + $Bundles = @( + { ConfigFilePath = "$OutputDirectory/config/document.json" } + { ConfigFilePath = "$OutputDirectory/resource/manifest.json" } + ) + } + + foreach ($BundleToExport in $Bundles) { + if ($null -eq $BundleToExport.OutputDirectory) { + $BundleToExport.OutputDirectory = "$OutputDirectory/bundled" + } else { + $BundleToExport.OutputDirectory = "$OutputDirectory/$($BundleToExport.OutputDirectory)" + } + if ($null -eq $BundleToExport.OutputFormat) { + $BundleToExport.OutputFormat = $OutputFormat + } + Write-Verbose "Exporting: $($BundleToExport | ConvertTo-Json)" + Export-MergedJsonSchema @BundleToExport -SchemaRegistry $SchemaRegistry -ErrorAction Stop + } +} + +end { + +} diff --git a/schemas/examples/foo.dsc.resource.json b/schemas/examples/foo.dsc.resource.json new file mode 100644 index 000000000..e0a2361c3 --- /dev/null +++ b/schemas/examples/foo.dsc.resource.json @@ -0,0 +1,40 @@ +{ + "$schema": "../2023/08/bundled/resource.manifest.vscode.json", + "type": "Example/Resource", + "description": "An example resource using the schema.", + "version": "0.1.0", + "tags": [ + "Example" + ], + "manifestVersion": "1.0.0", + "get": { + "executable": "foo", + "args": [ + "get" + ], + "input": "stdin" + }, + "set": { + "executable": "foo", + "args": [ + "set" + ], + "input": "stdin", + "preTest": false, + "return": "state" + }, + "schema": { + "embedded": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "bar": { + "type": "string" + }, + "baz": { + "type": "integer" + } + } + } + } +} diff --git a/schemas/examples/foo.dsc.resource.yaml b/schemas/examples/foo.dsc.resource.yaml new file mode 100644 index 000000000..1c35b9225 --- /dev/null +++ b/schemas/examples/foo.dsc.resource.yaml @@ -0,0 +1,20 @@ +# For testing outside of the repository, set the schema in the yaml server directive to: +# https://raw.githubusercontent.com/PowerShell/DSC/main/2023/08/resource/manifest.json +# +# yaml-language-server: $schema=../2023/08/bundled/resource.manifest.vscode.json +manifestVersion: 1.0.0 +type: Example/Foo +version: 0.1.0 +description: An example resource to manage the foo application. +tags: + - foo +get: + executable: foo + args: + - get + input: stdin +set: + executable: foo + input: stdin + preTest: false + return: state diff --git a/schemas/schemas.config.yaml b/schemas/schemas.config.yaml new file mode 100644 index 000000000..6b8404117 --- /dev/null +++ b/schemas/schemas.config.yaml @@ -0,0 +1,61 @@ +host: https://raw.githubusercontent.com +prefix: PowerShell/DSC/main/schemas +version: 2023/08 +bundle_schemas: + # Resource manifest bundle + - ConfigFilePath: resource/manifest.json + Name: manifest + OutputDirectory: bundled/resource + OutputFormat: ['Json', 'JsonVSCode'] + + # Configuration document bundle + - ConfigFilePath: config/document.json + Name: document + OutputDirectory: bundled/config + OutputFormat: ['Json', 'JsonVSCode'] + + # Output schema bundles + - ConfigFilePath: outputs/schema.json + Name: schema + OutputDirectory: bundled/outputs + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/config/get.json + Name: get + OutputDirectory: bundled/outputs/config + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/config/set.json + Name: set + OutputDirectory: bundled/outputs/config + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/config/test.json + Name: test + OutputDirectory: bundled/outputs/config + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/resource/get.json + Name: get + OutputDirectory: bundled/outputs/resource + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/resource/list.json + Name: list + OutputDirectory: bundled/outputs/resource + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/resource/schema.json + Name: schema + OutputDirectory: bundled/outputs/resource + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/resource/set.json + Name: set + OutputDirectory: bundled/outputs/resource + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/resource/test.json + Name: test + OutputDirectory: bundled/outputs/resource + OutputFormat: ['Json'] diff --git a/schemas/src/config/document.parameter.yaml b/schemas/src/config/document.parameter.yaml new file mode 100644 index 000000000..892edaa62 --- /dev/null +++ b/schemas/src/config/document.parameter.yaml @@ -0,0 +1,78 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///config/document.parameter.yaml +title: Parameter +description: Defines a runtime option for a DSC Configuration Document. + +type: object +required: + - type +properties: + type: + $ref: ///definitions/parameters/dataTypes.yaml + defaultValue: + title: Default value + description: >- + Defines the default value for the parameter. + $ref: ///definitions/parameters/validValueTypes.yaml + allowedValues: + title: Allowed values + description: >- + Defines a list of valid values for the parameter. If the + parameter is defined with any other values, it's invalid. + type: array + items: + $ref: ///definitions/parameters/validValueTypes.yaml + description: + title: Parameter description + description: >- + Defines a synopsis for the parameter explaining its purpose. + type: string + metadata: + title: Parameter metadata + description: >- + Defines a set of key-value pairs for the parameter. This metadata + isn't validated. + type: object +allOf: + - if: + properties: + type: + const: int + then: + minValue: + title: Minimum value + description: >- + The minimum valid value for an integer type. If defined with the + `maxValue` property, this value must be less than the value of + `maxValue`. + type: integer + maxValue: + title: Maximum value + description: >- + The maximum valid value for an integer type. If defined with the + `minValue` property, this value must be greater than the value of + `minValue`. + type: integer + - if: + oneOf: + - properties: { type: { const: string } } + - properties: { type: { const: securestring } } + - properties: { type: { const: array } } + then: + minLength: + title: Minimum length + description: >- + The minimum valid length for a `string`, `securestring`, or `array`. If + defined with the `maxLength` property, this value must be less than the + value of `maxLength`. + type: integer + minimum: 0 + maxLength: + title: Maximum length + description: >- + The maximum valid length for a `string`, `securestring`, or `array`. If + defined with the `minLength` property, this value must be less than the + value of `minLength`. + type: integer + minimum: 0 diff --git a/schemas/src/config/document.resource.yaml b/schemas/src/config/document.resource.yaml new file mode 100644 index 000000000..f2eb57c93 --- /dev/null +++ b/schemas/src/config/document.resource.yaml @@ -0,0 +1,32 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///config/document.resource.yaml + +title: DSC Resource instance +type: object +required: + - type + - name +properties: + type: + $ref: ///definitions/resourceType.yaml + name: + $ref: ///definitions/instanceName.yaml + dependsOn: + title: Instance depends on + description: >- + Defines a list of DSC Resource instances that DSC must successfully + process before processing this instance. Each value for this property + must be the value of another DSC Resource instance's `name` property. + type: array + items: + type: string + uniqueItems: true + pattern: ^\[\w+(\.\w+){0,2}\/\w+\].+$ + properties: + title: Managed instance properties + description: >- + Defines the properties of the DSC Resource this instance manages. This + property's value must be an object. DSC validates the property's value + against the DSC Resource's schema. + type: object diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml new file mode 100644 index 000000000..21cb2e613 --- /dev/null +++ b/schemas/src/config/document.yaml @@ -0,0 +1,56 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///config/document.yaml + +title: DSC Configuration Document schema +description: >- + Describes a valid DSC Configuration Document. + +type: object +required: + - $schema + - resources +properties: + $schema: + title: Schema + description: >- + This property must be the canonical URL of the DSC Configuration Document + schema that the document is implemented for. + type: string + format: uri + enum: + - ///config/document.yaml + + parameters: + title: DSC Configuration document parameters + description: >- + Defines runtime options for the configuration. Users and integrating tools + can override use the defined parameters to pass alternate values to the + configuration. + type: object + additionalProperties: + $ref: ///config/document.parameter.yaml + + variables: + title: Configuration variables + description: >- + Defines a set of reusable values for the configuration document. The + names of this value's properties are the strings used to reference a + variable's value. + type: object + + resources: + title: DSC Configuration document resources + description: >- + Defines a list of DSC Resource instances for the configuration to manage. + type: array + minItems: 1 + items: + $ref: ///config/document.resource.yaml + + metadata: + title: Configuration metadata + description: >- + Defines a set of key-value pairs for the configuration. This metadata + isn't validated. + type: object diff --git a/schemas/src/definitions/commandArgs.yaml b/schemas/src/definitions/commandArgs.yaml new file mode 100644 index 000000000..815f746ab --- /dev/null +++ b/schemas/src/definitions/commandArgs.yaml @@ -0,0 +1,10 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/commandArgs.yaml + +title: Executable Command Arguments +description: >- + The list of arguments to pass to the command. +type: array +items: + type: string diff --git a/schemas/src/definitions/commandExecutable.yaml b/schemas/src/definitions/commandExecutable.yaml new file mode 100644 index 000000000..18f8c3b69 --- /dev/null +++ b/schemas/src/definitions/commandExecutable.yaml @@ -0,0 +1,8 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/commandExecutable.yaml + +title: Executable Command Name +description: >- + The name of the command to run. +type: string diff --git a/schemas/src/definitions/hadErrors.yaml b/schemas/src/definitions/hadErrors.yaml new file mode 100644 index 000000000..f5ab2b407 --- /dev/null +++ b/schemas/src/definitions/hadErrors.yaml @@ -0,0 +1,8 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/hadErrors.yaml + +title: Had Errors +description: >- + Indicates whether any of the DSC Resources returned a non-zero exit code. +type: boolean \ No newline at end of file diff --git a/schemas/src/definitions/inputKind.yaml b/schemas/src/definitions/inputKind.yaml new file mode 100644 index 000000000..f907d2160 --- /dev/null +++ b/schemas/src/definitions/inputKind.yaml @@ -0,0 +1,13 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/inputKind.yaml + +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 diff --git a/schemas/src/definitions/instanceName.yaml b/schemas/src/definitions/instanceName.yaml new file mode 100644 index 000000000..82710e233 --- /dev/null +++ b/schemas/src/definitions/instanceName.yaml @@ -0,0 +1,9 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/instanceName.yaml + +title: Instance name +description: >- + The short, human-readable name for a DSC Resource instance. Must be unique + within a DSC Configuration document. +type: string diff --git a/schemas/src/definitions/message.yaml b/schemas/src/definitions/message.yaml new file mode 100644 index 000000000..249bbc26f --- /dev/null +++ b/schemas/src/definitions/message.yaml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/message.yaml + +title: Message +description: >- + A message emitted by a DSC Resource with associated metadata. + +type: object +required: + - name + - type + - message + - level +properties: + name: + title: Message source instance name + description: >- + The short, human-readable name for the instance that emitted the message, + as defined in the DSC Configuration Document. + type: string + type: + $ref: ///definitions/resourceType.yaml + message: + title: Message content + description: >- + The actual content of the message as emitted by the DSC Resource. + type: string + minLength: 1 + level: + title: Message level + description: >- + Indicates the severity of the message. + type: string + enum: + - Error + - Warning + - Information diff --git a/schemas/src/definitions/messages.yaml b/schemas/src/definitions/messages.yaml new file mode 100644 index 000000000..24663794f --- /dev/null +++ b/schemas/src/definitions/messages.yaml @@ -0,0 +1,12 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/messages.yaml + +title: Messages +description: >- + A list of structured messages emitted by the DSC Resources during an + operation. + +type: array +items: + $ref: ///definitions/message.yaml diff --git a/schemas/src/definitions/parameters/dataTypes.yaml b/schemas/src/definitions/parameters/dataTypes.yaml new file mode 100644 index 000000000..0f8715a5a --- /dev/null +++ b/schemas/src/definitions/parameters/dataTypes.yaml @@ -0,0 +1,16 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/parameters/dataTypes.yaml + +title: Data Types +description: >- + Defines the data type for the value. +type: string +enum: + - string + - securestring + - int + - bool + - object + - secureobject + - array diff --git a/schemas/src/definitions/parameters/validValueTypes.yaml b/schemas/src/definitions/parameters/validValueTypes.yaml new file mode 100644 index 000000000..d6419fdef --- /dev/null +++ b/schemas/src/definitions/parameters/validValueTypes.yaml @@ -0,0 +1,16 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/parameters/validValueTypes.yaml + +$comment: | + This schema fragment makes it a little easier to compose the valid properties + for DSC Configuration document parameters. As-written, values must be one of + those on this list - the schema definition for dataType excludes `null` and + numbers with fractional parts, like `3.5`. + +type: + - string + - integer + - object + - array + - boolean \ No newline at end of file diff --git a/schemas/src/definitions/resourceType.yaml b/schemas/src/definitions/resourceType.yaml new file mode 100644 index 000000000..cd6fdc0f6 --- /dev/null +++ b/schemas/src/definitions/resourceType.yaml @@ -0,0 +1,17 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/resourceType.yaml + +title: DSC Resource fully qualified type name +description: | + The namespaced name of the DSC Resource, using the syntax: + + owner[.group][.area]/name + + For example: + + - Microsoft.SqlServer/Database + - Microsoft.SqlServer.Database/User + +type: string +pattern: ^\w+(\.\w+){0,2}\/\w+$ diff --git a/schemas/src/definitions/returnKind.yaml b/schemas/src/definitions/returnKind.yaml new file mode 100644 index 000000000..30085de24 --- /dev/null +++ b/schemas/src/definitions/returnKind.yaml @@ -0,0 +1,16 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/returnKind.yaml + +title: Return Kind +type: string +enum: + - state + - stateAndDiff +default: state + +$comment: |- + While the enumeration for return kind is the same for the `set` and `test` + method, the way it changes the behavior of the command isn't. The description + keyword isn't included here because the respective schemas for those methods + document the behavior themselves. diff --git a/schemas/src/definitions/semver.yaml b/schemas/src/definitions/semver.yaml new file mode 100644 index 000000000..36ad62280 --- /dev/null +++ b/schemas/src/definitions/semver.yaml @@ -0,0 +1,31 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/semver.yaml + +type: string +title: Semantic Version +description: >- + A valid semantic version (semver) string. For reference, see https://semver.org/ +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 comes 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/schemas/src/outputs/config/get.yaml b/schemas/src/outputs/config/get.yaml new file mode 100644 index 000000000..491d0b785 --- /dev/null +++ b/schemas/src/outputs/config/get.yaml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/config/get.yaml + +title: DSC Configuration get command result +description: >- + Represents the data structure returned by the `dsc config get` command. + +type: object +required: + - results + - messages + - hadErrors +properties: + results: + title: Results + description: >- + The results of the `get` method for every DSC Resource instance in the + DSC Configuration Document with the instance's name and type. + type: array + items: + title: Get Result + type: object + required: + - name + - type + - result + properties: + name: + $ref: ///definitions/instanceName.yaml + type: + $ref: ///definitions/resourceType.yaml + result: + $ref: ///results/resource/get.yaml + messages: + $ref: ///definitions/messages.yaml + hadErrors: + $ref: ///definitions/hadErrors.yaml diff --git a/schemas/src/outputs/config/set.yaml b/schemas/src/outputs/config/set.yaml new file mode 100644 index 000000000..d6e97abea --- /dev/null +++ b/schemas/src/outputs/config/set.yaml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/config/set.yaml + +title: DSC Configuration set command result +description: >- + Represents the data structure returned by the `dsc config set` command. + +type: object +required: + - results + - messages + - hadErrors +properties: + results: + title: Results + description: >- + The results of the `set` method for every DSC Resource instance in the + DSC Configuration Document with the instance's name and type. + type: array + items: + title: Set Result + type: object + required: + - name + - type + - result + properties: + name: + $ref: ///definitions/instanceName.yaml + type: + $ref: ///definitions/resourceType.yaml + result: + $ref: ///results/resource/set.yaml + messages: + $ref: ///definitions/messages.yaml + hadErrors: + $ref: ///definitions/hadErrors.yaml diff --git a/schemas/src/outputs/config/test.yaml b/schemas/src/outputs/config/test.yaml new file mode 100644 index 000000000..ba79b7402 --- /dev/null +++ b/schemas/src/outputs/config/test.yaml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/config/test.yaml + +title: DSC Configuration test command result +description: >- + Represents the data structure returned by the `dsc config test` command. + +type: object +required: + - results + - messages + - hadErrors +properties: + results: + title: Results + description: >- + The results of the `test` method for every DSC Resource instance in the + DSC Configuration Document with the instance's name and type. + type: array + items: + title: Test Result + type: object + required: + - name + - type + - result + properties: + name: + $ref: ///definitions/instanceName.yaml + type: + $ref: ///definitions/resourceType.yaml + result: + $ref: ///results/resource/test.yaml + messages: + $ref: ///definitions/messages.yaml + hadErrors: + $ref: ///definitions/hadErrors.yaml diff --git a/schemas/src/outputs/resource/get.yaml b/schemas/src/outputs/resource/get.yaml new file mode 100644 index 000000000..831043855 --- /dev/null +++ b/schemas/src/outputs/resource/get.yaml @@ -0,0 +1,20 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/resource/get.yaml + +title: dsc resource get result +description: >- + Describes the return data for a DSC Resource instance from the + `dsc resource get` command. + +type: object +required: + - actualState +properties: + actualState: + title: Actual state + description: >- + This property always represents the current state of the DSC Resource + instance as returned by its `get` method. DSC validates this return value + against the DSC Resource's schema. + type: object diff --git a/schemas/src/outputs/resource/list.yaml b/schemas/src/outputs/resource/list.yaml new file mode 100644 index 000000000..f6a09bc9d --- /dev/null +++ b/schemas/src/outputs/resource/list.yaml @@ -0,0 +1,93 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/resource/list.yaml + +title: dsc resource list result +description: >- + Describes the return data for a DSC Resource instance from the + `dsc resource list` command. + +type: object +properties: + type: + # Even though I used the defined type here, I noticed that the Test* + # resources don't follow that pattern - their type name is just a name, + # no prefix. Should we have a different schema for those, or should this + # be relaxed? + $ref: ///definitions/resourceType.yaml + version: + # Only the Test* resources seem to have this field populated. + $ref: ///definitions/semver.yaml + description: + title: Resource Description + description: >- + A short synopsis of the DSC Resource's purpose. + # Should this include a maximum length or a pattern that forbids newlines? + type: string + path: + # This value seems to mean something different for the Test* resources + title: Path + description: >- + Indicates the path to the DSC Resource on the file system. + type: string + directory: + # This value seems to mean something different for the Test* resources + title: Directory + description: >- + Indicates the path to the folder containing the DSC Resource on the file + system. + type: string + implementedAs: + title: Implemented as + description: >- + Indicates how the DSC Resource was implemented. + oneOf: + - title: Standard implementation + description: >- + Indicates that the DSC Resource is implemented as one of the standard + implementations built into DSC. + type: string + enum: + - Command + + # Need to understand how this works to document it more usefully + - title: Custom implementation + description: >- + Indicates that the DSC Resource uses a custom implementation. + type: object + required: + - custom + properties: + custom: + title: Custom implementation name + description: >- + The name of the custom implementation. + type: string + author: + # Only the Test* resources seem to have this field populated. + title: Author + description: >- + Indicates the name of the person or organization that developed and + maintains the DSC Resource. + type: + - string + - 'null' + properties: + # Only the Test* resources seem to have this field populated. + title: Properties + description: >- + Defines the DSC Resource's property names. + type: array + items: + type: string + pattern: ^\w+$ + requires: + title: Required DSC Resource Provider + description: >- + Defines the fully qualified type name of the DSC Resource Provider the + DSC Resource depends on. + oneOf: + - $ref: ///definitions/resourceType.yaml + - type: 'null' + manifest: + $ref: ///resource/manifest.yaml \ No newline at end of file diff --git a/schemas/src/outputs/resource/schema.yaml b/schemas/src/outputs/resource/schema.yaml new file mode 100644 index 000000000..d010ff516 --- /dev/null +++ b/schemas/src/outputs/resource/schema.yaml @@ -0,0 +1,10 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/resource/schema.yaml + +title: DSC Resource schema result +description: >- + Describes the return data for a DSC Resource from the `dsc resource schema` + command. This command always returns the DSC Resource's JSON schema document. + +type: object diff --git a/schemas/src/outputs/resource/set.yaml b/schemas/src/outputs/resource/set.yaml new file mode 100644 index 000000000..1e4751a90 --- /dev/null +++ b/schemas/src/outputs/resource/set.yaml @@ -0,0 +1,40 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/resource/set.yaml + +title: dsc resource set result +description: >- + Describes the return data for a DSC Resource instance from the + `dsc resource set` command. + +type: object +required: + - beforeState + - afterState + - changedProperties +properties: + beforeState: + title: State before enforcing + description: >- + This property always represents the desired state of the DSC Resource + instance before the `set` method runs. DSC validates this return value + against the DSC Resource's schema. + type: object + afterState: + title: State after enforcing + description: >- + This property always represents the current state of the DSC Resource + instance as returned by its `set` method after enforcing the desired + state. DSC validates this return value against the DSC Resource's schema. + type: object + changedProperties: + title: Changed properties + description: >- + This property always represents the list of property names for the DSC + Resource instance that the `set` method modified. When this value is an + empty array, the `set` method didn't enforce any properties for the + instance. + type: array + default: [] + items: + type: string diff --git a/schemas/src/outputs/resource/test.yaml b/schemas/src/outputs/resource/test.yaml new file mode 100644 index 000000000..de0cb5503 --- /dev/null +++ b/schemas/src/outputs/resource/test.yaml @@ -0,0 +1,45 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/resource/test.yaml + +title: dsc resource test result +description: >- + Describes the return data for a DSC Resource instance from the + `dsc resource test` command. + +type: object +required: + - desiredState + - actualState + - inDesiredState + - differingProperties +properties: + desiredState: + title: Desired state + description: >- + This property always represents the desired state of the DSC Resource + instance as specified to DSC. + type: object + actualState: + title: Actual state + description: >- + This property always represents the current state of the DSC Resource + instance as returned by its `test` method or, if the DSC Resource doesn't + define the `test` method, by its `get` method. DSC validates this return + value against the DSC Resource's schema. + type: object + inDesiredState: + title: Instance is in the desired state + description: >- + This property indicates whether the instance is in the desired state. + type: boolean + differingProperties: + title: Differing properties + description: >- + This property always represents the list of property names for the DSC + Resource instance that aren't in the desired state. When this property + is an empty array, the instance is in the desired state. + type: array + default: [] + items: + type: string diff --git a/schemas/src/outputs/schema.yaml b/schemas/src/outputs/schema.yaml new file mode 100644 index 000000000..dd4d9a8ef --- /dev/null +++ b/schemas/src/outputs/schema.yaml @@ -0,0 +1,10 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///outputs/schema.yaml + +title: DSC Resource schema result +description: >- + Describes the return data for a DSC Resource from the `dsc schema` + command. This command always returns a JSON schema document. + +type: object diff --git a/schemas/src/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml new file mode 100644 index 000000000..fd10844cf --- /dev/null +++ b/schemas/src/resource/manifest.get.yaml @@ -0,0 +1,27 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/manifest.get.yaml + +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: ///definitions/commandExecutable.yaml + args: + $ref: ///definitions/commandArgs.yaml + input: + $ref: ///definitions/inputKind.yaml + +examples: + - executable: registry + args: + - config + - get + input: stdin + - executable: osinfo \ No newline at end of file diff --git a/schemas/src/resource/manifest.provider.yaml b/schemas/src/resource/manifest.provider.yaml new file mode 100644 index 000000000..a79b96acf --- /dev/null +++ b/schemas/src/resource/manifest.provider.yaml @@ -0,0 +1,49 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/manifest.provider.yaml + +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: ///definitions/commandExecutable.yaml + args: + $ref: ///definitions/commandArgs.yaml + 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 diff --git a/schemas/src/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml new file mode 100644 index 000000000..76b4144e6 --- /dev/null +++ b/schemas/src/resource/manifest.schema.yaml @@ -0,0 +1,154 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/manifest.schema.yaml + +title: Instance Schema +description: >- + Defines how DSC must validate a JSON blob representing an instance of the + DSC Resource. + +# 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. +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: ///definitions/commandExecutable.yaml + args: + $ref: ///definitions/commandArgs.yaml + 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 + required: + - $schema + - type + - properties + properties: + type: + title: Instance Type + description: >- + Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always + have the `object` type. + # Ensures the DSC Resource is always an object + const: object + $schema: + # Ensures the DSC Resource always uses a schema we can understand + title: DSC Resource instance schema dialect + description: >- + Defines which dialect of JSON Schema the DSC Resource is using to validate instances. + type: string + format: uri-reference + enum: + - https://json-schema.org/draft/2020-12/schema + - https://json-schema.org/draft/2019-09/schema + - http://json-schema.org/draft-07/schema# + $id: + title: DSC Resource instance schema ID + description: >- + Defines the unique ID for the DSC Resource's instance schema. + # Currently optional - maybe we should require this? + type: string + format: uri-reference + properties: + # Defines the property validation - requires authors to specify at + # least one property, ensures all unevaluated properties are of a kind + # we can understand, and makes the standard properties available to + # manifest authors. + title: Instance Properties + description: >- + Defines the schema for the DSC Resource's properties. Must define at least one property. + type: object + minProperties: 1 + unevaluatedProperties: + anyOf: + - $ref: https://json-schema.org/draft/2020-12/schema + - $ref: https://json-schema.org/draft/2019-09/schema + - $ref: http://json-schema.org/draft-07/schema# + properties: + _ensure: + title: 'Standard Property: _ensure' + description: >- + Indicates that the DSC Resource uses the standard `_ensure` property to specify + whether an instance should exist with the `Present` and `Absent` enums. + const: + $ref: ///resource/properties/ensure.yaml + _inDesiredState: + title: 'Standard Property: _inDesiredState' + description: >- + Indicates that the DSC Resource returns this value for it's own `test` method. This + property is mandatory when the manifest defines the `test` property. It shouldn't + be included if the DSC Resource relies on DSC's synthetic testing. + const: + $ref: ///resource/properties/inDesiredState.yaml + _purge: + title: 'Standard Property: _purge' + description: >- + Indicates that the DSC Resource uses the standard `_purge` property to specify + whether the DSC Resource should remove all non-specified members when it manages + an array of members or values. + const: + $ref: ///resource/properties/purge.yaml + _rebootRequested: + title: 'Standard property: _rebootRequested' + description: >- + Indicates that the DSC Resource uses the standard `_rebootRequested` property to + report whether the machine should be rebooted after the `set` method executes. + const: + $ref: ///resource/properties/rebootRequested.yaml + 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] diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml new file mode 100644 index 000000000..f6684d1f1 --- /dev/null +++ b/schemas/src/resource/manifest.set.yaml @@ -0,0 +1,43 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/manifest.set.yaml + +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: ///definitions/commandExecutable.yaml + args: + $ref: ///definitions/commandArgs.yaml + input: + $ref: ///definitions/inputKind.yaml + 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: + 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: ///definitions/returnKind.yaml + +examples: + - executable: registry + args: + - config + - set + input: stdin + preTest: true + return: state diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml new file mode 100644 index 000000000..3796aaed4 --- /dev/null +++ b/schemas/src/resource/manifest.test.yaml @@ -0,0 +1,34 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/manifest.test.yaml + +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: ///definitions/commandExecutable.yaml + args: + $ref: ///definitions/commandArgs.yaml + input: + $ref: ///definitions/inputKind.yaml + 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: ///definitions/returnKind.yaml + +examples: + - executable: registry + args: + - config + - test + input: stdin + return: state diff --git a/schemas/src/resource/manifest.validate.yaml b/schemas/src/resource/manifest.validate.yaml new file mode 100644 index 000000000..34b439700 --- /dev/null +++ b/schemas/src/resource/manifest.validate.yaml @@ -0,0 +1,23 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/manifest.validate.yaml + +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: ///definitions/commandExecutable.yaml + args: + $ref: ///definitions/commandArgs.yaml + +examples: + - executable: dsc + args: + - config + - validate diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml new file mode 100644 index 000000000..a6d80959c --- /dev/null +++ b/schemas/src/resource/manifest.yaml @@ -0,0 +1,84 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///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: ///definitions/semver.yaml + enums: + - '1.0' + type: + $ref: ///definitions/resourceType.yaml + 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: ///definitions/semver.yaml + description: + title: Resource Description + description: >- + A short synopsis of the DSC Resource's purpose. + # Should this include a maximum length or a pattern that forbids newlines? + type: string + tags: + title: Tags + description: >- + An array of short strings used to search for DSC Resources. + type: array + uniqueItems: true + items: + type: string + pattern: ^\w+$ + get: + $ref: ///resource/manifest.get.yaml + set: + $ref: ///resource/manifest.set.yaml + test: + $ref: ///resource/manifest.test.yaml + validate: + $ref: ///resource/manifest.validate.yaml + provider: + # I'm not clear on how this works in practice + $ref: ///resource/manifest.provider.yaml + exitCodes: + # 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? + 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 + schema: + $ref: ///resource/manifest.schema.yaml diff --git a/schemas/src/resource/properties/ensure.yaml b/schemas/src/resource/properties/ensure.yaml new file mode 100644 index 000000000..da9c60fd2 --- /dev/null +++ b/schemas/src/resource/properties/ensure.yaml @@ -0,0 +1,12 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/properties/ensure.yaml + +title: Ensure Existence +description: >- + Indicates whether the DSC Resource instance should exist. + +type: string +enum: + - Absent + - Present \ No newline at end of file diff --git a/schemas/src/resource/properties/inDesiredState.yaml b/schemas/src/resource/properties/inDesiredState.yaml new file mode 100644 index 000000000..ec4d9bf64 --- /dev/null +++ b/schemas/src/resource/properties/inDesiredState.yaml @@ -0,0 +1,13 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/properties/inDesiredState.yaml + +title: Instance is in the Desired State +description: >- + Indicates whether the instance is in the desired state. This property is only + returned by the `test` method. + +type: + - boolean + - 'null' +readOnly: true \ No newline at end of file diff --git a/schemas/src/resource/properties/purge.yaml b/schemas/src/resource/properties/purge.yaml new file mode 100644 index 000000000..db99424b4 --- /dev/null +++ b/schemas/src/resource/properties/purge.yaml @@ -0,0 +1,14 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/properties/purge.yaml + +title: Purge +description: >- + Indicates that only the components described in the DSC Resource should exist. + If other components exist, the DSC Resource is out of the desired state. When + enforcing desired state, the DSC Resource removes unmanaged components. + +type: + - boolean + - 'null' +writeOnly: true diff --git a/schemas/src/resource/properties/rebootRequested.yaml b/schemas/src/resource/properties/rebootRequested.yaml new file mode 100644 index 000000000..013e056d7 --- /dev/null +++ b/schemas/src/resource/properties/rebootRequested.yaml @@ -0,0 +1,12 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/properties/rebootRequested.yaml + +title: Reboot Requested +description: >- + Indicates that the set operation requires a reboot before it's fully complete. + +type: + - boolean + - 'null' +readOnly: true