diff --git a/schemas/2023/08/bundled/config/document.json b/schemas/2023/08/bundled/config/document.json index 836ddc58..0a0b72c2 100644 --- a/schemas/2023/08/bundled/config/document.json +++ b/schemas/2023/08/bundled/config/document.json @@ -14,7 +14,9 @@ "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"] + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] }, "parameters": { "title": "DSC Configuration document parameters", @@ -51,7 +53,9 @@ "title": "Parameter", "description": "Defines a runtime option for a DSC Configuration Document.", "type": "object", - "required": "type", + "required": [ + "type" + ], "properties": { "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" @@ -351,4 +355,4 @@ "minLength": 1 } } -} +} diff --git a/schemas/2023/08/bundled/config/document.vscode.json b/schemas/2023/08/bundled/config/document.vscode.json index a0e57c7f..e844e2b6 100644 --- a/schemas/2023/08/bundled/config/document.vscode.json +++ b/schemas/2023/08/bundled/config/document.vscode.json @@ -3,7 +3,7 @@ "$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.", - "markdownDescription": "> [Online Documentation][01]\n\nDescribes a valid DSC Configuration Document.\n\nDSC Configurations enable users to define state by combining different DSC Resources. A\nconfiguration document uses parameters and variables to pass to a set of one or more resources\nthat define a desired state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDescribes a valid DSC Configuration Document.\n\nDSC Configurations enable users to define state by combining different DSC Resources. A\nconfiguration document uses parameters and variables to pass to a set of one or more resources\nthat define a desired state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "$schema", @@ -18,9 +18,9 @@ "enum": [ "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" ], - "markdownDescription": "> [Online Documentation][01]\n\nThis property must be the canonical URL of the DSC Configuration Document schema that the\ndocument is implemented for.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#schema\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property must be the canonical URL of the DSC Configuration Document schema that the\ndocument is implemented for.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#schema\n", "markdownEnumDescriptions": [ - "Indicates that the configuration document adheres to the `2023/08` schema." + "\n\n> Indicates that the configuration document adheres to the `2023/08` schema.\n" ] }, "parameters": { @@ -30,30 +30,30 @@ "additionalProperties": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines runtime options for the configuration. Users and integrating tools can override use\nthe defined parameters to pass alternate values to the configuration.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#parameters\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines runtime options for the configuration. Users and integrating tools can override use\nthe defined parameters to pass alternate values to the configuration.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#parameters\n", "defaultSnippets": [ { - "label": "New Parameter", - "description": "Defines a new runtime option for the configuration.", + "label": " New Parameter", + "markdownDescription": "Defines a new runtime option for the configuration.\n\n```yaml\nparameterId:\n type: \n description: \n defaultValue: \n allowedValues:\n - \n```", "body": { "${1:parameterId}": { "type": "$2", - "defaultValue": "$3", + "description": "$3", + "defaultValue": "$4", "allowedValues": [ - "$4" - ], - "description": "$5" + "$5" + ] } } }, { - "label": "New Integer Parameter", - "description": "Defines a new runtime option for the configuration as an integer value.", + "label": " New Integer Parameter", + "markdownDescription": "Defines a new runtime option for the configuration as an integer value.\n\n```yaml\nparameterId:\n type: int\n description: \n defaultValue: \n minValue: \n minValue: \n```", "body": { - "${1:integerParameterId}": { + "${1:parameterId}": { "type": "int", - "defaultValue": "$2", - "description": "$3", + "description": "$2", + "defaultValue": "$3", "minValue": "$4", "maxValue": "$5" } @@ -65,18 +65,18 @@ "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", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a set of reusable values for the configuration document. The names of this value's\nproperties are the strings used to reference a variable's value.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#variables\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a set of reusable values for the configuration document. The names of this value's\nproperties are the strings used to reference a variable's value.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#variables\n", "defaultSnippets": [ { - "label": "New variable property", - "description": "Defines a new variable as a key-value pair", + "label": " New variable property", + "markdownDescription": "Defines a new variable as a key-value pair.\n\n```yaml\nvariableName: variableValue\n```", "body": { - "${1:metadataName}": "$2" + "${1:variableName}": "${2:variableValue}" } }, { - "label": "New variable property (object)", - "description": "Defines a new key-value pair for the variables where the value is an object.", + "label": " New variable property (object)", + "markdownDescription": "Defines a new key-value pair for the variables where the value is an object.\n\n```yaml\nvariableName:\n key: value\n```", "body": { "${1:variableName}": { "${2:key}": "${3:value}" @@ -84,8 +84,8 @@ } }, { - "label": "New variable property (array)", - "description": "Defines a new key-value pair for the variables where the value is an array.", + "label": " New variable property (array)", + "markdownDescription": "Defines a new key-value pair for the variables where the value is an array.\n\n```yaml\nvariableName:\n - firstValue\n - secondValue\n```", "body": { "${1:variableName}": [ "${2:firstValue}", @@ -103,24 +103,24 @@ "items": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines a list of DSC Resource instances for the configuration to manage.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#resources\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a list of DSC Resource instances for the configuration to manage.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#resources\n" }, "metadata": { "title": "Configuration metadata", "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", "type": "object", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a set of key-value pairs for the configuration. This metadata isn't validated.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#metadata-1\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a set of key-value pairs for the configuration. This metadata isn't validated.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#metadata-1\n", "defaultSnippets": [ { - "label": "New Metadata Property", - "description": "Defines a key-value pair for the metadata", + "label": " New metadata property", + "markdownDescription": "Defines a key-value pair for the metadata:\n\n```yaml\nmetadataName: value\n```", "body": { - "${1:metadataName}": "$2" + "${1:metadataName}": "${2:value}" } }, { - "label": "New metadata property (object)", - "description": "Defines a new key-value pair for the metadata where the value is an object.", + "label": " New metadata property (object)", + "markdownDescription": "Defines a new key-value pair for the metadata where the value is an object.\n\n```yaml\nmetadataName:\n key: value\n```", "body": { "${1:metadataName}": { "${2:key}": "${3:value}" @@ -128,8 +128,8 @@ } }, { - "label": "New metadata property (array)", - "description": "Defines a new key-value pair for the metadata where the value is an array.", + "label": " New metadata property (array)", + "markdownDescription": "Defines a new key-value pair for the metadata where the value is an array.\n\n```yaml\nmetadataName:\n - firstValue\n - secondValue\n```", "body": { "${1:metadataName}": [ "${2:firstValue}", @@ -153,7 +153,7 @@ "$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.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a runtime option for a DSC Configuration Document.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a runtime option for a DSC Configuration Document.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "type" @@ -166,7 +166,7 @@ "title": "Default value", "description": "Defines the default value for the parameter.", "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the default value for the parameter.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#allowedvalues\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the default value for the parameter.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#allowedvalues\n" }, "allowedValues": { "title": "Allowed values", @@ -175,30 +175,30 @@ "items": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines a list of valid values for the parameter. If the parameter is defined with any other\nvalues, it's invalid.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#allowedvalues\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a list of valid values for the parameter. If the parameter is defined with any other\nvalues, it's invalid.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#allowedvalues\n" }, "description": { "title": "Parameter description", "description": "Defines a synopsis for the parameter explaining its purpose.", "type": "string", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a synopsis for the parameter explaining its purpose.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#description-1\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a synopsis for the parameter explaining its purpose.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#description-1\n" }, "metadata": { "title": "Parameter metadata", "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", "type": "object", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a set of key-value pairs for the parameter. This metadata isn't validated.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#metadata-1\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a set of key-value pairs for the parameter. This metadata isn't validated.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#metadata-1\n", "defaultSnippets": [ { - "label": "New Metadata Property", - "description": "Defines a key-value pair for the metadata", + "label": " New metadata property", + "markdownDescription": "Defines a key-value pair for the metadata:\n\n```yaml\nmetadataName: value\n```", "body": { - "${1:metadataName}": "$2" + "${1:metadataName}": "${2:value}" } }, { - "label": "New metadata property (object)", - "description": "Defines a new key-value pair for the metadata where the value is an object.", + "label": " New metadata property (object)", + "markdownDescription": "Defines a new key-value pair for the metadata where the value is an object.\n\n```yaml\nmetadataName:\n key: value\n```", "body": { "${1:metadataName}": { "${2:key}": "${3:value}" @@ -206,8 +206,8 @@ } }, { - "label": "New metadata property (array)", - "description": "Defines a new key-value pair for the metadata where the value is an array.", + "label": " New metadata property (array)", + "markdownDescription": "Defines a new key-value pair for the metadata where the value is an array.\n\n```yaml\nmetadataName:\n - firstValue\n - secondValue\n```", "body": { "${1:metadataName}": [ "${2:firstValue}", @@ -233,13 +233,13 @@ "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", - "markdownDescription": "> [Online Documentation][01]\n\nThe minimum valid value for an integer type. If defined with the `maxValue` property,\nthis value must be less than the value of `maxValue`.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#minvalue\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe minimum valid value for an integer type. If defined with the `maxValue` property,\nthis value must be less than the value of `maxValue`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#minvalue\n" }, "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", - "markdownDescription": "> [Online Documentation][01]\n\nThe maximum valid value for an integer type. If defined with the `minValue` property,\nthis value must be greater than the value of `minValue`.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#maxvalue\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe maximum valid value for an integer type. If defined with the `minValue` property,\nthis value must be greater than the value of `minValue`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#maxvalue\n" } } } @@ -277,14 +277,14 @@ "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, - "markdownDescription": "> [Online Documentation][01]\n\nThe minimum valid length for a `string`, `securestring`, or `array`. If defined with\nthe `maxLength` property, this value must be less than the value of `maxLength`.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#minLength\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe minimum valid length for a `string`, `securestring`, or `array`. If defined with\nthe `maxLength` property, this value must be less than the value of `maxLength`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#minLength\n" }, "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, - "markdownDescription": "> [Online Documentation][01]\n\nThe maximum valid length for a `string`, `securestring`, or `array`. If defined with\nthe `minLength` property, this value must be less than the value of `minLength`.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#maxLength\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe maximum valid length for a `string`, `securestring`, or `array`. If defined with\nthe `minLength` property, this value must be less than the value of `minLength`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#maxLength\n" } } } @@ -438,37 +438,46 @@ "type": "string", "uniqueItems": true, "pattern": "^\\[resourceId\\(\\s*'\\w+(\\.\\w+){0,2}\\/\\w+'\\s*,\\s*'[a-zA-Z0-9 ]+'\\s*\\)\\]$", - "patternErrorMessage": "Invalid value, must be a value like `[resourceId('', '`)], such as\n`[resourceId('Microsoft/OSInfo', 'Foo')]`.\n\nThe `` and `` should be the fully qualified type of the resource and its\nfriendly name in the configuration.\n" + "patternErrorMessage": "Invalid value, must be a value like `[resourceId('', '`)], such as\n`[resourceId('Microsoft/OSInfo', 'Foo')]`.\n\nThe `` and `` should be the fully qualified type of the resource and its\nfriendly name in the configuration.\n", + "defaultSnippets": [ + { + "label": " New dependency", + "markdownDescription": "Defines a new dependency for the resource instance.\n\n```yaml\n\"[resourceId('dependencyInstance/Type', 'dependencyInstanceName')]\"\n```", + "bodyText": "\"[resourceId('${3:dependencyInstance/Type}', '${4:dependencyInstanceName}')]\"" + } + ] }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines a list of DSC Resource instances that DSC must successfully process before processing\nthis instance. Each value for this property must be the `resourceID()` lookup for another\ninstance in the configuration. Multiple instances can depend on the same instance, but every\ndependency for an instance must be unique in that instance's `dependsOn` property.\n\nThe `resourceID()` function uses this syntax:\n\n```yaml\n\"[resourceId('', '']\"\n```\n\nThe `` value is the `type` property of the dependent resource and\n`` is the dependency's `name` property. When adding a dependency in a\nYAML-format configuration document, always wrap the `resourceID()` lookup in double quotes\n(`\"`).\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#properties-1\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a list of DSC Resource instances that DSC must successfully process before processing\nthis instance. Each value for this property must be the `resourceID()` lookup for another\ninstance in the configuration. Multiple instances can depend on the same instance, but every\ndependency for an instance must be unique in that instance's `dependsOn` property.\n\nThe `resourceID()` function uses this syntax:\n\n```yaml\n\"[resourceId('', '']\"\n```\n\nThe `` value is the `type` property of the dependent resource and\n`` is the dependency's `name` property. When adding a dependency in a\nYAML-format configuration document, always wrap the `resourceID()` lookup in double quotes\n(`\"`).\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true#properties-1\n" }, "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", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the properties of the DSC Resource this instance manages. This property's value must\nbe an object. DSC validates the property's value against the DSC Resource's schema.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#properties-1\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the properties of the DSC Resource this instance manages. This property's value must\nbe an object. DSC validates the property's value against the DSC Resource's schema.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true#properties-1\n" } }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines an instance of a DSC Resource in a configuration.\n\nThe `resources` property of a DSC Configuration document always includes at least one DSC Resource\ninstance. Together, the instances in a configuration define the desired state that DSC can get,\ntest, and set on a machine.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an instance of a DSC Resource in a configuration.\n\nThe `resources` property of a DSC Configuration document always includes at least one DSC Resource\ninstance. Together, the instances in a configuration define the desired state that DSC can get,\ntest, and set on a machine.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true\n", "defaultSnippets": [ { - "label": "New resource instance", - "description": "Defines a new instance of a DSC Resource for the configuration", + "label": " New resource instance", + "markdownDescription": "Defines a new instance of a DSC Resource for the configuration.\n\n```yaml\ntype: owner[.group][.area]/name\nname: instance_name\nproperties:\n propertyName: propertyValue\n```", "body": { - "type": "$1", - "name": "$2", + "type": "${1:owner[.group][.area]/name}", + "name": "${2:instance_name}", "properties": { "${3:propertyName}": "${4:propertyValue}" } } }, { - "label": "New dependent resource instance", - "description": "Defines a new instance of a DSC Resource for the configuration that depends on another instance.", + "label": " New dependent resource instance", + "markdownDescription": "Defines a new instance of a DSC Resource for the configuration that depends on another\ninstance.\n\n```yaml\ntype: owner[.group][.area]/name\nname: instance_name\ndependsOn:\n - \"[resourceId('dependencyInstance/Type', 'dependencyInstanceName')]\"\nproperties:\n propertyName: propertyValue\n```", "body": { - "type": "$1", - "name": "$2", - "dependsOn": "['[${3:dependencyType}]${4:dependencyName}']", + "type": "${1:owner[.group][.area]/name}", + "name": "${2:instance_name}", + "dependsOn": [ + "\"[resourceId('${3:dependencyInstance/Type}', '${4:dependencyInstanceName}')]\"" + ], "properties": { "${5:propertyName}": "${6:propertyValue}" } @@ -494,15 +503,15 @@ "secureobject", "array" ], - "markdownDescription": "> [Online Documentation][01]\n\nDefines the data type for the parameter value.\n\nThe valid data types for a parameter are:\n\n- `array` for arrays\n- `bool` for booleans\n- `int` for integers\n- `object` for objects\n- `string` for strings\n- `secureobject` for secure objects\n- `securestring` for secure strings\n\nAccess parameters in a configuration using this syntax:\n\n```yaml\n\"[parameter('')]\"\n```\n\nIn YAML, the parameter syntax needs to be enclosed in double-quotes when used as an inline value.\nIf the syntax isn't quoted, YAML interprets the syntax as an array.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the data type for the parameter value.\n\nThe valid data types for a parameter are:\n\n- `array` for arrays\n- `bool` for booleans\n- `int` for integers\n- `object` for objects\n- `string` for strings\n- `secureobject` for secure objects\n- `securestring` for secure strings\n\nAccess parameters in a configuration using this syntax:\n\n```yaml\n\"[parameter('')]\"\n```\n\nIn YAML, the parameter syntax needs to be enclosed in double-quotes when used as an inline value.\nIf the syntax isn't quoted, YAML interprets the syntax as an array.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true\n", "markdownEnumDescriptions": [ - "> [Online Documentation][01]\n\nStrings are an arbitrary set of text.\n\nTo define a long strings in YAML, use the folded block syntax or literal block syntax by\nadding a `>` or `|` and a line break after the key. Then, indent the next line. Every line in\nthe string must start at the same level of indentation. You can trim the trailing whitespace\nby using `>-` or `|-` instead.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#strings\n", - "> [Online Documentation][01]\n\nSecure strings are an arbitrary set of text that DSC and integrating tools shouldn't log or\nrecord. If a secure data type parameter is used for a resource instance property that doesn't\nexpect a secure value, the resource may still log or record the value. If the resource has\nindependent logging or recording that isn't handled by DSC, the value may be stored\ninsecurely.\n\nUse secure strings for passwords and secrets. Never define a default value for secure string\nparameters.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#secure-strings-and-objects\n", - "> [Online Documentation][01]\n\nInteger values are numbers without a fractional part. Integer values may be limited by\nintegrating tools or the DSC Resources they're used with. DSC itself supports integer values\nbetween `-9223372036854775808` and `9223372036854775807`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#integers\n", - "> [Online Documentation][01]\n\nBoolean values are either `true` or `false`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#booleans\n", - "> [Online Documentation][01]\n\nObjects define a set of key-value pairs. The value for each key can be any valid data type.\nThe values can be the same type or different types.\n\nAccess keys in the object using dot-notation. Dot-notation uses this syntax:\n\n```yaml\n\"[parameters('').]\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#objects\n", - "> [Online Documentation][01]\n\nSecure objects define a set of key-value pairs that DSC and integrating tools shouldn't log\nor record. If a secure data type parameter is used for a resource instance property that\ndoesn't expect a secure value, the resource may still log or record the value. If the\nresource has independent logging or recording that isn't handled by DSC, the value may be\nstored insecurely.\n\nNever define a default value for secure object parameters.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#secure-strings-and-objects\n", - "> [Online Documentation][01]\n\nArrays are a list of one or more values. The values in the array can be any valid data type.\nValues in the array can be the same type or different types.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#arrays\n" + "_Strings are an arbitrary set of text._\n\n> To define a long strings in YAML, use the folded block syntax or literal block syntax by\n> adding a `>` or `|` and a line break after the key. Then, indent the next line. Every line\n> in the string must start at the same level of indentation. You can trim the trailing\n> whitespace by using `>-` or `|-` instead.\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#strings\n", + "_Secure strings are text that needs to be handled securely._\n\n> Secure strings are an arbitrary set of text that DSC and integrating tools shouldn't log or\n> record. If a secure data type parameter is used for a resource instance property that doesn't\n> expect a secure value, the resource may still log or record the value. If the resource has\n> independent logging or recording that isn't handled by DSC, the value may be stored\n> insecurely.\n>\n> Use secure strings for passwords and secrets. Never define a default value for secure string\n> parameters.\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#secure-strings-and-objects\n", + "_Integer values are numbers without a fractional part._\n\n> Integer values may be limited by integrating tools or the DSC Resources they're used with.\n> DSC itself supports integer values between `-9223372036854775808` and `9223372036854775807`.\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#integers\n", + "_Boolean values are either `true` or `false`._\n\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#booleans\n", + "_Objects define a set of key-value pairs._\n\n> The value for each key can be any valid data type. The values can be the same type or\n> different types.\n>\n> Access keys in the object using dot-notation. Dot-notation uses this syntax:\n>\n> ```yaml\n> \"[parameters('').]\n> ```\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#objects\n", + "_Secure objects are key-value pairs that need to be handled securely._\n\n> Secure objects define a set of key-value pairs that DSC and integrating tools shouldn't log\n> or record. If a secure data type parameter is used for a resource instance property that\n> doesn't expect a secure value, the resource may still log or record the value. If the\n> resource has independent logging or recording that isn't handled by DSC, the value may be\n> stored insecurely.\n>\n> Never define a default value for secure object parameters.\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#secure-strings-and-objects\n", + "_Arrays are a list of one or more values._\n\n> The values in the array can be any valid data type. Values in the array can be the same type\n> or different types.\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#arrays\n" ] }, "validValueTypes.json": { @@ -525,7 +534,7 @@ "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+$", - "markdownDescription": "> [Online Documentation][01]\n\nThe namespaced name of the DSC Resource, using the syntax:\n\n```text\nowner[.group][.area]/name\n```\n\nFor example:\n\n- `Microsoft.SqlServer/Database`\n- `Microsoft.SqlServer.Database/User`\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe namespaced name of the DSC Resource, using the syntax:\n\n```yaml\nowner[.group][.area]/name\n```\n\nFor example:\n\n- `Microsoft.SqlServer/Database`\n- `Microsoft.SqlServer.Database/User`\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserve-view=true\n", "patternErrorMessage": "Invalid type name. Valid resource type names always define an owner and a name separated by a\nslash, like `Microsoft/OSInfo`. Type names may optionally include a group and area to namespace\nthe resource under the owner, like `Microsoft.Windows/Registry`.\n" }, "instanceName.json": { @@ -537,7 +546,7 @@ "pattern": "^[a-zA-Z0-9 ]+$", "minLength": 1, "patternErrorMessage": "Invalid value for instance name. An instance name must be a non-empty string containing only\nletters, numbers, and spaces.\n", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the short, human-readable name for a DSC Resource instance. This property must be unique\nwithin a DSC Configuration document. If any resource instances share the same name, DSC raises an\nerror.\n\nThe instance name must be a non-empty string containing only letters, numbers, and spaces.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#name\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the short, human-readable name for a DSC Resource instance. This property must be unique\nwithin a DSC Configuration document. If any resource instances share the same name, DSC raises an\nerror.\n\nThe instance name must be a non-empty string containing only letters, numbers, and spaces.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true#name\n" } } } diff --git a/schemas/2023/08/bundled/outputs/config/get.json b/schemas/2023/08/bundled/outputs/config/get.json index 673aa7f0..6ddd148a 100644 --- a/schemas/2023/08/bundled/outputs/config/get.json +++ b/schemas/2023/08/bundled/outputs/config/get.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/get.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json" } } } @@ -60,6 +60,23 @@ "type": "string", "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json": { + "$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" + } + } + }, "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", diff --git a/schemas/2023/08/bundled/outputs/config/set.json b/schemas/2023/08/bundled/outputs/config/set.json index 2cf07b03..7df29415 100644 --- a/schemas/2023/08/bundled/outputs/config/set.json +++ b/schemas/2023/08/bundled/outputs/config/set.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/set.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json" } } } @@ -60,6 +60,39 @@ "type": "string", "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json": { + "$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" + } + } + } + }, "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", diff --git a/schemas/2023/08/bundled/outputs/config/test.json b/schemas/2023/08/bundled/outputs/config/test.json index 372c8bd9..91f98d6b 100644 --- a/schemas/2023/08/bundled/outputs/config/test.json +++ b/schemas/2023/08/bundled/outputs/config/test.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/test.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json" } } } @@ -60,6 +60,45 @@ "type": "string", "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json": { + "$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" + } + } + } + }, "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", diff --git a/schemas/2023/08/bundled/outputs/resource/get.json b/schemas/2023/08/bundled/outputs/resource/get.json index f1b85eb6..8ed6684d 100644 --- a/schemas/2023/08/bundled/outputs/resource/get.json +++ b/schemas/2023/08/bundled/outputs/resource/get.json @@ -4,7 +4,9 @@ "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", + "required": [ + "actualState" + ], "properties": { "actualState": { "title": "Actual state", diff --git a/schemas/2023/08/bundled/outputs/resource/list.json b/schemas/2023/08/bundled/outputs/resource/list.json index 85e977b7..5b5f4acd 100644 --- a/schemas/2023/08/bundled/outputs/resource/list.json +++ b/schemas/2023/08/bundled/outputs/resource/list.json @@ -34,13 +34,17 @@ "title": "Standard implementation", "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", "type": "string", - "enum": "Command" + "enum": [ + "Command" + ] }, { "title": "Custom implementation", "description": "Indicates that the DSC Resource uses a custom implementation.", "type": "object", - "required": "custom", + "required": [ + "custom" + ], "properties": { "custom": { "title": "Custom implementation name", @@ -99,7 +103,8 @@ "type": "string", "title": "Semantic Version", "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", - "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-]+)*))?$" + "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": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\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\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -108,17 +113,20 @@ "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.", "type": "object", "required": [ - "manifestVersion", + "$schema", "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" + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json" + ] }, "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" @@ -178,13 +186,15 @@ "0": "Success", "1": "Error" }, - "examples": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } + "examples": [ + { + "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" @@ -197,7 +207,9 @@ "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -229,7 +241,9 @@ "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -270,16 +284,18 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "set" - ], - "input": "stdin", - "implementsPretest": true, - "return": "state" - } + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "implementsPretest": true, + "return": "state" + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -307,15 +323,17 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "test" - ], - "input": "stdin", - "return": "state" - } + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -323,7 +341,9 @@ "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", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -332,13 +352,15 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" } }, - "examples": { - "executable": "dsc", - "args": [ - "config", - "validate" - ] - } + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -355,7 +377,9 @@ "title": "List Command", "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -375,19 +399,21 @@ ] } }, - "examples": { - "config": "full", - "list": { - "executable": "pwsh", - "args": [ - "-NoLogo", - "-NonInteractive", - "-NoProfile", - "-Command", - "./powershellgroup.resource.ps1 List" - ] + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } } - } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -397,10 +423,14 @@ "type": "object", "oneOf": [ { - "required": "command" + "required": [ + "command" + ] }, { - "required": "embedded" + "required": [ + "embedded" + ] } ], "properties": { @@ -408,7 +438,9 @@ "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", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -468,6 +500,7 @@ } ] }, + "additionalProperties": {}, "properties": { "_ensure": { "title": "Standard Property: _ensure", @@ -478,7 +511,7 @@ }, "_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.", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This read-only 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" } @@ -492,7 +525,7 @@ }, "_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.", + "description": "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.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" } @@ -512,7 +545,9 @@ { "command": { "executable": "registry", - "args": "schema" + "args": [ + "schema" + ] } }, { @@ -597,13 +632,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.", + "description": "Defines how DSC should pass input to the command, either as environment variables or JSON over stdin. When this value isn't defined, DSC doesn't send the resource any input.", "type": "string", "enum": [ - "args", + "env", "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", @@ -662,4 +696,4 @@ "readOnly": true } } -} +} diff --git a/schemas/2023/08/bundled/resource/manifest.json b/schemas/2023/08/bundled/resource/manifest.json index a10db24b..c5d29991 100644 --- a/schemas/2023/08/bundled/resource/manifest.json +++ b/schemas/2023/08/bundled/resource/manifest.json @@ -5,17 +5,20 @@ "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.", "type": "object", "required": [ - "manifestVersion", + "$schema", "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" + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json" + ] }, "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" @@ -75,27 +78,21 @@ "0": "Success", "1": "Error" }, - "examples": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } + "examples": [ + { + "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.\n\nFor reference, see https://semver.org/\n", - "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", @@ -104,13 +101,24 @@ "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.\n\nFor reference, see https://semver.org/\n", + "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": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\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\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" + }, "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", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -142,7 +150,9 @@ "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -183,16 +193,18 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "set" - ], - "input": "stdin", - "implementsPretest": true, - "return": "state" - } + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "implementsPretest": true, + "return": "state" + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -220,15 +232,17 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "test" - ], - "input": "stdin", - "return": "state" - } + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -236,7 +250,9 @@ "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", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -245,13 +261,15 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" } }, - "examples": { - "executable": "dsc", - "args": [ - "config", - "validate" - ] - } + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -268,7 +286,9 @@ "title": "List Command", "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -288,19 +308,21 @@ ] } }, - "examples": { - "config": "full", - "list": { - "executable": "pwsh", - "args": [ - "-NoLogo", - "-NonInteractive", - "-NoProfile", - "-Command", - "./powershellgroup.resource.ps1 List" - ] + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } } - } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -310,10 +332,14 @@ "type": "object", "oneOf": [ { - "required": "command" + "required": [ + "command" + ] }, { - "required": "embedded" + "required": [ + "embedded" + ] } ], "properties": { @@ -321,7 +347,9 @@ "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", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -381,6 +409,7 @@ } ] }, + "additionalProperties": {}, "properties": { "_ensure": { "title": "Standard Property: _ensure", @@ -391,7 +420,7 @@ }, "_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.", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This read-only 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" } @@ -405,7 +434,7 @@ }, "_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.", + "description": "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.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" } @@ -425,7 +454,9 @@ { "command": { "executable": "registry", - "args": "schema" + "args": [ + "schema" + ] } }, { @@ -510,13 +541,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.", + "description": "Defines how DSC should pass input to the command, either as environment variables or JSON over stdin. When this value isn't defined, DSC doesn't send the resource any input.", "type": "string", "enum": [ - "args", + "env", "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", @@ -575,4 +605,4 @@ "readOnly": true } } -} +} diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json index ab0731d2..9fc6ff97 100644 --- a/schemas/2023/08/bundled/resource/manifest.vscode.json +++ b/schemas/2023/08/bundled/resource/manifest.vscode.json @@ -3,25 +3,216 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", "title": "Command-based DSC Resource Manifest", "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the information DSC and integrating require to process and call a command-based DSC\nResource. For DSC to use a manifest on a system, the manifest file must:\n\n1. Be discoverable in the `PATH` environment variable.\n1. Follow the naming convention `.dsc.resource.json`.\n1. Be valid for this schema.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the information DSC and integrating require to process and call a command-based DSC\nResource. For DSC to use a manifest on a system, the manifest file must:\n\n1. Be discoverable in the `PATH` environment variable.\n1. Follow the naming convention `.dsc.resource.json`.\n1. Be valid for this schema.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true\n", + "defaultSnippets": [ + { + "label": " Define a resource", + "markdownDescription": "Defines a standard resource that:\n\n- Can get the current state of an instance\n- Can set an instance to the desired state\n- Relies on DSC's synthetic testing to determine whether an instance is in the desired state\n- Defines an embedded JSON schema.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "set": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "implementsPretest": "^${11:false}", + "return": "${12:state}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "${14:name}": { + "title": "${15:property title}", + "description": "${16:explanation of property purpose and usage}", + "type": "${17|string,integer,number,array,object,null|}" + } + } + } + } + } + }, + { + "label": " Define a resource (group)", + "markdownDescription": "Defines a group resource that expects a list of resource instances and operates on them.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "test": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "return": "${12:state}" + }, + "set": { + "executable": "${13:executable name}", + "args": [ + "${14:argument}" + ], + "input": "${15:stdin}", + "implementsPretest": "^${16:false}", + "return": "${17:state}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${18|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "resources": { + "title": "${19:Resources}", + "description": "${20:Defines a list of resource instances to process}", + "type": "array", + "items": { + "${escape_dollar:$}ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "${21:name}": { + "title": "${22:property title}", + "description": "${23:explanation of property purpose and usage}", + "type": "${24|string,integer,number,array,object,null|}" + } + } + } + } + } + }, + { + "label": " Define a resource (provider)", + "markdownDescription": "Defines a provider resource that enables users to define non-command-based DSC Resources in\nthe configuration.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "test": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "return": "${12:state}" + }, + "set": { + "executable": "${13:executable name}", + "args": [ + "${14:argument}" + ], + "input": "${15:stdin}", + "implementsPretest": "^${16:false}", + "return": "${17:state}" + }, + "provider": { + "config": "${18|full,sequence|}", + "list": { + "executable": "${19:executable name}", + "args": [ + "${20:argument}" + ] + } + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${23|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "resources": { + "title": "${24:Resources}", + "description": "${25:Defines a list of resource instances to process}", + "type": "array", + "items": { + "${escape_dollar:$}ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "${26:name}": { + "title": "${27:property title}", + "description": "${28:explanation of property purpose and usage}", + "type": "${29|string,integer,number,array,object,null|}" + } + } + } + } + } + }, + { + "label": " Define a resource (assertion-only)", + "markdownDescription": "Defines an assertion resource that can get the current state of an instance but not configure\nit. By default, the resource relies on DSC's synthetic testing feature. If the resource\nimplements the `test` operation itself, define the `test` property.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "${14:name}": { + "title": "${15:property title}", + "description": "${16:explanation of property purpose and usage}", + "type": "${17|string,integer,number,array,object,null|}" + } + } + } + } + } + } + ], "type": "object", "required": [ - "manifestVersion", + "$schema", "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" + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json" ], - "markdownDescription": "> [Online Documentation][01]\n\nThe semver of the DSC Resource manifest schema to validate this manifest with.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#manifestversion\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property must be the canonical URL of the Command-based DSC Resource Manifest schema\nthat the manifest is implemented for.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#schema\n", "markdownEnumDescriptions": [ - "> [Online Documentation][01]\n\nThe initial release version of the manifest schema.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true\n" + "_Initial release_\n" ] }, "type": { @@ -31,18 +222,18 @@ "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", - "markdownDescription": "> [Online Documentation][03]\n\nThe semantic version ([semver][01]) of the DSC Resource. This version identifies the DSC\nResource, not the version of the application it manages.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\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\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n[03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#version\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe semantic version ([semver][02]) of the DSC Resource. This version identifies the DSC\nResource, not the version of the application it manages.\n\nThis value uses the [suggested regular expression][03] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\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\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#version\n[02]: https://semver.org/\n[03]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" }, "description": { "title": "Resource Description", "description": "A short synopsis of the DSC Resource's purpose.", "type": "string", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a short synopsis of the DSC Resource's purpose.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#description-1\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a short synopsis of the DSC Resource's purpose.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#description-1\n" }, "tags": { "title": "Tags", "description": "Defines a list of searchable terms for the resource.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a list of searchable terms for the resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#tags\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a list of searchable terms for the resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#tags\n", "type": "array", "uniqueItems": true, "items": { @@ -72,7 +263,6 @@ "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.", - "markdownDescription": "> [Online Documentation][01]\n\nThis property defines a map of valid exit codes for the DSC Resource. DSC always interprets\nexit code `0` as a successful operation and any other exit code as an error. Use this\nproperty to indicate human-readable semantic meanings for the DSC Resource's exit codes.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#exitcodes\n", "type": "object", "propertyNames": { "pattern": "^[0-9]+$", @@ -96,6 +286,18 @@ "3": "Registry error", "4": "JSON serialization failed" } + ], + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property defines a map of valid exit codes for the DSC Resource. DSC always interprets\nexit code `0` as a successful operation and any other exit code as an error. Use this\nproperty to indicate human-readable semantic meanings for the DSC Resource's exit codes.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#exitcodes\n", + "defaultSnippets": [ + { + "label": " Defined exit codes", + "description": "Defines exit codes with semantic meaning for the resource.", + "body": { + "0": "Success", + "${1:first exit code number}": "${2:first exit code meaning}", + "${3:second exit code number}": "${4:second exit code meaning}" + } + } ] }, "schema": { @@ -110,16 +312,6 @@ "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.\n\nFor reference, see https://semver.org/\n", - "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-]+)*))?$", - "markdownDescription": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\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\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n", - "patternErrorMessage": "Invalid value, must be a semantic version like `..`, such as `1.2.3`.\n\nThe value may also include pre-release version information and build metadata.\n" - }, "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", @@ -127,16 +319,25 @@ "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+$", - "markdownDescription": "> [Online Documentation][01]\n\nThe namespaced name of the DSC Resource, using the syntax:\n\n```text\nowner[.group][.area]/name\n```\n\nFor example:\n\n- `Microsoft.SqlServer/Database`\n- `Microsoft.SqlServer.Database/User`\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe namespaced name of the DSC Resource, using the syntax:\n\n```yaml\nowner[.group][.area]/name\n```\n\nFor example:\n\n- `Microsoft.SqlServer/Database`\n- `Microsoft.SqlServer.Database/User`\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserve-view=true\n", "patternErrorMessage": "Invalid type name. Valid resource type names always define an owner and a name separated by a\nslash, like `Microsoft/OSInfo`. Type names may optionally include a group and area to namespace\nthe resource under the owner, like `Microsoft.Windows/Registry`.\n" }, + "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.\n\nFor reference, see https://semver.org/\n", + "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-]+)*))?$", + "patternErrorMessage": "Invalid value, must be a semantic version like `..`, such as `1.2.3`.\n\nThe value may also include pre-release version information and build metadata.\n", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\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\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" + }, "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", - "markdownDescription": "Defines the name of the command to run. The value must be the name of a command discoverable in\nthe system's `PATH` environment variable or the full path to the command. A file extension is\nonly required when the command isn't recognizable by the operating system as an executable.\n" + "type": "string" }, "commandArgs.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -146,24 +347,21 @@ "type": "array", "items": { "type": "string" - }, - "markdownDescription": "Defines an array of strings to pass as arguments to the command. DSC passes the arguments to the\ncommand in the order they're specified.\n" + } }, "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.", + "description": "Defines how DSC should pass input to the command, either as environment variables or JSON over stdin. When this value isn't defined, DSC doesn't send the resource any input.", "type": "string", "enum": [ - "args", + "env", "stdin" ], - "default": "args", - "markdownDescription": "Defines how DSC should pass input to the command, either as arguments or JSON over `stdin`.\n", "markdownEnumDescriptions": [ - "Indicates that the resource expects the properties of an instance to be specified with\ncommand line arguments. This option isn't implemented yet.\n", - "Indicates that the resource expects a JSON blob representing an instance from `stdin`.\n" + "_Environment variables_\n\n> Indicates that the resource expects the properties of an instance to be specified as\n> environment variables with the same names and casing.\n>\n> This option only supports the following data types for instance properties:\n>\n> - `boolean`\n> - `integer`\n> - `number`\n> - `string`\n> - `array` of `integer` values\n> - `array` of `number` values\n> - `array` of `string` values\n>\n> For non-array values, DSC sets the environment variable to the specified value as-is. When\n> the data type is an array of values, DSC sets the environment variable as a comma-delimited\n> string. For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo`\n> environment variable as `\"1,2,3\"`.\n>\n> If the resource needs to support complex properties with an `object` value or multi-type\n> arrays, set this to `stdin` instead.\n", + "_JSON over `stdin`_\n\n> Indicates that the resource expects a JSON blob representing an instance from `stdin`.\n> The JSON must adhere to the instance schema.\n" ] }, "returnKind.json": { @@ -185,20 +383,23 @@ "$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.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to get the current state of an instance.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to get the current state of an instance.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "executable" ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"config\", \"get\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config get\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#args\n" }, "input": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. If this value isn't defined, DSC doesn't send the resource any input when\ninvoking the `get` operation.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#input\n" } }, "examples": [ @@ -213,6 +414,27 @@ { "executable": "osinfo" } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the get command for the resource when no arguments are required.\n", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the get command for the resource when at least one argument is required.\n", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + } ] }, "manifest.export.json": { @@ -220,26 +442,47 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.export.json", "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to get the current state of every instance.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to get the current state of every instance.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "executable" ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"config\", \"export\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config export\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true#args\n" } - } + }, + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the export command for the resource when no arguments are required.\n", + "body": { + "executable": "${1:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the export command for the resource when at least one argument is required.\n", + "body": { + "executable": "${1:executable_name}", + "args": [ + "${2:--first-argument}" + ] + } + } + ] }, "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.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to set the desired state of an instance and how to\nprocess the output from the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to set the desired state of an instance and how to\nprocess the output from the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "executable", @@ -247,28 +490,31 @@ ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"config\", \"set\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config set\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#args\n" }, "input": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" }, "implementsPretest": { "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, - "markdownDescription": "> [Online Documentation][01]\n\nDefines whether the DSC Resource performs its own test to ensure idempotency when calling the\n`set` command. Set this value to `true` if the DSC Resource tests input before modifying\nsystem state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true#implementsPretest\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the DSC Resource performs its own test to ensure idempotency when calling the\n`set` command. Set this value to `true` if the DSC Resource tests input before modifying\nsystem state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#implementspretest\n" }, "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", - "markdownDescription": "> [Online Documentation][01]\n\nDefines whether the command returns a JSON blob of the DSC Resource's state after the set\noperation or the state and an array of the properties the DSC Resource modified.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true#return\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the command returns a JSON blob of the DSC Resource's state after the set\noperation or the state and an array of the properties the DSC Resource modified.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#return\n", "markdownEnumDescriptions": [ - "Indicates that the resource returns only the instance's final state after the set\noperation as a JSON blob.\n", - "Indicates that the resource returns the instance's final state and an array of property\nnames that the resource modified.\n" + "_Final state only_\n\n> Indicates that the resource returns only the instance's final state after the set\n> operation as a JSON blob.\n", + "_Final state and changed properties_\n\n> Indicates that the resource returns the instance's final state and an array of property\n> names that the resource modified.\n" ] } }, @@ -283,6 +529,31 @@ "implementsPretest": true, "return": "state" } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `set` command for the resource when no arguments are required.\n", + "body": { + "input": "${1|input,env|}", + "implementsPretest": "^${2|true,false|}", + "return": "${3|state,stateAndDiff|}", + "executable": "${4:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the `set` command for the resource when at least one argument is required.\n", + "body": { + "input": "${1|input,env|}", + "implementsPretest": "^${2|true,false|}", + "return": "${3|state,stateAndDiff|}", + "executable": "${4:executable_name}", + "args": [ + "${5:--first-argument}" + ] + } + } ] }, "manifest.test.json": { @@ -290,7 +561,7 @@ "$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.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to test if an instance is in the desired state and how\nto process the output from the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to test if an instance is in the desired state and how\nto process the output from the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "executable", @@ -298,22 +569,25 @@ ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"config\", \"test\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config test\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#args\n" }, "input": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" }, "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", - "markdownDescription": "> [Online Documentation][01]\n\nDefines whether the command returns a JSON blob of the DSC Resource's current state or the\nstate and an array of the properties that are out of the desired state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserveView=true#return\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the command returns a JSON blob of the DSC Resource's current state or the\nstate and an array of the properties that are out of the desired state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserve-view=true#return\n", "markdownEnumDescriptions": [ - "Indicates that the resource returns only the instance's actual state.\n", - "Indicates that the resource returns the instance's actual state and an array of property\nnames that are out of the desired state.\n" + "_Actual state only_\n\n> Indicates that the resource returns only the instance's actual state as a JSON blob.\n", + "_Actual state and differing properties_\n\n> Indicates that the resource returns the instance's actual state and an array of\n> property names that are out of the desired state.\n" ] } }, @@ -327,6 +601,29 @@ "input": "stdin", "return": "state" } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `test` command for the resource when no arguments are required.\n", + "body": { + "input": "${1|input,env|}", + "return": "${2|state,stateAndDiff|}", + "executable": "${3:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the `test` command for the resource when at least one argument is required.\n", + "body": { + "input": "${1|input,env|}", + "return": "${2|state,stateAndDiff|}", + "executable": "${3:executable_name}", + "args": [ + "${4:--first-argument}" + ] + } + } ] }, "manifest.validate.json": { @@ -334,17 +631,19 @@ "$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.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to validate the state of an instance. This method is\nmandatory for DSC Group Resources. It's ignored for all other DSC Resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to validate the state of an instance. This method is\nmandatory for DSC Group Resources. It's ignored for all other DSC Resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "executable" ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"config\", \"validate\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config validate\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#args\n" } }, "examples": [ @@ -355,6 +654,25 @@ "validate" ] } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `validate` command for the resource when no arguments are required.\n", + "body": { + "executable": "${1:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the `validate` command for the resource when at least one argument is required.\n", + "body": { + "executable": "${1:executable_name}", + "args": [ + "${2:--first-argument}" + ] + } + } ] }, "manifest.provider.json": { @@ -362,7 +680,7 @@ "$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.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to\nmanage resources that don't have their own manifests with DSC.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to\nmanage resources that don't have their own manifests with DSC.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "list", @@ -372,17 +690,19 @@ "list": { "title": "List Command", "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource Provider to list its supported DSC Resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true#list\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource Provider to list its supported DSC Resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserve-view=true#list\n", "type": "object", "required": [ "executable" ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"resources\", \"list\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry resources list\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserve-view=true#args\n" } } }, @@ -394,10 +714,10 @@ "full", "sequence" ], - "markdownDescription": "> [Online Documentation][01]\n\nDefines whether the provider expects to receive a full and unprocessed configuration as a\nsingle JSON blob over stdin or a sequence of JSON Lines for each child resource's\nconfigurations.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true#config\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the provider expects to receive a full and unprocessed configuration as a\nsingle JSON blob over stdin or a sequence of JSON Lines for each child resource's\nconfigurations.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserve-view=true#config\n", "markdownEnumDescriptions": [ - "Indicates that the provider expects a JSON blob containing the full and unprocessed\nconfiguration as a single JSON blob over `stdin`.\n", - "Indicates that the provider expects each resource's configuration as a [JSON Line][01]\nover `stdin`.\n\n[01]: https://jsonlines.org/\n" + "_Full and unprocessed config as a JSON blob_\n\n> Indicates that the provider expects a JSON blob containing the full and unprocessed\n> configuration as a single JSON blob over `stdin`.\n", + "_Resource instances as JSON Lines_\n\n> Indicates that the provider expects each resource's configuration as a [JSON Line][01]\n> over `stdin`.\n\n[01]: https://jsonlines.org/\n" ] } }, @@ -415,6 +735,31 @@ ] } } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the provider config kind and `list` command for the resource when no arguments are\nrequired.\n", + "body": { + "config": "$1", + "list": { + "executable": "${2:executable_name}" + } + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the provider config kind and `list` command for the resource when at least one\nargument is required.\n", + "body": { + "config": "$1", + "list": { + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + } + } ] }, "manifest.schema.json": { @@ -445,18 +790,39 @@ ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"schema\", \"resource\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry schema resource\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#args\n" } }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob\nrepresenting an instance of the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#command\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob\nrepresenting an instance of the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#command\n", + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `schema` command for the resource when no arguments are required.\n", + "body": { + "executable": "${1:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the `schema` command for the resource when at least one argument is required.\n", + "body": { + "executable": "${1:executable_name}", + "args": [ + "${2:--first-argument}" + ] + } + } + ] }, "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.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the JSON Schema DSC must use to validate a JSON blob representing an instance of the\nDSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the JSON Schema DSC must use to validate a JSON blob representing an instance of the\nDSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "$schema", @@ -468,7 +834,7 @@ "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", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the JSON type for an instance of the DSC Resource. DSC Resource instances always\nhave the `object` type.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true#type\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the JSON type for an instance of the DSC Resource. DSC Resource instances always\nhave the `object` type.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserve-view=true#type\n" }, "$schema": { "title": "DSC Resource instance schema dialect", @@ -480,11 +846,11 @@ "https://json-schema.org/draft/2019-09/schema", "http://json-schema.org/draft-07/schema#" ], - "markdownDescription": "> [Online Documentation][01]\n\nDefines the JSON type for an instance of the DSC Resource. DSC Resource instances always\nhave the `object` type. DSC only supports JSON Schema Draft 07 and later.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true#type\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the JSON type for an instance of the DSC Resource. DSC Resource instances always\nhave the `object` type. DSC only supports JSON Schema Draft 07 and later.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserve-view=true#type\n", "markdownEnumDescriptions": [ - "Indicates the resource instance schema adheres to [JSON Schema Draft 2020-12][01].\n\n[01]: https://json-schema.org/specification-links.html#2020-12\n", - "Indicates the resource instance schema adheres to [JSON Schema Draft 2019-09][01].\n\n[01]: https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8\n", - "Indicates the resource instance schema adheres to [JSON Schema Draft 07][01].\n\n[01]: https://json-schema.org/specification-links.html#draft-7\n" + "_Draft 2020-12 (recommended)_\n\n> Indicates that the resource instance schema adheres to\n> [JSON Schema Draft 2020-12][01].\n>\n> This is the latest published draft of JSON Schema and is the draft future drafts\n> will be most compatible with.\n\n[01]: https://json-schema.org/specification-links.html#2020-12\n", + "_Draft 2019-09_\n\n> Indicates that the resource instance schema adheres to\n> [JSON Schema Draft 2019-09][01].\n>\n> This is the previous published draft of JSON Schema. It's mostly compatible with\n> 2020-12, but less extensible and can't be bundled.\n\n[01]: https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8\n", + "_Draft 07_\n\n> Indicates that the resource instance schema adheres to [JSON Schema Draft 07][01].\n>\n> This is an older published draft of JSON Schema. It's widely used, but incompatible\n> with 2019-09 and later. It's less expressive, extensible, maintainable, and isn't\n> recommended for new schema definitions.\n\n[01]: https://json-schema.org/specification-links.html#draft-7\n" ] }, "$id": { @@ -492,12 +858,12 @@ "description": "Defines the unique ID for the DSC Resource's instance schema. If the instance schema is published to its own public URI, set this keyword to that URI.", "type": "string", "format": "uri-reference", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the unique ID for the DSC Resource's instance schema. If the instance schema is\npublished to its own public URI, set this keyword to that URI.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#id\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the unique ID for the DSC Resource's instance schema. If the instance schema is\npublished to its own public URI, set this keyword to that URI.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#id\n" }, "properties": { "title": "Instance Properties", "description": "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.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the properties that DSC can retrieve and manage for the resource's instances.\nThis keyword must define at least one property as a key-value pair. The key is the\nproperty's name. The value is a subschema that validates the property.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#properties\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the properties that DSC can retrieve and manage for the resource's instances.\nThis keyword must define at least one property as a key-value pair. The key is the\nproperty's name. The value is a subschema that validates the property.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#properties\n", "type": "object", "minProperties": 1, "unevaluatedProperties": { @@ -513,6 +879,104 @@ } ] }, + "additionalProperties": { + "defaultSnippets": [ + { + "label": " Define a property", + "markdownDescription": "Define a new property for the resource instance schema.", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "${3|boolean,string,integer,number,array,object,null|}" + } + }, + { + "label": " Define a property (boolean)", + "markdownDescription": "Define a new [boolean][01] property for the resource instance schema, requiring the\nvalue to be either `true` or `false`.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/boolean.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "boolean" + } + }, + { + "label": " Define a property (string)", + "markdownDescription": "Define a new [string][01] property for the resource instance schema, requiring the\nvalue to be a blob of text.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/string.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "string" + } + }, + { + "label": " Define a property (integer)", + "markdownDescription": "Define a new [integer][01] property for the resource instance schema, requiring the\nvalue to be a number without a fractional part.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/numeric.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "integer" + } + }, + { + "label": " Define a property (number)", + "markdownDescription": "Define a new [number][01] property for the resource instance schema, requiring the\nvalue to be a number that may include a fractional part.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/numeric.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "number" + } + }, + { + "label": " Define a property (array)", + "markdownDescription": "Define a new [array][01] property for the resource instance schema, requiring the\nvalue to be a list of values.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/array.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "array", + "items": { + "type": "${3|boolean,string,integer,number,array,object,null|}" + } + } + }, + { + "label": " Define a property (object)", + "markdownDescription": "Define a new [object][01] property for the resource instance schema, requiring the\nvalue to be a set of key-value pairs.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/object.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "object", + "properties": { + "${3:propertyName}": { + "title": "${4:propertyTitle}", + "description": "${5:explanation of property purpose and usage}", + "type": "${6|string,integer,number,array,object,null|}" + } + } + } + }, + { + "label": " Define a property (enum)", + "markdownDescription": "Define a new [enum][01] property for the resource instance schema that only accepts\na defined set of values.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "enum": [ + "^${3:\"first value\"}", + "^${4:\"second value\"}" + ] + } + }, + { + "label": " Define a property (const)", + "markdownDescription": "Define a new [const][01] property for the resource instance schema that only\naccepts a specific value.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/generic.html#constant-values", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "const": "^${3:\"constant value\"}" + } + } + ] + }, "properties": { "_ensure": { "title": "Standard Property: _ensure", @@ -520,15 +984,15 @@ "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nIndicates that the DSC Resource uses the standard `_ensure` property to specify\nwhether an instance should exist with the `Present` and `Absent` enums.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/ensure?view=dsc-3.0&preserveView=true\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nIndicates that the resource can enforce whether instances exist using the shared\n`present` and `absent` semantics. If a resource must distinguish between states\nbeyond whether an instance is `present` or `absent`, the resource should define its\nown `ensure` property without the leading underscore. This property provides shared\nsemantics for DSC Resources and integrating tools, but doesn't enable any additional\nbuilt-in processing with DSC.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/ensure?view=dsc-3.0&preserve-view=true\n" }, "_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.", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This read-only 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" }, - "markdownDescription": "> [Online Documentation][01]\n\nIndicates that the DSC Resource returns this value for it's own `test` method. This\nproperty is mandatory when the manifest defines the `test` property. It shouldn't\nbe included if the DSC Resource relies on DSC's synthetic testing.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/indesiredstate?view=dsc-3.0&preserveView=true\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nIndicates that the DSC Resource returns this value for it's own `test` method. This\nproperty is mandatory when the manifest defines the `test` property. It shouldn't\nbe included if the DSC Resource relies on DSC's synthetic testing.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/indesiredstate?view=dsc-3.0&preserve-view=true\n" }, "_purge": { "title": "Standard Property: _purge", @@ -536,17 +1000,30 @@ "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nIndicates that the DSC Resource uses the standard `_purge` property to specify\nwhether the DSC Resource should remove all non-specified members when it manages\nan array of members or values.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/purge?view=dsc-3.0&preserveView=true\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nIndicates that the DSC Resource uses the standard `_purge` property to specify\nwhether the DSC Resource should remove all non-specified members when it manages\nan array of members or values.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/purge?view=dsc-3.0&preserve-view=true\n" }, "_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.", + "description": "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.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nIndicates that the DSC Resource uses the standard `_rebootRequested` property to\nreport whether the machine should be rebooted after the `set` method executes.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/rebootrequested?view=dsc-3.0&preserveView=true\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nIndicates that the DSC Resource uses the standard `_rebootRequested` property to\nreport whether the machine should be rebooted after the `set` method executes.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/rebootrequested?view=dsc-3.0&preserve-view=true\n" } - } + }, + "defaultSnippets": [ + { + "label": " Define an instance property", + "markdownDescription": "Define a property for the resource instance schema.", + "body": { + "${1:propertyName}": { + "title": "${2:property title}", + "description": "${3:explanation of property purpose and usage}", + "type": "${4|string,integer,number,array,object,null|}" + } + } + } + ] } } }, @@ -555,7 +1032,7 @@ "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", "type": "string", "format": "uri", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the URL to the DSC Resource's JSON schema for integrating tools.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#url\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the URL to the DSC Resource's JSON schema for integrating tools.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#url\n" } }, "examples": [ @@ -627,7 +1104,47 @@ } } ], - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must validate a JSON blob representing an instance of the DSC Resource.\n\nThe JSON schema can be defined dynamically with the `command` property or statically with the\n`embedded` property.\n\nFor development purposes, it can be more convenient to use the `command` property and avoid\nneeding to adjust both the code and the schema.\n\nMicrosoft recommends using the `embedded` property when publishing a resource publicly. When the\nmanifest declares the schema with the `command` property, DSC calls the command at the beginning\nof any operation using the resource, possibly impacting performance. The schema is also\nunavailable to integrating tools when the resource isn't installed locally. When the schema is\nembedded in the manifest, DSC and integrating tools only need the manifest itself.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must validate a JSON blob representing an instance of the DSC Resource.\n\nThe JSON schema can be defined dynamically with the `command` property or statically with the\n`embedded` property.\n\nFor development purposes, it can be more convenient to use the `command` property and avoid\nneeding to adjust both the code and the schema.\n\nMicrosoft recommends using the `embedded` property when publishing a resource publicly. When the\nmanifest declares the schema with the `command` property, DSC calls the command at the beginning\nof any operation using the resource, possibly impacting performance. The schema is also\nunavailable to integrating tools when the resource isn't installed locally. When the schema is\nembedded in the manifest, DSC and integrating tools only need the manifest itself.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true\n", + "defaultSnippets": [ + { + "label": " Define as command without arguments", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefine the resource instance schema as a command when no arguments are required.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#command\n", + "body": { + "command": { + "executable": "${1:executable_name}" + } + } + }, + { + "label": " Define as command with arguments", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefine the resource instance schema as a command when at least one argument is required.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#command\n", + "body": { + "command": { + "executable": "${1:executable_name}", + "args": [ + "${2:--first-argument}" + ] + } + } + }, + { + "label": " Define as an embedded schema", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefine the resource instance schema embedded in the manifest. This is the preferred option\nfor publicly published resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserve-view=true\n", + "body": { + "embedded": { + "${escape_dollar:$}schema": "${1|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "${2:name}": { + "title": "${3:property title}", + "description": "${4:explanation of property purpose and usage}", + "type": "${5|string,integer,number,array,object,null|}" + } + } + } + } + } + ] } } } @@ -637,4 +1154,4 @@ } } } -} +} diff --git a/schemas/2023/08/config/document.json b/schemas/2023/08/config/document.json index 8078b2ba..234c5761 100644 --- a/schemas/2023/08/config/document.json +++ b/schemas/2023/08/config/document.json @@ -14,7 +14,9 @@ "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" + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] }, "parameters": { "title": "DSC Configuration document parameters", diff --git a/schemas/2023/08/config/document.parameter.json b/schemas/2023/08/config/document.parameter.json index 86b21705..82966dc9 100644 --- a/schemas/2023/08/config/document.parameter.json +++ b/schemas/2023/08/config/document.parameter.json @@ -4,7 +4,9 @@ "title": "Parameter", "description": "Defines a runtime option for a DSC Configuration Document.", "type": "object", - "required": "type", + "required": [ + "type" + ], "properties": { "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" diff --git a/schemas/2023/08/definitions/inputKind.json b/schemas/2023/08/definitions/inputKind.json index c6305bd5..5914172f 100644 --- a/schemas/2023/08/definitions/inputKind.json +++ b/schemas/2023/08/definitions/inputKind.json @@ -2,11 +2,10 @@ "$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.", + "description": "Defines how DSC should pass input to the command, either as environment variables or JSON over stdin. When this value isn't defined, DSC doesn't send the resource any input.", "type": "string", "enum": [ - "args", + "env", "stdin" - ], - "default": "args" + ] } diff --git a/schemas/2023/08/definitions/semver.json b/schemas/2023/08/definitions/semver.json index 24d89afc..a49169e6 100644 --- a/schemas/2023/08/definitions/semver.json +++ b/schemas/2023/08/definitions/semver.json @@ -4,5 +4,6 @@ "type": "string", "title": "Semantic Version", "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", - "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-]+)*))?$" + "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": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\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\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" } diff --git a/schemas/2023/08/outputs/config/get.json b/schemas/2023/08/outputs/config/get.json index 9c5de7d6..61918db2 100644 --- a/schemas/2023/08/outputs/config/get.json +++ b/schemas/2023/08/outputs/config/get.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/get.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json" } } } diff --git a/schemas/2023/08/outputs/config/set.json b/schemas/2023/08/outputs/config/set.json index 450eb783..8da20f0c 100644 --- a/schemas/2023/08/outputs/config/set.json +++ b/schemas/2023/08/outputs/config/set.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/set.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json" } } } diff --git a/schemas/2023/08/outputs/config/test.json b/schemas/2023/08/outputs/config/test.json index 964c98fd..9e90567e 100644 --- a/schemas/2023/08/outputs/config/test.json +++ b/schemas/2023/08/outputs/config/test.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/test.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json" } } } diff --git a/schemas/2023/08/outputs/resource/get.json b/schemas/2023/08/outputs/resource/get.json index 9c191c86..00a30602 100644 --- a/schemas/2023/08/outputs/resource/get.json +++ b/schemas/2023/08/outputs/resource/get.json @@ -4,7 +4,9 @@ "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", + "required": [ + "actualState" + ], "properties": { "actualState": { "title": "Actual state", diff --git a/schemas/2023/08/outputs/resource/list.json b/schemas/2023/08/outputs/resource/list.json index 88eada11..13b4a509 100644 --- a/schemas/2023/08/outputs/resource/list.json +++ b/schemas/2023/08/outputs/resource/list.json @@ -34,13 +34,17 @@ "title": "Standard implementation", "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", "type": "string", - "enum": "Command" + "enum": [ + "Command" + ] }, { "title": "Custom implementation", "description": "Indicates that the DSC Resource uses a custom implementation.", "type": "object", - "required": "custom", + "required": [ + "custom" + ], "properties": { "custom": { "title": "Custom implementation name", diff --git a/schemas/2023/08/resource/manifest.export.json b/schemas/2023/08/resource/manifest.export.json index e1fc9ed7..5c918b52 100644 --- a/schemas/2023/08/resource/manifest.export.json +++ b/schemas/2023/08/resource/manifest.export.json @@ -4,7 +4,9 @@ "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" diff --git a/schemas/2023/08/resource/manifest.get.json b/schemas/2023/08/resource/manifest.get.json index 8ccfa99b..351aa81d 100644 --- a/schemas/2023/08/resource/manifest.get.json +++ b/schemas/2023/08/resource/manifest.get.json @@ -4,7 +4,9 @@ "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" diff --git a/schemas/2023/08/resource/manifest.json b/schemas/2023/08/resource/manifest.json index a3afd66c..25efc748 100644 --- a/schemas/2023/08/resource/manifest.json +++ b/schemas/2023/08/resource/manifest.json @@ -5,17 +5,20 @@ "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.", "type": "object", "required": [ - "manifestVersion", + "$schema", "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" + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json" + ] }, "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" @@ -75,13 +78,15 @@ "0": "Success", "1": "Error" }, - "examples": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } + "examples": [ + { + "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 index 86f51156..efbcbcf3 100644 --- a/schemas/2023/08/resource/manifest.provider.json +++ b/schemas/2023/08/resource/manifest.provider.json @@ -13,7 +13,9 @@ "title": "List Command", "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -33,17 +35,19 @@ ] } }, - "examples": { - "config": "full", - "list": { - "executable": "pwsh", - "args": [ - "-NoLogo", - "-NonInteractive", - "-NoProfile", - "-Command", - "./powershellgroup.resource.ps1 List" - ] + "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 index 29ad74b5..58ab86d5 100644 --- a/schemas/2023/08/resource/manifest.schema.json +++ b/schemas/2023/08/resource/manifest.schema.json @@ -6,10 +6,14 @@ "type": "object", "oneOf": [ { - "required": "command" + "required": [ + "command" + ] }, { - "required": "embedded" + "required": [ + "embedded" + ] } ], "properties": { @@ -17,7 +21,9 @@ "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", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -77,6 +83,7 @@ } ] }, + "additionalProperties": {}, "properties": { "_ensure": { "title": "Standard Property: _ensure", @@ -87,7 +94,7 @@ }, "_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.", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This read-only 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" } @@ -101,7 +108,7 @@ }, "_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.", + "description": "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.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" } @@ -121,7 +128,9 @@ { "command": { "executable": "registry", - "args": "schema" + "args": [ + "schema" + ] } }, { diff --git a/schemas/2023/08/resource/manifest.set.json b/schemas/2023/08/resource/manifest.set.json index aa39c13e..7484863e 100644 --- a/schemas/2023/08/resource/manifest.set.json +++ b/schemas/2023/08/resource/manifest.set.json @@ -29,14 +29,16 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "set" - ], - "input": "stdin", - "implementsPretest": true, - "return": "state" - } -} + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "implementsPretest": true, + "return": "state" + } + ] +} diff --git a/schemas/2023/08/resource/manifest.test.json b/schemas/2023/08/resource/manifest.test.json index 0cf89b00..c503d570 100644 --- a/schemas/2023/08/resource/manifest.test.json +++ b/schemas/2023/08/resource/manifest.test.json @@ -24,13 +24,15 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "test" - ], - "input": "stdin", - "return": "state" - } + "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 index fbb7b5e5..b646ae48 100644 --- a/schemas/2023/08/resource/manifest.validate.json +++ b/schemas/2023/08/resource/manifest.validate.json @@ -4,7 +4,9 @@ "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", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -13,11 +15,13 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" } }, - "examples": { - "executable": "dsc", - "args": [ - "config", - "validate" - ] - } + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] } diff --git a/schemas/build.ps1 b/schemas/build.ps1 index b5318981..1b11a870 100644 --- a/schemas/build.ps1 +++ b/schemas/build.ps1 @@ -38,6 +38,8 @@ begin { [string]$SchemaHost [string]$SchemaPrefix [string]$SchemaVersion + [string]$DocsBaseUrl + [string]$DocsVersionPin LocalJsonSchemaRegistry() { $this.FileMap = [Specialized.OrderedDictionary]::new() @@ -48,14 +50,18 @@ begin { LocalJsonSchemaRegistry( [string]$SchemaHost, [string]$SchemaPrefix, - [string]$SchemaVersion + [string]$SchemaVersion, + [string]$DocsBaseUrl, + [string]$DocsVersionPin ) { - $this.SchemaHost = $SchemaHost - $this.SchemaPrefix = $SchemaPrefix - $this.SchemaVersion = $SchemaVersion - $this.FileMap = [Specialized.OrderedDictionary]::new() - $this.Map = [Specialized.OrderedDictionary]::new() - $this.List = [Generic.List[Specialized.OrderedDictionary]]::new() + $this.SchemaHost = $SchemaHost + $this.SchemaPrefix = $SchemaPrefix + $this.SchemaVersion = $SchemaVersion + $this.DocsBaseUrl = $DocsBaseUrl + $this.DocsVersionPin = $DocsVersionPin + $this.FileMap = [Specialized.OrderedDictionary]::new() + $this.Map = [Specialized.OrderedDictionary]::new() + $this.List = [Generic.List[Specialized.OrderedDictionary]]::new() } } @@ -84,7 +90,16 @@ begin { if ($_.Value -is [Object[]]) { if ($_.Value.Count -ge 1) { $MungedKeyValue = Remove-JsonSchemaKey -KeyName $KeyName -SchemaList $_.Value - $MungedSchema.Add($_.Key, $MungedKeyValue) + # Need to ensure single-item returns get correctly handled as arays, + # not munged into scalars. + if ( + ($MungedKeyValue.Count -eq 1) -or + ($MungedKeyValue -is [Specialized.OrderedDictionary]) + ) { + $MungedSchema.Add($_.Key, [object[]]$MungedKeyValue) + } else { + $MungedSchema.Add($_.Key, $MungedKeyValue) + } } else { $MungedSchema.Add($_.Key, $_.Value) } @@ -128,11 +143,19 @@ begin { [string[]]$SchemaDirectories = @(), [string]$SchemaHost = 'https://raw.githubusercontent.com', [string]$SchemaPrefix = 'PowerShell/DSC/main', - [string]$SchemaVersion = '2023/08' + [string]$SchemaVersion = '2023/08', + [string]$DocsBaseUrl = 'https://learn.microsoft.com/powershell/dsc', + [string]$DocsVersionPin = 'view=dsc-3.0&preserve-view=true' ) begin { - $Info = [LocalJsonSchemaRegistry]::new($SchemaHost, $SchemaPrefix, $SchemaVersion) + $Info = [LocalJsonSchemaRegistry]::new( + $SchemaHost, + $SchemaPrefix, + $SchemaVersion, + $DocsBaseUrl, + $DocsVersionPin + ) } process { @@ -574,11 +597,13 @@ process { 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 + $SchemaContent = $SchemaContent -replace '', $Config.host + $SchemaContent = $SchemaContent -replace '', $Config.prefix + $SchemaContent = $SchemaContent -replace '', $Config.version + $SchemaContent = $SchemaContent -replace '', $Config.docs_base_url + $SchemaContent = $SchemaContent -replace '', $Config.docs_version_pin + $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 diff --git a/schemas/schemas.config.yaml b/schemas/schemas.config.yaml index 6b840411..34a6348d 100644 --- a/schemas/schemas.config.yaml +++ b/schemas/schemas.config.yaml @@ -1,6 +1,8 @@ -host: https://raw.githubusercontent.com -prefix: PowerShell/DSC/main/schemas -version: 2023/08 +host: https://raw.githubusercontent.com +prefix: PowerShell/DSC/main/schemas +version: 2023/08 +docs_base_url: https://learn.microsoft.com/powershell/dsc +docs_version_pin: view=dsc-3.0&preserve-view=true bundle_schemas: # Resource manifest bundle - ConfigFilePath: resource/manifest.json diff --git a/schemas/src/config/document.parameter.yaml b/schemas/src/config/document.parameter.yaml index 79e40470..2162e055 100644 --- a/schemas/src/config/document.parameter.yaml +++ b/schemas/src/config/document.parameter.yaml @@ -5,11 +5,13 @@ title: Parameter description: Defines a runtime option for a DSC Configuration Document. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a runtime option for a DSC Configuration Document. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/config/parameter? type: object @@ -25,11 +27,13 @@ properties: $ref: ///definitions/parameters/validValueTypes.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the default value for the parameter. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#allowedvalues + [01]: /reference/schemas/config/parameter?#allowedvalues allowedValues: title: Allowed values description: >- @@ -40,12 +44,14 @@ properties: $ref: ///definitions/parameters/validValueTypes.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#allowedvalues + [01]: /reference/schemas/config/parameter?#allowedvalues description: title: Parameter description description: >- @@ -53,11 +59,13 @@ properties: type: string # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a synopsis for the parameter explaining its purpose. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#description-1 + [01]: /reference/schemas/config/parameter?#description-1 metadata: title: Parameter metadata description: >- @@ -66,23 +74,49 @@ properties: type: object # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a set of key-value pairs for the parameter. This metadata isn't validated. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#metadata-1 + [01]: /reference/schemas/config/parameter?#metadata-1 defaultSnippets: - - label: New Metadata Property - description: Defines a key-value pair for the metadata - body: { '${1:metadataName}': '$2' } - - label: New metadata property (object) - description: Defines a new key-value pair for the metadata where the value is an object. + - label: ' New metadata property' + markdownDescription: |- + Defines a key-value pair for the metadata: + + ```yaml + metadataName: value + ``` + body: + ${1:metadataName}: ${2:value} + + - label: ' New metadata property (object)' + markdownDescription: |- + Defines a new key-value pair for the metadata where the value is an object. + + ```yaml + metadataName: + key: value + ``` body: - '${1:metadataName}': { '${2:key}': '${3:value}' } - - label: New metadata property (array) - description: Defines a new key-value pair for the metadata where the value is an array. + ${1:metadataName}: + ${2:key}: ${3:value} + + - label: ' New metadata property (array)' + markdownDescription: |- + Defines a new key-value pair for the metadata where the value is an array. + + ```yaml + metadataName: + - firstValue + - secondValue + ``` body: - '${1:metadataName}': ['${2:firstValue}', '${3:secondValue}'] + ${1:metadataName}: + - ${2:firstValue} + - ${3:secondValue} # Conditional settings depending on parameter type allOf: @@ -101,12 +135,14 @@ allOf: type: integer # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#minvalue + [01]: /reference/schemas/config/parameter?#minvalue maxValue: title: Maximum value @@ -116,12 +152,14 @@ allOf: type: integer # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#maxvalue + [01]: /reference/schemas/config/parameter?#maxvalue # Additional properties for string and array parameters - if: @@ -140,12 +178,14 @@ allOf: minimum: 0 # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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`. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#minLength + [01]: /reference/schemas/config/parameter?#minLength maxLength: title: Maximum length description: >- @@ -155,12 +195,14 @@ allOf: minimum: 0 # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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`. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#maxLength + [01]: /reference/schemas/config/parameter?#maxLength # defaultValue strict validation - if: oneOf: diff --git a/schemas/src/config/document.resource.yaml b/schemas/src/config/document.resource.yaml index 5b33e874..9f83e6a1 100644 --- a/schemas/src/config/document.resource.yaml +++ b/schemas/src/config/document.resource.yaml @@ -32,8 +32,20 @@ properties: The `` and `` should be the fully qualified type of the resource and its friendly name in the configuration. + defaultSnippets: + - label: ' New dependency' + markdownDescription: |- + Defines a new dependency for the resource instance. + + ```yaml + "[resourceId('dependencyInstance/Type', 'dependencyInstanceName')]" + ``` + bodyText: >- + "[resourceId('${3:dependencyInstance/Type}', '${4:dependencyInstanceName}')]" markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the `resourceID()` lookup for another @@ -51,7 +63,7 @@ properties: YAML-format configuration document, always wrap the `resourceID()` lookup in double quotes (`"`). - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#properties-1 + [01]: /reference/schemas/config/resource?#properties-1 properties: title: Managed instance properties description: >- @@ -60,16 +72,20 @@ properties: type: object # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#properties-1 + [01]: /reference/schemas/config/resource?#properties-1 # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines an instance of a DSC Resource in a configuration. @@ -77,23 +93,43 @@ markdownDescription: | instance. Together, the instances in a configuration define the desired state that DSC can get, test, and set on a machine. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/config/resource? defaultSnippets: - - label: New resource instance - description: Defines a new instance of a DSC Resource for the configuration + - label: ' New resource instance' + markdownDescription: |- + Defines a new instance of a DSC Resource for the configuration. + + ```yaml + type: owner[.group][.area]/name + name: instance_name + properties: + propertyName: propertyValue + ``` body: - type: $1 - name: $2 + type: ${1:owner[.group][.area]/name} + name: ${2:instance_name} properties: - '${3:propertyName}': '${4:propertyValue}' - - label: New dependent resource instance - description: >- + ${3:propertyName}: ${4:propertyValue} + + - label: ' New dependent resource instance' + markdownDescription: |- Defines a new instance of a DSC Resource for the configuration that depends on another instance. + + ```yaml + type: owner[.group][.area]/name + name: instance_name + dependsOn: + - "[resourceId('dependencyInstance/Type', 'dependencyInstanceName')]" + properties: + propertyName: propertyValue + ``` body: - type: $1 - name: $2 - dependsOn: "['[${3:dependencyType}]${4:dependencyName}']" + type: ${1:owner[.group][.area]/name} + name: ${2:instance_name} + dependsOn: + - >- + "[resourceId('${3:dependencyInstance/Type}', '${4:dependencyInstanceName}')]" properties: - '${5:propertyName}': '${6:propertyValue}' + ${5:propertyName}: ${6:propertyValue} diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index f60a013e..ca5e6b56 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -5,7 +5,9 @@ title: DSC Configuration Document schema description: Describes a valid DSC Configuration Document. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Describes a valid DSC Configuration Document. @@ -13,7 +15,7 @@ markdownDescription: | # VS Code only configuration document uses parameters and variables to pass to a set of one or more resources that define a desired state. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/config/document? type: object @@ -32,14 +34,19 @@ properties: - ///config/document.yaml # VS Code only: markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#schema + [01]: /reference/schemas/config/document?#schema markdownEnumDescriptions: - - Indicates that the configuration document adheres to the `` schema. + - | # ///config/document.yaml + + + > Indicates that the configuration document adheres to the `` schema. parameters: title: DSC Configuration document parameters @@ -51,30 +58,54 @@ properties: $ref: ///config/document.parameter.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#parameters + [01]: /reference/schemas/config/document?#parameters defaultSnippets: - - label: New Parameter - description: Defines a new runtime option for the configuration. + - label: ' New Parameter' + markdownDescription: |- + Defines a new runtime option for the configuration. + + ```yaml + parameterId: + type: + description: + defaultValue: + allowedValues: + - + ``` body: - '${1:parameterId}': - type: '$2' - defaultValue: '$3' - allowedValues: ['$4'] - description: '$5' - - label: New Integer Parameter - description: Defines a new runtime option for the configuration as an integer value. + ${1:parameterId}: + type: $2 + description: $3 + defaultValue: $4 + allowedValues: + - $5 + + - label: ' New Integer Parameter' + markdownDescription: |- + Defines a new runtime option for the configuration as an integer value. + + ```yaml + parameterId: + type: int + description: + defaultValue: + minValue: + minValue: + ``` body: - '${1:integerParameterId}': + ${1:parameterId}: type: int - defaultValue: '$2' - description: '$3' - minValue: '$4' - maxValue: '$5' + description: $2 + defaultValue: $3 + minValue: $4 + maxValue: $5 variables: title: Configuration variables @@ -84,24 +115,50 @@ properties: type: object # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#variables + [01]: /reference/schemas/config/document?#variables defaultSnippets: - - label: New variable property - description: Defines a new variable as a key-value pair - body: { '${1:metadataName}': '$2' } - - label: New variable property (object) - description: Defines a new key-value pair for the variables where the value is an object. + - label: ' New variable property' + markdownDescription: |- + Defines a new variable as a key-value pair. + + ```yaml + variableName: variableValue + ``` + body: + ${1:variableName}: ${2:variableValue} + + - label: ' New variable property (object)' + markdownDescription: |- + Defines a new key-value pair for the variables where the value is an object. + + ```yaml + variableName: + key: value + ``` body: - '${1:variableName}': { '${2:key}': '${3:value}' } - - label: New variable property (array) - description: Defines a new key-value pair for the variables where the value is an array. + ${1:variableName}: + ${2:key}: ${3:value} + + - label: ' New variable property (array)' + markdownDescription: |- + Defines a new key-value pair for the variables where the value is an array. + + ```yaml + variableName: + - firstValue + - secondValue + ``` body: - '${1:variableName}': ['${2:firstValue}', '${3:secondValue}'] + ${1:variableName}: + - ${2:firstValue} + - ${3:secondValue} resources: title: DSC Configuration document resources @@ -112,11 +169,13 @@ properties: $ref: ///config/document.resource.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a list of DSC Resource instances for the configuration to manage. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#resources + [01]: /reference/schemas/config/document?#resources metadata: title: Configuration metadata @@ -126,20 +185,46 @@ properties: type: object # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a set of key-value pairs for the configuration. This metadata isn't validated. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#metadata-1 + [01]: /reference/schemas/config/document?#metadata-1 defaultSnippets: - - label: New Metadata Property - description: Defines a key-value pair for the metadata - body: { '${1:metadataName}': '$2' } - - label: New metadata property (object) - description: Defines a new key-value pair for the metadata where the value is an object. + - label: ' New metadata property' + markdownDescription: |- + Defines a key-value pair for the metadata: + + ```yaml + metadataName: value + ``` + body: + ${1:metadataName}: ${2:value} + + - label: ' New metadata property (object)' + markdownDescription: |- + Defines a new key-value pair for the metadata where the value is an object. + + ```yaml + metadataName: + key: value + ``` body: - '${1:metadataName}': { '${2:key}': '${3:value}' } - - label: New metadata property (array) - description: Defines a new key-value pair for the metadata where the value is an array. + ${1:metadataName}: + ${2:key}: ${3:value} + + - label: ' New metadata property (array)' + markdownDescription: |- + Defines a new key-value pair for the metadata where the value is an array. + + ```yaml + metadataName: + - firstValue + - secondValue + ``` body: - '${1:metadataName}': ['${2:firstValue}', '${3:secondValue}'] + ${1:metadataName}: + - ${2:firstValue} + - ${3:secondValue} diff --git a/schemas/src/definitions/commandArgs.yaml b/schemas/src/definitions/commandArgs.yaml index a3fb3f0c..815f746a 100644 --- a/schemas/src/definitions/commandArgs.yaml +++ b/schemas/src/definitions/commandArgs.yaml @@ -8,7 +8,3 @@ description: >- type: array items: type: string - -markdownDescription: | - 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. diff --git a/schemas/src/definitions/commandExecutable.yaml b/schemas/src/definitions/commandExecutable.yaml index 2758d2e4..18f8c3b6 100644 --- a/schemas/src/definitions/commandExecutable.yaml +++ b/schemas/src/definitions/commandExecutable.yaml @@ -6,9 +6,3 @@ title: Executable Command Name description: >- The name of the command to run. type: string - -# VS Code only -markdownDescription: | - 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. diff --git a/schemas/src/definitions/inputKind.yaml b/schemas/src/definitions/inputKind.yaml index c58a8ba2..c3c4bb4f 100644 --- a/schemas/src/definitions/inputKind.yaml +++ b/schemas/src/definitions/inputKind.yaml @@ -4,22 +4,41 @@ $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. + Defines how DSC should pass input to the command, either as environment variables or + JSON over stdin. When this value isn't defined, DSC doesn't send the resource any input. type: string enum: - - args + - env - stdin -default: args # VS Code only -markdownDescription: | - Defines how DSC should pass input to the command, either as arguments or JSON over `stdin`. +# Don't define markdownDescription - each schema using this must define it, to link correctly. markdownEnumDescriptions: - # 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`. + - | # env + _Environment variables_ + + > Indicates that the resource expects the properties of an instance to be specified as + > environment variables with the same names and casing. + > + > This option only supports the following data types for instance properties: + > + > - `boolean` + > - `integer` + > - `number` + > - `string` + > - `array` of `integer` values + > - `array` of `number` values + > - `array` of `string` values + > + > For non-array values, DSC sets the environment variable to the specified value as-is. When + > the data type is an array of values, DSC sets the environment variable as a comma-delimited + > string. For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo` + > environment variable as `"1,2,3"`. + > + > If the resource needs to support complex properties with an `object` value or multi-type + > arrays, set this to `stdin` instead. + - | # stdin + _JSON over `stdin`_ + + > Indicates that the resource expects a JSON blob representing an instance from `stdin`. + > The JSON must adhere to the instance schema. diff --git a/schemas/src/definitions/instanceName.yaml b/schemas/src/definitions/instanceName.yaml index a2fca5a4..9ec752ed 100644 --- a/schemas/src/definitions/instanceName.yaml +++ b/schemas/src/definitions/instanceName.yaml @@ -15,7 +15,9 @@ patternErrorMessage: | Invalid value for instance name. An instance name must be a non-empty string containing only letters, numbers, and spaces. markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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 @@ -23,4 +25,4 @@ markdownDescription: | The instance name must be a non-empty string containing only letters, numbers, and spaces. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#name + [01]: /reference/schemas/config/resource?#name diff --git a/schemas/src/definitions/parameters/dataTypes.yaml b/schemas/src/definitions/parameters/dataTypes.yaml index 9658cb6b..e73b1eab 100644 --- a/schemas/src/definitions/parameters/dataTypes.yaml +++ b/schemas/src/definitions/parameters/dataTypes.yaml @@ -17,7 +17,9 @@ enum: # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the data type for the parameter value. @@ -40,85 +42,90 @@ markdownDescription: | 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/definitions/parameters/datatypes? markdownEnumDescriptions: - # string - - | - > [Online Documentation][01] - - Strings are an arbitrary set of text. - - To define a long strings in YAML, use the folded block syntax or literal block syntax by - adding a `>` or `|` 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. You can trim the trailing whitespace - by using `>-` or `|-` instead. - - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#strings - - # securestring - - | - > [Online Documentation][01] - - Secure strings are an arbitrary set of text that DSC and integrating tools shouldn't log or - record. 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 - parameters. - - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#secure-strings-and-objects - - # int - - | - > [Online Documentation][01] - - 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`. - - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#integers - # bool - - | - > [Online Documentation][01] - - Boolean values are either `true` or `false`. - - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#booleans - # object - - | - > [Online Documentation][01] - - 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. - - Access keys in the object using dot-notation. Dot-notation uses this syntax: - - ```yaml - "[parameters('').] - ``` - - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#objects - - # secureobject - - | - > [Online Documentation][01] - - Secure objects define a set of key-value pairs that DSC and integrating tools shouldn't log - or record. 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. - - Never define a default value for secure object parameters. - - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#secure-strings-and-objects - # array - - | - > [Online Documentation][01] - - 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. - - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#arrays + - | # string + _Strings are an arbitrary set of text._ + + > To define a long strings in YAML, use the folded block syntax or literal block syntax by + > adding a `>` or `|` 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. You can trim the trailing + > whitespace by using `>-` or `|-` instead. + > + > For more information, see the [_Online Documentation_][01]. + + [01]: /reference/schemas/definitions/parameters/datatypes?#strings + + - | # securestring + _Secure strings are text that needs to be handled securely._ + + > Secure strings are an arbitrary set of text that DSC and integrating tools shouldn't log or + > record. 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 + > parameters. + > + > For more information, see the [_Online Documentation_][01]. + + [01]: /reference/schemas/definitions/parameters/datatypes?#secure-strings-and-objects + + - | # int + _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`. + > + > For more information, see the [_Online Documentation_][01]. + + [01]: /reference/schemas/definitions/parameters/datatypes?#integers + + - | # bool + _Boolean values are either `true` or `false`._ + + > For more information, see the [_Online Documentation_][01]. + + [01]: /reference/schemas/definitions/parameters/datatypes?#booleans + + - | # object + _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. + > + > Access keys in the object using dot-notation. Dot-notation uses this syntax: + > + > ```yaml + > "[parameters('').] + > ``` + > + > For more information, see the [_Online Documentation_][01]. + + [01]: /reference/schemas/definitions/parameters/datatypes?#objects + + - | # secureobject + _Secure objects are key-value pairs that need to be handled securely._ + + > Secure objects define a set of key-value pairs that DSC and integrating tools shouldn't log + > or record. 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. + > + > Never define a default value for secure object parameters. + > + > For more information, see the [_Online Documentation_][01]. + + [01]: /reference/schemas/definitions/parameters/datatypes?#secure-strings-and-objects + + - | # array + _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. + > + > For more information, see the [_Online Documentation_][01]. + + [01]: /reference/schemas/definitions/parameters/datatypes?#arrays diff --git a/schemas/src/definitions/resourceType.yaml b/schemas/src/definitions/resourceType.yaml index 6c28eddd..f993f1e1 100644 --- a/schemas/src/definitions/resourceType.yaml +++ b/schemas/src/definitions/resourceType.yaml @@ -18,11 +18,13 @@ pattern: ^\w+(\.\w+){0,2}\/\w+$ # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** The namespaced name of the DSC Resource, using the syntax: - ```text + ```yaml owner[.group][.area]/name ``` @@ -31,7 +33,7 @@ markdownDescription: | - `Microsoft.SqlServer/Database` - `Microsoft.SqlServer.Database/User` - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/definitions/resourcetype? patternErrorMessage: | Invalid type name. Valid resource type names always define an owner and a name separated by a slash, like `Microsoft/OSInfo`. Type names may optionally include a group and area to namespace diff --git a/schemas/src/definitions/semver.yaml b/schemas/src/definitions/semver.yaml index 3a369699..38964407 100644 --- a/schemas/src/definitions/semver.yaml +++ b/schemas/src/definitions/semver.yaml @@ -10,9 +10,12 @@ description: | 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-]+)*))?$ +patternErrorMessage: | # VS Code only + Invalid value, must be a semantic version like `..`, such as `1.2.3`. + + The value may also include pre-release version information and build metadata. -# VS Code only -markdownDescription: | +$comment: | A valid semantic version ([semver][01]) string. This value uses the [suggested regular expression][02] to validate whether the string is valid @@ -32,7 +35,3 @@ markdownDescription: | [01]: https://semver.org/ [02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string -patternErrorMessage: | - Invalid value, must be a semantic version like `..`, such as `1.2.3`. - - The value may also include pre-release version information and build metadata. diff --git a/schemas/src/outputs/config/get.yaml b/schemas/src/outputs/config/get.yaml index 491d0b78..6e731a7b 100644 --- a/schemas/src/outputs/config/get.yaml +++ b/schemas/src/outputs/config/get.yaml @@ -31,7 +31,7 @@ properties: type: $ref: ///definitions/resourceType.yaml result: - $ref: ///results/resource/get.yaml + $ref: ///outputs/resource/get.yaml messages: $ref: ///definitions/messages.yaml hadErrors: diff --git a/schemas/src/outputs/config/set.yaml b/schemas/src/outputs/config/set.yaml index d6e97abe..653c1115 100644 --- a/schemas/src/outputs/config/set.yaml +++ b/schemas/src/outputs/config/set.yaml @@ -31,7 +31,7 @@ properties: type: $ref: ///definitions/resourceType.yaml result: - $ref: ///results/resource/set.yaml + $ref: ///outputs/resource/set.yaml messages: $ref: ///definitions/messages.yaml hadErrors: diff --git a/schemas/src/outputs/config/test.yaml b/schemas/src/outputs/config/test.yaml index ba79b740..28201af9 100644 --- a/schemas/src/outputs/config/test.yaml +++ b/schemas/src/outputs/config/test.yaml @@ -31,7 +31,7 @@ properties: type: $ref: ///definitions/resourceType.yaml result: - $ref: ///results/resource/test.yaml + $ref: ///outputs/resource/test.yaml messages: $ref: ///definitions/messages.yaml hadErrors: diff --git a/schemas/src/resource/manifest.export.yaml b/schemas/src/resource/manifest.export.yaml index 7983de2c..97da2440 100644 --- a/schemas/src/resource/manifest.export.yaml +++ b/schemas/src/resource/manifest.export.yaml @@ -6,11 +6,13 @@ title: Get Method description: >- Defines how DSC must call the DSC Resource to get the current state of every instance. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must call the DSC Resource to get the current state of every instance. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/export? type: object required: @@ -18,5 +20,55 @@ required: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + [01]: /reference/schemas/resource/manifest/export?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["config", "export"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry config export + ``` + + [01]: /reference/schemas/resource/manifest/export?#args + +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the export command for the resource when no arguments are required. + body: + executable: ${1:executable_name} + + - label: ' Define with arguments' + markdownDescription: | + Define the export command for the resource when at least one argument is required. + body: + executable: ${1:executable_name} + args: + - ${2:--first-argument} diff --git a/schemas/src/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml index c76bc376..b84c7682 100644 --- a/schemas/src/resource/manifest.get.yaml +++ b/schemas/src/resource/manifest.get.yaml @@ -6,11 +6,13 @@ title: Get Method description: >- Defines how DSC must call the DSC Resource to get the current state of an instance. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must call the DSC Resource to get the current state of an instance. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/get? type: object required: @@ -18,10 +20,55 @@ required: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + [01]: /reference/schemas/resource/manifest/get?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["config", "get"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry config get + ``` + + [01]: /reference/schemas/resource/manifest/get?#args input: $ref: ///definitions/inputKind.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines how DSC should pass input to the command, either as environment variables or JSON + over `stdin`. If this value isn't defined, DSC doesn't send the resource any input when + invoking the `get` operation. + + [01]: /reference/schemas/resource/manifest/get?#input examples: - executable: registry @@ -30,3 +77,20 @@ examples: - get input: stdin - executable: osinfo + +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the get command for the resource when no arguments are required. + body: + input: ${1|stdin,env|} + executable: ${2:executable_name} + + - label: ' Define with arguments' + markdownDescription: | + Define the get command for the resource when at least one argument is required. + body: + input: ${1|stdin,env|} + executable: ${2:executable_name} + args: + - ${3:--first-argument} diff --git a/schemas/src/resource/manifest.provider.yaml b/schemas/src/resource/manifest.provider.yaml index 5d452e2b..f1c704f0 100644 --- a/schemas/src/resource/manifest.provider.yaml +++ b/schemas/src/resource/manifest.provider.yaml @@ -7,12 +7,14 @@ 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. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/provider? type: object required: @@ -24,19 +26,56 @@ properties: description: >- Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true#list + [01]: /reference/schemas/resource/manifest/provider?#list type: object required: - executable properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + [01]: /reference/schemas/resource/manifest/provider?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["resources", "list"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry resources list + ``` + + [01]: /reference/schemas/resource/manifest/provider?#args config: title: Expected Configuration description: >- @@ -49,22 +88,26 @@ properties: - sequence # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true#config + [01]: /reference/schemas/resource/manifest/provider?#config markdownEnumDescriptions: - # 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`. + - | # full + _Full and unprocessed config as a JSON blob_ + + > Indicates that the provider expects a JSON blob containing the full and unprocessed + > configuration as a single JSON blob over `stdin`. + - | # sequence + _Resource instances as JSON Lines_ + + > Indicates that the provider expects each resource's configuration as a [JSON Line][01] + > over `stdin`. [01]: https://jsonlines.org/ @@ -78,3 +121,24 @@ examples: - -NoProfile - -Command - ./powershellgroup.resource.ps1 List + +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the provider config kind and `list` command for the resource when no arguments are + required. + body: + config: $1 + list: + executable: ${2:executable_name} + + - label: ' Define with arguments' + markdownDescription: | + Define the provider config kind and `list` command for the resource when at least one + argument is required. + body: + config: $1 + list: + executable: ${2:executable_name} + args: + - ${3:--first-argument} diff --git a/schemas/src/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml index c652470a..04075460 100644 --- a/schemas/src/resource/manifest.schema.yaml +++ b/schemas/src/resource/manifest.schema.yaml @@ -27,28 +27,82 @@ properties: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + [01]: /reference/schemas/resource/manifest/set?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["schema", "resource"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry schema resource + ``` + + [01]: /reference/schemas/resource/manifest/set?#args # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#command + [01]: /reference/schemas/resource/manifest/schema/property?#command + defaultSnippets: + - label: ' Define without arguments' + markdownDescription: | + Define the `schema` command for the resource when no arguments are required. + body: + executable: ${1:executable_name} + + - label: ' Define with arguments' + markdownDescription: | + Define the `schema` command for the resource when at least one argument is required. + body: + executable: ${1:executable_name} + args: + - ${2:--first-argument} + 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. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/schema/embedded? type: object required: - $schema @@ -63,12 +117,14 @@ properties: # Ensures the DSC Resource is always an object const: object markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true#type + [01]: /reference/schemas/resource/manifest/schema/embedded?#type $schema: # Ensures the DSC Resource always uses a schema we can understand title: DSC Resource instance schema dialect @@ -82,26 +138,43 @@ properties: - http://json-schema.org/draft-07/schema# # VS Code only markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type. DSC only supports JSON Schema Draft 07 and later. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true#type + [01]: /reference/schemas/resource/manifest/schema/embedded?#type markdownEnumDescriptions: - # https://json-schema.org/draft/2020-12/schema - - | - Indicates the resource instance schema adheres to [JSON Schema Draft 2020-12][01]. + - | # https://json-schema.org/draft/2020-12/schema + _Draft 2020-12 (recommended)_ + + > Indicates that the resource instance schema adheres to + > [JSON Schema Draft 2020-12][01]. + > + > This is the latest published draft of JSON Schema and is the draft future drafts + > will be most compatible with. [01]: https://json-schema.org/specification-links.html#2020-12 - # https://json-schema.org/draft/2019-09/schema - - | - Indicates the resource instance schema adheres to [JSON Schema Draft 2019-09][01]. + - | # https://json-schema.org/draft/2019-09/schema + _Draft 2019-09_ + + > Indicates that the resource instance schema adheres to + > [JSON Schema Draft 2019-09][01]. + > + > This is the previous published draft of JSON Schema. It's mostly compatible with + > 2020-12, but less extensible and can't be bundled. [01]: https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8 - # http://json-schema.org/draft-07/schema# - - | - Indicates the resource instance schema adheres to [JSON Schema Draft 07][01]. + - | # http://json-schema.org/draft-07/schema# + _Draft 07_ + + > Indicates that the resource instance schema adheres to [JSON Schema Draft 07][01]. + > + > This is an older published draft of JSON Schema. It's widely used, but incompatible + > with 2019-09 and later. It's less expressive, extensible, maintainable, and isn't + > recommended for new schema definitions. [01]: https://json-schema.org/specification-links.html#draft-7 $id: @@ -113,12 +186,14 @@ properties: type: string format: uri-reference markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the unique ID for the DSC Resource's instance schema. If the instance schema is published to its own public URI, set this keyword to that URI. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#id + [01]: /reference/schemas/resource/manifest/schema/property?#id properties: # Defines the property validation - requires authors to specify at @@ -131,13 +206,15 @@ properties: 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. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#properties + [01]: /reference/schemas/resource/manifest/schema/property?#properties type: object minProperties: 1 unevaluatedProperties: @@ -145,6 +222,112 @@ properties: - $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# + additionalProperties: + defaultSnippets: # VS Code only + - label: ' Define a property' + markdownDescription: Define a new property for the resource instance schema. + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: ${3|boolean,string,integer,number,array,object,null|} + + - label: ' Define a property (boolean)' + markdownDescription: |- + Define a new [boolean][01] property for the resource instance schema, requiring the + value to be either `true` or `false`. + + [01]: https://json-schema.org/understanding-json-schema/reference/boolean.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: boolean + + - label: ' Define a property (string)' + markdownDescription: |- + Define a new [string][01] property for the resource instance schema, requiring the + value to be a blob of text. + + [01]: https://json-schema.org/understanding-json-schema/reference/string.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: string + + - label: ' Define a property (integer)' + markdownDescription: |- + Define a new [integer][01] property for the resource instance schema, requiring the + value to be a number without a fractional part. + + [01]: https://json-schema.org/understanding-json-schema/reference/numeric.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: integer + + - label: ' Define a property (number)' + markdownDescription: |- + Define a new [number][01] property for the resource instance schema, requiring the + value to be a number that may include a fractional part. + + [01]: https://json-schema.org/understanding-json-schema/reference/numeric.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: number + + - label: ' Define a property (array)' + markdownDescription: |- + Define a new [array][01] property for the resource instance schema, requiring the + value to be a list of values. + + [01]: https://json-schema.org/understanding-json-schema/reference/array.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: array + items: + type: ${3|boolean,string,integer,number,array,object,null|} + + - label: ' Define a property (object)' + markdownDescription: |- + Define a new [object][01] property for the resource instance schema, requiring the + value to be a set of key-value pairs. + + [01]: https://json-schema.org/understanding-json-schema/reference/object.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: object + properties: + ${3:propertyName}: + title: ${4:propertyTitle} + description: ${5:explanation of property purpose and usage} + type: ${6|string,integer,number,array,object,null|} + + - label: ' Define a property (enum)' + markdownDescription: |- + Define a new [enum][01] property for the resource instance schema that only accepts + a defined set of values. + + [01]: https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + enum: + - ^${3:"first value"} + - ^${4:"second value"} + + - label: ' Define a property (const)' + markdownDescription: |- + Define a new [const][01] property for the resource instance schema that only + accepts a specific value. + + [01]: https://json-schema.org/understanding-json-schema/reference/generic.html#constant-values + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + const: ^${3:"constant value"} + properties: _ensure: title: 'Standard Property: _ensure' @@ -155,29 +338,37 @@ properties: $ref: ///resource/properties/ensure.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] - - Indicates that the DSC Resource uses the standard `_ensure` property to specify - whether an instance should exist with the `Present` and `Absent` enums. - - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/ensure?view=dsc-3.0&preserveView=true + *** + [_Online Documentation_][01] + *** + + 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. + + [01]: /reference/schemas/resource/properties/ensure? _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. + read-only 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 # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/indesiredstate?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/indesiredstate? _purge: title: 'Standard Property: _purge' description: >- @@ -188,28 +379,41 @@ properties: $ref: ///resource/properties/purge.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/purge?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/purge? _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. + 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. const: $ref: ///resource/properties/rebootRequested.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/rebootrequested?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/rebootrequested? + defaultSnippets: # VS Code only + - label: ' Define an instance property' + markdownDescription: Define a property for the resource instance schema. + body: + ${1:propertyName}: + title: ${2:property title} + description: ${3:explanation of property purpose and usage} + type: ${4|string,integer,number,array,object,null|} url: title: Instance Schema URL description: >- @@ -218,11 +422,13 @@ properties: format: uri # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the URL to the DSC Resource's JSON schema for integrating tools. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#url + [01]: /reference/schemas/resource/manifest/schema/property?#url examples: - command: @@ -260,7 +466,9 @@ examples: # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must validate a JSON blob representing an instance of the DSC Resource. @@ -276,4 +484,53 @@ markdownDescription: | 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/schema/property? + +defaultSnippets: # VS Code only + - label: ' Define as command without arguments' + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Define the resource instance schema as a command when no arguments are required. + + [01]: /reference/schemas/resource/manifest/schema/property?#command + body: + command: + executable: ${1:executable_name} + + - label: ' Define as command with arguments' + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Define the resource instance schema as a command when at least one argument is required. + + [01]: /reference/schemas/resource/manifest/schema/property?#command + body: + command: + executable: ${1:executable_name} + args: + - ${2:--first-argument} + + - label: ' Define as an embedded schema' + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Define the resource instance schema embedded in the manifest. This is the preferred option + for publicly published resources. + + [01]: /reference/schemas/resource/manifest/schema/embedded? + body: + embedded: + ${escape_dollar:$}schema: ${1|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} + type: object + properties: + ${2:name}: + title: ${3:property title} + description: ${4:explanation of property purpose and usage} + type: ${5|string,integer,number,array,object,null|} diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 51a1a1ee..1f3b2415 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -7,12 +7,14 @@ 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. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/set? type: object required: @@ -21,11 +23,55 @@ required: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + [01]: /reference/schemas/resource/manifest/set?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["config", "set"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry config set + ``` + + [01]: /reference/schemas/resource/manifest/set?#args input: $ref: ///definitions/inputKind.yaml - preTest: + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines how DSC should pass input to the command, either as environment variables or JSON + over `stdin`. + + [01]: /reference/schemas/resource/manifest/set?#input + implementsPretest: title: Resource Performs Pre-Test description: >- Defines whether the DSC Resource performs its own test to ensure idempotency when calling the @@ -35,13 +81,15 @@ properties: default: false # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true#pretest + [01]: /reference/schemas/resource/manifest/set?#implementspretest return: description: >- Defines whether the command returns a JSON blob of the DSC Resource's state after the set @@ -49,27 +97,52 @@ properties: $ref: ///definitions/returnKind.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true#return + [01]: /reference/schemas/resource/manifest/set?#return markdownEnumDescriptions: - # 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. + - | # state + _Final state only_ + + > Indicates that the resource returns only the instance's final state after the set + > operation as a JSON blob. + - | # stateAndDiff + _Final state and changed properties_ + + > Indicates that the resource returns the instance's final state and an array of property + > names that the resource modified. examples: - executable: registry args: - config - set - input: stdin - preTest: true - return: state + input: stdin + implementsPretest: true + return: state + +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the `set` command for the resource when no arguments are required. + body: + input: ${1|input,env|} + implementsPretest: ^${2|true,false|} + return: ${3|state,stateAndDiff|} + executable: ${4:executable_name} + + - label: ' Define with arguments' + markdownDescription: | + Define the `set` command for the resource when at least one argument is required. + body: + input: ${1|input,env|} + implementsPretest: ^${2|true,false|} + return: ${3|state,stateAndDiff|} + executable: ${4:executable_name} + args: + - ${5:--first-argument} diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index 89093fbf..99e68138 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -7,12 +7,14 @@ 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. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/test? type: object @@ -22,10 +24,54 @@ required: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + [01]: /reference/schemas/resource/manifest/set?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["config", "test"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry config test + ``` + + [01]: /reference/schemas/resource/manifest/set?#args input: $ref: ///definitions/inputKind.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines how DSC should pass input to the command, either as environment variables or JSON + over `stdin`. + + [01]: /reference/schemas/resource/manifest/set?#input return: title: Test Command Return Type description: >- @@ -34,20 +80,24 @@ properties: $ref: ///definitions/returnKind.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserveView=true#return + [01]: /reference/schemas/resource/manifest/test?#return markdownEnumDescriptions: - # 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. + - | # state + _Actual state only_ + + > Indicates that the resource returns only the instance's actual state as a JSON blob. + - | # stateAndDiff + _Actual state and differing properties_ + + > Indicates that the resource returns the instance's actual state and an array of + > property names that are out of the desired state. examples: - executable: registry @@ -56,3 +106,22 @@ examples: - test input: stdin return: state + +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the `test` command for the resource when no arguments are required. + body: + input: ${1|input,env|} + return: ${2|state,stateAndDiff|} + executable: ${3:executable_name} + + - label: ' Define with arguments' + markdownDescription: | + Define the `test` command for the resource when at least one argument is required. + body: + input: ${1|input,env|} + return: ${2|state,stateAndDiff|} + executable: ${3:executable_name} + args: + - ${4:--first-argument} diff --git a/schemas/src/resource/manifest.validate.yaml b/schemas/src/resource/manifest.validate.yaml index 87986188..f40bdacc 100644 --- a/schemas/src/resource/manifest.validate.yaml +++ b/schemas/src/resource/manifest.validate.yaml @@ -8,12 +8,14 @@ description: >- mandatory for DSC Group Resources. It's ignored for all other DSC Resources. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/validate? type: object required: @@ -21,11 +23,61 @@ required: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + [01]: /reference/schemas/resource/manifest/set?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["config", "validate"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry config validate + ``` + + [01]: /reference/schemas/resource/manifest/set?#args examples: - executable: dsc args: - config - validate + +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the `validate` command for the resource when no arguments are required. + body: + executable: ${1:executable_name} + + - label: ' Define with arguments' + markdownDescription: | + Define the `validate` command for the resource when at least one argument is required. + body: + executable: ${1:executable_name} + args: + - ${2:--first-argument} diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index 3c6cdb8b..940b01f9 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -7,7 +7,9 @@ description: >- Defines the information DSC and integrating require to process and call a command-based DSC Resource. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the information DSC and integrating require to process and call a command-based DSC Resource. For DSC to use a manifest on a system, the manifest file must: @@ -16,37 +18,179 @@ markdownDescription: | # VS Code only 1. Follow the naming convention `.dsc.resource.json`. 1. Be valid for this schema. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/root? + +defaultSnippets: + - label: ' Define a resource' + markdownDescription: |- + Defines a standard resource that: + + - Can get the current state of an instance + - Can set an instance to the desired state + - Relies on DSC's synthetic testing to determine whether an instance is in the desired state + - Defines an embedded JSON schema. + body: + $schema: ///bundled/resource/manifest.yaml + type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' + version: '${3:0.1.0}' + description: ${4:Synopsis for the resource's purpose} + get: + executable: ${5:executable name} + args: ['${6:argument}'] + input: ${7:stdin} + set: + executable: ${8:executable name} + args: ['${9:argument}'] + input: ${10:stdin} + implementsPretest: ^${11:false} + return: ${12:state} + schema: + embedded: + ${escape_dollar:$}schema: ${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} + type: object + properties: + ${14:name}: + title: ${15:property title} + description: ${16:explanation of property purpose and usage} + type: ${17|string,integer,number,array,object,null|} + + - label: ' Define a resource (group)' + markdownDescription: |- + Defines a group resource that expects a list of resource instances and operates on them. + body: + $schema: ///bundled/resource/manifest.yaml + type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' + version: '${3:0.1.0}' + description: ${4:Synopsis for the resource's purpose} + get: + executable: ${5:executable name} + args: ['${6:argument}'] + input: ${7:stdin} + test: + executable: ${8:executable name} + args: ['${9:argument}'] + input: ${10:stdin} + return: ${12:state} + set: + executable: ${13:executable name} + args: ['${14:argument}'] + input: ${15:stdin} + implementsPretest: ^${16:false} + return: ${17:state} + schema: + embedded: + ${escape_dollar:$}schema: ${18|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} + type: object + properties: + resources: + title: ${19:Resources} + description: ${20:Defines a list of resource instances to process} + type: array + items: + ${escape_dollar:$}ref: ///config/document.resource.json + ${21:name}: + title: ${22:property title} + description: ${23:explanation of property purpose and usage} + type: ${24|string,integer,number,array,object,null|} + + - label: ' Define a resource (provider)' + markdownDescription: |- + Defines a provider resource that enables users to define non-command-based DSC Resources in + the configuration. + body: + $schema: ///bundled/resource/manifest.yaml + type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' + version: '${3:0.1.0}' + description: ${4:Synopsis for the resource's purpose} + get: + executable: ${5:executable name} + args: ['${6:argument}'] + input: ${7:stdin} + test: + executable: ${8:executable name} + args: ['${9:argument}'] + input: ${10:stdin} + return: ${12:state} + set: + executable: ${13:executable name} + args: ['${14:argument}'] + input: ${15:stdin} + implementsPretest: ^${16:false} + return: ${17:state} + provider: + config: ${18|full,sequence|} + list: + executable: ${19:executable name} + args: ['${20:argument}'] + schema: + embedded: + ${escape_dollar:$}schema: ${23|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} + type: object + properties: + resources: + title: ${24:Resources} + description: ${25:Defines a list of resource instances to process} + type: array + items: + ${escape_dollar:$}ref: ///config/document.resource.json + ${26:name}: + title: ${27:property title} + description: ${28:explanation of property purpose and usage} + type: ${29|string,integer,number,array,object,null|} + + - label: ' Define a resource (assertion-only)' + markdownDescription: |- + Defines an assertion resource that can get the current state of an instance but not configure + it. By default, the resource relies on DSC's synthetic testing feature. If the resource + implements the `test` operation itself, define the `test` property. + body: + $schema: ///bundled/resource/manifest.yaml + type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' + version: '${3:0.1.0}' + description: ${4:Synopsis for the resource's purpose} + get: + executable: ${5:executable name} + args: ['${6:argument}'] + input: ${7:stdin} + schema: + embedded: + ${escape_dollar:$}schema: ${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} + type: object + properties: + ${14:name}: + title: ${15:property title} + description: ${16:explanation of property purpose and usage} + type: ${17|string,integer,number,array,object,null|} type: object required: - - manifestVersion + - $schema - type - version - get properties: - manifestVersion: - title: Manifest Version + $schema: + title: Manifest Schema description: >- - The semver of the DSC Resource manifest schema to validate this manifest with. - $ref: ///definitions/semver.yaml - enums: - - '1.0' + This property must be the canonical URL of the Command-based DSC Resource Manifest schema + that the manifest is implemented for. + type: string + format: uri + enum: + - ///bundled/resource/manifest.yaml # VS Code Only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** - The semver of the DSC Resource manifest schema to validate this manifest with. + This property must be the canonical URL of the Command-based DSC Resource Manifest schema + that the manifest is implemented for. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#manifestversion + [01]: /reference/schemas/resource/manifest/root?#schema markdownEnumDescriptions: - # 1.0 - - | - > [Online Documentation][01] - - The initial release version of the manifest schema. - - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true + - | # 1.0 + _Initial release_ type: $ref: ///definitions/resourceType.yaml version: @@ -56,12 +200,14 @@ properties: not the version of the application it manages. $ref: ///definitions/semver.yaml markdownDescription: | # VS Code only - > [Online Documentation][03] + *** + [_Online Documentation_][01] + *** - The semantic version ([semver][01]) of the DSC Resource. This version identifies the DSC + The semantic version ([semver][02]) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages. - This value uses the [suggested regular expression][02] to validate whether the string is valid + This value uses the [suggested regular expression][03] to validate whether the string is valid semver. This is the same pattern, made multi-line for easier readability: ```regex @@ -76,30 +222,34 @@ properties: 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. - [01]: https://semver.org/ - [02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string - [03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#version + [01]: /reference/schemas/resource/manifest/root?#version + [02]: https://semver.org/ + [03]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string description: title: Resource Description description: >- A short synopsis of the DSC Resource's purpose. type: string markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a short synopsis of the DSC Resource's purpose. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#description-1 + [01]: /reference/schemas/resource/manifest/root?#description-1 tags: title: Tags description: >- Defines a list of searchable terms for the resource. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a list of searchable terms for the resource. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#tags + [01]: /reference/schemas/resource/manifest/root?#tags type: array uniqueItems: true items: @@ -130,14 +280,6 @@ properties: 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. - markdownDescription: | - > [Online Documentation][01] - - 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. - - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#exitcodes type: object propertyNames: pattern: "^[0-9]+$" @@ -156,5 +298,23 @@ properties: '2': Invalid input '3': Registry error '4': JSON serialization failed + # VS Code only + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + 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. + + [01]: /reference/schemas/resource/manifest/root?#exitcodes + defaultSnippets: + - label: ' Defined exit codes' + description: Defines exit codes with semantic meaning for the resource. + body: + '0': Success + ${1:first exit code number}: ${2:first exit code meaning} + ${3:second exit code number}: ${4:second exit code meaning} schema: $ref: ///resource/manifest.schema.yaml diff --git a/schemas/src/resource/properties/ensure.yaml b/schemas/src/resource/properties/ensure.yaml index 07eb9eb1..06024b27 100644 --- a/schemas/src/resource/properties/ensure.yaml +++ b/schemas/src/resource/properties/ensure.yaml @@ -13,11 +13,21 @@ enum: # VS Code Only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Indicates whether the DSC Resource instance should exist. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/ensure?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/ensure? markdownEnumDescriptions: - - Indicates that the instance shouldn't exist. - - Indicates that the instance should exist. + - | # Absent + _Instance shouldn't exist._ + + > If the desired state for `_ensure` is `absent` and the instance exists, the resource removes + > the instance during the `set` operation. + - | # Present + _Instance should exist._ + + > If the desired state for `_ensure` is `present` and the instance doesn't exist, the resource + > adds or creates the instance during the `set` operation. diff --git a/schemas/src/resource/properties/inDesiredState.yaml b/schemas/src/resource/properties/inDesiredState.yaml index e2c35430..a696cefc 100644 --- a/schemas/src/resource/properties/inDesiredState.yaml +++ b/schemas/src/resource/properties/inDesiredState.yaml @@ -14,9 +14,11 @@ readOnly: true # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Indicates whether the instance is in the desired state. This property is only returned by the `test` method. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/indesiredstate?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/indesiredstate? diff --git a/schemas/src/resource/properties/purge.yaml b/schemas/src/resource/properties/purge.yaml index 77c57b70..9ba4330e 100644 --- a/schemas/src/resource/properties/purge.yaml +++ b/schemas/src/resource/properties/purge.yaml @@ -15,10 +15,12 @@ writeOnly: true # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** 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. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/purge?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/purge? diff --git a/schemas/src/resource/properties/rebootRequested.yaml b/schemas/src/resource/properties/rebootRequested.yaml index d2044748..8d32f720 100644 --- a/schemas/src/resource/properties/rebootRequested.yaml +++ b/schemas/src/resource/properties/rebootRequested.yaml @@ -13,8 +13,10 @@ readOnly: true # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Indicates that the set operation requires a reboot before it's fully complete. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/rebootrequested?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/rebootrequested?