diff --git a/.vscode/settings.json b/.vscode/settings.json index 1411786d..36b80c4d 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -11,5 +11,15 @@ "./test_group_resource/Cargo.toml", "./y2j/Cargo.toml" ], - "rust-analyzer.showUnlinkedFileNotification": true + "rust-analyzer.showUnlinkedFileNotification": true, + "json.schemas": [ + { + "fileMatch": ["**/*.dsc.resource.json"], + "url": "/schemas/2023/08/bundled/resource/manifest.vscode.json" + } + ], + "yaml.schemas": { + "schemas/2023/08/bundled/config/document.vscode.json": "**.dsc.{yaml,yml,config.yaml,config.yml}", + "schemas/2023/08/bundled/resource/manifest.vscode.json": "**.dsc.resource.{yaml,yml}" + } } \ No newline at end of file diff --git a/schemas/2023/08/bundled/config/document.json b/schemas/2023/08/bundled/config/document.json index 55b7b467..e2ac11ee 100644 --- a/schemas/2023/08/bundled/config/document.json +++ b/schemas/2023/08/bundled/config/document.json @@ -1,226 +1,352 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", - "title": "DSC Configuration Document schema", - "description": "Describes a valid DSC Configuration Document.", - "type": "object", - "required": [ - "$schema", - "resources" - ], - "properties": { - "$schema": { - "title": "Schema", - "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", - "type": "string", - "format": "uri", - "enum": [ - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" - ] - }, - "parameters": { - "title": "DSC Configuration document parameters", - "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", - "type": "object", - "additionalProperties": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" - } - }, - "variables": { - "title": "Configuration variables", - "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", - "type": "object" - }, - "resources": { - "title": "DSC Configuration document resources", - "description": "Defines a list of DSC Resource instances for the configuration to manage.", - "type": "array", - "minItems": 1, - "items": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" - } - }, - "metadata": { - "title": "Configuration metadata", - "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", - "type": "object" - } - }, - "$defs": { - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", - "title": "Parameter", - "description": "Defines a runtime option for a DSC Configuration Document.", - "type": "object", - "required": "type", - "properties": { - "type": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" - }, - "defaultValue": { - "title": "Default value", - "description": "Defines the default value for the parameter.", - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" - }, - "allowedValues": { - "title": "Allowed values", - "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", - "type": "array", - "items": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" - } - }, - "description": { - "title": "Parameter description", - "description": "Defines a synopsis for the parameter explaining its purpose.", - "type": "string" - }, - "metadata": { - "title": "Parameter metadata", - "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", - "type": "object" - } - }, - "allOf": [ - { - "if": { - "properties": { - "type": { - "const": "int" - } - } - }, - "then": { - "minValue": { - "title": "Minimum value", - "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", - "type": "integer" - }, - "maxValue": { - "title": "Maximum value", - "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", - "type": "integer" - } - } - }, - { - "if": { - "oneOf": [ - { - "properties": { - "type": { - "const": "string" - } - } - }, - { - "properties": { - "type": { - "const": "securestring" - } - } - }, - { - "properties": { - "type": { - "const": "array" - } - } - } - ] - }, - "then": { - "minLength": { - "title": "Minimum length", - "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", - "type": "integer", - "minimum": 0 - }, - "maxLength": { - "title": "Maximum length", - "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", - "type": "integer", - "minimum": 0 - } - } - } - ] - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", - "title": "DSC Resource instance", - "type": "object", - "required": [ - "type", - "name" - ], - "properties": { - "type": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" - }, - "name": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" - }, - "dependsOn": { - "title": "Instance depends on", - "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", - "type": "array", - "items": { - "type": "string", - "uniqueItems": true, - "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" - } - }, - "properties": { - "title": "Managed instance properties", - "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", - "type": "object" - } - } - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", - "title": "Data Types", - "description": "Defines the data type for the value.", - "type": "string", - "enum": [ - "string", - "securestring", - "int", - "bool", - "object", - "secureobject", - "array" - ] - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", - "type": [ - "string", - "integer", - "object", - "array", - "boolean" - ] - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", - "title": "Instance name", - "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", - "type": "string" - } - } +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": "type", + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "properties": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "properties": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "string" + }, + "allowedValues": { + "items": { + "type": "string" + } + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "object" + } + } + }, + { + "properties": { + "type": { + "const": "secureobject" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "object" + }, + "allowedValues": { + "items": { + "type": "object" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "integer" + }, + "allowedValues": { + "items": { + "type": "integer" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "array" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "array" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "bool" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "boolean" + }, + "allowedValues": { + "items": { + "type": "boolean" + } + } + } + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", + "title": "DSC Resource instance", + "description": "Defines an instance of a DSC Resource in a configuration.", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the parameter value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. As-written, values must be one of\nthose on this list - the schema definition for dataType excludes `null` and\nnumbers with fractional parts, like `3.5`.\n", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + } + } } diff --git a/schemas/2023/08/bundled/config/document.vscode.json b/schemas/2023/08/bundled/config/document.vscode.json index 1006c4d8..ae7e5bf9 100644 --- a/schemas/2023/08/bundled/config/document.vscode.json +++ b/schemas/2023/08/bundled/config/document.vscode.json @@ -1,244 +1,547 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", - "title": "DSC Configuration Document schema", - "description": "Describes a valid DSC Configuration Document.", - "type": "object", - "required": [ - "$schema", - "resources" - ], - "properties": { - "$schema": { - "title": "Schema", - "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", - "type": "string", - "format": "uri", - "enum": [ - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" - ] - }, - "parameters": { - "title": "DSC Configuration document parameters", - "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" - } - }, - "variables": { - "title": "Configuration variables", - "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", - "type": "object" - }, - "resources": { - "title": "DSC Configuration document resources", - "description": "Defines a list of DSC Resource instances for the configuration to manage.", - "type": "array", - "minItems": 1, - "items": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" - } - }, - "metadata": { - "title": "Configuration metadata", - "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", - "type": "object" - } - }, - "$defs": { - "PowerShell": { - "DSC": { - "main": { - "schemas": { - "2023": { - "08": { - "config": { - "document.parameter.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", - "title": "Parameter", - "description": "Defines a runtime option for a DSC Configuration Document.", - "type": "object", - "required": "type", - "properties": { - "type": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" - }, - "defaultValue": { - "title": "Default value", - "description": "Defines the default value for the parameter.", - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" - }, - "allowedValues": { - "title": "Allowed values", - "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", - "type": "array", - "items": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" - } - }, - "description": { - "title": "Parameter description", - "description": "Defines a synopsis for the parameter explaining its purpose.", - "type": "string" - }, - "metadata": { - "title": "Parameter metadata", - "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", - "type": "object" - } - }, - "allOf": [ - { - "if": { - "properties": { - "type": { - "const": "int" - } - } - }, - "then": { - "minValue": { - "title": "Minimum value", - "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", - "type": "integer" - }, - "maxValue": { - "title": "Maximum value", - "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", - "type": "integer" - } - } - }, - { - "if": { - "oneOf": [ - { - "properties": { - "type": { - "const": "string" - } - } - }, - { - "properties": { - "type": { - "const": "securestring" - } - } - }, - { - "properties": { - "type": { - "const": "array" - } - } - } - ] - }, - "then": { - "minLength": { - "title": "Minimum length", - "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", - "type": "integer", - "minimum": 0 - }, - "maxLength": { - "title": "Maximum length", - "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", - "type": "integer", - "minimum": 0 - } - } - } - ] - }, - "document.resource.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", - "title": "DSC Resource instance", - "type": "object", - "required": [ - "type", - "name" - ], - "properties": { - "type": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" - }, - "name": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" - }, - "dependsOn": { - "title": "Instance depends on", - "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", - "type": "array", - "items": { - "type": "string", - "uniqueItems": true, - "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" - } - }, - "properties": { - "title": "Managed instance properties", - "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", - "type": "object" - } - } - } - }, - "definitions": { - "parameters": { - "dataTypes.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", - "title": "Data Types", - "description": "Defines the data type for the value.", - "type": "string", - "enum": [ - "string", - "securestring", - "int", - "bool", - "object", - "secureobject", - "array" - ] - }, - "validValueTypes.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", - "type": [ - "string", - "integer", - "object", - "array", - "boolean" - ] - } - }, - "resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "instanceName.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", - "title": "Instance name", - "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", - "type": "string" - } - } - } - } - } - } - } - } - } +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "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", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ], + "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", + "markdownEnumDescriptions": [ + "Indicates that the configuration document adheres to the `2023/08` schema." + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + }, + "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", + "defaultSnippets": [ + { + "label": "New Parameter", + "description": "Defines a new runtime option for the configuration.", + "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.", + "body": { + "${1:integerParameterId}": { + "type": "int", + "defaultValue": "$2", + "description": "$3", + "minValue": "$4", + "maxValue": "$5" + } + } + } + ] + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object", + "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", + "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.", + "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.", + "body": { + "${1:variableName}": [ + "${2:firstValue}", + "${3:secondValue}" + ] + } + } + ] + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + }, + "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" + }, + "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", + "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.", + "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.", + "body": { + "${1:metadataName}": [ + "${2:firstValue}", + "${3:secondValue}" + ] + } + } + ] + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2023": { + "08": { + "config": { + "document.parameter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "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", + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", + "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" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + }, + "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" + }, + "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" + }, + "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", + "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.", + "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.", + "body": { + "${1:metadataName}": [ + "${2:firstValue}", + "${3:secondValue}" + ] + } + } + ] + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "properties": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer", + "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" + }, + "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" + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "properties": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0, + "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" + }, + "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" + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "string" + }, + "allowedValues": { + "items": { + "type": "string" + } + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "object" + } + } + }, + { + "properties": { + "type": { + "const": "secureobject" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "object" + }, + "allowedValues": { + "items": { + "type": "object" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "integer" + }, + "allowedValues": { + "items": { + "type": "integer" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "array" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "array" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "bool" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "boolean" + }, + "allowedValues": { + "items": { + "type": "boolean" + } + } + } + } + } + ] + }, + "document.resource.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", + "title": "DSC Resource instance", + "description": "Defines an instance of a DSC Resource in a configuration.", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "name": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$", + "patternErrorMessage": "Invalid value, must be a value like `[]`, such as `[Microsoft/OSInfo]Foo`.\n\nThe `` and `` should be the fully qualified type of the resource and its\nfriendly name in the configuration.\n" + }, + "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 value of another DSC Resource\ninstance's `name` property.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=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": "> [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", + "defaultSnippets": [ + { + "label": "New resource instance", + "description": "Defines a new instance of a DSC Resource for the configuration", + "body": { + "type": "$1", + "name": "$2", + "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.", + "body": { + "type": "$1", + "name": "$2", + "dependsOn": "['[${3:dependencyType}]${4:dependencyName}']", + "properties": { + "${5:propertyName}": "${6:propertyValue}" + } + } + } + ] + } + }, + "definitions": { + "parameters": { + "dataTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the parameter value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "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", + "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" + ] + }, + "validValueTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. As-written, values must be one of\nthose on this list - the schema definition for dataType excludes `null` and\nnumbers with fractional parts, like `3.5`.\n", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + } + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", + "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", + "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": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string", + "markdownDescription": "> [Online Documentation][01]\n\nThe short, human-readable name for a DSC Resource instance. Must be unique within a DSC\nConfiguration document.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#name\n" + } + } + } + } + } + } + } + } + } } diff --git a/schemas/2023/08/bundled/outputs/resource/get.json b/schemas/2023/08/bundled/outputs/resource/get.json index 8ed6684d..f1b85eb6 100644 --- a/schemas/2023/08/bundled/outputs/resource/get.json +++ b/schemas/2023/08/bundled/outputs/resource/get.json @@ -4,9 +4,7 @@ "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 18cd2107..be2031ac 100644 --- a/schemas/2023/08/bundled/outputs/resource/list.json +++ b/schemas/2023/08/bundled/outputs/resource/list.json @@ -34,17 +34,13 @@ "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", @@ -102,14 +98,14 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", "type": "string", "title": "Semantic Version", - "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "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/resource/manifest.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", "title": "Command-based DSC Resource Manifest", - "description": "Defines a valid command-based DSC Resource.", + "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.", "type": "object", "required": [ "manifestVersion", @@ -139,7 +135,7 @@ }, "tags": { "title": "Tags", - "description": "An array of short strings used to search for DSC Resources.", + "description": "Defines a list of searchable terms for the resource.", "type": "array", "uniqueItems": true, "items": { @@ -173,6 +169,18 @@ "^[0-9]+$": { "type": "string" } + }, + "unevaluatedProperties": false, + "default": { + "0": "Success", + "1": "Error" + }, + "examples": { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" } }, "schema": { @@ -197,7 +205,20 @@ "input": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" } - } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -229,6 +250,16 @@ "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } + }, + "examples": { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "preTest": true, + "return": "state" } }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json": { @@ -256,6 +287,15 @@ "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } + }, + "examples": { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" } }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json": { @@ -272,6 +312,13 @@ "args": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" } + }, + "examples": { + "executable": "dsc", + "args": [ + "config", + "validate" + ] } }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json": { @@ -308,6 +355,19 @@ "sequence" ] } + }, + "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": { @@ -367,13 +427,13 @@ }, "$id": { "title": "DSC Resource instance schema ID", - "description": "Defines the unique ID for the DSC Resource's instance schema.", + "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" }, "properties": { "title": "Instance Properties", - "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "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.", "type": "object", "minProperties": 1, "unevaluatedProperties": { @@ -428,7 +488,74 @@ "type": "string", "format": "uri" } - } + }, + "examples": [ + { + "command": { + "executable": "registry", + "args": "schema" + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -468,7 +595,8 @@ "state", "stateAndDiff" ], - "default": "state" + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", diff --git a/schemas/2023/08/bundled/resource/manifest.json b/schemas/2023/08/bundled/resource/manifest.json index 6ebcc1d0..027d58fa 100644 --- a/schemas/2023/08/bundled/resource/manifest.json +++ b/schemas/2023/08/bundled/resource/manifest.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", "title": "Command-based DSC Resource Manifest", - "description": "Defines a valid command-based DSC Resource.", + "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.", "type": "object", "required": [ "manifestVersion", @@ -15,9 +15,7 @@ "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" - ] + "enums": "1.0" }, "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" @@ -34,7 +32,7 @@ }, "tags": { "title": "Tags", - "description": "An array of short strings used to search for DSC Resources.", + "description": "Defines a list of searchable terms for the resource.", "type": "array", "uniqueItems": true, "items": { @@ -69,17 +67,18 @@ "type": "string" } }, - "examples": [ - { - "exitCodes": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } - } - ] + "unevaluatedProperties": false, + "default": { + "0": "Success", + "1": "Error" + }, + "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" @@ -91,7 +90,7 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", "type": "string", "title": "Semantic Version", - "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "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": { @@ -119,7 +118,20 @@ "input": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" } - } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -151,6 +163,16 @@ "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } + }, + "examples": { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "preTest": true, + "return": "state" } }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json": { @@ -178,6 +200,15 @@ "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } + }, + "examples": { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" } }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json": { @@ -194,6 +225,13 @@ "args": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" } + }, + "examples": { + "executable": "dsc", + "args": [ + "config", + "validate" + ] } }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json": { @@ -230,6 +268,19 @@ "sequence" ] } + }, + "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": { @@ -289,13 +340,13 @@ }, "$id": { "title": "DSC Resource instance schema ID", - "description": "Defines the unique ID for the DSC Resource's instance schema.", + "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" }, "properties": { "title": "Instance Properties", - "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "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.", "type": "object", "minProperties": 1, "unevaluatedProperties": { @@ -350,7 +401,74 @@ "type": "string", "format": "uri" } - } + }, + "examples": [ + { + "command": { + "executable": "registry", + "args": "schema" + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -390,7 +508,8 @@ "state", "stateAndDiff" ], - "default": "state" + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json index d9e6cdc0..73cda898 100644 --- a/schemas/2023/08/bundled/resource/manifest.vscode.json +++ b/schemas/2023/08/bundled/resource/manifest.vscode.json @@ -2,7 +2,8 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", "title": "Command-based DSC Resource Manifest", - "description": "Defines a valid command-based DSC Resource.", + "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", "type": "object", "required": [ "manifestVersion", @@ -17,6 +18,10 @@ "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", "enums": [ "1.0" + ], + "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", + "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" ] }, "type": { @@ -25,21 +30,25 @@ "version": { "title": "Resource Semantic Version", "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + "$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" }, "description": { "title": "Resource Description", "description": "A short synopsis of the DSC Resource's purpose.", - "type": "string" + "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" }, "tags": { "title": "Tags", - "description": "An array of short strings used to search for DSC Resources.", + "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", "type": "array", "uniqueItems": true, "items": { "type": "string", - "pattern": "^\\w+$" + "pattern": "^\\w+$", + "patternErrorMessage": "Invalid tag. Tags must be a string of alphanumeric characters and underscores. No other\ncharacters are permitted.\n" } }, "get": { @@ -60,24 +69,29 @@ "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]+$" + "pattern": "^[0-9]+$", + "patternErrorMessage": "Invalid exit code. Must be a string representing an integer greater than or equal to `0`.\n" }, "patternProperties": { "^[0-9]+$": { "type": "string" } }, + "unevaluatedProperties": false, + "default": { + "0": "Success", + "1": "Error" + }, "examples": [ { - "exitCodes": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" } ] }, @@ -98,8 +112,10 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", "type": "string", "title": "Semantic Version", - "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" + "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", @@ -107,14 +123,17 @@ "title": "DSC Resource fully qualified type name", "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + "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", + "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" }, "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" + "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" }, "commandArgs.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -124,7 +143,8 @@ "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", @@ -136,7 +156,12 @@ "args", "stdin" ], - "default": "args" + "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" + ] }, "returnKind.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -147,7 +172,8 @@ "state", "stateAndDiff" ], - "default": "state" + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." } }, "resource": { @@ -156,8 +182,11 @@ "$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/provider?view=dsc-3.0&preserveView=true\n", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -168,13 +197,27 @@ "input": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" } - } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ] }, "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", "type": "object", "required": [ "executable", @@ -194,19 +237,38 @@ "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 + "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#pretest\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" + "$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", + "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" + ] } - } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "preTest": true, + "return": "state" + } + ] }, "manifest.test.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json", "title": "Test Method", "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", + "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", "type": "object", "required": [ "executable", @@ -225,17 +287,36 @@ "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" + "$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", + "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" + ] } - } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] }, "manifest.validate.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json", "title": "Validate Method", "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", + "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", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -243,13 +324,23 @@ "args": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" } - } + }, + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] }, "manifest.provider.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json", "title": "Provider", "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", + "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", "type": "object", "required": [ "list", @@ -259,8 +350,11 @@ "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", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -277,9 +371,29 @@ "enum": [ "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", + "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" ] } - } + }, + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } + } + ] }, "manifest.schema.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -289,10 +403,14 @@ "type": "object", "oneOf": [ { - "required": "command" + "required": [ + "command" + ] }, { - "required": "embedded" + "required": [ + "embedded" + ] } ], "properties": { @@ -300,7 +418,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": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -308,11 +428,13 @@ "args": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" } - } + }, + "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" }, "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", "type": "object", "required": [ "$schema", @@ -323,7 +445,8 @@ "type": { "title": "Instance Type", "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", - "const": "object" + "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" }, "$schema": { "title": "DSC Resource instance schema dialect", @@ -334,17 +457,25 @@ "https://json-schema.org/draft/2020-12/schema", "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", + "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" ] }, "$id": { "title": "DSC Resource instance schema ID", - "description": "Defines the unique ID for the DSC Resource's instance schema.", + "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" + "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" }, "properties": { "title": "Instance Properties", - "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "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", "type": "object", "minProperties": 1, "unevaluatedProperties": { @@ -366,28 +497,32 @@ "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" - } + }, + "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" }, "_inDesiredState": { "title": "Standard Property: _inDesiredState", "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" - } + }, + "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" }, "_purge": { "title": "Standard Property: _purge", "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" - } + }, + "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" }, "_rebootRequested": { "title": "Standard property: _rebootRequested", "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" - } + }, + "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" } } } @@ -397,9 +532,80 @@ "title": "Instance Schema URL", "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", "type": "string", - "format": "uri" + "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" } - } + }, + "examples": [ + { + "command": { + "executable": "registry", + "args": [ + "schema" + ] + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ], + "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" } } } diff --git a/schemas/2023/08/config/document.json b/schemas/2023/08/config/document.json index 9b9ba5a3..8078b2ba 100644 --- a/schemas/2023/08/config/document.json +++ b/schemas/2023/08/config/document.json @@ -1,49 +1,47 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", - "title": "DSC Configuration Document schema", - "description": "Describes a valid DSC Configuration Document.", - "type": "object", - "required": [ - "$schema", - "resources" - ], - "properties": { - "$schema": { - "title": "Schema", - "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", - "type": "string", - "format": "uri", - "enum": [ - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" - ] - }, - "parameters": { - "title": "DSC Configuration document parameters", - "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", - "type": "object", - "additionalProperties": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" - } - }, - "variables": { - "title": "Configuration variables", - "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", - "type": "object" - }, - "resources": { - "title": "DSC Configuration document resources", - "description": "Defines a list of DSC Resource instances for the configuration to manage.", - "type": "array", - "minItems": 1, - "items": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" - } - }, - "metadata": { - "title": "Configuration metadata", - "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", - "type": "object" - } - } +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + } } diff --git a/schemas/2023/08/config/document.parameter.json b/schemas/2023/08/config/document.parameter.json index 26b606a1..86b21705 100644 --- a/schemas/2023/08/config/document.parameter.json +++ b/schemas/2023/08/config/document.parameter.json @@ -4,9 +4,7 @@ "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" @@ -45,15 +43,17 @@ } }, "then": { - "minValue": { - "title": "Minimum value", - "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", - "type": "integer" - }, - "maxValue": { - "title": "Maximum value", - "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", - "type": "integer" + "properties": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } } } }, @@ -84,17 +84,141 @@ ] }, "then": { - "minLength": { - "title": "Minimum length", - "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", - "type": "integer", - "minimum": 0 - }, - "maxLength": { - "title": "Maximum length", - "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", - "type": "integer", - "minimum": 0 + "properties": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "string" + }, + "allowedValues": { + "items": { + "type": "string" + } + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "object" + } + } + }, + { + "properties": { + "type": { + "const": "secureobject" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "object" + }, + "allowedValues": { + "items": { + "type": "object" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "integer" + }, + "allowedValues": { + "items": { + "type": "integer" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "array" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "array" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "bool" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "boolean" + }, + "allowedValues": { + "items": { + "type": "boolean" + } + } } } } diff --git a/schemas/2023/08/config/document.resource.json b/schemas/2023/08/config/document.resource.json index 4a0bebb9..f35fa817 100644 --- a/schemas/2023/08/config/document.resource.json +++ b/schemas/2023/08/config/document.resource.json @@ -2,6 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", "title": "DSC Resource instance", + "description": "Defines an instance of a DSC Resource in a configuration.", "type": "object", "required": [ "type", diff --git a/schemas/2023/08/definitions/parameters/dataTypes.json b/schemas/2023/08/definitions/parameters/dataTypes.json index 0a3951dc..3c0033fd 100644 --- a/schemas/2023/08/definitions/parameters/dataTypes.json +++ b/schemas/2023/08/definitions/parameters/dataTypes.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", "title": "Data Types", - "description": "Defines the data type for the value.", + "description": "Defines the data type for the parameter value.", "type": "string", "enum": [ "string", diff --git a/schemas/2023/08/definitions/semver.json b/schemas/2023/08/definitions/semver.json index 6e19aa65..24d89afc 100644 --- a/schemas/2023/08/definitions/semver.json +++ b/schemas/2023/08/definitions/semver.json @@ -3,7 +3,6 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", "type": "string", "title": "Semantic Version", - "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", - "$comment": "This pattern comes from the semver website's FAQ:\n\nhttps://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n\nIt's the suggested regex pattern for JavaScript.\n\nThis is the same pattern, made multi-line for easier readability.\n\n```\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n" + "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-]+)*))?$" } diff --git a/schemas/2023/08/outputs/resource/get.json b/schemas/2023/08/outputs/resource/get.json index 00a30602..9c191c86 100644 --- a/schemas/2023/08/outputs/resource/get.json +++ b/schemas/2023/08/outputs/resource/get.json @@ -4,9 +4,7 @@ "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 13b4a509..88eada11 100644 --- a/schemas/2023/08/outputs/resource/list.json +++ b/schemas/2023/08/outputs/resource/list.json @@ -34,17 +34,13 @@ "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.get.json b/schemas/2023/08/resource/manifest.get.json index 351aa81d..8ccfa99b 100644 --- a/schemas/2023/08/resource/manifest.get.json +++ b/schemas/2023/08/resource/manifest.get.json @@ -4,9 +4,7 @@ "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 07f125eb..366788f1 100644 --- a/schemas/2023/08/resource/manifest.json +++ b/schemas/2023/08/resource/manifest.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", "title": "Command-based DSC Resource Manifest", - "description": "Defines a valid command-based DSC Resource.", + "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.", "type": "object", "required": [ "manifestVersion", @@ -15,9 +15,7 @@ "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" - ] + "enums": "1.0" }, "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" @@ -34,7 +32,7 @@ }, "tags": { "title": "Tags", - "description": "An array of short strings used to search for DSC Resources.", + "description": "Defines a list of searchable terms for the resource.", "type": "array", "uniqueItems": true, "items": { @@ -69,17 +67,18 @@ "type": "string" } }, - "examples": [ - { - "exitCodes": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } - } - ] + "unevaluatedProperties": false, + "default": { + "0": "Success", + "1": "Error" + }, + "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 efbcbcf3..86f51156 100644 --- a/schemas/2023/08/resource/manifest.provider.json +++ b/schemas/2023/08/resource/manifest.provider.json @@ -13,9 +13,7 @@ "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" @@ -35,19 +33,17 @@ ] } }, - "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 11145f7e..29ad74b5 100644 --- a/schemas/2023/08/resource/manifest.schema.json +++ b/schemas/2023/08/resource/manifest.schema.json @@ -6,14 +6,10 @@ "type": "object", "oneOf": [ { - "required": [ - "command" - ] + "required": "command" }, { - "required": [ - "embedded" - ] + "required": "embedded" } ], "properties": { @@ -21,9 +17,7 @@ "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" @@ -61,13 +55,13 @@ }, "$id": { "title": "DSC Resource instance schema ID", - "description": "Defines the unique ID for the DSC Resource's instance schema.", + "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" }, "properties": { "title": "Instance Properties", - "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "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.", "type": "object", "minProperties": 1, "unevaluatedProperties": { @@ -127,9 +121,7 @@ { "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 37adb350..0c2a5fdd 100644 --- a/schemas/2023/08/resource/manifest.set.json +++ b/schemas/2023/08/resource/manifest.set.json @@ -29,16 +29,14 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": [ - { - "executable": "registry", - "args": [ - "config", - "set" - ], - "input": "stdin", - "preTest": true, - "return": "state" - } - ] + "examples": { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "preTest": true, + "return": "state" + } } diff --git a/schemas/2023/08/resource/manifest.test.json b/schemas/2023/08/resource/manifest.test.json index c503d570..0cf89b00 100644 --- a/schemas/2023/08/resource/manifest.test.json +++ b/schemas/2023/08/resource/manifest.test.json @@ -24,15 +24,13 @@ "$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 b646ae48..fbb7b5e5 100644 --- a/schemas/2023/08/resource/manifest.validate.json +++ b/schemas/2023/08/resource/manifest.validate.json @@ -4,9 +4,7 @@ "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" @@ -15,13 +13,11 @@ "$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 bd0261a2..b5318981 100644 --- a/schemas/build.ps1 +++ b/schemas/build.ps1 @@ -26,6 +26,9 @@ param( begin { class LocalJsonSchemaRegistry { + [Specialized.OrderedDictionary] + $FileMap + [Specialized.OrderedDictionary] $Map @@ -37,8 +40,9 @@ begin { [string]$SchemaVersion LocalJsonSchemaRegistry() { - $this.Map = [Specialized.OrderedDictionary]::new() - $this.List = [Generic.List[Specialized.OrderedDictionary]]::new() + $this.FileMap = [Specialized.OrderedDictionary]::new() + $this.Map = [Specialized.OrderedDictionary]::new() + $this.List = [Generic.List[Specialized.OrderedDictionary]]::new() } LocalJsonSchemaRegistry( @@ -49,6 +53,7 @@ begin { $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() } @@ -77,8 +82,14 @@ begin { $Schema.GetEnumerator().Where({$_.Key -ne $KeyName}).ForEach({ if ($_.Value -is [Object[]]) { - $MungedKeyValue = Remove-JsonSchemaKey -KeyName $KeyName -SchemaList $_.Value - $MungedSchema.Add($_.Key, $MungedKeyValue) + if ($_.Value.Count -ge 1) { + $MungedKeyValue = Remove-JsonSchemaKey -KeyName $KeyName -SchemaList $_.Value + $MungedSchema.Add($_.Key, $MungedKeyValue) + } else { + $MungedSchema.Add($_.Key, $_.Value) + } + # $MungedKeyValue = Remove-JsonSchemaKey -KeyName $KeyName -SchemaList $_.Value + # $MungedSchema.Add($_.Key, $MungedKeyValue) } elseif ($_.Value -is [Specialized.OrderedDictionary]) { $MungedKeyValue = Remove-JsonSchemaKey -KeyName $KeyName -Schema $_.Value $MungedSchema.Add($_.Key, $MungedKeyValue) @@ -146,6 +157,7 @@ begin { $Info.List.Add($Schema) $Info.Map.Add($SchemaID, $Schema) $Info.Map.Add($SchemaRefID, $Schema) + $Info.FileMap.Add($_.FullName, $Schema) } } @@ -463,6 +475,19 @@ begin { if (-not (Test-Path -Path $OutputDirectory)) { $null = New-Item -Path $OutputDirectory -ItemType Directory -Force } + $VSCodeKeywords = @( + 'defaultSnippets' + 'errorMessage' + 'patternErrorMessage' + 'deprecationMessage' + 'enumDescriptions' + 'markdownEnumDescriptions' + 'markdownDescription' + 'doNotSuggest' + 'suggestSortText' + 'allowComments' + 'allowTrailingCommas' + ) } process { @@ -482,6 +507,10 @@ begin { $Bundled = Merge-JsonSchema @SharedMergeParams | Set-BundledSchemaID -BundledName $Name + foreach ($VSCodeKeyword in $VSCodeKeywords) { + $Bundled = Remove-JsonSchemaKey -Schema $Bundled -KeyName $VSCodeKeyword + } + if ($OutputFormat -contains 'json') { $Bundled | ConvertTo-MergedAndMungedJson @@ -516,6 +545,20 @@ begin { } } } + + $VSCodeKeywords = @( + 'defaultSnippets' + 'errorMessage' + 'patternErrorMessage' + 'deprecationMessage' + 'enumDescriptions' + 'markdownEnumDescriptions' + 'markdownDescription' + 'doNotSuggest' + 'suggestSortText' + 'allowComments' + 'allowTrailingCommas' + ) } process { @@ -541,8 +584,7 @@ process { $null = New-Item -Path $SchemaFolder -ItemType Directory -Force } - $SchemaContent - | yayaml\ConvertFrom-Yaml + $SchemaContent | yayaml\ConvertFrom-Yaml | ConvertTo-Json -Depth 99 | ForEach-Object { $_ -replace '\r\n', "`n" } | Out-File -FilePath ($SchemaPath -replace '\.yaml$', '.json') -Force @@ -558,8 +600,8 @@ process { SchemaHost = $Config.host SchemaPrefix = $Config.prefix SchemaVersion = $Config.version - WithoutExamples = $true - WithoutComments = $true + # WithoutExamples = $true + # WithoutComments = $true } $SchemaRegistry = Get-LocalJsonSchemaRegistry @RegistryParameters @@ -590,6 +632,30 @@ process { Write-Verbose "Exporting: $($BundleToExport | ConvertTo-Json)" Export-MergedJsonSchema @BundleToExport -SchemaRegistry $SchemaRegistry -ErrorAction Stop } + + # Remove VS Code keywords from non-bundled schemas + # $SchemaRegistry.FileMap.GetEnumerator() | ForEach-Object -Process { + # $SchemaPath = $_.Key + # $SchemaData = $_.Value + + # $SchemaData + # | ConvertTo-Json -Depth 99 + # | ForEach-Object { $_ -replace '\r\n', "`n" } + # | Out-File -FilePath $SchemaPath -Force + # } + + $SchemaRegistry.FileMap.GetEnumerator() | ForEach-Object -Process { + $SchemaPath = $_.Key + $SchemaData = $_.Value + foreach ($VSCodeKeyword in $VSCodeKeywords) { + $SchemaData = Remove-JsonSchemaKey -Schema $SchemaData -KeyName $VSCodeKeyword + } + + $SchemaData + | ConvertTo-Json -Depth 99 + | ForEach-Object { $_ -replace '\r\n', "`n" } + | Out-File -FilePath $SchemaPath -Force + } } end { diff --git a/schemas/examples/foo.dsc.config.yaml b/schemas/examples/foo.dsc.config.yaml new file mode 100644 index 00000000..05a4efbb --- /dev/null +++ b/schemas/examples/foo.dsc.config.yaml @@ -0,0 +1,10 @@ +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +# Try adding the variables, metadata, and parameters properties, +# then use IntelliSense to define a few entries. + +resources: + - type: example/resource + name: My Example + properties: + foo: bar + # Define a new resource instance diff --git a/schemas/examples/foo.dsc.resource.json b/schemas/examples/foo.dsc.resource.json index e0a2361c..7e05a300 100644 --- a/schemas/examples/foo.dsc.resource.json +++ b/schemas/examples/foo.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "../2023/08/bundled/resource.manifest.vscode.json", + "$schema": "../2023/08/bundled/resource/manifest.vscode.json", "type": "Example/Resource", "description": "An example resource using the schema.", "version": "0.1.0", diff --git a/schemas/examples/foo.dsc.resource.yaml b/schemas/examples/foo.dsc.resource.yaml index 1c35b922..0bcda745 100644 --- a/schemas/examples/foo.dsc.resource.yaml +++ b/schemas/examples/foo.dsc.resource.yaml @@ -1,7 +1,7 @@ # For testing outside of the repository, set the schema in the yaml server directive to: # https://raw.githubusercontent.com/PowerShell/DSC/main/2023/08/resource/manifest.json # -# yaml-language-server: $schema=../2023/08/bundled/resource.manifest.vscode.json +# Hover on the keys to see the documentation. Try changing values and adding new settings. manifestVersion: 1.0.0 type: Example/Foo version: 0.1.0 diff --git a/schemas/src/config/document.parameter.yaml b/schemas/src/config/document.parameter.yaml index 892edaa6..79e40470 100644 --- a/schemas/src/config/document.parameter.yaml +++ b/schemas/src/config/document.parameter.yaml @@ -4,6 +4,14 @@ $id: ///config/document.parameter.yaml title: Parameter description: Defines a runtime option for a DSC Configuration Document. +markdownDescription: | # VS Code only + > [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 + + type: object required: - type @@ -15,6 +23,13 @@ properties: description: >- Defines the default value for the parameter. $ref: ///definitions/parameters/validValueTypes.yaml + # VS Code only + markdownDescription: | + > [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 allowedValues: title: Allowed values description: >- @@ -23,56 +38,159 @@ properties: type: array items: $ref: ///definitions/parameters/validValueTypes.yaml + # VS Code only + markdownDescription: | + > [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 description: title: Parameter description description: >- Defines a synopsis for the parameter explaining its purpose. type: string + # VS Code only + markdownDescription: | + > [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 metadata: title: Parameter metadata description: >- - Defines a set of key-value pairs for the parameter. This metadata - isn't validated. + Defines a set of key-value pairs for the parameter. This metadata isn't validated. + type: object + # VS Code only + markdownDescription: | + > [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 + 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. + 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. + body: + '${1:metadataName}': ['${2:firstValue}', '${3:secondValue}'] + +# Conditional settings depending on parameter type allOf: + # Additional properties for integer parameters - if: properties: type: const: int then: - minValue: - title: Minimum value - description: >- - The minimum valid value for an integer type. If defined with the - `maxValue` property, this value must be less than the value of - `maxValue`. - type: integer - maxValue: - title: Maximum value - description: >- - The maximum valid value for an integer type. If defined with the - `minValue` property, this value must be greater than the value of - `minValue`. - type: integer + properties: + minValue: + title: Minimum value + description: >- + The minimum valid value for an integer type. If defined with the `maxValue` property, + this value must be less than the value of `maxValue`. + type: integer + # VS Code only + markdownDescription: | + > [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 + + 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 + # VS Code only + markdownDescription: | + > [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 + + # Additional properties for string and array parameters - if: oneOf: - properties: { type: { const: string } } - properties: { type: { const: securestring } } - properties: { type: { const: array } } then: - minLength: - title: Minimum length - description: >- - The minimum valid length for a `string`, `securestring`, or `array`. If - defined with the `maxLength` property, this value must be less than the - value of `maxLength`. - type: integer - minimum: 0 - maxLength: - title: Maximum length - description: >- - The maximum valid length for a `string`, `securestring`, or `array`. If - defined with the `minLength` property, this value must be less than the - value of `minLength`. - type: integer - minimum: 0 + properties: + minLength: + title: Minimum length + description: >- + The minimum valid length for a `string`, `securestring`, or `array`. If defined with + the `maxLength` property, this value must be less than the value of `maxLength`. + type: integer + minimum: 0 + # VS Code only + markdownDescription: | + > [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 + 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 + # VS Code only + markdownDescription: | + > [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 + # defaultValue strict validation + - if: + oneOf: + - properties: { type: { const: string } } + - properties: { type: { const: securestring } } + then: + properties: + defaultValue: { type: string } + allowedValues: { items: { type: string } } + - if: + oneOf: + - properties: { type: { const: object } } + - properties: { type: { const: secureobject } } + then: + properties: + defaultValue: { type: object } + allowedValues: { items: { type: object } } + - if: + properties: { type: { const: int } } + then: + properties: + defaultValue: { type: integer } + allowedValues: { items: { type: integer } } + - if: + properties: { type: { const: array } } + then: + properties: { defaultValue: { type: array } } + - if: + properties: { type: { const: bool } } + then: + properties: + defaultValue: { type: boolean } + allowedValues: { items: { type: boolean } } diff --git a/schemas/src/config/document.resource.yaml b/schemas/src/config/document.resource.yaml index f2eb57c9..9d7604b0 100644 --- a/schemas/src/config/document.resource.yaml +++ b/schemas/src/config/document.resource.yaml @@ -1,8 +1,9 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema -$schema: https://json-schema.org/draft/2020-12/schema -$id: ///config/document.resource.yaml +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///config/document.resource.yaml +title: DSC Resource instance +description: Defines an instance of a DSC Resource in a configuration. -title: DSC Resource instance type: object required: - type @@ -15,18 +16,70 @@ properties: dependsOn: title: Instance depends on description: >- - Defines a list of DSC Resource instances that DSC must successfully - process before processing this instance. Each value for this property - must be the value of another DSC Resource instance's `name` property. + Defines a list of DSC Resource instances that DSC must successfully process before processing + this instance. Each value for this property must be the value of another DSC Resource + instance's `name` property. type: array items: type: string uniqueItems: true pattern: ^\[\w+(\.\w+){0,2}\/\w+\].+$ + # VS Code only + patternErrorMessage: | + Invalid value, must be a value like `[]`, such as `[Microsoft/OSInfo]Foo`. + + The `` and `` should be the fully qualified type of the resource and its + friendly name in the configuration. + markdownDescription: | + > [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 value of another DSC Resource + instance's `name` property. + + [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#properties-1 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. + 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 + # VS Code only + markdownDescription: | + > [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 + +# VS Code only +markdownDescription: | + > [Online Documentation][01] + + Defines an instance of a DSC Resource in a configuration. + + The `resources` property of a DSC Configuration document always includes at least one DSC Resource + instance. Together, the instances in a configuration define the desired state that DSC can get, + test, and set on a machine. + + [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true + +defaultSnippets: + - label: New resource instance + description: Defines a new instance of a DSC Resource for the configuration + body: + type: $1 + name: $2 + 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. + body: + type: $1 + name: $2 + dependsOn: "['[${3:dependencyType}]${4:dependencyName}']" + properties: + '${5:propertyName}': '${6:propertyValue}' diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index 21cb2e61..f60a013e 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -1,11 +1,21 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema -$schema: https://json-schema.org/draft/2020-12/schema -$id: ///config/document.yaml +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///config/document.yaml +title: DSC Configuration Document schema +description: Describes a valid DSC Configuration Document. + +markdownDescription: | # VS Code only + > [Online Documentation][01] -title: DSC Configuration Document schema -description: >- Describes a valid DSC Configuration Document. + DSC Configurations enable users to define state by combining different DSC Resources. A + configuration document uses parameters and variables to pass to a set of one or more resources + that define a desired state. + + [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true + + type: object required: - $schema @@ -14,39 +24,99 @@ properties: $schema: title: Schema description: >- - This property must be the canonical URL of the DSC Configuration Document - schema that the document is implemented for. + This property must be the canonical URL of the DSC Configuration Document schema that the + document is implemented for. type: string format: uri enum: - ///config/document.yaml + # VS Code only: + markdownDescription: | + > [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 + markdownEnumDescriptions: + - Indicates that the configuration document adheres to the `` schema. parameters: title: DSC Configuration document parameters description: >- - Defines runtime options for the configuration. Users and integrating tools - can override use the defined parameters to pass alternate values to the - configuration. + Defines runtime options for the configuration. Users and integrating tools can override use + the defined parameters to pass alternate values to the configuration. type: object additionalProperties: $ref: ///config/document.parameter.yaml + # VS Code only + markdownDescription: | + > [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 + defaultSnippets: + - label: New Parameter + description: Defines a new runtime option for the configuration. + 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. + body: + '${1:integerParameterId}': + type: int + defaultValue: '$2' + description: '$3' + minValue: '$4' + maxValue: '$5' variables: title: Configuration variables description: >- - Defines a set of reusable values for the configuration document. The - names of this value's properties are the strings used to reference a - variable's value. + 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 + # VS Code only + markdownDescription: | + > [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 + 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. + 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. + body: + '${1:variableName}': ['${2:firstValue}', '${3:secondValue}'] resources: - title: DSC Configuration document resources - description: >- - Defines a list of DSC Resource instances for the configuration to manage. - type: array - minItems: 1 + title: DSC Configuration document resources + description: Defines a list of DSC Resource instances for the configuration to manage. + type: array + minItems: 1 items: $ref: ///config/document.resource.yaml + # VS Code only + markdownDescription: | + > [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 metadata: title: Configuration metadata @@ -54,3 +124,22 @@ properties: Defines a set of key-value pairs for the configuration. This metadata isn't validated. type: object + # VS Code only + markdownDescription: | + > [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 + 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. + 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. + body: + '${1:metadataName}': ['${2:firstValue}', '${3:secondValue}'] diff --git a/schemas/src/definitions/commandArgs.yaml b/schemas/src/definitions/commandArgs.yaml index 815f746a..a3fb3f0c 100644 --- a/schemas/src/definitions/commandArgs.yaml +++ b/schemas/src/definitions/commandArgs.yaml @@ -8,3 +8,7 @@ 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 18f8c3b6..2758d2e4 100644 --- a/schemas/src/definitions/commandExecutable.yaml +++ b/schemas/src/definitions/commandExecutable.yaml @@ -6,3 +6,9 @@ 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 f907d216..c58a8ba2 100644 --- a/schemas/src/definitions/inputKind.yaml +++ b/schemas/src/definitions/inputKind.yaml @@ -11,3 +11,15 @@ enum: - args - stdin default: args + +# VS Code only +markdownDescription: | + Defines how DSC should pass input to the command, either as arguments or JSON over `stdin`. +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`. diff --git a/schemas/src/definitions/instanceName.yaml b/schemas/src/definitions/instanceName.yaml index 82710e23..05fb7e6a 100644 --- a/schemas/src/definitions/instanceName.yaml +++ b/schemas/src/definitions/instanceName.yaml @@ -7,3 +7,12 @@ description: >- The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. type: string + +# VS Code only +markdownDescription: | + > [Online Documentation][01] + + The short, human-readable name for a DSC Resource instance. Must be unique within a DSC + Configuration document. + + [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#name diff --git a/schemas/src/definitions/parameters/dataTypes.yaml b/schemas/src/definitions/parameters/dataTypes.yaml index 0f8715a5..9658cb6b 100644 --- a/schemas/src/definitions/parameters/dataTypes.yaml +++ b/schemas/src/definitions/parameters/dataTypes.yaml @@ -4,7 +4,7 @@ $id: ///definitions/parameters/dataTypes.yaml title: Data Types description: >- - Defines the data type for the value. + Defines the data type for the parameter value. type: string enum: - string @@ -14,3 +14,111 @@ enum: - object - secureobject - array + +# VS Code only +markdownDescription: | + > [Online Documentation][01] + + Defines the data type for the parameter value. + + The valid data types for a parameter are: + + - `array` for arrays + - `bool` for booleans + - `int` for integers + - `object` for objects + - `string` for strings + - `secureobject` for secure objects + - `securestring` for secure strings + + Access parameters in a configuration using this syntax: + + ```yaml + "[parameter('')]" + ``` + + In YAML, the parameter syntax needs to be enclosed in double-quotes when used as an inline value. + If the syntax isn't quoted, YAML interprets the syntax as an array. + + [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true +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 diff --git a/schemas/src/definitions/resourceType.yaml b/schemas/src/definitions/resourceType.yaml index cd6fdc0f..6c28eddd 100644 --- a/schemas/src/definitions/resourceType.yaml +++ b/schemas/src/definitions/resourceType.yaml @@ -15,3 +15,24 @@ description: | type: string pattern: ^\w+(\.\w+){0,2}\/\w+$ + +# VS Code only +markdownDescription: | + > [Online Documentation][01] + + The namespaced name of the DSC Resource, using the syntax: + + ```text + owner[.group][.area]/name + ``` + + For example: + + - `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 +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 + the resource under the owner, like `Microsoft.Windows/Registry`. \ No newline at end of file diff --git a/schemas/src/definitions/semver.yaml b/schemas/src/definitions/semver.yaml index 36ad6228..3a369699 100644 --- a/schemas/src/definitions/semver.yaml +++ b/schemas/src/definitions/semver.yaml @@ -4,21 +4,21 @@ $id: ///definitions/semver.yaml type: string title: Semantic Version -description: >- - A valid semantic version (semver) string. For reference, see https://semver.org/ +description: | + A valid semantic version (semver) string. + + For reference, see https://semver.org/ pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ -$comment: | - This pattern comes from the semver website's FAQ: - - https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string +# VS Code only +markdownDescription: | + A valid semantic version ([semver][01]) string. - It's the suggested regex pattern for JavaScript. + This value uses the [suggested regular expression][02] to validate whether the string is valid + semver. This is the same pattern, made multi-line for easier readability: - This is the same pattern, made multi-line for easier readability. - - ``` + ```regex ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*) (?:-( (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*) @@ -26,6 +26,13 @@ $comment: | *))? (?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ ``` - + The first line matches the `major.minor.patch` components of the version. The middle lines match the pre-release components. The last line matches the build metadata component. + + [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/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml index fd10844c..dc554cfa 100644 --- a/schemas/src/resource/manifest.get.yaml +++ b/schemas/src/resource/manifest.get.yaml @@ -4,8 +4,13 @@ $id: ///resource/manifest.get.yaml title: Get Method description: >- - Defines how DSC must call the DSC Resource to get the current state of an - instance. + Defines how DSC must call the DSC Resource to get the current state of an instance. +markdownDescription: | # VS Code only + > [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/provider?view=dsc-3.0&preserveView=true type: object required: @@ -24,4 +29,4 @@ examples: - config - get input: stdin - - executable: osinfo \ No newline at end of file + - executable: osinfo diff --git a/schemas/src/resource/manifest.provider.yaml b/schemas/src/resource/manifest.provider.yaml index a79b96ac..5d452e2b 100644 --- a/schemas/src/resource/manifest.provider.yaml +++ b/schemas/src/resource/manifest.provider.yaml @@ -4,9 +4,15 @@ $id: ///resource/manifest.provider.yaml title: Provider description: >- - Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider - enables users to manage resources that don't have their own manifests with - DSC. + 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] + + 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 type: object required: @@ -16,8 +22,13 @@ properties: list: title: List Command description: >- - Defines how DSC must call the DSC Resource Provider to list its supported - DSC Resources. + Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources. + markdownDescription: | # VS Code only + > [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 type: object required: - executable @@ -29,13 +40,33 @@ properties: config: title: Expected Configuration description: >- - Defines whether the provider expects to receive a full and unprocessed - configuration as a single JSON blob over stdin or a sequence of JSON - Lines for each child resource's configurations. + Defines whether the provider expects to receive a full and unprocessed configuration as a + single JSON blob over stdin or a sequence of JSON Lines for each child resource's + configurations. type: string enum: - full - sequence + # VS Code only + markdownDescription: | + > [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 + 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`. + + [01]: https://jsonlines.org/ examples: - config: full diff --git a/schemas/src/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml index 76b4144e..c652470a 100644 --- a/schemas/src/resource/manifest.schema.yaml +++ b/schemas/src/resource/manifest.schema.yaml @@ -4,8 +4,7 @@ $id: ///resource/manifest.schema.yaml title: Instance Schema description: >- - Defines how DSC must validate a JSON blob representing an instance of the - DSC Resource. + Defines how DSC must validate a JSON blob representing an instance of the DSC Resource. # While the current implementation is somewhat confusing in the schema, I # think it's actually easier to document. Mainly, the complexity comes from @@ -20,8 +19,8 @@ properties: command: title: Instance Schema Command description: >- - Defines how DSC must call the DSC Resource to get the JSON Schema for - validating a JSON blob representing an instance of the DSC Resource. + 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 @@ -30,11 +29,26 @@ properties: $ref: ///definitions/commandExecutable.yaml args: $ref: ///definitions/commandArgs.yaml + # VS Code only + markdownDescription: | + > [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 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. + 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] + + 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 type: object required: - $schema @@ -48,6 +62,13 @@ properties: have the `object` type. # Ensures the DSC Resource is always an object const: object + markdownDescription: | # VS Code only + > [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 $schema: # Ensures the DSC Resource always uses a schema we can understand title: DSC Resource instance schema dialect @@ -59,13 +80,46 @@ properties: - https://json-schema.org/draft/2020-12/schema - https://json-schema.org/draft/2019-09/schema - http://json-schema.org/draft-07/schema# + # VS Code only + markdownDescription: | # VS Code only + > [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 + markdownEnumDescriptions: + # https://json-schema.org/draft/2020-12/schema + - | + Indicates the resource instance schema adheres to [JSON Schema Draft 2020-12][01]. + + [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]. + + [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]. + + [01]: https://json-schema.org/specification-links.html#draft-7 $id: title: DSC Resource instance schema ID description: >- - Defines the unique ID for the DSC Resource's instance schema. + 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. # Currently optional - maybe we should require this? type: string format: uri-reference + markdownDescription: | + > [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 + properties: # Defines the property validation - requires authors to specify at # least one property, ensures all unevaluated properties are of a kind @@ -73,7 +127,17 @@ properties: # manifest authors. title: Instance Properties description: >- - Defines the schema for the DSC Resource's properties. Must define at least one property. + 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: | # VS Code only + > [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 type: object minProperties: 1 unevaluatedProperties: @@ -89,6 +153,14 @@ properties: whether an instance should exist with the `Present` and `Absent` enums. const: $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 _inDesiredState: title: 'Standard Property: _inDesiredState' description: >- @@ -97,6 +169,15 @@ properties: 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] + + 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 _purge: title: 'Standard Property: _purge' description: >- @@ -105,6 +186,15 @@ properties: an array of members or values. const: $ref: ///resource/properties/purge.yaml + # VS Code only + markdownDescription: | + > [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 _rebootRequested: title: 'Standard property: _rebootRequested' description: >- @@ -112,12 +202,27 @@ properties: report whether the machine should be rebooted after the `set` method executes. const: $ref: ///resource/properties/rebootRequested.yaml + # VS Code only + markdownDescription: | + > [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 url: title: Instance Schema URL description: >- Defines the URL to the DSC Resource's JSON schema for integrating tools. type: string format: uri + # VS Code only + markdownDescription: | + > [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 examples: - command: @@ -152,3 +257,23 @@ examples: Family: type: string enum: [Linux, macOS, Windows] + +# VS Code only +markdownDescription: | + > [Online Documentation][01] + + Defines how DSC must validate a JSON blob representing an instance of the DSC Resource. + + The JSON schema can be defined dynamically with the `command` property or statically with the + `embedded` property. + + For development purposes, it can be more convenient to use the `command` property and avoid + needing to adjust both the code and the schema. + + Microsoft recommends using the `embedded` property when publishing a resource publicly. When the + manifest declares the schema with the `command` property, DSC calls the command at the beginning + of any operation using the resource, possibly impacting performance. The schema is also + unavailable to integrating tools when the resource isn't installed locally. When the schema is + embedded in the manifest, DSC and integrating tools only need the manifest itself. + + [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index f6684d1f..51a1a1ee 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -4,8 +4,15 @@ $id: ///resource/manifest.set.yaml title: Set Method description: >- - Defines how DSC must call the DSC Resource to set the desired state of - an instance and how to process the output from the DSC Resource. + 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] + + 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 type: object required: @@ -21,17 +28,42 @@ properties: preTest: title: Resource Performs Pre-Test description: >- - Defines whether the DSC Resource performs its own test to ensure - idempotency when calling the `set` command. Set this value to `true` - if the DSC Resource tests input before modifying system state. + 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 + # VS Code only + markdownDescription: | + > [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 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. + Defines whether the command returns a JSON blob of the DSC Resource's state after the set + operation or the state and an array of the properties the DSC Resource modified. $ref: ///definitions/returnKind.yaml + # VS Code only + markdownDescription: | + > [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 + 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. examples: - executable: registry diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index 3796aaed..89093fbf 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -4,8 +4,16 @@ $id: ///resource/manifest.test.yaml title: Test Method description: >- - Defines how DSC must call the DSC Resource to test if an instance is in - the desired state and how to process the output from the DSC Resource. + 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] + + 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 + type: object required: @@ -24,6 +32,22 @@ properties: Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state. $ref: ///definitions/returnKind.yaml + # VS Code only + markdownDescription: | + > [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 + 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. examples: - executable: registry diff --git a/schemas/src/resource/manifest.validate.yaml b/schemas/src/resource/manifest.validate.yaml index 34b43970..87986188 100644 --- a/schemas/src/resource/manifest.validate.yaml +++ b/schemas/src/resource/manifest.validate.yaml @@ -4,9 +4,17 @@ $id: ///resource/manifest.validate.yaml title: Validate Method description: >- - Defines how DSC must call the DSC Resource to validate the state of an - instance. This method is mandatory for DSC Group Resources. It's ignored for - all other DSC Resources. + 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: | # VS Code only + > [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 + type: object required: - executable diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index a6d80959..0cb1cea6 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -4,7 +4,19 @@ $id: ///resource/manifest.yaml title: Command-based DSC Resource Manifest description: >- - Defines a valid command-based DSC Resource. + Defines the information DSC and integrating require to process and call a command-based DSC + Resource. +markdownDescription: | # VS Code only + > [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: + + 1. Be discoverable in the `PATH` environment variable. + 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 type: object required: @@ -16,35 +28,86 @@ properties: manifestVersion: title: Manifest Version description: >- - The semver of the DSC Resource manifest schema to validate this manifest - with. + The semver of the DSC Resource manifest schema to validate this manifest with. $ref: ///definitions/semver.yaml enums: - '1.0' + # VS Code Only + markdownDescription: | + > [Online Documentation][01] + + The semver of the DSC Resource manifest schema to validate this manifest with. + + [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#manifestversion + 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 type: $ref: ///definitions/resourceType.yaml version: title: Resource Semantic Version description: >- - The semantic version (semver) of the DSC Resource. This version - identifies the DSC Resource, not the version of the application it - manages. + The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, + not the version of the application it manages. $ref: ///definitions/semver.yaml + markdownDescription: | # VS Code only + > [Online Documentation][03] + + The semantic version ([semver][01]) 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 + semver. This is the same pattern, made multi-line for easier readability: + + ```regex + ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*) + (?:-( + (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*) + (?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)) + *))? + (?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ + ``` + + The first line matches the `major.minor.patch` components of the version. The middle lines match + the pre-release components. The last line matches the build metadata component. + + [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 description: title: Resource Description description: >- A short synopsis of the DSC Resource's purpose. - # Should this include a maximum length or a pattern that forbids newlines? type: string + markdownDescription: | # VS Code only + > [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 tags: title: Tags description: >- - An array of short strings used to search for DSC Resources. + Defines a list of searchable terms for the resource. + markdownDescription: | # VS Code only + > [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 type: array uniqueItems: true items: type: string pattern: ^\w+$ + patternErrorMessage: | # VS Code only + Invalid tag. Tags must be a string of alphanumeric characters and underscores. No other + characters are permitted. get: $ref: ///resource/manifest.get.yaml set: @@ -54,7 +117,6 @@ properties: validate: $ref: ///resource/manifest.validate.yaml provider: - # I'm not clear on how this works in practice $ref: ///resource/manifest.provider.yaml exitCodes: # This setting in the root of the schema implies exit codes must have the @@ -63,22 +125,34 @@ properties: # command/method objects too? title: Exit Codes description: >- - This property defines a map of valid exit codes for the DSC Resource. - DSC always interprets exit code `0` as a successful operation and any - other exit code as an error. Use this property to indicate human-readable - semantic meanings for the DSC Resource's exit codes. + 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]+$" + patternErrorMessage: | + Invalid exit code. Must be a string representing an integer greater than or equal to `0`. patternProperties: "^[0-9]+$": type: string + unevaluatedProperties: false + default: + '0': Success + '1': Error examples: - - exitCodes: - "0": Success - "1": Invalid parameter - "2": Invalid input - "3": Registry error - "4": JSON serialization failed + - '0': Success + '1': Invalid parameter + '2': Invalid input + '3': Registry error + '4': JSON serialization failed schema: $ref: ///resource/manifest.schema.yaml diff --git a/schemas/src/resource/properties/ensure.yaml b/schemas/src/resource/properties/ensure.yaml index da9c60fd..07eb9eb1 100644 --- a/schemas/src/resource/properties/ensure.yaml +++ b/schemas/src/resource/properties/ensure.yaml @@ -9,4 +9,15 @@ description: >- type: string enum: - Absent - - Present \ No newline at end of file + - Present + +# VS Code Only +markdownDescription: | + > [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 +markdownEnumDescriptions: + - Indicates that the instance shouldn't exist. + - Indicates that the instance should exist. diff --git a/schemas/src/resource/properties/inDesiredState.yaml b/schemas/src/resource/properties/inDesiredState.yaml index ec4d9bf6..e2c35430 100644 --- a/schemas/src/resource/properties/inDesiredState.yaml +++ b/schemas/src/resource/properties/inDesiredState.yaml @@ -4,10 +4,19 @@ $id: ///resource/properties/inDesiredState.yaml title: Instance is in the Desired State description: >- - Indicates whether the instance is in the desired state. This property is only - returned by the `test` method. + Indicates whether the instance is in the desired state. This property is only returned by the + `test` method. type: - boolean - 'null' -readOnly: true \ No newline at end of file +readOnly: true + +# VS Code only +markdownDescription: | + > [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 diff --git a/schemas/src/resource/properties/purge.yaml b/schemas/src/resource/properties/purge.yaml index db99424b..77c57b70 100644 --- a/schemas/src/resource/properties/purge.yaml +++ b/schemas/src/resource/properties/purge.yaml @@ -4,11 +4,21 @@ $id: ///resource/properties/purge.yaml title: Purge description: >- - Indicates that only the components described in the DSC Resource should exist. - If other components exist, the DSC Resource is out of the desired state. When - enforcing desired state, the DSC Resource removes unmanaged components. + Indicates that only the components described in the DSC Resource should exist. If other + components exist, the DSC Resource is out of the desired state. When enforcing desired state, the + DSC Resource removes unmanaged components. type: - boolean - 'null' writeOnly: true + +# VS Code only +markdownDescription: | + > [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 diff --git a/schemas/src/resource/properties/rebootRequested.yaml b/schemas/src/resource/properties/rebootRequested.yaml index 013e056d..d2044748 100644 --- a/schemas/src/resource/properties/rebootRequested.yaml +++ b/schemas/src/resource/properties/rebootRequested.yaml @@ -10,3 +10,11 @@ type: - boolean - 'null' readOnly: true + +# VS Code only +markdownDescription: | + > [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