From 65b4bc174be2a042207f9ec6057e2bf4aa5dceff Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Thu, 21 Sep 2023 13:44:45 -0500 Subject: [PATCH 01/16] (MAINT) Update schema build for docs URLS Prior to this change, the schema generation relied on hard-coding the full URL to docs pages, including the version query parameters. This change updates the build script and configuration for schema generation to handle replacing the URLs using placeholders. --- schemas/build.ps1 | 44 +++++++++++++++++++++++++------------ schemas/schemas.config.yaml | 8 ++++--- 2 files changed, 35 insertions(+), 17 deletions(-) diff --git a/schemas/build.ps1 b/schemas/build.ps1 index b5318981..2f6044c2 100644 --- a/schemas/build.ps1 +++ b/schemas/build.ps1 @@ -38,6 +38,8 @@ begin { [string]$SchemaHost [string]$SchemaPrefix [string]$SchemaVersion + [string]$DocsBaseUrl + [string]$DocsVersionPin LocalJsonSchemaRegistry() { $this.FileMap = [Specialized.OrderedDictionary]::new() @@ -48,14 +50,18 @@ begin { LocalJsonSchemaRegistry( [string]$SchemaHost, [string]$SchemaPrefix, - [string]$SchemaVersion + [string]$SchemaVersion, + [string]$DocsBaseUrl, + [string]$DocsVersionPin ) { - $this.SchemaHost = $SchemaHost - $this.SchemaPrefix = $SchemaPrefix - $this.SchemaVersion = $SchemaVersion - $this.FileMap = [Specialized.OrderedDictionary]::new() - $this.Map = [Specialized.OrderedDictionary]::new() - $this.List = [Generic.List[Specialized.OrderedDictionary]]::new() + $this.SchemaHost = $SchemaHost + $this.SchemaPrefix = $SchemaPrefix + $this.SchemaVersion = $SchemaVersion + $this.DocsBaseUrl = $DocsBaseUrl + $this.DocsVersionPin = $DocsVersionPin + $this.FileMap = [Specialized.OrderedDictionary]::new() + $this.Map = [Specialized.OrderedDictionary]::new() + $this.List = [Generic.List[Specialized.OrderedDictionary]]::new() } } @@ -128,11 +134,19 @@ begin { [string[]]$SchemaDirectories = @(), [string]$SchemaHost = 'https://raw.githubusercontent.com', [string]$SchemaPrefix = 'PowerShell/DSC/main', - [string]$SchemaVersion = '2023/08' + [string]$SchemaVersion = '2023/08', + [string]$DocsBaseUrl = 'https://learn.microsoft.com/powershell/dsc', + [string]$DocsVersionPin = 'view=dsc-3.0&preserve-view=true' ) begin { - $Info = [LocalJsonSchemaRegistry]::new($SchemaHost, $SchemaPrefix, $SchemaVersion) + $Info = [LocalJsonSchemaRegistry]::new( + $SchemaHost, + $SchemaPrefix, + $SchemaVersion, + $DocsBaseUrl, + $DocsVersionPin + ) } process { @@ -574,11 +588,13 @@ process { Get-ChildItem -Path $PSScriptRoot/src -Filter *.yaml -Recurse | ForEach-Object -Process { $SchemaContent = Get-Content -Path $_.FullName -Raw - $SchemaContent = $SchemaContent -replace '', $Config.host - $SchemaContent = $SchemaContent -replace '', $Config.prefix - $SchemaContent = $SchemaContent -replace '', $Config.version - $SchemaContent = $SchemaContent -replace '(?m)\.yaml$"?,?', '.json' - $SchemaPath = $_.FullName -replace 'src', $Config.version + $SchemaContent = $SchemaContent -replace '', $Config.host + $SchemaContent = $SchemaContent -replace '', $Config.prefix + $SchemaContent = $SchemaContent -replace '', $Config.version + $SchemaContent = $SchemaContent -replace '', $Config.docs_base_url + $SchemaContent = $SchemaContent -replace '', $Config.docs_version_pin + $SchemaContent = $SchemaContent -replace '(?m)\.yaml$"?,?', '.json' + $SchemaPath = $_.FullName -replace 'src', $Config.version $SchemaFolder = Split-Path -Parent $SchemaPath if (-not (Test-Path -Path ($SchemaFolder))) { $null = New-Item -Path $SchemaFolder -ItemType Directory -Force diff --git a/schemas/schemas.config.yaml b/schemas/schemas.config.yaml index 6b840411..34a6348d 100644 --- a/schemas/schemas.config.yaml +++ b/schemas/schemas.config.yaml @@ -1,6 +1,8 @@ -host: https://raw.githubusercontent.com -prefix: PowerShell/DSC/main/schemas -version: 2023/08 +host: https://raw.githubusercontent.com +prefix: PowerShell/DSC/main/schemas +version: 2023/08 +docs_base_url: https://learn.microsoft.com/powershell/dsc +docs_version_pin: view=dsc-3.0&preserve-view=true bundle_schemas: # Resource manifest bundle - ConfigFilePath: resource/manifest.json From a1262a2c83668b02a59b55330b156275d06791d8 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Thu, 21 Sep 2023 14:10:12 -0500 Subject: [PATCH 02/16] (MAINT) Update docs links in schema descriptions This change updates the documentation links in the markdown descriptions for the schemas to: 1. Use the placeholders for more robust linking. 1. Reformat the display so the link is wrapped in horizontal rules. --- schemas/src/config/document.parameter.yaml | 54 +++++++++----- schemas/src/config/document.resource.yaml | 18 +++-- schemas/src/config/document.yaml | 39 ++++++---- schemas/src/definitions/instanceName.yaml | 6 +- .../src/definitions/parameters/dataTypes.yaml | 72 +++++++++++-------- schemas/src/definitions/resourceType.yaml | 8 ++- schemas/src/resource/manifest.export.yaml | 6 +- schemas/src/resource/manifest.get.yaml | 6 +- schemas/src/resource/manifest.provider.yaml | 18 +++-- schemas/src/resource/manifest.schema.yaml | 72 ++++++++++++------- schemas/src/resource/manifest.set.yaml | 18 +++-- schemas/src/resource/manifest.test.yaml | 12 ++-- schemas/src/resource/manifest.validate.yaml | 6 +- schemas/src/resource/manifest.yaml | 34 ++++++--- schemas/src/resource/properties/ensure.yaml | 6 +- .../resource/properties/inDesiredState.yaml | 6 +- schemas/src/resource/properties/purge.yaml | 6 +- .../resource/properties/rebootRequested.yaml | 6 +- 18 files changed, 256 insertions(+), 137 deletions(-) diff --git a/schemas/src/config/document.parameter.yaml b/schemas/src/config/document.parameter.yaml index 79e40470..b4c586e1 100644 --- a/schemas/src/config/document.parameter.yaml +++ b/schemas/src/config/document.parameter.yaml @@ -5,11 +5,13 @@ title: Parameter description: Defines a runtime option for a DSC Configuration Document. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a runtime option for a DSC Configuration Document. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/config/parameter? type: object @@ -25,11 +27,13 @@ properties: $ref: ///definitions/parameters/validValueTypes.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the default value for the parameter. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#allowedvalues + [01]: /reference/schemas/config/parameter?#allowedvalues allowedValues: title: Allowed values description: >- @@ -40,12 +44,14 @@ properties: $ref: ///definitions/parameters/validValueTypes.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#allowedvalues + [01]: /reference/schemas/config/parameter?#allowedvalues description: title: Parameter description description: >- @@ -53,11 +59,13 @@ properties: type: string # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a synopsis for the parameter explaining its purpose. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#description-1 + [01]: /reference/schemas/config/parameter?#description-1 metadata: title: Parameter metadata description: >- @@ -66,11 +74,13 @@ properties: type: object # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a set of key-value pairs for the parameter. This metadata isn't validated. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#metadata-1 + [01]: /reference/schemas/config/parameter?#metadata-1 defaultSnippets: - label: New Metadata Property description: Defines a key-value pair for the metadata @@ -101,12 +111,14 @@ allOf: type: integer # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#minvalue + [01]: /reference/schemas/config/parameter?#minvalue maxValue: title: Maximum value @@ -116,12 +128,14 @@ allOf: type: integer # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#maxvalue + [01]: /reference/schemas/config/parameter?#maxvalue # Additional properties for string and array parameters - if: @@ -140,12 +154,14 @@ allOf: minimum: 0 # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#minLength + [01]: /reference/schemas/config/parameter?#minLength maxLength: title: Maximum length description: >- @@ -155,12 +171,14 @@ allOf: minimum: 0 # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`. - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#maxLength + [01]: /reference/schemas/config/parameter?#maxLength # defaultValue strict validation - if: oneOf: diff --git a/schemas/src/config/document.resource.yaml b/schemas/src/config/document.resource.yaml index 5b33e874..4fe2a58c 100644 --- a/schemas/src/config/document.resource.yaml +++ b/schemas/src/config/document.resource.yaml @@ -33,7 +33,9 @@ properties: The `` and `` should be the fully qualified type of the resource and its friendly name in the configuration. markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the `resourceID()` lookup for another @@ -51,7 +53,7 @@ properties: YAML-format configuration document, always wrap the `resourceID()` lookup in double quotes (`"`). - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#properties-1 + [01]: /reference/schemas/config/resource?#properties-1 properties: title: Managed instance properties description: >- @@ -60,16 +62,20 @@ properties: type: object # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#properties-1 + [01]: /reference/schemas/config/resource?#properties-1 # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines an instance of a DSC Resource in a configuration. @@ -77,7 +83,7 @@ markdownDescription: | instance. Together, the instances in a configuration define the desired state that DSC can get, test, and set on a machine. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/config/resource? defaultSnippets: - label: New resource instance diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index f60a013e..22d2d6ac 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -5,7 +5,9 @@ title: DSC Configuration Document schema description: Describes a valid DSC Configuration Document. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Describes a valid DSC Configuration Document. @@ -13,7 +15,7 @@ markdownDescription: | # VS Code only configuration document uses parameters and variables to pass to a set of one or more resources that define a desired state. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/config/document? type: object @@ -32,14 +34,17 @@ properties: - ///config/document.yaml # VS Code only: markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#schema + [01]: /reference/schemas/config/document?#schema markdownEnumDescriptions: - - Indicates that the configuration document adheres to the `` schema. + - | # ///config/document.yaml + Indicates that the configuration document adheres to the `` schema. parameters: title: DSC Configuration document parameters @@ -51,12 +56,14 @@ properties: $ref: ///config/document.parameter.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#parameters + [01]: /reference/schemas/config/document?#parameters defaultSnippets: - label: New Parameter description: Defines a new runtime option for the configuration. @@ -84,12 +91,14 @@ properties: type: object # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#variables + [01]: /reference/schemas/config/document?#variables defaultSnippets: - label: New variable property description: Defines a new variable as a key-value pair @@ -112,11 +121,13 @@ properties: $ref: ///config/document.resource.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a list of DSC Resource instances for the configuration to manage. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#resources + [01]: /reference/schemas/config/document?#resources metadata: title: Configuration metadata @@ -126,11 +137,13 @@ properties: type: object # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a set of key-value pairs for the configuration. This metadata isn't validated. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#metadata-1 + [01]: /reference/schemas/config/document?#metadata-1 defaultSnippets: - label: New Metadata Property description: Defines a key-value pair for the metadata diff --git a/schemas/src/definitions/instanceName.yaml b/schemas/src/definitions/instanceName.yaml index a2fca5a4..9ec752ed 100644 --- a/schemas/src/definitions/instanceName.yaml +++ b/schemas/src/definitions/instanceName.yaml @@ -15,7 +15,9 @@ patternErrorMessage: | Invalid value for instance name. An instance name must be a non-empty string containing only letters, numbers, and spaces. markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the short, human-readable name for a DSC Resource instance. This property must be unique within a DSC Configuration document. If any resource instances share the same name, DSC raises an @@ -23,4 +25,4 @@ markdownDescription: | The instance name must be a non-empty string containing only letters, numbers, and spaces. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#name + [01]: /reference/schemas/config/resource?#name diff --git a/schemas/src/definitions/parameters/dataTypes.yaml b/schemas/src/definitions/parameters/dataTypes.yaml index 9658cb6b..c4148fe7 100644 --- a/schemas/src/definitions/parameters/dataTypes.yaml +++ b/schemas/src/definitions/parameters/dataTypes.yaml @@ -17,7 +17,9 @@ enum: # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the data type for the parameter value. @@ -40,11 +42,12 @@ markdownDescription: | In YAML, the parameter syntax needs to be enclosed in double-quotes when used as an inline value. If the syntax isn't quoted, YAML interprets the syntax as an array. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/definitions/parameters/datatypes? markdownEnumDescriptions: - # string - - | - > [Online Documentation][01] + - | # string + *** + [_Online Documentation_][01] + *** Strings are an arbitrary set of text. @@ -53,11 +56,12 @@ markdownEnumDescriptions: 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 + [01]: /reference/schemas/definitions/parameters/datatypes?#strings - # securestring - - | - > [Online Documentation][01] + - | # 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 @@ -68,27 +72,32 @@ markdownEnumDescriptions: 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 + [01]: /reference/schemas/definitions/parameters/datatypes?#secure-strings-and-objects - # int - - | - > [Online Documentation][01] + - | # 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] + [01]: /reference/schemas/definitions/parameters/datatypes?#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] + [01]: /reference/schemas/definitions/parameters/datatypes?#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. @@ -99,11 +108,12 @@ markdownEnumDescriptions: "[parameters('').] ``` - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#objects + [01]: /reference/schemas/definitions/parameters/datatypes?#objects - # secureobject - - | - > [Online Documentation][01] + - | # 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 @@ -113,12 +123,14 @@ markdownEnumDescriptions: 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] + [01]: /reference/schemas/definitions/parameters/datatypes?#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 + [01]: /reference/schemas/definitions/parameters/datatypes?#arrays diff --git a/schemas/src/definitions/resourceType.yaml b/schemas/src/definitions/resourceType.yaml index 6c28eddd..f993f1e1 100644 --- a/schemas/src/definitions/resourceType.yaml +++ b/schemas/src/definitions/resourceType.yaml @@ -18,11 +18,13 @@ pattern: ^\w+(\.\w+){0,2}\/\w+$ # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** The namespaced name of the DSC Resource, using the syntax: - ```text + ```yaml owner[.group][.area]/name ``` @@ -31,7 +33,7 @@ markdownDescription: | - `Microsoft.SqlServer/Database` - `Microsoft.SqlServer.Database/User` - [01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/definitions/resourcetype? patternErrorMessage: | Invalid type name. Valid resource type names always define an owner and a name separated by a slash, like `Microsoft/OSInfo`. Type names may optionally include a group and area to namespace diff --git a/schemas/src/resource/manifest.export.yaml b/schemas/src/resource/manifest.export.yaml index 7983de2c..7cca1bbb 100644 --- a/schemas/src/resource/manifest.export.yaml +++ b/schemas/src/resource/manifest.export.yaml @@ -6,11 +6,13 @@ title: Get Method description: >- Defines how DSC must call the DSC Resource to get the current state of every instance. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must call the DSC Resource to get the current state of every instance. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/export? type: object required: diff --git a/schemas/src/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml index c76bc376..fa369868 100644 --- a/schemas/src/resource/manifest.get.yaml +++ b/schemas/src/resource/manifest.get.yaml @@ -6,11 +6,13 @@ title: Get Method description: >- Defines how DSC must call the DSC Resource to get the current state of an instance. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must call the DSC Resource to get the current state of an instance. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/get? type: object required: diff --git a/schemas/src/resource/manifest.provider.yaml b/schemas/src/resource/manifest.provider.yaml index 5d452e2b..7f564f8e 100644 --- a/schemas/src/resource/manifest.provider.yaml +++ b/schemas/src/resource/manifest.provider.yaml @@ -7,12 +7,14 @@ description: >- Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/provider? type: object required: @@ -24,11 +26,13 @@ properties: description: >- Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true#list + [01]: /reference/schemas/resource/manifest/provider?#list type: object required: - executable @@ -49,13 +53,15 @@ properties: - sequence # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true#config + [01]: /reference/schemas/resource/manifest/provider?#config markdownEnumDescriptions: # full - | diff --git a/schemas/src/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml index c652470a..c2d40b4c 100644 --- a/schemas/src/resource/manifest.schema.yaml +++ b/schemas/src/resource/manifest.schema.yaml @@ -31,24 +31,28 @@ properties: $ref: ///definitions/commandArgs.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#command + [01]: /reference/schemas/resource/manifest/schema/property?#command embedded: title: Embedded Instance Schema description: >- Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/schema/embedded? type: object required: - $schema @@ -63,12 +67,14 @@ properties: # Ensures the DSC Resource is always an object const: object markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true#type + [01]: /reference/schemas/resource/manifest/schema/embedded?#type $schema: # Ensures the DSC Resource always uses a schema we can understand title: DSC Resource instance schema dialect @@ -82,12 +88,14 @@ properties: - http://json-schema.org/draft-07/schema# # VS Code only markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type. DSC only supports JSON Schema Draft 07 and later. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true#type + [01]: /reference/schemas/resource/manifest/schema/embedded?#type markdownEnumDescriptions: # https://json-schema.org/draft/2020-12/schema - | @@ -113,12 +121,14 @@ properties: type: string format: uri-reference markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the unique ID for the DSC Resource's instance schema. If the instance schema is published to its own public URI, set this keyword to that URI. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#id + [01]: /reference/schemas/resource/manifest/schema/property?#id properties: # Defines the property validation - requires authors to specify at @@ -131,13 +141,15 @@ properties: This keyword must define at least one property as a key-value pair. The key is the property's name. The value is a subschema that validates the property. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the properties that DSC can retrieve and manage for the resource's instances. This keyword must define at least one property as a key-value pair. The key is the property's name. The value is a subschema that validates the property. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#properties + [01]: /reference/schemas/resource/manifest/schema/property?#properties type: object minProperties: 1 unevaluatedProperties: @@ -155,12 +167,14 @@ properties: $ref: ///resource/properties/ensure.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_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 + [01]: /reference/schemas/resource/properties/ensure? _inDesiredState: title: 'Standard Property: _inDesiredState' description: >- @@ -171,13 +185,15 @@ properties: $ref: ///resource/properties/inDesiredState.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/indesiredstate?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/indesiredstate? _purge: title: 'Standard Property: _purge' description: >- @@ -188,13 +204,15 @@ properties: $ref: ///resource/properties/purge.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/purge?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/purge? _rebootRequested: title: 'Standard property: _rebootRequested' description: >- @@ -204,12 +222,14 @@ properties: $ref: ///resource/properties/rebootRequested.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/rebootrequested?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/rebootrequested? url: title: Instance Schema URL description: >- @@ -218,11 +238,13 @@ properties: format: uri # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the URL to the DSC Resource's JSON schema for integrating tools. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#url + [01]: /reference/schemas/resource/manifest/schema/property?#url examples: - command: @@ -260,7 +282,9 @@ examples: # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must validate a JSON blob representing an instance of the DSC Resource. @@ -276,4 +300,4 @@ markdownDescription: | unavailable to integrating tools when the resource isn't installed locally. When the schema is embedded in the manifest, DSC and integrating tools only need the manifest itself. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/schema/property? diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 51a1a1ee..6516dbf9 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -7,12 +7,14 @@ description: >- Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/set? type: object required: @@ -35,13 +37,15 @@ properties: default: false # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true#pretest + [01]: /reference/schemas/resource/manifest/set?#pretest return: description: >- Defines whether the command returns a JSON blob of the DSC Resource's state after the set @@ -49,12 +53,14 @@ properties: $ref: ///definitions/returnKind.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true#return + [01]: /reference/schemas/resource/manifest/set?#return markdownEnumDescriptions: # state - | diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index 89093fbf..bfb65ab5 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -7,12 +7,14 @@ description: >- Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/test? type: object @@ -34,12 +36,14 @@ properties: $ref: ///definitions/returnKind.yaml # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserveView=true#return + [01]: /reference/schemas/resource/manifest/test?#return markdownEnumDescriptions: # state - | diff --git a/schemas/src/resource/manifest.validate.yaml b/schemas/src/resource/manifest.validate.yaml index 87986188..88fa59f6 100644 --- a/schemas/src/resource/manifest.validate.yaml +++ b/schemas/src/resource/manifest.validate.yaml @@ -8,12 +8,14 @@ description: >- mandatory for DSC Group Resources. It's ignored for all other DSC Resources. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/validate? type: object required: diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index 3c6cdb8b..c05cd3a5 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -7,7 +7,9 @@ description: >- Defines the information DSC and integrating require to process and call a command-based DSC Resource. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines the information DSC and integrating require to process and call a command-based DSC Resource. For DSC to use a manifest on a system, the manifest file must: @@ -16,7 +18,7 @@ markdownDescription: | # VS Code only 1. Follow the naming convention `.dsc.resource.json`. 1. Be valid for this schema. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/manifest/root? type: object required: @@ -34,11 +36,13 @@ properties: - '1.0' # VS Code Only markdownDescription: | - > [Online Documentation][01] + *** + [_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 + [01]: /reference/schemas/resource/manifest/root?#manifestversion markdownEnumDescriptions: # 1.0 - | @@ -56,7 +60,9 @@ properties: not the version of the application it manages. $ref: ///definitions/semver.yaml markdownDescription: | # VS Code only - > [Online Documentation][03] + *** + [_Online Documentation_][01] + *** The semantic version ([semver][01]) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages. @@ -85,21 +91,25 @@ properties: A short synopsis of the DSC Resource's purpose. type: string markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a short synopsis of the DSC Resource's purpose. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#description-1 + [01]: /reference/schemas/resource/manifest/root?#description-1 tags: title: Tags description: >- Defines a list of searchable terms for the resource. markdownDescription: | # VS Code only - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Defines a list of searchable terms for the resource. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#tags + [01]: /reference/schemas/resource/manifest/root?#tags type: array uniqueItems: true items: @@ -131,13 +141,15 @@ properties: 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] + *** + [_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 + [01]: /reference/schemas/resource/manifest/root?#exitcodes type: object propertyNames: pattern: "^[0-9]+$" diff --git a/schemas/src/resource/properties/ensure.yaml b/schemas/src/resource/properties/ensure.yaml index 07eb9eb1..7b1226b5 100644 --- a/schemas/src/resource/properties/ensure.yaml +++ b/schemas/src/resource/properties/ensure.yaml @@ -13,11 +13,13 @@ enum: # VS Code Only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Indicates whether the DSC Resource instance should exist. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/ensure?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/ensure? markdownEnumDescriptions: - Indicates that the instance shouldn't exist. - Indicates that the instance should exist. diff --git a/schemas/src/resource/properties/inDesiredState.yaml b/schemas/src/resource/properties/inDesiredState.yaml index e2c35430..a696cefc 100644 --- a/schemas/src/resource/properties/inDesiredState.yaml +++ b/schemas/src/resource/properties/inDesiredState.yaml @@ -14,9 +14,11 @@ readOnly: true # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Indicates whether the instance is in the desired state. This property is only returned by the `test` method. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/indesiredstate?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/indesiredstate? diff --git a/schemas/src/resource/properties/purge.yaml b/schemas/src/resource/properties/purge.yaml index 77c57b70..9ba4330e 100644 --- a/schemas/src/resource/properties/purge.yaml +++ b/schemas/src/resource/properties/purge.yaml @@ -15,10 +15,12 @@ writeOnly: true # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/purge?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/purge? diff --git a/schemas/src/resource/properties/rebootRequested.yaml b/schemas/src/resource/properties/rebootRequested.yaml index d2044748..8d32f720 100644 --- a/schemas/src/resource/properties/rebootRequested.yaml +++ b/schemas/src/resource/properties/rebootRequested.yaml @@ -13,8 +13,10 @@ readOnly: true # VS Code only markdownDescription: | - > [Online Documentation][01] + *** + [_Online Documentation_][01] + *** Indicates that the set operation requires a reboot before it's fully complete. - [01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/rebootrequested?view=dsc-3.0&preserveView=true + [01]: /reference/schemas/resource/properties/rebootrequested? From 525d511e18a8a239135e2715157bf95a95057759 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 22 Sep 2023 11:47:50 -0500 Subject: [PATCH 03/16] (MAINT) Reformat enum markdown descriptions This change reformats and rewords the Markdown descriptions for schema enum values. This change only affects the schemas enhanced for authoring in VS Code. The standardized format it to include a brief synopsis at the start of the enum description in italics, then additional information in a blockquote. --- schemas/src/config/document.yaml | 4 +- schemas/src/definitions/inputKind.yaml | 17 +-- .../src/definitions/parameters/dataTypes.yaml | 113 +++++++++--------- schemas/src/resource/manifest.provider.yaml | 18 +-- schemas/src/resource/manifest.schema.yaml | 33 +++-- schemas/src/resource/manifest.set.yaml | 18 +-- schemas/src/resource/manifest.test.yaml | 16 +-- schemas/src/resource/manifest.yaml | 9 +- schemas/src/resource/properties/ensure.yaml | 12 +- 9 files changed, 132 insertions(+), 108 deletions(-) diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index 22d2d6ac..fc2e477b 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -44,7 +44,9 @@ properties: [01]: /reference/schemas/config/document?#schema markdownEnumDescriptions: - | # ///config/document.yaml - Indicates that the configuration document adheres to the `` schema. + + + > Indicates that the configuration document adheres to the `` schema. parameters: title: DSC Configuration document parameters diff --git a/schemas/src/definitions/inputKind.yaml b/schemas/src/definitions/inputKind.yaml index c58a8ba2..1cf21eb7 100644 --- a/schemas/src/definitions/inputKind.yaml +++ b/schemas/src/definitions/inputKind.yaml @@ -16,10 +16,13 @@ default: args 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`. + - | # args + _Command line arguments_ + + > Indicates that the resource expects the properties of an instance to be specified with + > command line arguments. This option isn't implemented yet. + - | # stdin + _JSON over `stdin`_ + + > Indicates that the resource expects a JSON blob representing an instance from `stdin`. + > The JSON must adhere to the instance schema. diff --git a/schemas/src/definitions/parameters/dataTypes.yaml b/schemas/src/definitions/parameters/dataTypes.yaml index c4148fe7..e73b1eab 100644 --- a/schemas/src/definitions/parameters/dataTypes.yaml +++ b/schemas/src/definitions/parameters/dataTypes.yaml @@ -45,92 +45,87 @@ markdownDescription: | [01]: /reference/schemas/definitions/parameters/datatypes? markdownEnumDescriptions: - | # string - *** - [_Online Documentation_][01] - *** - - Strings are an arbitrary set of text. + _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. + > To define a long strings in YAML, use the folded block syntax or literal block syntax by + > adding a `>` or `|` and a line break after the key. Then, indent the next line. Every line + > in the string must start at the same level of indentation. You can trim the trailing + > whitespace by using `>-` or `|-` instead. + > + > For more information, see the [_Online Documentation_][01]. [01]: /reference/schemas/definitions/parameters/datatypes?#strings - | # securestring - *** - [_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. + _Secure strings are text that needs to be handled securely._ + + > Secure strings are an arbitrary set of text that DSC and integrating tools shouldn't log or + > record. If a secure data type parameter is used for a resource instance property that doesn't + > expect a secure value, the resource may still log or record the value. If the resource has + > independent logging or recording that isn't handled by DSC, the value may be stored + > insecurely. + > + > Use secure strings for passwords and secrets. Never define a default value for secure string + > parameters. + > + > For more information, see the [_Online Documentation_][01]. [01]: /reference/schemas/definitions/parameters/datatypes?#secure-strings-and-objects - | # int - *** - [_Online Documentation_][01] - *** + _Integer values are numbers without a fractional part._ - 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`. + > Integer values may be limited by integrating tools or the DSC Resources they're used with. + > DSC itself supports integer values between `-9223372036854775808` and `9223372036854775807`. + > + > For more information, see the [_Online Documentation_][01]. [01]: /reference/schemas/definitions/parameters/datatypes?#integers - | # bool - *** - [_Online Documentation_][01] - *** + _Boolean values are either `true` or `false`._ - Boolean values are either `true` or `false`. + > For more information, see the [_Online Documentation_][01]. [01]: /reference/schemas/definitions/parameters/datatypes?#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('').] - ``` + _Objects define a set of key-value pairs._ + + > The value for each key can be any valid data type. The values can be the same type or + > different types. + > + > Access keys in the object using dot-notation. Dot-notation uses this syntax: + > + > ```yaml + > "[parameters('').] + > ``` + > + > For more information, see the [_Online Documentation_][01]. [01]: /reference/schemas/definitions/parameters/datatypes?#objects - | # secureobject - *** - [_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. + _Secure objects are key-value pairs that need to be handled securely._ + + > Secure objects define a set of key-value pairs that DSC and integrating tools shouldn't log + > or record. If a secure data type parameter is used for a resource instance property that + > doesn't expect a secure value, the resource may still log or record the value. If the + > resource has independent logging or recording that isn't handled by DSC, the value may be + > stored insecurely. + > + > Never define a default value for secure object parameters. + > + > For more information, see the [_Online Documentation_][01]. [01]: /reference/schemas/definitions/parameters/datatypes?#secure-strings-and-objects - | # array - *** - [_Online Documentation_][01] - *** + _Arrays are a list of one or more values._ - 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. + > The values in the array can be any valid data type. Values in the array can be the same type + > or different types. + > + > For more information, see the [_Online Documentation_][01]. [01]: /reference/schemas/definitions/parameters/datatypes?#arrays diff --git a/schemas/src/resource/manifest.provider.yaml b/schemas/src/resource/manifest.provider.yaml index 7f564f8e..c1165533 100644 --- a/schemas/src/resource/manifest.provider.yaml +++ b/schemas/src/resource/manifest.provider.yaml @@ -63,14 +63,16 @@ properties: [01]: /reference/schemas/resource/manifest/provider?#config markdownEnumDescriptions: - # full - - | - Indicates that the provider expects a JSON blob containing the full and unprocessed - configuration as a single JSON blob over `stdin`. - # sequence - - | - Indicates that the provider expects each resource's configuration as a [JSON Line][01] - over `stdin`. + - | # full + _Full and unprocessed config as a JSON blob_ + + > Indicates that the provider expects a JSON blob containing the full and unprocessed + > configuration as a single JSON blob over `stdin`. + - | # sequence + _Resource instances as JSON Lines_ + + > Indicates that the provider expects each resource's configuration as a [JSON Line][01] + > over `stdin`. [01]: https://jsonlines.org/ diff --git a/schemas/src/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml index c2d40b4c..baba10b2 100644 --- a/schemas/src/resource/manifest.schema.yaml +++ b/schemas/src/resource/manifest.schema.yaml @@ -97,19 +97,34 @@ properties: [01]: /reference/schemas/resource/manifest/schema/embedded?#type markdownEnumDescriptions: - # https://json-schema.org/draft/2020-12/schema - - | - Indicates the resource instance schema adheres to [JSON Schema Draft 2020-12][01]. + - | # https://json-schema.org/draft/2020-12/schema + _Draft 2020-12 (recommended)_ + + > Indicates that the resource instance schema adheres to + > [JSON Schema Draft 2020-12][01]. + > + > This is the latest published draft of JSON Schema and is the draft future drafts + > will be most compatible with. [01]: https://json-schema.org/specification-links.html#2020-12 - # https://json-schema.org/draft/2019-09/schema - - | - Indicates the resource instance schema adheres to [JSON Schema Draft 2019-09][01]. + - | # https://json-schema.org/draft/2019-09/schema + _Draft 2019-09_ + + > Indicates that the resource instance schema adheres to + > [JSON Schema Draft 2019-09][01]. + > + > This is the previous published draft of JSON Schema. It's mostly compatible with + > 2020-12, but less extensible and can't be bundled. [01]: https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8 - # http://json-schema.org/draft-07/schema# - - | - Indicates the resource instance schema adheres to [JSON Schema Draft 07][01]. + - | # http://json-schema.org/draft-07/schema# + _Draft 07_ + + > Indicates that the resource instance schema adheres to [JSON Schema Draft 07][01]. + > + > This is an older published draft of JSON Schema. It's widely used, but incompatible + > with 2019-09 and later. It's less expressive, extensible, maintainable, and isn't + > recommended for new schema definitions. [01]: https://json-schema.org/specification-links.html#draft-7 $id: diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 6516dbf9..6993a950 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -62,14 +62,16 @@ properties: [01]: /reference/schemas/resource/manifest/set?#return markdownEnumDescriptions: - # state - - | - Indicates that the resource returns only the instance's final state after the set - operation as a JSON blob. - # stateAndDiff - - | - Indicates that the resource returns the instance's final state and an array of property - names that the resource modified. + - | # state + _Final state only_ + + > Indicates that the resource returns only the instance's final state after the set + > operation as a JSON blob. + - | # stateAndDiff + _Final state and changed properties_ + + > Indicates that the resource returns the instance's final state and an array of property + > names that the resource modified. examples: - executable: registry diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index bfb65ab5..41f16102 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -45,13 +45,15 @@ properties: [01]: /reference/schemas/resource/manifest/test?#return markdownEnumDescriptions: - # state - - | - Indicates that the resource returns only the instance's actual state. - # stateAndDiff - - | - Indicates that the resource returns the instance's actual state and an array of property - names that are out of the desired state. + - | # state + _Actual state only_ + + > Indicates that the resource returns only the instance's actual state as a JSON blob. + - | # stateAndDiff + _Actual state and differing properties_ + + > Indicates that the resource returns the instance's actual state and an array of + > property names that are out of the desired state. examples: - executable: registry diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index c05cd3a5..a8889941 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -44,13 +44,8 @@ properties: [01]: /reference/schemas/resource/manifest/root?#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 + - | # 1.0 + _Initial release_ type: $ref: ///definitions/resourceType.yaml version: diff --git a/schemas/src/resource/properties/ensure.yaml b/schemas/src/resource/properties/ensure.yaml index 7b1226b5..06024b27 100644 --- a/schemas/src/resource/properties/ensure.yaml +++ b/schemas/src/resource/properties/ensure.yaml @@ -21,5 +21,13 @@ markdownDescription: | [01]: /reference/schemas/resource/properties/ensure? markdownEnumDescriptions: - - Indicates that the instance shouldn't exist. - - Indicates that the instance should exist. + - | # Absent + _Instance shouldn't exist._ + + > If the desired state for `_ensure` is `absent` and the instance exists, the resource removes + > the instance during the `set` operation. + - | # Present + _Instance should exist._ + + > If the desired state for `_ensure` is `present` and the instance doesn't exist, the resource + > adds or creates the instance during the `set` operation. From 36ec2f60ce6bd1b0dec90d79eaec9fe30513013b Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 22 Sep 2023 11:58:22 -0500 Subject: [PATCH 04/16] (MAINT) Update schema descriptions --- schemas/src/definitions/commandArgs.yaml | 4 -- .../src/definitions/commandExecutable.yaml | 6 --- schemas/src/definitions/inputKind.yaml | 3 +- schemas/src/resource/manifest.export.yaml | 36 +++++++++++++ schemas/src/resource/manifest.get.yaml | 43 +++++++++++++++ schemas/src/resource/manifest.provider.yaml | 35 +++++++++++++ schemas/src/resource/manifest.schema.yaml | 52 ++++++++++++++++--- schemas/src/resource/manifest.set.yaml | 44 ++++++++++++++++ schemas/src/resource/manifest.test.yaml | 43 +++++++++++++++ schemas/src/resource/manifest.validate.yaml | 35 +++++++++++++ schemas/src/resource/manifest.yaml | 31 +++++------ 11 files changed, 299 insertions(+), 33 deletions(-) diff --git a/schemas/src/definitions/commandArgs.yaml b/schemas/src/definitions/commandArgs.yaml index a3fb3f0c..815f746a 100644 --- a/schemas/src/definitions/commandArgs.yaml +++ b/schemas/src/definitions/commandArgs.yaml @@ -8,7 +8,3 @@ description: >- type: array items: type: string - -markdownDescription: | - Defines an array of strings to pass as arguments to the command. DSC passes the arguments to the - command in the order they're specified. diff --git a/schemas/src/definitions/commandExecutable.yaml b/schemas/src/definitions/commandExecutable.yaml index 2758d2e4..18f8c3b6 100644 --- a/schemas/src/definitions/commandExecutable.yaml +++ b/schemas/src/definitions/commandExecutable.yaml @@ -6,9 +6,3 @@ title: Executable Command Name description: >- The name of the command to run. type: string - -# VS Code only -markdownDescription: | - Defines the name of the command to run. The value must be the name of a command discoverable in - the system's `PATH` environment variable or the full path to the command. A file extension is - only required when the command isn't recognizable by the operating system as an executable. diff --git a/schemas/src/definitions/inputKind.yaml b/schemas/src/definitions/inputKind.yaml index 1cf21eb7..9d5e4e0b 100644 --- a/schemas/src/definitions/inputKind.yaml +++ b/schemas/src/definitions/inputKind.yaml @@ -13,8 +13,7 @@ enum: default: args # VS Code only -markdownDescription: | - Defines how DSC should pass input to the command, either as arguments or JSON over `stdin`. +# Don't define markdownDescription - each schema using this must define it, to link correctly. markdownEnumDescriptions: - | # args _Command line arguments_ diff --git a/schemas/src/resource/manifest.export.yaml b/schemas/src/resource/manifest.export.yaml index 7cca1bbb..19f47a82 100644 --- a/schemas/src/resource/manifest.export.yaml +++ b/schemas/src/resource/manifest.export.yaml @@ -20,5 +20,41 @@ required: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines the name of the command to run. The value must be the name of a command discoverable + in the system's `PATH` environment variable or the full path to the command. A file extension + is only required when the command isn't recognizable by the operating system as an + executable. + + [01]: /reference/schemas/resource/manifest/export?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines an array of strings to pass as arguments to the command. DSC passes the arguments to + the command in the order they're specified. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["config", "export"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry config export + ``` + + [01]: /reference/schemas/resource/manifest/export?#args + diff --git a/schemas/src/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml index fa369868..30e3653f 100644 --- a/schemas/src/resource/manifest.get.yaml +++ b/schemas/src/resource/manifest.get.yaml @@ -20,10 +20,53 @@ required: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines the name of the command to run. The value must be the name of a command discoverable + in the system's `PATH` environment variable or the full path to the command. A file extension + is only required when the command isn't recognizable by the operating system as an + executable. + + [01]: /reference/schemas/resource/manifest/get?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines an array of strings to pass as arguments to the command. DSC passes the arguments to + the command in the order they're specified. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["config", "get"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry config get + ``` + + [01]: /reference/schemas/resource/manifest/get?#args input: $ref: ///definitions/inputKind.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines how DSC should pass input to the command, either as arguments or JSON over `stdin`. + + [01]: /reference/schemas/resource/manifest/get?#input examples: - executable: registry diff --git a/schemas/src/resource/manifest.provider.yaml b/schemas/src/resource/manifest.provider.yaml index c1165533..2403762e 100644 --- a/schemas/src/resource/manifest.provider.yaml +++ b/schemas/src/resource/manifest.provider.yaml @@ -39,8 +39,43 @@ properties: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines the name of the command to run. The value must be the name of a command discoverable + in the system's `PATH` environment variable or the full path to the command. A file extension + is only required when the command isn't recognizable by the operating system as an + executable. + + [01]: /reference/schemas/resource/manifest/provider?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines an array of strings to pass as arguments to the command. DSC passes the arguments to + the command in the order they're specified. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["resources", "list"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry resources list + ``` + + [01]: /reference/schemas/resource/manifest/provider?#args config: title: Expected Configuration description: >- diff --git a/schemas/src/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml index baba10b2..813e712b 100644 --- a/schemas/src/resource/manifest.schema.yaml +++ b/schemas/src/resource/manifest.schema.yaml @@ -27,8 +27,43 @@ properties: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines the name of the command to run. The value must be the name of a command discoverable + in the system's `PATH` environment variable or the full path to the command. A file extension + is only required when the command isn't recognizable by the operating system as an + executable. + + [01]: /reference/schemas/resource/manifest/set?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines an array of strings to pass as arguments to the command. DSC passes the arguments to + the command in the order they're specified. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["schema", "resource"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry schema resource + ``` + + [01]: /reference/schemas/resource/manifest/set?#args # VS Code only markdownDescription: | *** @@ -186,16 +221,20 @@ properties: [_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. + Indicates that the resource can enforce whether instances exist using the shared + `present` and `absent` semantics. If a resource must distinguish between states + beyond whether an instance is `present` or `absent`, the resource should define its + own `ensure` property without the leading underscore. This property provides shared + semantics for DSC Resources and integrating tools, but doesn't enable any additional + built-in processing with DSC. [01]: /reference/schemas/resource/properties/ensure? _inDesiredState: title: 'Standard Property: _inDesiredState' description: >- Indicates that the DSC Resource returns this value for it's own `test` method. This - property is mandatory when the manifest defines the `test` property. It shouldn't - be included if the DSC Resource relies on DSC's synthetic testing. + read-only property is mandatory when the manifest defines the `test` property. It + shouldn't be included if the DSC Resource relies on DSC's synthetic testing. const: $ref: ///resource/properties/inDesiredState.yaml # VS Code only @@ -231,8 +270,9 @@ properties: _rebootRequested: title: 'Standard property: _rebootRequested' description: >- - Indicates that the DSC Resource uses the standard `_rebootRequested` property to - report whether the machine should be rebooted after the `set` method executes. + Indicates whether a resource instance requires a reboot after a set operation. To use + DSC's built-in reboot notification processing, resources must define this property in + their manifest. const: $ref: ///resource/properties/rebootRequested.yaml # VS Code only diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 6993a950..5848720f 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -23,10 +23,54 @@ required: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines the name of the command to run. The value must be the name of a command discoverable + in the system's `PATH` environment variable or the full path to the command. A file extension + is only required when the command isn't recognizable by the operating system as an + executable. + + [01]: /reference/schemas/resource/manifest/set?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines an array of strings to pass as arguments to the command. DSC passes the arguments to + the command in the order they're specified. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["config", "set"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry config set + ``` + + [01]: /reference/schemas/resource/manifest/set?#args input: $ref: ///definitions/inputKind.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines how DSC should pass input to the command, either as arguments or JSON over `stdin`. + + [01]: /reference/schemas/resource/manifest/set?#input + preTest: title: Resource Performs Pre-Test description: >- diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index 41f16102..a302cb6c 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -24,10 +24,53 @@ required: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines the name of the command to run. The value must be the name of a command discoverable + in the system's `PATH` environment variable or the full path to the command. A file extension + is only required when the command isn't recognizable by the operating system as an + executable. + + [01]: /reference/schemas/resource/manifest/set?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines an array of strings to pass as arguments to the command. DSC passes the arguments to + the command in the order they're specified. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["config", "test"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry config test + ``` + + [01]: /reference/schemas/resource/manifest/set?#args input: $ref: ///definitions/inputKind.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines how DSC should pass input to the command, either as arguments or JSON over `stdin`. + + [01]: /reference/schemas/resource/manifest/set?#input return: title: Test Command Return Type description: >- diff --git a/schemas/src/resource/manifest.validate.yaml b/schemas/src/resource/manifest.validate.yaml index 88fa59f6..1333892c 100644 --- a/schemas/src/resource/manifest.validate.yaml +++ b/schemas/src/resource/manifest.validate.yaml @@ -23,8 +23,43 @@ required: properties: executable: $ref: ///definitions/commandExecutable.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines the name of the command to run. The value must be the name of a command discoverable + in the system's `PATH` environment variable or the full path to the command. A file extension + is only required when the command isn't recognizable by the operating system as an + executable. + + [01]: /reference/schemas/resource/manifest/set?#executable args: $ref: ///definitions/commandArgs.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines an array of strings to pass as arguments to the command. DSC passes the arguments to + the command in the order they're specified. + + For example, the given the following definition: + + ```json + { + "executable": "registry", + "args": ["config", "validate"], + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry config validate + ``` + + [01]: /reference/schemas/resource/manifest/set?#args examples: - executable: dsc diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index a8889941..2a61aee2 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -59,10 +59,10 @@ properties: [_Online Documentation_][01] *** - The semantic version ([semver][01]) of the DSC Resource. This version identifies the DSC + The semantic version ([semver][02]) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages. - This value uses the [suggested regular expression][02] to validate whether the string is valid + This value uses the [suggested regular expression][03] to validate whether the string is valid semver. This is the same pattern, made multi-line for easier readability: ```regex @@ -77,9 +77,9 @@ properties: The first line matches the `major.minor.patch` components of the version. The middle lines match the pre-release components. The last line matches the build metadata component. - [01]: https://semver.org/ - [02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string - [03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#version + [01]: /reference/schemas/resource/manifest/root?#version + [02]: https://semver.org/ + [03]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string description: title: Resource Description description: >- @@ -135,16 +135,6 @@ properties: This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes. - markdownDescription: | - *** - [_Online Documentation_][01] - *** - - This property defines a map of valid exit codes for the DSC Resource. DSC always interprets - exit code `0` as a successful operation and any other exit code as an error. Use this - property to indicate human-readable semantic meanings for the DSC Resource's exit codes. - - [01]: /reference/schemas/resource/manifest/root?#exitcodes type: object propertyNames: pattern: "^[0-9]+$" @@ -163,5 +153,16 @@ properties: '2': Invalid input '3': Registry error '4': JSON serialization failed + # VS Code only + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + This property defines a map of valid exit codes for the DSC Resource. DSC always interprets + exit code `0` as a successful operation and any other exit code as an error. Use this + property to indicate human-readable semantic meanings for the DSC Resource's exit codes. + + [01]: /reference/schemas/resource/manifest/root?#exitcodes schema: $ref: ///resource/manifest.schema.yaml From 208fe3ab37e2b792edefc0592629bcb14dd88142 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Sat, 23 Sep 2023 21:16:58 -0500 Subject: [PATCH 05/16] (MAINT) Improve snippets This change reworks the snippets for usability and contextual help. It: - Ensures snippets use `body` instead of `bodyText` for non-scalar value snippets, so they are correctly inserted instead of relying on fragile strings, which might break indentation or syntax. - Adds many new snippets for faster authoring - Shows a preview of the snippet insert for the configuration snippets, where we can reliably show YAML syntax. --- schemas/src/config/document.parameter.yaml | 36 +++- schemas/src/config/document.resource.yaml | 51 ++++-- schemas/src/config/document.yaml | 127 ++++++++++---- schemas/src/resource/manifest.export.yaml | 13 ++ schemas/src/resource/manifest.get.yaml | 16 ++ schemas/src/resource/manifest.provider.yaml | 20 +++ schemas/src/resource/manifest.schema.yaml | 174 ++++++++++++++++++++ schemas/src/resource/manifest.set.yaml | 20 +++ schemas/src/resource/manifest.test.yaml | 18 ++ schemas/src/resource/manifest.validate.yaml | 14 ++ schemas/src/resource/manifest.yaml | 146 ++++++++++++++++ 11 files changed, 587 insertions(+), 48 deletions(-) diff --git a/schemas/src/config/document.parameter.yaml b/schemas/src/config/document.parameter.yaml index b4c586e1..d78be445 100644 --- a/schemas/src/config/document.parameter.yaml +++ b/schemas/src/config/document.parameter.yaml @@ -82,17 +82,39 @@ properties: [01]: /reference/schemas/config/parameter?#metadata-1 defaultSnippets: - - label: New Metadata Property - description: Defines a key-value pair for the metadata - body: { '${1:metadataName}': '$2' } + - label: New metadata property + markdownDescription: |- + Defines a key-value pair for the metadata: + + ```yaml + metadataName: value + ``` + body: + ${1:metadataName}: ${2:value} - label: New metadata property (object) - description: Defines a new key-value pair for the metadata where the value is an object. + markdownDescription: |- + Defines a new key-value pair for the metadata where the value is an object. + + ```yaml + metadataName: + key: value + ``` body: - '${1:metadataName}': { '${2:key}': '${3:value}' } + ${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. + markdownDescription: |- + Defines a new key-value pair for the metadata where the value is an array. + + ```yaml + metadataName: + - firstValue + - secondValue + ``` body: - '${1:metadataName}': ['${2:firstValue}', '${3:secondValue}'] + ${1:metadataName}: + - ${2:firstValue} + - ${3:secondValue} # Conditional settings depending on parameter type allOf: diff --git a/schemas/src/config/document.resource.yaml b/schemas/src/config/document.resource.yaml index 4fe2a58c..69353fb6 100644 --- a/schemas/src/config/document.resource.yaml +++ b/schemas/src/config/document.resource.yaml @@ -32,6 +32,16 @@ properties: The `` and `` should be the fully qualified type of the resource and its friendly name in the configuration. + defaultSnippets: + - label: New dependency + markdownDescription: |- + Defines a new dependency for the resource instance. + + ```yaml + "[resourceId('dependencyInstance/Type', 'dependencyInstanceName')]" + ``` + bodyText: >- + "[resourceId('${3:dependencyInstance/Type}', '${4:dependencyInstanceName}')]" markdownDescription: | *** [_Online Documentation_][01] @@ -86,20 +96,39 @@ markdownDescription: | [01]: /reference/schemas/config/resource? defaultSnippets: - - label: New resource instance - description: Defines a new instance of a DSC Resource for the configuration + - label: ' New resource instance' + markdownDescription: |- + Defines a new instance of a DSC Resource for the configuration. + + ```yaml + type: owner[.group][.area]/name + name: instance_name + properties: + propertyName: propertyValue + ``` body: - type: $1 - name: $2 + type: ${1:owner[.group][.area]/name} + name: ${2:instance_name} properties: - '${3:propertyName}': '${4:propertyValue}' - - label: New dependent resource instance - description: >- + ${3:propertyName}: ${4:propertyValue} + - label: ' New dependent resource instance' + markdownDescription: |- Defines a new instance of a DSC Resource for the configuration that depends on another instance. + + ```yaml + type: owner[.group][.area]/name + name: instance_name + dependsOn: + - "[resourceId('dependencyInstance/Type', 'dependencyInstanceName')]" + properties: + propertyName: propertyValue + ``` body: - type: $1 - name: $2 - dependsOn: "['[${3:dependencyType}]${4:dependencyName}']" + type: ${1:owner[.group][.area]/name} + name: ${2:instance_name} + dependsOn: + - >- + "[resourceId('${3:dependencyInstance/Type}', '${4:dependencyInstanceName}')]" properties: - '${5:propertyName}': '${6:propertyValue}' + ${5:propertyName}: ${6:propertyValue} diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index fc2e477b..05eb85af 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -67,23 +67,44 @@ properties: [01]: /reference/schemas/config/document?#parameters defaultSnippets: - - label: New Parameter - description: Defines a new runtime option for the configuration. + - label: ' New Parameter' + markdownDescription: |- + Defines a new runtime option for the configuration. + + ```yaml + parameterId: + type: + description: + defaultValue: + allowedValues: + - + ``` body: - '${1:parameterId}': - type: '$2' - defaultValue: '$3' - allowedValues: ['$4'] - description: '$5' - - label: New Integer Parameter - description: Defines a new runtime option for the configuration as an integer value. + ${1:parameterId}: + type: $2 + description: $3 + defaultValue: $4 + allowedValues: + - $5 + - label: ' New Integer Parameter' + markdownDescription: |- + Defines a new runtime option for the configuration as an integer value. + + ```yaml + parameterId: + type: int + description: + defaultValue: + minValue: + minValue: + ``` body: - '${1:integerParameterId}': + ${1:parameterId}: type: int - defaultValue: '$2' - description: '$3' - minValue: '$4' - maxValue: '$5' + description: $2 + defaultValue: $3 + minValue: $4 + maxValue: $5 variables: title: Configuration variables @@ -102,17 +123,41 @@ properties: [01]: /reference/schemas/config/document?#variables defaultSnippets: - - label: New variable property - description: Defines a new variable as a key-value pair - body: { '${1:metadataName}': '$2' } - - label: New variable property (object) - description: Defines a new key-value pair for the variables where the value is an object. + - label: ' New variable property' + markdownDescription: |- + Defines a new variable as a key-value pair. + + ```yaml + variableName: variableValue + ``` + body: + ${1:variableName}: ${2:variableValue} + + - label: ' New variable property (object)' + markdownDescription: |- + Defines a new key-value pair for the variables where the value is an object. + + ```yaml + variableName: + key: value + ``` body: - '${1:variableName}': { '${2:key}': '${3:value}' } - - label: New variable property (array) - description: Defines a new key-value pair for the variables where the value is an array. + ${1:variableName}: + ${2:key}: ${3:value} + + - label: ' New variable property (array)' + markdownDescription: |- + Defines a new key-value pair for the variables where the value is an array. + + ```yaml + variableName: + - firstValue + - secondValue + ``` body: - '${1:variableName}': ['${2:firstValue}', '${3:secondValue}'] + ${1:variableName}: + - ${2:firstValue} + - ${3:secondValue} resources: title: DSC Configuration document resources @@ -147,14 +192,36 @@ properties: [01]: /reference/schemas/config/document?#metadata-1 defaultSnippets: - - label: New Metadata Property - description: Defines a key-value pair for the metadata - body: { '${1:metadataName}': '$2' } + - label: New metadata property + markdownDescription: |- + Defines a key-value pair for the metadata: + + ```yaml + metadataName: value + ``` + body: + ${1:metadataName}: ${2:value} - label: New metadata property (object) - description: Defines a new key-value pair for the metadata where the value is an object. + markdownDescription: |- + Defines a new key-value pair for the metadata where the value is an object. + + ```yaml + metadataName: + key: value + ``` body: - '${1:metadataName}': { '${2:key}': '${3:value}' } + ${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. + markdownDescription: |- + Defines a new key-value pair for the metadata where the value is an array. + + ```yaml + metadataName: + - firstValue + - secondValue + ``` body: - '${1:metadataName}': ['${2:firstValue}', '${3:secondValue}'] + ${1:metadataName}: + - ${2:firstValue} + - ${3:secondValue} diff --git a/schemas/src/resource/manifest.export.yaml b/schemas/src/resource/manifest.export.yaml index 19f47a82..961ab233 100644 --- a/schemas/src/resource/manifest.export.yaml +++ b/schemas/src/resource/manifest.export.yaml @@ -58,3 +58,16 @@ properties: [01]: /reference/schemas/resource/manifest/export?#args +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the export command for the resource when no arguments are required. + body: + executable: ${1:executable_name} + - label: ' Define with arguments' + markdownDescription: | + Define the export command for the resource when at least one argument is required. + body: + executable: ${1:executable_name} + args: + - ${2:--first-argument} diff --git a/schemas/src/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml index 30e3653f..0b3945be 100644 --- a/schemas/src/resource/manifest.get.yaml +++ b/schemas/src/resource/manifest.get.yaml @@ -75,3 +75,19 @@ examples: - get input: stdin - executable: osinfo + +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the get command for the resource when no arguments are required. + body: + input: ${1|stdin,args|} + executable: ${2:executable_name} + - label: ' Define with arguments' + markdownDescription: | + Define the get command for the resource when at least one argument is required. + body: + input: ${1|stdin,args|} + executable: ${2:executable_name} + args: + - ${3:--first-argument} diff --git a/schemas/src/resource/manifest.provider.yaml b/schemas/src/resource/manifest.provider.yaml index 2403762e..70c8426f 100644 --- a/schemas/src/resource/manifest.provider.yaml +++ b/schemas/src/resource/manifest.provider.yaml @@ -121,3 +121,23 @@ examples: - -NoProfile - -Command - ./powershellgroup.resource.ps1 List + +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the provider config kind and `list` command for the resource when no arguments are + required. + body: + config: $1 + list: + executable: ${2:executable_name} + - label: ' Define with arguments' + markdownDescription: | + Define the provider config kind and `list` command for the resource when at least one + argument is required. + body: + config: $1 + list: + executable: ${2:executable_name} + args: + - ${3:--first-argument} diff --git a/schemas/src/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml index 813e712b..620d08ed 100644 --- a/schemas/src/resource/manifest.schema.yaml +++ b/schemas/src/resource/manifest.schema.yaml @@ -74,6 +74,20 @@ properties: representing an instance of the DSC Resource. [01]: /reference/schemas/resource/manifest/schema/property?#command + defaultSnippets: + - label: ' Define without arguments' + markdownDescription: | + Define the `schema` command for the resource when no arguments are required. + body: + executable: ${1:executable_name} + - label: ' Define with arguments' + markdownDescription: | + Define the `schema` command for the resource when at least one argument is required. + body: + executable: ${1:executable_name} + args: + - ${2:--first-argument} + embedded: title: Embedded Instance Schema description: >- @@ -207,6 +221,111 @@ properties: - $ref: https://json-schema.org/draft/2020-12/schema - $ref: https://json-schema.org/draft/2019-09/schema - $ref: http://json-schema.org/draft-07/schema# + additionalProperties: + defaultSnippets: # VS Code only + - label: ' Define a property' + markdownDescription: Define a new property for the resource instance schema. + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: ${3|boolean,string,integer,number,array,object,null|} + + - label: ' Define a property (boolean)' + markdownDescription: |- + Define a new [boolean][01] property for the resource instance schema, requiring the + value to be either `true` or `false`. + + [01]: https://json-schema.org/understanding-json-schema/reference/boolean.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: boolean + + - label: ' Define a property (string)' + markdownDescription: |- + Define a new [string][01] property for the resource instance schema, requiring the + value to be a blob of text. + + [01]: https://json-schema.org/understanding-json-schema/reference/string.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: string + + - label: ' Define a property (integer)' + markdownDescription: |- + Define a new [integer][01] property for the resource instance schema, requiring the + value to be a number without a fractional part. + + [01]: https://json-schema.org/understanding-json-schema/reference/numeric.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: integer + + - label: ' Define a property (number)' + markdownDescription: |- + Define a new [number][01] property for the resource instance schema, requiring the + value to be a number that may include a fractional part. + + [01]: https://json-schema.org/understanding-json-schema/reference/numeric.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: number + + - label: ' Define a property (array)' + markdownDescription: |- + Define a new [array][01] property for the resource instance schema, requiring the + value to be a list of values. + + [01]: https://json-schema.org/understanding-json-schema/reference/array.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: array + items: + type: ${3|boolean,string,integer,number,array,object,null|} + + - label: ' Define a property (object)' + markdownDescription: |- + Define a new [object][01] property for the resource instance schema, requiring the + value to be a set of key-value pairs. + + [01]: https://json-schema.org/understanding-json-schema/reference/object.html + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + type: object + properties: + ${3:propertyName}: + title: ${4:propertyTitle} + description: ${5:explanation of property purpose and usage} + type: ${6|string,integer,number,array,object,null|} + + - label: ' Define a property (enum)' + markdownDescription: |- + Define a new [enum][01] property for the resource instance schema that only accepts + a defined set of values. + + [01]: https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + enum: + - ^${3:"first value"} + - ^${4:"second value"} + - label: ' Define a property (const)' + markdownDescription: |- + Define a new [const][01] property for the resource instance schema that only + accepts a specific value. + + [01]: https://json-schema.org/understanding-json-schema/reference/generic.html#constant-values + body: + title: ${1:property title} + description: ${2:explanation of property purpose and usage} + const: ^${3:"constant value"} + properties: _ensure: title: 'Standard Property: _ensure' @@ -285,6 +404,14 @@ properties: report whether the machine should be rebooted after the `set` method executes. [01]: /reference/schemas/resource/properties/rebootrequested? + defaultSnippets: # VS Code only + - label: ' Define an instance property' + markdownDescription: Define a property for the resource instance schema. + body: + ${1:propertyName}: + title: ${2:property title} + description: ${3:explanation of property purpose and usage} + type: ${4|string,integer,number,array,object,null|} url: title: Instance Schema URL description: >- @@ -356,3 +483,50 @@ markdownDescription: | embedded in the manifest, DSC and integrating tools only need the manifest itself. [01]: /reference/schemas/resource/manifest/schema/property? + +defaultSnippets: # VS Code only + - label: ' Define as command without arguments' + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Define the resource instance schema as a command when no arguments are required. + + [01]: /reference/schemas/resource/manifest/schema/property?#command + body: + command: + executable: ${1:executable_name} + - label: ' Define as command with arguments' + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Define the resource instance schema as a command when at least one argument is required. + + [01]: /reference/schemas/resource/manifest/schema/property?#command + body: + command: + executable: ${1:executable_name} + args: + - ${2:--first-argument} + - label: ' Define as an embedded schema' + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Define the resource instance schema embedded in the manifest. This is the preferred option + for publicly published resources. + + [01]: /reference/schemas/resource/manifest/schema/embedded? + body: + embedded: + ${escape_dollar:$}schema: ${1|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} + type: object + properties: + ${2:name}: + title: ${3:property title} + description: ${4:explanation of property purpose and usage} + type: ${5|string,integer,number,array,object,null|} diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 5848720f..23c4b242 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -125,3 +125,23 @@ examples: input: stdin preTest: true return: state + +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the `set` command for the resource when no arguments are required. + body: + input: ${1|input,args|} + preTest: ^${2|true,false|} + return: ${3|state,stateAndDiff|} + executable: ${4:executable_name} + - label: ' Define with arguments' + markdownDescription: | + Define the `set` command for the resource when at least one argument is required. + body: + input: $1 + preTest: ^$2 + return: $3 + executable: ${4:executable_name} + args: + - ${5:--first-argument} diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index a302cb6c..2f8c86fa 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -105,3 +105,21 @@ examples: - test input: stdin return: state + +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the `test` command for the resource when no arguments are required. + body: + input: $1 + return: $2 + executable: ${3:executable_name} + - label: ' Define with arguments' + markdownDescription: | + Define the `test` command for the resource when at least one argument is required. + body: + input: $1 + return: $2 + executable: ${3:executable_name} + args: + - ${4:--first-argument} diff --git a/schemas/src/resource/manifest.validate.yaml b/schemas/src/resource/manifest.validate.yaml index 1333892c..f051a6e3 100644 --- a/schemas/src/resource/manifest.validate.yaml +++ b/schemas/src/resource/manifest.validate.yaml @@ -66,3 +66,17 @@ examples: args: - config - validate + +defaultSnippets: # VS Code only + - label: ' Define without arguments' + markdownDescription: | + Define the `validate` command for the resource when no arguments are required. + body: + executable: ${1:executable_name} + - label: ' Define with arguments' + markdownDescription: | + Define the `validate` command for the resource when at least one argument is required. + body: + executable: ${1:executable_name} + args: + - ${2:--first-argument} diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index 2a61aee2..283abc30 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -20,6 +20,145 @@ markdownDescription: | # VS Code only [01]: /reference/schemas/resource/manifest/root? +defaultSnippets: + - label: ' Define a resource' + markdownDescription: |- + Defines a standard resource that: + + - Can get the current state of an instance + - Can set an instance to the desired state + - Relies on DSC's synthetic testing to determine whether an instance is in the desired state + - Defines an embedded JSON schema. + body: + manifestVersion: '1.0' + type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' + version: '${3:0.1.0}' + description: ${4:Synopsis for the resource's purpose} + get: + executable: ${5:executable name} + args: ['${6:argument}'] + input: ${7:stdin} + set: + executable: ${8:executable name} + args: ['${9:argument}'] + input: ${10:stdin} + preTest: ^${11:false} + return: ${12:state} + schema: + embedded: + ${escape_dollar:$}schema: ${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} + type: object + properties: + ${14:name}: + title: ${15:property title} + description: ${16:explanation of property purpose and usage} + type: ${17|string,integer,number,array,object,null|} + - label: ' Define a resource (group)' + markdownDescription: |- + Defines a group resource that expects a list of resource instances and operates on them. + body: + manifestVersion: '1.0' + type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' + version: '${3:0.1.0}' + description: ${4:Synopsis for the resource's purpose} + get: + executable: ${5:executable name} + args: ['${6:argument}'] + input: ${7:stdin} + test: + executable: ${8:executable name} + args: ['${9:argument}'] + input: ${10:stdin} + return: ${12:state} + set: + executable: ${13:executable name} + args: ['${14:argument}'] + input: ${15:stdin} + preTest: ^${16:false} + return: ${17:state} + schema: + embedded: + ${escape_dollar:$}schema: ${18|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} + type: object + properties: + resources: + title: ${19:Resources} + description: ${20:Defines a list of resource instances to process} + type: array + items: + ${escape_dollar:$}ref: ///config/document.resource.json + ${21:name}: + title: ${22:property title} + description: ${23:explanation of property purpose and usage} + type: ${24|string,integer,number,array,object,null|} + - label: ' Define a resource (provider)' + markdownDescription: |- + Defines a provider resource that enables users to define non-command-based DSC Resources in + the configuration. + body: + manifestVersion: '1.0' + type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' + version: '${3:0.1.0}' + description: ${4:Synopsis for the resource's purpose} + get: + executable: ${5:executable name} + args: ['${6:argument}'] + input: ${7:stdin} + test: + executable: ${8:executable name} + args: ['${9:argument}'] + input: ${10:stdin} + return: ${12:state} + set: + executable: ${13:executable name} + args: ['${14:argument}'] + input: ${15:stdin} + preTest: ^${16:false} + return: ${17:state} + provider: + config: ${18|full,sequence|} + list: + executable: ${19:executable name} + args: ['${20:argument}'] + schema: + embedded: + ${escape_dollar:$}schema: ${23|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} + type: object + properties: + resources: + title: ${24:Resources} + description: ${25:Defines a list of resource instances to process} + type: array + items: + ${escape_dollar:$}ref: ///config/document.resource.json + ${26:name}: + title: ${27:property title} + description: ${28:explanation of property purpose and usage} + type: ${29|string,integer,number,array,object,null|} + - label: ' Define a resource (assertion-only)' + markdownDescription: |- + Defines an assertion resource that can get the current state of an instance but not configure + it. By default, the resource relies on DSC's synthetic testing feature. If the resource + implements the `test` operation itself, define the `test` property. + body: + manifestVersion: '1.0' + type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' + version: '${3:0.1.0}' + description: ${4:Synopsis for the resource's purpose} + get: + executable: ${5:executable name} + args: ['${6:argument}'] + input: ${7:stdin} + schema: + embedded: + ${escape_dollar:$}schema: ${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} + type: object + properties: + ${14:name}: + title: ${15:property title} + description: ${16:explanation of property purpose and usage} + type: ${17|string,integer,number,array,object,null|} + type: object required: - manifestVersion @@ -164,5 +303,12 @@ properties: property to indicate human-readable semantic meanings for the DSC Resource's exit codes. [01]: /reference/schemas/resource/manifest/root?#exitcodes + defaultSnippets: + - label: Defined exit codes + description: Defines exit codes with semantic meaning for the resource. + body: + '0': Success + ${1:first exit code number}: ${2:first exit code meaning} + ${3:second exit code number}: ${4:second exit code meaning} schema: $ref: ///resource/manifest.schema.yaml From 5779305de5e290fdd9c279db4eedd5eb86383da3 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Sat, 23 Sep 2023 21:23:01 -0500 Subject: [PATCH 06/16] (MAINT) Remove markdown description from semver Prior to this change, the markdown description for the semver schema was used anywhere the value of a property referenced that definition instead of the defined description on that property. This change converts the markdownDescription for the definition into a comment for maintainers, ensuring that more specific documentation can be shown in the hover context for manifest and configuration authors. --- schemas/src/definitions/semver.yaml | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/schemas/src/definitions/semver.yaml b/schemas/src/definitions/semver.yaml index 3a369699..38964407 100644 --- a/schemas/src/definitions/semver.yaml +++ b/schemas/src/definitions/semver.yaml @@ -10,9 +10,12 @@ description: | For reference, see https://semver.org/ pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +patternErrorMessage: | # VS Code only + Invalid value, must be a semantic version like `..`, such as `1.2.3`. + + The value may also include pre-release version information and build metadata. -# VS Code only -markdownDescription: | +$comment: | A valid semantic version ([semver][01]) string. This value uses the [suggested regular expression][02] to validate whether the string is valid @@ -32,7 +35,3 @@ markdownDescription: | [01]: https://semver.org/ [02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string -patternErrorMessage: | - Invalid value, must be a semantic version like `..`, such as `1.2.3`. - - The value may also include pre-release version information and build metadata. From a5a050959e36ef35b7798e403f482509d419e8bd Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Sat, 23 Sep 2023 21:24:00 -0500 Subject: [PATCH 07/16] (MAINT) Fix manifestVersion definition Prior to this change, the schema specified `enums` instead of `enum`, which broke the validation for that property. This change corrects the spelling and ensures the validation applies. --- schemas/src/resource/manifest.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index 283abc30..a58644b4 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -171,7 +171,7 @@ properties: description: >- The semver of the DSC Resource manifest schema to validate this manifest with. $ref: ///definitions/semver.yaml - enums: + enum: - '1.0' # VS Code Only markdownDescription: | From 7b49d9aca7a35332125808f1b198300659e2bdd9 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Sat, 23 Sep 2023 21:25:19 -0500 Subject: [PATCH 08/16] (MAINT) Regenerate schemas This change regenerates the schemas from the updated source definitions. This ensures the fixes and enhancements are usable. --- schemas/2023/08/bundled/config/document.json | 4 +- .../08/bundled/config/document.vscode.json | 143 ++-- .../08/bundled/outputs/resource/list.json | 16 +- .../2023/08/bundled/resource/manifest.json | 16 +- .../08/bundled/resource/manifest.vscode.json | 665 ++++++++++++++++-- schemas/2023/08/definitions/semver.json | 3 +- schemas/2023/08/resource/manifest.json | 2 +- schemas/2023/08/resource/manifest.schema.json | 5 +- schemas/2023/08/resource/manifest.set.json | 6 +- 9 files changed, 696 insertions(+), 164 deletions(-) diff --git a/schemas/2023/08/bundled/config/document.json b/schemas/2023/08/bundled/config/document.json index 836ddc58..b03ace6e 100644 --- a/schemas/2023/08/bundled/config/document.json +++ b/schemas/2023/08/bundled/config/document.json @@ -14,7 +14,7 @@ "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", "type": "string", "format": "uri", - "enum": ["https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json"] + "enum": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" }, "parameters": { "title": "DSC Configuration document parameters", @@ -351,4 +351,4 @@ "minLength": 1 } } -} +} diff --git a/schemas/2023/08/bundled/config/document.vscode.json b/schemas/2023/08/bundled/config/document.vscode.json index a0e57c7f..c5a55f6e 100644 --- a/schemas/2023/08/bundled/config/document.vscode.json +++ b/schemas/2023/08/bundled/config/document.vscode.json @@ -3,7 +3,7 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", "title": "DSC Configuration Document schema", "description": "Describes a valid DSC Configuration Document.", - "markdownDescription": "> [Online Documentation][01]\n\nDescribes a valid DSC Configuration Document.\n\nDSC Configurations enable users to define state by combining different DSC Resources. A\nconfiguration document uses parameters and variables to pass to a set of one or more resources\nthat define a desired state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDescribes a valid DSC Configuration Document.\n\nDSC Configurations enable users to define state by combining different DSC Resources. A\nconfiguration document uses parameters and variables to pass to a set of one or more resources\nthat define a desired state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "$schema", @@ -18,9 +18,9 @@ "enum": [ "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" ], - "markdownDescription": "> [Online Documentation][01]\n\nThis property must be the canonical URL of the DSC Configuration Document schema that the\ndocument is implemented for.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#schema\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property must be the canonical URL of the DSC Configuration Document schema that the\ndocument is implemented for.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#schema\n", "markdownEnumDescriptions": [ - "Indicates that the configuration document adheres to the `2023/08` schema." + "\n\n> Indicates that the configuration document adheres to the `2023/08` schema.\n" ] }, "parameters": { @@ -30,30 +30,30 @@ "additionalProperties": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines runtime options for the configuration. Users and integrating tools can override use\nthe defined parameters to pass alternate values to the configuration.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#parameters\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines runtime options for the configuration. Users and integrating tools can override use\nthe defined parameters to pass alternate values to the configuration.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#parameters\n", "defaultSnippets": [ { - "label": "New Parameter", - "description": "Defines a new runtime option for the configuration.", + "label": " New Parameter", + "markdownDescription": "Defines a new runtime option for the configuration.\n\n```yaml\nparameterId:\n type: \n description: \n defaultValue: \n allowedValues:\n - \n```", "body": { "${1:parameterId}": { "type": "$2", - "defaultValue": "$3", + "description": "$3", + "defaultValue": "$4", "allowedValues": [ - "$4" - ], - "description": "$5" + "$5" + ] } } }, { - "label": "New Integer Parameter", - "description": "Defines a new runtime option for the configuration as an integer value.", + "label": " New Integer Parameter", + "markdownDescription": "Defines a new runtime option for the configuration as an integer value.\n\n```yaml\nparameterId:\n type: int\n description: \n defaultValue: \n minValue: \n minValue: \n```", "body": { - "${1:integerParameterId}": { + "${1:parameterId}": { "type": "int", - "defaultValue": "$2", - "description": "$3", + "description": "$2", + "defaultValue": "$3", "minValue": "$4", "maxValue": "$5" } @@ -65,18 +65,18 @@ "title": "Configuration variables", "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", "type": "object", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a set of reusable values for the configuration document. The names of this value's\nproperties are the strings used to reference a variable's value.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#variables\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a set of reusable values for the configuration document. The names of this value's\nproperties are the strings used to reference a variable's value.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#variables\n", "defaultSnippets": [ { - "label": "New variable property", - "description": "Defines a new variable as a key-value pair", + "label": " New variable property", + "markdownDescription": "Defines a new variable as a key-value pair.\n\n```yaml\nvariableName: variableValue\n```", "body": { - "${1:metadataName}": "$2" + "${1:variableName}": "${2:variableValue}" } }, { - "label": "New variable property (object)", - "description": "Defines a new key-value pair for the variables where the value is an object.", + "label": " New variable property (object)", + "markdownDescription": "Defines a new key-value pair for the variables where the value is an object.\n\n```yaml\nvariableName:\n key: value\n```", "body": { "${1:variableName}": { "${2:key}": "${3:value}" @@ -84,8 +84,8 @@ } }, { - "label": "New variable property (array)", - "description": "Defines a new key-value pair for the variables where the value is an array.", + "label": " New variable property (array)", + "markdownDescription": "Defines a new key-value pair for the variables where the value is an array.\n\n```yaml\nvariableName:\n - firstValue\n - secondValue\n```", "body": { "${1:variableName}": [ "${2:firstValue}", @@ -103,24 +103,24 @@ "items": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines a list of DSC Resource instances for the configuration to manage.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#resources\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a list of DSC Resource instances for the configuration to manage.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#resources\n" }, "metadata": { "title": "Configuration metadata", "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", "type": "object", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a set of key-value pairs for the configuration. This metadata isn't validated.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserveView=true#metadata-1\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a set of key-value pairs for the configuration. This metadata isn't validated.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#metadata-1\n", "defaultSnippets": [ { - "label": "New Metadata Property", - "description": "Defines a key-value pair for the metadata", + "label": "New metadata property", + "markdownDescription": "Defines a key-value pair for the metadata:\n\n```yaml\nmetadataName: value\n```", "body": { - "${1:metadataName}": "$2" + "${1:metadataName}": "${2:value}" } }, { "label": "New metadata property (object)", - "description": "Defines a new key-value pair for the metadata where the value is an object.", + "markdownDescription": "Defines a new key-value pair for the metadata where the value is an object.\n\n```yaml\nmetadataName:\n key: value\n```", "body": { "${1:metadataName}": { "${2:key}": "${3:value}" @@ -129,7 +129,7 @@ }, { "label": "New metadata property (array)", - "description": "Defines a new key-value pair for the metadata where the value is an array.", + "markdownDescription": "Defines a new key-value pair for the metadata where the value is an array.\n\n```yaml\nmetadataName:\n - firstValue\n - secondValue\n```", "body": { "${1:metadataName}": [ "${2:firstValue}", @@ -153,7 +153,7 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", "title": "Parameter", "description": "Defines a runtime option for a DSC Configuration Document.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a runtime option for a DSC Configuration Document.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a runtime option for a DSC Configuration Document.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "type" @@ -166,7 +166,7 @@ "title": "Default value", "description": "Defines the default value for the parameter.", "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the default value for the parameter.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#allowedvalues\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the default value for the parameter.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#allowedvalues\n" }, "allowedValues": { "title": "Allowed values", @@ -175,30 +175,30 @@ "items": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines a list of valid values for the parameter. If the parameter is defined with any other\nvalues, it's invalid.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#allowedvalues\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a list of valid values for the parameter. If the parameter is defined with any other\nvalues, it's invalid.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#allowedvalues\n" }, "description": { "title": "Parameter description", "description": "Defines a synopsis for the parameter explaining its purpose.", "type": "string", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a synopsis for the parameter explaining its purpose.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#description-1\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a synopsis for the parameter explaining its purpose.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#description-1\n" }, "metadata": { "title": "Parameter metadata", "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", "type": "object", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a set of key-value pairs for the parameter. This metadata isn't validated.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#metadata-1\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a set of key-value pairs for the parameter. This metadata isn't validated.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#metadata-1\n", "defaultSnippets": [ { - "label": "New Metadata Property", - "description": "Defines a key-value pair for the metadata", + "label": "New metadata property", + "markdownDescription": "Defines a key-value pair for the metadata:\n\n```yaml\nmetadataName: value\n```", "body": { - "${1:metadataName}": "$2" + "${1:metadataName}": "${2:value}" } }, { "label": "New metadata property (object)", - "description": "Defines a new key-value pair for the metadata where the value is an object.", + "markdownDescription": "Defines a new key-value pair for the metadata where the value is an object.\n\n```yaml\nmetadataName:\n key: value\n```", "body": { "${1:metadataName}": { "${2:key}": "${3:value}" @@ -207,7 +207,7 @@ }, { "label": "New metadata property (array)", - "description": "Defines a new key-value pair for the metadata where the value is an array.", + "markdownDescription": "Defines a new key-value pair for the metadata where the value is an array.\n\n```yaml\nmetadataName:\n - firstValue\n - secondValue\n```", "body": { "${1:metadataName}": [ "${2:firstValue}", @@ -233,13 +233,13 @@ "title": "Minimum value", "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", "type": "integer", - "markdownDescription": "> [Online Documentation][01]\n\nThe minimum valid value for an integer type. If defined with the `maxValue` property,\nthis value must be less than the value of `maxValue`.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#minvalue\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe minimum valid value for an integer type. If defined with the `maxValue` property,\nthis value must be less than the value of `maxValue`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#minvalue\n" }, "maxValue": { "title": "Maximum value", "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", "type": "integer", - "markdownDescription": "> [Online Documentation][01]\n\nThe maximum valid value for an integer type. If defined with the `minValue` property,\nthis value must be greater than the value of `minValue`.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#maxvalue\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe maximum valid value for an integer type. If defined with the `minValue` property,\nthis value must be greater than the value of `minValue`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#maxvalue\n" } } } @@ -277,14 +277,14 @@ "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", "type": "integer", "minimum": 0, - "markdownDescription": "> [Online Documentation][01]\n\nThe minimum valid length for a `string`, `securestring`, or `array`. If defined with\nthe `maxLength` property, this value must be less than the value of `maxLength`.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#minLength\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe minimum valid length for a `string`, `securestring`, or `array`. If defined with\nthe `maxLength` property, this value must be less than the value of `maxLength`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#minLength\n" }, "maxLength": { "title": "Maximum length", "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", "type": "integer", "minimum": 0, - "markdownDescription": "> [Online Documentation][01]\n\nThe maximum valid length for a `string`, `securestring`, or `array`. If defined with\nthe `minLength` property, this value must be less than the value of `minLength`.\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserveView=true#maxLength\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe maximum valid length for a `string`, `securestring`, or `array`. If defined with\nthe `minLength` property, this value must be less than the value of `minLength`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#maxLength\n" } } } @@ -438,37 +438,46 @@ "type": "string", "uniqueItems": true, "pattern": "^\\[resourceId\\(\\s*'\\w+(\\.\\w+){0,2}\\/\\w+'\\s*,\\s*'[a-zA-Z0-9 ]+'\\s*\\)\\]$", - "patternErrorMessage": "Invalid value, must be a value like `[resourceId('', '`)], such as\n`[resourceId('Microsoft/OSInfo', 'Foo')]`.\n\nThe `` and `` should be the fully qualified type of the resource and its\nfriendly name in the configuration.\n" + "patternErrorMessage": "Invalid value, must be a value like `[resourceId('', '`)], such as\n`[resourceId('Microsoft/OSInfo', 'Foo')]`.\n\nThe `` and `` should be the fully qualified type of the resource and its\nfriendly name in the configuration.\n", + "defaultSnippets": [ + { + "label": "New dependency", + "markdownDescription": "Defines a new dependency for the resource instance.\n\n```yaml\n\"[resourceId('dependencyInstance/Type', 'dependencyInstanceName')]\"\n```", + "bodyText": "\"[resourceId('${3:dependencyInstance/Type}', '${4:dependencyInstanceName}')]\"" + } + ] }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines a list of DSC Resource instances that DSC must successfully process before processing\nthis instance. Each value for this property must be the `resourceID()` lookup for another\ninstance in the configuration. Multiple instances can depend on the same instance, but every\ndependency for an instance must be unique in that instance's `dependsOn` property.\n\nThe `resourceID()` function uses this syntax:\n\n```yaml\n\"[resourceId('', '']\"\n```\n\nThe `` value is the `type` property of the dependent resource and\n`` is the dependency's `name` property. When adding a dependency in a\nYAML-format configuration document, always wrap the `resourceID()` lookup in double quotes\n(`\"`).\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#properties-1\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a list of DSC Resource instances that DSC must successfully process before processing\nthis instance. Each value for this property must be the `resourceID()` lookup for another\ninstance in the configuration. Multiple instances can depend on the same instance, but every\ndependency for an instance must be unique in that instance's `dependsOn` property.\n\nThe `resourceID()` function uses this syntax:\n\n```yaml\n\"[resourceId('', '']\"\n```\n\nThe `` value is the `type` property of the dependent resource and\n`` is the dependency's `name` property. When adding a dependency in a\nYAML-format configuration document, always wrap the `resourceID()` lookup in double quotes\n(`\"`).\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true#properties-1\n" }, "properties": { "title": "Managed instance properties", "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", "type": "object", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the properties of the DSC Resource this instance manages. This property's value must\nbe an object. DSC validates the property's value against the DSC Resource's schema.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#properties-1\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the properties of the DSC Resource this instance manages. This property's value must\nbe an object. DSC validates the property's value against the DSC Resource's schema.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true#properties-1\n" } }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines an instance of a DSC Resource in a configuration.\n\nThe `resources` property of a DSC Configuration document always includes at least one DSC Resource\ninstance. Together, the instances in a configuration define the desired state that DSC can get,\ntest, and set on a machine.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an instance of a DSC Resource in a configuration.\n\nThe `resources` property of a DSC Configuration document always includes at least one DSC Resource\ninstance. Together, the instances in a configuration define the desired state that DSC can get,\ntest, and set on a machine.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true\n", "defaultSnippets": [ { - "label": "New resource instance", - "description": "Defines a new instance of a DSC Resource for the configuration", + "label": " New resource instance", + "markdownDescription": "Defines a new instance of a DSC Resource for the configuration.\n\n```yaml\ntype: owner[.group][.area]/name\nname: instance_name\nproperties:\n propertyName: propertyValue\n```", "body": { - "type": "$1", - "name": "$2", + "type": "${1:owner[.group][.area]/name}", + "name": "${2:instance_name}", "properties": { "${3:propertyName}": "${4:propertyValue}" } } }, { - "label": "New dependent resource instance", - "description": "Defines a new instance of a DSC Resource for the configuration that depends on another instance.", + "label": " New dependent resource instance", + "markdownDescription": "Defines a new instance of a DSC Resource for the configuration that depends on another\ninstance.\n\n```yaml\ntype: owner[.group][.area]/name\nname: instance_name\ndependsOn:\n - \"[resourceId('dependencyInstance/Type', 'dependencyInstanceName')]\"\nproperties:\n propertyName: propertyValue\n```", "body": { - "type": "$1", - "name": "$2", - "dependsOn": "['[${3:dependencyType}]${4:dependencyName}']", + "type": "${1:owner[.group][.area]/name}", + "name": "${2:instance_name}", + "dependsOn": [ + "\"[resourceId('${3:dependencyInstance/Type}', '${4:dependencyInstanceName}')]\"" + ], "properties": { "${5:propertyName}": "${6:propertyValue}" } @@ -494,15 +503,15 @@ "secureobject", "array" ], - "markdownDescription": "> [Online Documentation][01]\n\nDefines the data type for the parameter value.\n\nThe valid data types for a parameter are:\n\n- `array` for arrays\n- `bool` for booleans\n- `int` for integers\n- `object` for objects\n- `string` for strings\n- `secureobject` for secure objects\n- `securestring` for secure strings\n\nAccess parameters in a configuration using this syntax:\n\n```yaml\n\"[parameter('')]\"\n```\n\nIn YAML, the parameter syntax needs to be enclosed in double-quotes when used as an inline value.\nIf the syntax isn't quoted, YAML interprets the syntax as an array.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the data type for the parameter value.\n\nThe valid data types for a parameter are:\n\n- `array` for arrays\n- `bool` for booleans\n- `int` for integers\n- `object` for objects\n- `string` for strings\n- `secureobject` for secure objects\n- `securestring` for secure strings\n\nAccess parameters in a configuration using this syntax:\n\n```yaml\n\"[parameter('')]\"\n```\n\nIn YAML, the parameter syntax needs to be enclosed in double-quotes when used as an inline value.\nIf the syntax isn't quoted, YAML interprets the syntax as an array.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true\n", "markdownEnumDescriptions": [ - "> [Online Documentation][01]\n\nStrings are an arbitrary set of text.\n\nTo define a long strings in YAML, use the folded block syntax or literal block syntax by\nadding a `>` or `|` and a line break after the key. Then, indent the next line. Every line in\nthe string must start at the same level of indentation. You can trim the trailing whitespace\nby using `>-` or `|-` instead.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#strings\n", - "> [Online Documentation][01]\n\nSecure strings are an arbitrary set of text that DSC and integrating tools shouldn't log or\nrecord. If a secure data type parameter is used for a resource instance property that doesn't\nexpect a secure value, the resource may still log or record the value. If the resource has\nindependent logging or recording that isn't handled by DSC, the value may be stored\ninsecurely.\n\nUse secure strings for passwords and secrets. Never define a default value for secure string\nparameters.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#secure-strings-and-objects\n", - "> [Online Documentation][01]\n\nInteger values are numbers without a fractional part. Integer values may be limited by\nintegrating tools or the DSC Resources they're used with. DSC itself supports integer values\nbetween `-9223372036854775808` and `9223372036854775807`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#integers\n", - "> [Online Documentation][01]\n\nBoolean values are either `true` or `false`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#booleans\n", - "> [Online Documentation][01]\n\nObjects define a set of key-value pairs. The value for each key can be any valid data type.\nThe values can be the same type or different types.\n\nAccess keys in the object using dot-notation. Dot-notation uses this syntax:\n\n```yaml\n\"[parameters('').]\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#objects\n", - "> [Online Documentation][01]\n\nSecure objects define a set of key-value pairs that DSC and integrating tools shouldn't log\nor record. If a secure data type parameter is used for a resource instance property that\ndoesn't expect a secure value, the resource may still log or record the value. If the\nresource has independent logging or recording that isn't handled by DSC, the value may be\nstored insecurely.\n\nNever define a default value for secure object parameters.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#secure-strings-and-objects\n", - "> [Online Documentation][01]\n\nArrays are a list of one or more values. The values in the array can be any valid data type.\nValues in the array can be the same type or different types.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserveView=true#arrays\n" + "_Strings are an arbitrary set of text._\n\n> To define a long strings in YAML, use the folded block syntax or literal block syntax by\n> adding a `>` or `|` and a line break after the key. Then, indent the next line. Every line\n> in the string must start at the same level of indentation. You can trim the trailing\n> whitespace by using `>-` or `|-` instead.\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#strings\n", + "_Secure strings are text that needs to be handled securely._\n\n> Secure strings are an arbitrary set of text that DSC and integrating tools shouldn't log or\n> record. If a secure data type parameter is used for a resource instance property that doesn't\n> expect a secure value, the resource may still log or record the value. If the resource has\n> independent logging or recording that isn't handled by DSC, the value may be stored\n> insecurely.\n>\n> Use secure strings for passwords and secrets. Never define a default value for secure string\n> parameters.\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#secure-strings-and-objects\n", + "_Integer values are numbers without a fractional part._\n\n> Integer values may be limited by integrating tools or the DSC Resources they're used with.\n> DSC itself supports integer values between `-9223372036854775808` and `9223372036854775807`.\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#integers\n", + "_Boolean values are either `true` or `false`._\n\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#booleans\n", + "_Objects define a set of key-value pairs._\n\n> The value for each key can be any valid data type. The values can be the same type or\n> different types.\n>\n> Access keys in the object using dot-notation. Dot-notation uses this syntax:\n>\n> ```yaml\n> \"[parameters('').]\n> ```\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#objects\n", + "_Secure objects are key-value pairs that need to be handled securely._\n\n> Secure objects define a set of key-value pairs that DSC and integrating tools shouldn't log\n> or record. If a secure data type parameter is used for a resource instance property that\n> doesn't expect a secure value, the resource may still log or record the value. If the\n> resource has independent logging or recording that isn't handled by DSC, the value may be\n> stored insecurely.\n>\n> Never define a default value for secure object parameters.\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#secure-strings-and-objects\n", + "_Arrays are a list of one or more values._\n\n> The values in the array can be any valid data type. Values in the array can be the same type\n> or different types.\n>\n> For more information, see the [_Online Documentation_][01].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/parameters/datatypes?view=dsc-3.0&preserve-view=true#arrays\n" ] }, "validValueTypes.json": { @@ -525,7 +534,7 @@ "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", "type": "string", "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", - "markdownDescription": "> [Online Documentation][01]\n\nThe namespaced name of the DSC Resource, using the syntax:\n\n```text\nowner[.group][.area]/name\n```\n\nFor example:\n\n- `Microsoft.SqlServer/Database`\n- `Microsoft.SqlServer.Database/User`\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe namespaced name of the DSC Resource, using the syntax:\n\n```yaml\nowner[.group][.area]/name\n```\n\nFor example:\n\n- `Microsoft.SqlServer/Database`\n- `Microsoft.SqlServer.Database/User`\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserve-view=true\n", "patternErrorMessage": "Invalid type name. Valid resource type names always define an owner and a name separated by a\nslash, like `Microsoft/OSInfo`. Type names may optionally include a group and area to namespace\nthe resource under the owner, like `Microsoft.Windows/Registry`.\n" }, "instanceName.json": { @@ -537,7 +546,7 @@ "pattern": "^[a-zA-Z0-9 ]+$", "minLength": 1, "patternErrorMessage": "Invalid value for instance name. An instance name must be a non-empty string containing only\nletters, numbers, and spaces.\n", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the short, human-readable name for a DSC Resource instance. This property must be unique\nwithin a DSC Configuration document. If any resource instances share the same name, DSC raises an\nerror.\n\nThe instance name must be a non-empty string containing only letters, numbers, and spaces.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserveView=true#name\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the short, human-readable name for a DSC Resource instance. This property must be unique\nwithin a DSC Configuration document. If any resource instances share the same name, DSC raises an\nerror.\n\nThe instance name must be a non-empty string containing only letters, numbers, and spaces.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true#name\n" } } } diff --git a/schemas/2023/08/bundled/outputs/resource/list.json b/schemas/2023/08/bundled/outputs/resource/list.json index 85e977b7..9b93ca4d 100644 --- a/schemas/2023/08/bundled/outputs/resource/list.json +++ b/schemas/2023/08/bundled/outputs/resource/list.json @@ -99,7 +99,8 @@ "type": "string", "title": "Semantic Version", "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -118,7 +119,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" + "enum": "1.0" }, "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" @@ -259,7 +260,7 @@ "input": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" }, - "implementsPretest": { + "preTest": { "title": "Resource Performs Pre-Test", "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", "type": "boolean", @@ -277,7 +278,7 @@ "set" ], "input": "stdin", - "implementsPretest": true, + "preTest": true, "return": "state" } }, @@ -468,6 +469,7 @@ } ] }, + "additionalProperties": {}, "properties": { "_ensure": { "title": "Standard Property: _ensure", @@ -478,7 +480,7 @@ }, "_inDesiredState": { "title": "Standard Property: _inDesiredState", - "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This read-only property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" } @@ -492,7 +494,7 @@ }, "_rebootRequested": { "title": "Standard property: _rebootRequested", - "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "description": "Indicates whether a resource instance requires a reboot after a set operation. To use DSC's built-in reboot notification processing, resources must define this property in their manifest.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" } @@ -662,4 +664,4 @@ "readOnly": true } } -} +} diff --git a/schemas/2023/08/bundled/resource/manifest.json b/schemas/2023/08/bundled/resource/manifest.json index a10db24b..db557037 100644 --- a/schemas/2023/08/bundled/resource/manifest.json +++ b/schemas/2023/08/bundled/resource/manifest.json @@ -15,7 +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" + "enum": "1.0" }, "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" @@ -94,7 +94,8 @@ "type": "string", "title": "Semantic Version", "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -172,7 +173,7 @@ "input": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" }, - "implementsPretest": { + "preTest": { "title": "Resource Performs Pre-Test", "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", "type": "boolean", @@ -190,7 +191,7 @@ "set" ], "input": "stdin", - "implementsPretest": true, + "preTest": true, "return": "state" } }, @@ -381,6 +382,7 @@ } ] }, + "additionalProperties": {}, "properties": { "_ensure": { "title": "Standard Property: _ensure", @@ -391,7 +393,7 @@ }, "_inDesiredState": { "title": "Standard Property: _inDesiredState", - "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This read-only property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" } @@ -405,7 +407,7 @@ }, "_rebootRequested": { "title": "Standard property: _rebootRequested", - "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "description": "Indicates whether a resource instance requires a reboot after a set operation. To use DSC's built-in reboot notification processing, resources must define this property in their manifest.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" } @@ -575,4 +577,4 @@ "readOnly": true } } -} +} diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json index ab0731d2..5137e19f 100644 --- a/schemas/2023/08/bundled/resource/manifest.vscode.json +++ b/schemas/2023/08/bundled/resource/manifest.vscode.json @@ -3,7 +3,197 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", "title": "Command-based DSC Resource Manifest", "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the information DSC and integrating require to process and call a command-based DSC\nResource. For DSC to use a manifest on a system, the manifest file must:\n\n1. Be discoverable in the `PATH` environment variable.\n1. Follow the naming convention `.dsc.resource.json`.\n1. Be valid for this schema.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the information DSC and integrating require to process and call a command-based DSC\nResource. For DSC to use a manifest on a system, the manifest file must:\n\n1. Be discoverable in the `PATH` environment variable.\n1. Follow the naming convention `.dsc.resource.json`.\n1. Be valid for this schema.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true\n", + "defaultSnippets": [ + { + "label": " Define a resource", + "markdownDescription": "Defines a standard resource that:\n\n- Can get the current state of an instance\n- Can set an instance to the desired state\n- Relies on DSC's synthetic testing to determine whether an instance is in the desired state\n- Defines an embedded JSON schema.", + "body": { + "manifestVersion": "1.0", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "set": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "preTest": "^${11:false}", + "return": "${12:state}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "${14:name}": { + "title": "${15:property title}", + "description": "${16:explanation of property purpose and usage}", + "type": "${17|string,integer,number,array,object,null|}" + } + } + } + } + } + }, + { + "label": " Define a resource (group)", + "markdownDescription": "Defines a group resource that expects a list of resource instances and operates on them.", + "body": { + "manifestVersion": "1.0", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "test": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "return": "${12:state}" + }, + "set": { + "executable": "${13:executable name}", + "args": [ + "${14:argument}" + ], + "input": "${15:stdin}", + "preTest": "^${16:false}", + "return": "${17:state}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${18|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "resources": { + "title": "${19:Resources}", + "description": "${20:Defines a list of resource instances to process}", + "type": "array", + "items": { + "${escape_dollar:$}ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "${21:name}": { + "title": "${22:property title}", + "description": "${23:explanation of property purpose and usage}", + "type": "${24|string,integer,number,array,object,null|}" + } + } + } + } + } + }, + { + "label": " Define a resource (provider)", + "markdownDescription": "Defines a provider resource that enables users to define non-command-based DSC Resources in\nthe configuration.", + "body": { + "manifestVersion": "1.0", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "test": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "return": "${12:state}" + }, + "set": { + "executable": "${13:executable name}", + "args": [ + "${14:argument}" + ], + "input": "${15:stdin}", + "preTest": "^${16:false}", + "return": "${17:state}" + }, + "provider": { + "config": "${18|full,sequence|}", + "list": { + "executable": "${19:executable name}", + "args": [ + "${20:argument}" + ] + } + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${23|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "resources": { + "title": "${24:Resources}", + "description": "${25:Defines a list of resource instances to process}", + "type": "array", + "items": { + "${escape_dollar:$}ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "${26:name}": { + "title": "${27:property title}", + "description": "${28:explanation of property purpose and usage}", + "type": "${29|string,integer,number,array,object,null|}" + } + } + } + } + } + }, + { + "label": " Define a resource (assertion-only)", + "markdownDescription": "Defines an assertion resource that can get the current state of an instance but not configure\nit. By default, the resource relies on DSC's synthetic testing feature. If the resource\nimplements the `test` operation itself, define the `test` property.", + "body": { + "manifestVersion": "1.0", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "${14:name}": { + "title": "${15:property title}", + "description": "${16:explanation of property purpose and usage}", + "type": "${17|string,integer,number,array,object,null|}" + } + } + } + } + } + } + ], "type": "object", "required": [ "manifestVersion", @@ -16,12 +206,12 @@ "title": "Manifest Version", "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", - "enums": [ + "enum": [ "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", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\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&preserve-view=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" + "_Initial release_\n" ] }, "type": { @@ -31,18 +221,18 @@ "title": "Resource Semantic Version", "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", - "markdownDescription": "> [Online Documentation][03]\n\nThe semantic version ([semver][01]) of the DSC Resource. This version identifies the DSC\nResource, not the version of the application it manages.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n[03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#version\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe semantic version ([semver][02]) of the DSC Resource. This version identifies the DSC\nResource, not the version of the application it manages.\n\nThis value uses the [suggested regular expression][03] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#version\n[02]: https://semver.org/\n[03]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" }, "description": { "title": "Resource Description", "description": "A short synopsis of the DSC Resource's purpose.", "type": "string", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a short synopsis of the DSC Resource's purpose.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#description-1\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a short synopsis of the DSC Resource's purpose.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#description-1\n" }, "tags": { "title": "Tags", "description": "Defines a list of searchable terms for the resource.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines a list of searchable terms for the resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#tags\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a list of searchable terms for the resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#tags\n", "type": "array", "uniqueItems": true, "items": { @@ -72,7 +262,6 @@ "exitCodes": { "title": "Exit Codes", "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", - "markdownDescription": "> [Online Documentation][01]\n\nThis property defines a map of valid exit codes for the DSC Resource. DSC always interprets\nexit code `0` as a successful operation and any other exit code as an error. Use this\nproperty to indicate human-readable semantic meanings for the DSC Resource's exit codes.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserveView=true#exitcodes\n", "type": "object", "propertyNames": { "pattern": "^[0-9]+$", @@ -96,6 +285,18 @@ "3": "Registry error", "4": "JSON serialization failed" } + ], + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property defines a map of valid exit codes for the DSC Resource. DSC always interprets\nexit code `0` as a successful operation and any other exit code as an error. Use this\nproperty to indicate human-readable semantic meanings for the DSC Resource's exit codes.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#exitcodes\n", + "defaultSnippets": [ + { + "label": "Defined exit codes", + "description": "Defines exit codes with semantic meaning for the resource.", + "body": { + "0": "Success", + "${1:first exit code number}": "${2:first exit code meaning}", + "${3:second exit code number}": "${4:second exit code meaning}" + } + } ] }, "schema": { @@ -117,8 +318,8 @@ "title": "Semantic Version", "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", - "markdownDescription": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n", - "patternErrorMessage": "Invalid value, must be a semantic version like `..`, such as `1.2.3`.\n\nThe value may also include pre-release version information and build metadata.\n" + "patternErrorMessage": "Invalid value, must be a semantic version like `..`, such as `1.2.3`.\n\nThe value may also include pre-release version information and build metadata.\n", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" }, "resourceType.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -127,7 +328,7 @@ "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", "type": "string", "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", - "markdownDescription": "> [Online Documentation][01]\n\nThe namespaced name of the DSC Resource, using the syntax:\n\n```text\nowner[.group][.area]/name\n```\n\nFor example:\n\n- `Microsoft.SqlServer/Database`\n- `Microsoft.SqlServer.Database/User`\n\n[01]: https://learn.microsoft.com/en-us/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe namespaced name of the DSC Resource, using the syntax:\n\n```yaml\nowner[.group][.area]/name\n```\n\nFor example:\n\n- `Microsoft.SqlServer/Database`\n- `Microsoft.SqlServer.Database/User`\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserve-view=true\n", "patternErrorMessage": "Invalid type name. Valid resource type names always define an owner and a name separated by a\nslash, like `Microsoft/OSInfo`. Type names may optionally include a group and area to namespace\nthe resource under the owner, like `Microsoft.Windows/Registry`.\n" }, "commandExecutable.json": { @@ -135,8 +336,7 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", "title": "Executable Command Name", "description": "The name of the command to run.", - "type": "string", - "markdownDescription": "Defines the name of the command to run. The value must be the name of a command discoverable in\nthe system's `PATH` environment variable or the full path to the command. A file extension is\nonly required when the command isn't recognizable by the operating system as an executable.\n" + "type": "string" }, "commandArgs.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -146,8 +346,7 @@ "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", @@ -160,10 +359,9 @@ "stdin" ], "default": "args", - "markdownDescription": "Defines how DSC should pass input to the command, either as arguments or JSON over `stdin`.\n", "markdownEnumDescriptions": [ - "Indicates that the resource expects the properties of an instance to be specified with\ncommand line arguments. This option isn't implemented yet.\n", - "Indicates that the resource expects a JSON blob representing an instance from `stdin`.\n" + "_Command line arguments_\n\n> Indicates that the resource expects the properties of an instance to be specified with\n> command line arguments. This option isn't implemented yet.\n", + "_JSON over `stdin`_\n\n> Indicates that the resource expects a JSON blob representing an instance from `stdin`.\n> The JSON must adhere to the instance schema.\n" ] }, "returnKind.json": { @@ -185,20 +383,23 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json", "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to get the current state of an instance.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to get the current state of an instance.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "executable" ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"config\", \"get\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config get\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#args\n" }, "input": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as arguments or JSON over `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#input\n" } }, "examples": [ @@ -213,6 +414,27 @@ { "executable": "osinfo" } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the get command for the resource when no arguments are required.\n", + "body": { + "input": "${1|stdin,args|}", + "executable": "${2:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the get command for the resource when at least one argument is required.\n", + "body": { + "input": "${1|stdin,args|}", + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + } ] }, "manifest.export.json": { @@ -220,26 +442,47 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.export.json", "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to get the current state of every instance.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to get the current state of every instance.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "executable" ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"config\", \"export\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config export\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true#args\n" } - } + }, + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the export command for the resource when no arguments are required.\n", + "body": { + "executable": "${1:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the export command for the resource when at least one argument is required.\n", + "body": { + "executable": "${1:executable_name}", + "args": [ + "${2:--first-argument}" + ] + } + } + ] }, "manifest.set.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json", "title": "Set Method", "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to set the desired state of an instance and how to\nprocess the output from the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to set the desired state of an instance and how to\nprocess the output from the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "executable", @@ -247,28 +490,31 @@ ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"config\", \"set\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config set\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#args\n" }, "input": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as arguments or JSON over `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" }, - "implementsPretest": { + "preTest": { "title": "Resource Performs Pre-Test", "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", "type": "boolean", "default": false, - "markdownDescription": "> [Online Documentation][01]\n\nDefines whether the DSC Resource performs its own test to ensure idempotency when calling the\n`set` command. Set this value to `true` if the DSC Resource tests input before modifying\nsystem state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true#implementsPretest\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the DSC Resource performs its own test to ensure idempotency when calling the\n`set` command. Set this value to `true` if the DSC Resource tests input before modifying\nsystem state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#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", - "markdownDescription": "> [Online Documentation][01]\n\nDefines whether the command returns a JSON blob of the DSC Resource's state after the set\noperation or the state and an array of the properties the DSC Resource modified.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserveView=true#return\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the command returns a JSON blob of the DSC Resource's state after the set\noperation or the state and an array of the properties the DSC Resource modified.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#return\n", "markdownEnumDescriptions": [ - "Indicates that the resource returns only the instance's final state after the set\noperation as a JSON blob.\n", - "Indicates that the resource returns the instance's final state and an array of property\nnames that the resource modified.\n" + "_Final state only_\n\n> Indicates that the resource returns only the instance's final state after the set\n> operation as a JSON blob.\n", + "_Final state and changed properties_\n\n> Indicates that the resource returns the instance's final state and an array of property\n> names that the resource modified.\n" ] } }, @@ -280,9 +526,34 @@ "set" ], "input": "stdin", - "implementsPretest": true, + "preTest": true, "return": "state" } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `set` command for the resource when no arguments are required.\n", + "body": { + "input": "${1|input,args|}", + "preTest": "^${2|true,false|}", + "return": "${3|state,stateAndDiff|}", + "executable": "${4:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the `set` command for the resource when at least one argument is required.\n", + "body": { + "input": "$1", + "preTest": "^$2", + "return": "$3", + "executable": "${4:executable_name}", + "args": [ + "${5:--first-argument}" + ] + } + } ] }, "manifest.test.json": { @@ -290,7 +561,7 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json", "title": "Test Method", "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to test if an instance is in the desired state and how\nto process the output from the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to test if an instance is in the desired state and how\nto process the output from the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "executable", @@ -298,22 +569,25 @@ ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"config\", \"test\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config test\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#args\n" }, "input": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as arguments or JSON over `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" }, "return": { "title": "Test Command Return Type", "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json", - "markdownDescription": "> [Online Documentation][01]\n\nDefines whether the command returns a JSON blob of the DSC Resource's current state or the\nstate and an array of the properties that are out of the desired state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserveView=true#return\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the command returns a JSON blob of the DSC Resource's current state or the\nstate and an array of the properties that are out of the desired state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserve-view=true#return\n", "markdownEnumDescriptions": [ - "Indicates that the resource returns only the instance's actual state.\n", - "Indicates that the resource returns the instance's actual state and an array of property\nnames that are out of the desired state.\n" + "_Actual state only_\n\n> Indicates that the resource returns only the instance's actual state as a JSON blob.\n", + "_Actual state and differing properties_\n\n> Indicates that the resource returns the instance's actual state and an array of\n> property names that are out of the desired state.\n" ] } }, @@ -327,6 +601,29 @@ "input": "stdin", "return": "state" } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `test` command for the resource when no arguments are required.\n", + "body": { + "input": "$1", + "return": "$2", + "executable": "${3:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the `test` command for the resource when at least one argument is required.\n", + "body": { + "input": "$1", + "return": "$2", + "executable": "${3:executable_name}", + "args": [ + "${4:--first-argument}" + ] + } + } ] }, "manifest.validate.json": { @@ -334,17 +631,19 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json", "title": "Validate Method", "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to validate the state of an instance. This method is\nmandatory for DSC Group Resources. It's ignored for all other DSC Resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to validate the state of an instance. This method is\nmandatory for DSC Group Resources. It's ignored for all other DSC Resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "executable" ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"config\", \"validate\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config validate\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#args\n" } }, "examples": [ @@ -355,6 +654,25 @@ "validate" ] } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `validate` command for the resource when no arguments are required.\n", + "body": { + "executable": "${1:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the `validate` command for the resource when at least one argument is required.\n", + "body": { + "executable": "${1:executable_name}", + "args": [ + "${2:--first-argument}" + ] + } + } ] }, "manifest.provider.json": { @@ -362,7 +680,7 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json", "title": "Provider", "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to\nmanage resources that don't have their own manifests with DSC.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to\nmanage resources that don't have their own manifests with DSC.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "list", @@ -372,17 +690,19 @@ "list": { "title": "List Command", "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource Provider to list its supported DSC Resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true#list\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource Provider to list its supported DSC Resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserve-view=true#list\n", "type": "object", "required": [ "executable" ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"resources\", \"list\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry resources list\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserve-view=true#args\n" } } }, @@ -394,10 +714,10 @@ "full", "sequence" ], - "markdownDescription": "> [Online Documentation][01]\n\nDefines whether the provider expects to receive a full and unprocessed configuration as a\nsingle JSON blob over stdin or a sequence of JSON Lines for each child resource's\nconfigurations.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserveView=true#config\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the provider expects to receive a full and unprocessed configuration as a\nsingle JSON blob over stdin or a sequence of JSON Lines for each child resource's\nconfigurations.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/provider?view=dsc-3.0&preserve-view=true#config\n", "markdownEnumDescriptions": [ - "Indicates that the provider expects a JSON blob containing the full and unprocessed\nconfiguration as a single JSON blob over `stdin`.\n", - "Indicates that the provider expects each resource's configuration as a [JSON Line][01]\nover `stdin`.\n\n[01]: https://jsonlines.org/\n" + "_Full and unprocessed config as a JSON blob_\n\n> Indicates that the provider expects a JSON blob containing the full and unprocessed\n> configuration as a single JSON blob over `stdin`.\n", + "_Resource instances as JSON Lines_\n\n> Indicates that the provider expects each resource's configuration as a [JSON Line][01]\n> over `stdin`.\n\n[01]: https://jsonlines.org/\n" ] } }, @@ -415,6 +735,31 @@ ] } } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the provider config kind and `list` command for the resource when no arguments are\nrequired.\n", + "body": { + "config": "$1", + "list": { + "executable": "${2:executable_name}" + } + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the provider config kind and `list` command for the resource when at least one\nargument is required.\n", + "body": { + "config": "$1", + "list": { + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + } + } ] }, "manifest.schema.json": { @@ -445,18 +790,39 @@ ], "properties": { "executable": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the name of the command to run. The value must be the name of a command discoverable\nin the system's `PATH` environment variable or the full path to the command. A file extension\nis only required when the command isn't recognizable by the operating system as an\nexecutable.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines an array of strings to pass as arguments to the command. DSC passes the arguments to\nthe command in the order they're specified.\n\nFor example, the given the following definition:\n\n```json\n{\n \"executable\": \"registry\",\n \"args\": [\"schema\", \"resource\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry schema resource\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#args\n" } }, - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob\nrepresenting an instance of the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#command\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob\nrepresenting an instance of the DSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#command\n", + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `schema` command for the resource when no arguments are required.\n", + "body": { + "executable": "${1:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the `schema` command for the resource when at least one argument is required.\n", + "body": { + "executable": "${1:executable_name}", + "args": [ + "${2:--first-argument}" + ] + } + } + ] }, "embedded": { "title": "Embedded Instance Schema", "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the JSON Schema DSC must use to validate a JSON blob representing an instance of the\nDSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the JSON Schema DSC must use to validate a JSON blob representing an instance of the\nDSC Resource.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "$schema", @@ -468,7 +834,7 @@ "title": "Instance Type", "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", "const": "object", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the JSON type for an instance of the DSC Resource. DSC Resource instances always\nhave the `object` type.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true#type\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the JSON type for an instance of the DSC Resource. DSC Resource instances always\nhave the `object` type.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserve-view=true#type\n" }, "$schema": { "title": "DSC Resource instance schema dialect", @@ -480,11 +846,11 @@ "https://json-schema.org/draft/2019-09/schema", "http://json-schema.org/draft-07/schema#" ], - "markdownDescription": "> [Online Documentation][01]\n\nDefines the JSON type for an instance of the DSC Resource. DSC Resource instances always\nhave the `object` type. DSC only supports JSON Schema Draft 07 and later.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserveView=true#type\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the JSON type for an instance of the DSC Resource. DSC Resource instances always\nhave the `object` type. DSC only supports JSON Schema Draft 07 and later.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserve-view=true#type\n", "markdownEnumDescriptions": [ - "Indicates the resource instance schema adheres to [JSON Schema Draft 2020-12][01].\n\n[01]: https://json-schema.org/specification-links.html#2020-12\n", - "Indicates the resource instance schema adheres to [JSON Schema Draft 2019-09][01].\n\n[01]: https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8\n", - "Indicates the resource instance schema adheres to [JSON Schema Draft 07][01].\n\n[01]: https://json-schema.org/specification-links.html#draft-7\n" + "_Draft 2020-12 (recommended)_\n\n> Indicates that the resource instance schema adheres to\n> [JSON Schema Draft 2020-12][01].\n>\n> This is the latest published draft of JSON Schema and is the draft future drafts\n> will be most compatible with.\n\n[01]: https://json-schema.org/specification-links.html#2020-12\n", + "_Draft 2019-09_\n\n> Indicates that the resource instance schema adheres to\n> [JSON Schema Draft 2019-09][01].\n>\n> This is the previous published draft of JSON Schema. It's mostly compatible with\n> 2020-12, but less extensible and can't be bundled.\n\n[01]: https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8\n", + "_Draft 07_\n\n> Indicates that the resource instance schema adheres to [JSON Schema Draft 07][01].\n>\n> This is an older published draft of JSON Schema. It's widely used, but incompatible\n> with 2019-09 and later. It's less expressive, extensible, maintainable, and isn't\n> recommended for new schema definitions.\n\n[01]: https://json-schema.org/specification-links.html#draft-7\n" ] }, "$id": { @@ -492,12 +858,12 @@ "description": "Defines the unique ID for the DSC Resource's instance schema. If the instance schema is published to its own public URI, set this keyword to that URI.", "type": "string", "format": "uri-reference", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the unique ID for the DSC Resource's instance schema. If the instance schema is\npublished to its own public URI, set this keyword to that URI.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#id\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the unique ID for the DSC Resource's instance schema. If the instance schema is\npublished to its own public URI, set this keyword to that URI.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#id\n" }, "properties": { "title": "Instance Properties", "description": "Defines the properties that DSC can retrieve and manage for the resource's instances. This keyword must define at least one property as a key-value pair. The key is the property's name. The value is a subschema that validates the property.", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the properties that DSC can retrieve and manage for the resource's instances.\nThis keyword must define at least one property as a key-value pair. The key is the\nproperty's name. The value is a subschema that validates the property.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#properties\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the properties that DSC can retrieve and manage for the resource's instances.\nThis keyword must define at least one property as a key-value pair. The key is the\nproperty's name. The value is a subschema that validates the property.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#properties\n", "type": "object", "minProperties": 1, "unevaluatedProperties": { @@ -513,6 +879,104 @@ } ] }, + "additionalProperties": { + "defaultSnippets": [ + { + "label": " Define a property", + "markdownDescription": "Define a new property for the resource instance schema.", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "${3|boolean,string,integer,number,array,object,null|}" + } + }, + { + "label": " Define a property (boolean)", + "markdownDescription": "Define a new [boolean][01] property for the resource instance schema, requiring the\nvalue to be either `true` or `false`.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/boolean.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "boolean" + } + }, + { + "label": " Define a property (string)", + "markdownDescription": "Define a new [string][01] property for the resource instance schema, requiring the\nvalue to be a blob of text.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/string.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "string" + } + }, + { + "label": " Define a property (integer)", + "markdownDescription": "Define a new [integer][01] property for the resource instance schema, requiring the\nvalue to be a number without a fractional part.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/numeric.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "integer" + } + }, + { + "label": " Define a property (number)", + "markdownDescription": "Define a new [number][01] property for the resource instance schema, requiring the\nvalue to be a number that may include a fractional part.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/numeric.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "number" + } + }, + { + "label": " Define a property (array)", + "markdownDescription": "Define a new [array][01] property for the resource instance schema, requiring the\nvalue to be a list of values.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/array.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "array", + "items": { + "type": "${3|boolean,string,integer,number,array,object,null|}" + } + } + }, + { + "label": " Define a property (object)", + "markdownDescription": "Define a new [object][01] property for the resource instance schema, requiring the\nvalue to be a set of key-value pairs.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/object.html", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "type": "object", + "properties": { + "${3:propertyName}": { + "title": "${4:propertyTitle}", + "description": "${5:explanation of property purpose and usage}", + "type": "${6|string,integer,number,array,object,null|}" + } + } + } + }, + { + "label": " Define a property (enum)", + "markdownDescription": "Define a new [enum][01] property for the resource instance schema that only accepts\na defined set of values.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "enum": [ + "^${3:\"first value\"}", + "^${4:\"second value\"}" + ] + } + }, + { + "label": " Define a property (const)", + "markdownDescription": "Define a new [const][01] property for the resource instance schema that only\naccepts a specific value.\n\n[01]: https://json-schema.org/understanding-json-schema/reference/generic.html#constant-values", + "body": { + "title": "${1:property title}", + "description": "${2:explanation of property purpose and usage}", + "const": "^${3:\"constant value\"}" + } + } + ] + }, "properties": { "_ensure": { "title": "Standard Property: _ensure", @@ -520,15 +984,15 @@ "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nIndicates that the DSC Resource uses the standard `_ensure` property to specify\nwhether an instance should exist with the `Present` and `Absent` enums.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/ensure?view=dsc-3.0&preserveView=true\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nIndicates that the resource can enforce whether instances exist using the shared\n`present` and `absent` semantics. If a resource must distinguish between states\nbeyond whether an instance is `present` or `absent`, the resource should define its\nown `ensure` property without the leading underscore. This property provides shared\nsemantics for DSC Resources and integrating tools, but doesn't enable any additional\nbuilt-in processing with DSC.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/ensure?view=dsc-3.0&preserve-view=true\n" }, "_inDesiredState": { "title": "Standard Property: _inDesiredState", - "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This read-only property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nIndicates that the DSC Resource returns this value for it's own `test` method. This\nproperty is mandatory when the manifest defines the `test` property. It shouldn't\nbe included if the DSC Resource relies on DSC's synthetic testing.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/indesiredstate?view=dsc-3.0&preserveView=true\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nIndicates that the DSC Resource returns this value for it's own `test` method. This\nproperty is mandatory when the manifest defines the `test` property. It shouldn't\nbe included if the DSC Resource relies on DSC's synthetic testing.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/indesiredstate?view=dsc-3.0&preserve-view=true\n" }, "_purge": { "title": "Standard Property: _purge", @@ -536,17 +1000,30 @@ "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nIndicates that the DSC Resource uses the standard `_purge` property to specify\nwhether the DSC Resource should remove all non-specified members when it manages\nan array of members or values.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/purge?view=dsc-3.0&preserveView=true\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nIndicates that the DSC Resource uses the standard `_purge` property to specify\nwhether the DSC Resource should remove all non-specified members when it manages\nan array of members or values.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/purge?view=dsc-3.0&preserve-view=true\n" }, "_rebootRequested": { "title": "Standard property: _rebootRequested", - "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "description": "Indicates whether a resource instance requires a reboot after a set operation. To use DSC's built-in reboot notification processing, resources must define this property in their manifest.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" }, - "markdownDescription": "> [Online Documentation][01]\n\nIndicates that the DSC Resource uses the standard `_rebootRequested` property to\nreport whether the machine should be rebooted after the `set` method executes.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/rebootrequested?view=dsc-3.0&preserveView=true\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nIndicates that the DSC Resource uses the standard `_rebootRequested` property to\nreport whether the machine should be rebooted after the `set` method executes.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/rebootrequested?view=dsc-3.0&preserve-view=true\n" } - } + }, + "defaultSnippets": [ + { + "label": " Define an instance property", + "markdownDescription": "Define a property for the resource instance schema.", + "body": { + "${1:propertyName}": { + "title": "${2:property title}", + "description": "${3:explanation of property purpose and usage}", + "type": "${4|string,integer,number,array,object,null|}" + } + } + } + ] } } }, @@ -555,7 +1032,7 @@ "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", "type": "string", "format": "uri", - "markdownDescription": "> [Online Documentation][01]\n\nDefines the URL to the DSC Resource's JSON schema for integrating tools.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true#url\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the URL to the DSC Resource's JSON schema for integrating tools.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#url\n" } }, "examples": [ @@ -627,7 +1104,47 @@ } } ], - "markdownDescription": "> [Online Documentation][01]\n\nDefines how DSC must validate a JSON blob representing an instance of the DSC Resource.\n\nThe JSON schema can be defined dynamically with the `command` property or statically with the\n`embedded` property.\n\nFor development purposes, it can be more convenient to use the `command` property and avoid\nneeding to adjust both the code and the schema.\n\nMicrosoft recommends using the `embedded` property when publishing a resource publicly. When the\nmanifest declares the schema with the `command` property, DSC calls the command at the beginning\nof any operation using the resource, possibly impacting performance. The schema is also\nunavailable to integrating tools when the resource isn't installed locally. When the schema is\nembedded in the manifest, DSC and integrating tools only need the manifest itself.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserveView=true\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must validate a JSON blob representing an instance of the DSC Resource.\n\nThe JSON schema can be defined dynamically with the `command` property or statically with the\n`embedded` property.\n\nFor development purposes, it can be more convenient to use the `command` property and avoid\nneeding to adjust both the code and the schema.\n\nMicrosoft recommends using the `embedded` property when publishing a resource publicly. When the\nmanifest declares the schema with the `command` property, DSC calls the command at the beginning\nof any operation using the resource, possibly impacting performance. The schema is also\nunavailable to integrating tools when the resource isn't installed locally. When the schema is\nembedded in the manifest, DSC and integrating tools only need the manifest itself.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true\n", + "defaultSnippets": [ + { + "label": " Define as command without arguments", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefine the resource instance schema as a command when no arguments are required.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#command\n", + "body": { + "command": { + "executable": "${1:executable_name}" + } + } + }, + { + "label": " Define as command with arguments", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefine the resource instance schema as a command when at least one argument is required.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#command\n", + "body": { + "command": { + "executable": "${1:executable_name}", + "args": [ + "${2:--first-argument}" + ] + } + } + }, + { + "label": " Define as an embedded schema", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefine the resource instance schema embedded in the manifest. This is the preferred option\nfor publicly published resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/embedded?view=dsc-3.0&preserve-view=true\n", + "body": { + "embedded": { + "${escape_dollar:$}schema": "${1|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "${2:name}": { + "title": "${3:property title}", + "description": "${4:explanation of property purpose and usage}", + "type": "${5|string,integer,number,array,object,null|}" + } + } + } + } + } + ] } } } @@ -637,4 +1154,4 @@ } } } -} +} diff --git a/schemas/2023/08/definitions/semver.json b/schemas/2023/08/definitions/semver.json index 24d89afc..a49169e6 100644 --- a/schemas/2023/08/definitions/semver.json +++ b/schemas/2023/08/definitions/semver.json @@ -4,5 +4,6 @@ "type": "string", "title": "Semantic Version", "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" } diff --git a/schemas/2023/08/resource/manifest.json b/schemas/2023/08/resource/manifest.json index a3afd66c..5abfbd96 100644 --- a/schemas/2023/08/resource/manifest.json +++ b/schemas/2023/08/resource/manifest.json @@ -15,7 +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" + "enum": "1.0" }, "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" diff --git a/schemas/2023/08/resource/manifest.schema.json b/schemas/2023/08/resource/manifest.schema.json index 29ad74b5..39f84bbc 100644 --- a/schemas/2023/08/resource/manifest.schema.json +++ b/schemas/2023/08/resource/manifest.schema.json @@ -77,6 +77,7 @@ } ] }, + "additionalProperties": {}, "properties": { "_ensure": { "title": "Standard Property: _ensure", @@ -87,7 +88,7 @@ }, "_inDesiredState": { "title": "Standard Property: _inDesiredState", - "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This read-only property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" } @@ -101,7 +102,7 @@ }, "_rebootRequested": { "title": "Standard property: _rebootRequested", - "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "description": "Indicates whether a resource instance requires a reboot after a set operation. To use DSC's built-in reboot notification processing, resources must define this property in their manifest.", "const": { "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" } diff --git a/schemas/2023/08/resource/manifest.set.json b/schemas/2023/08/resource/manifest.set.json index aa39c13e..0c2a5fdd 100644 --- a/schemas/2023/08/resource/manifest.set.json +++ b/schemas/2023/08/resource/manifest.set.json @@ -18,7 +18,7 @@ "input": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" }, - "implementsPretest": { + "preTest": { "title": "Resource Performs Pre-Test", "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", "type": "boolean", @@ -36,7 +36,7 @@ "set" ], "input": "stdin", - "implementsPretest": true, + "preTest": true, "return": "state" } -} +} From 133b431461ce8d5a2314980e0cb513484b6c3930 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 27 Sep 2023 12:51:41 -0500 Subject: [PATCH 09/16] (SCHEMA) Replace `preTest` with `implementsPretest` This change updates the schemas to reflect the renaming of the `set.preTest` setting in the resource manifest to the more readable and semantically correct `set.implementsPretest` to reflect the change in #197. --- .../08/bundled/outputs/resource/list.json | 4 +-- .../2023/08/bundled/resource/manifest.json | 4 +-- .../08/bundled/resource/manifest.vscode.json | 16 +++++----- schemas/2023/08/resource/manifest.set.json | 4 +-- schemas/src/resource/manifest.set.yaml | 26 ++++++++-------- schemas/src/resource/manifest.yaml | 30 +++++++++---------- 6 files changed, 42 insertions(+), 42 deletions(-) diff --git a/schemas/2023/08/bundled/outputs/resource/list.json b/schemas/2023/08/bundled/outputs/resource/list.json index 9b93ca4d..2e93fd77 100644 --- a/schemas/2023/08/bundled/outputs/resource/list.json +++ b/schemas/2023/08/bundled/outputs/resource/list.json @@ -260,7 +260,7 @@ "input": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" }, - "preTest": { + "implementsPretest": { "title": "Resource Performs Pre-Test", "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", "type": "boolean", @@ -278,7 +278,7 @@ "set" ], "input": "stdin", - "preTest": true, + "implementsPretest": true, "return": "state" } }, diff --git a/schemas/2023/08/bundled/resource/manifest.json b/schemas/2023/08/bundled/resource/manifest.json index db557037..9148f835 100644 --- a/schemas/2023/08/bundled/resource/manifest.json +++ b/schemas/2023/08/bundled/resource/manifest.json @@ -173,7 +173,7 @@ "input": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" }, - "preTest": { + "implementsPretest": { "title": "Resource Performs Pre-Test", "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", "type": "boolean", @@ -191,7 +191,7 @@ "set" ], "input": "stdin", - "preTest": true, + "implementsPretest": true, "return": "state" } }, diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json index 5137e19f..d94af8d0 100644 --- a/schemas/2023/08/bundled/resource/manifest.vscode.json +++ b/schemas/2023/08/bundled/resource/manifest.vscode.json @@ -26,7 +26,7 @@ "${9:argument}" ], "input": "${10:stdin}", - "preTest": "^${11:false}", + "implementsPretest": "^${11:false}", "return": "${12:state}" }, "schema": { @@ -73,7 +73,7 @@ "${14:argument}" ], "input": "${15:stdin}", - "preTest": "^${16:false}", + "implementsPretest": "^${16:false}", "return": "${17:state}" }, "schema": { @@ -128,7 +128,7 @@ "${14:argument}" ], "input": "${15:stdin}", - "preTest": "^${16:false}", + "implementsPretest": "^${16:false}", "return": "${17:state}" }, "provider": { @@ -501,12 +501,12 @@ "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as arguments or JSON over `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" }, - "preTest": { + "implementsPretest": { "title": "Resource Performs Pre-Test", "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", "type": "boolean", "default": false, - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the DSC Resource performs its own test to ensure idempotency when calling the\n`set` command. Set this value to `true` if the DSC Resource tests input before modifying\nsystem state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#pretest\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the DSC Resource performs its own test to ensure idempotency when calling the\n`set` command. Set this value to `true` if the DSC Resource tests input before modifying\nsystem state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#implementspretest\n" }, "return": { "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", @@ -526,7 +526,7 @@ "set" ], "input": "stdin", - "preTest": true, + "implementsPretest": true, "return": "state" } ], @@ -536,7 +536,7 @@ "markdownDescription": "Define the `set` command for the resource when no arguments are required.\n", "body": { "input": "${1|input,args|}", - "preTest": "^${2|true,false|}", + "implementsPretest": "^${2|true,false|}", "return": "${3|state,stateAndDiff|}", "executable": "${4:executable_name}" } @@ -546,7 +546,7 @@ "markdownDescription": "Define the `set` command for the resource when at least one argument is required.\n", "body": { "input": "$1", - "preTest": "^$2", + "implementsPretest": "^$2", "return": "$3", "executable": "${4:executable_name}", "args": [ diff --git a/schemas/2023/08/resource/manifest.set.json b/schemas/2023/08/resource/manifest.set.json index 0c2a5fdd..d065286a 100644 --- a/schemas/2023/08/resource/manifest.set.json +++ b/schemas/2023/08/resource/manifest.set.json @@ -18,7 +18,7 @@ "input": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" }, - "preTest": { + "implementsPretest": { "title": "Resource Performs Pre-Test", "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", "type": "boolean", @@ -36,7 +36,7 @@ "set" ], "input": "stdin", - "preTest": true, + "implementsPretest": true, "return": "state" } } diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 23c4b242..53f42809 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -71,7 +71,7 @@ properties: [01]: /reference/schemas/resource/manifest/set?#input - preTest: + implementsPretest: title: Resource Performs Pre-Test description: >- Defines whether the DSC Resource performs its own test to ensure idempotency when calling the @@ -89,7 +89,7 @@ properties: `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state. - [01]: /reference/schemas/resource/manifest/set?#pretest + [01]: /reference/schemas/resource/manifest/set?#implementspretest return: description: >- Defines whether the command returns a JSON blob of the DSC Resource's state after the set @@ -122,26 +122,26 @@ examples: args: - config - set - input: stdin - preTest: true - return: state + input: stdin + implementsPretest: true + return: state defaultSnippets: # VS Code only - label: ' Define without arguments' markdownDescription: | Define the `set` command for the resource when no arguments are required. body: - input: ${1|input,args|} - preTest: ^${2|true,false|} - return: ${3|state,stateAndDiff|} - executable: ${4:executable_name} + input: ${1|input,args|} + implementsPretest: ^${2|true,false|} + return: ${3|state,stateAndDiff|} + executable: ${4:executable_name} - label: ' Define with arguments' markdownDescription: | Define the `set` command for the resource when at least one argument is required. body: - input: $1 - preTest: ^$2 - return: $3 - executable: ${4:executable_name} + input: $1 + implementsPretest: ^$2 + return: $3 + executable: ${4:executable_name} args: - ${5:--first-argument} diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index a58644b4..29ed649e 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -39,11 +39,11 @@ defaultSnippets: args: ['${6:argument}'] input: ${7:stdin} set: - executable: ${8:executable name} - args: ['${9:argument}'] - input: ${10:stdin} - preTest: ^${11:false} - return: ${12:state} + executable: ${8:executable name} + args: ['${9:argument}'] + input: ${10:stdin} + implementsPretest: ^${11:false} + return: ${12:state} schema: embedded: ${escape_dollar:$}schema: ${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} @@ -71,11 +71,11 @@ defaultSnippets: input: ${10:stdin} return: ${12:state} set: - executable: ${13:executable name} - args: ['${14:argument}'] - input: ${15:stdin} - preTest: ^${16:false} - return: ${17:state} + executable: ${13:executable name} + args: ['${14:argument}'] + input: ${15:stdin} + implementsPretest: ^${16:false} + return: ${17:state} schema: embedded: ${escape_dollar:$}schema: ${18|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} @@ -110,11 +110,11 @@ defaultSnippets: input: ${10:stdin} return: ${12:state} set: - executable: ${13:executable name} - args: ['${14:argument}'] - input: ${15:stdin} - preTest: ^${16:false} - return: ${17:state} + executable: ${13:executable name} + args: ['${14:argument}'] + input: ${15:stdin} + implementsPretest: ^${16:false} + return: ${17:state} provider: config: ${18|full,sequence|} list: From 4332f3dffa5212663974362a585a29c9fbcee5aa Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 27 Sep 2023 14:33:56 -0500 Subject: [PATCH 10/16] (MAINT) Fix schema gen for array values Prior to this change, the schema generation had a bug that incorrectly munged the values for always-array keywords, like `enum` and `requires` to scalar values when the definition was a single-item array. This change ensures that those values are not incorrectly munged, fixing hidden bugs in the behavior for those values in the generated schemas. --- schemas/2023/08/bundled/config/document.json | 8 +- .../2023/08/bundled/outputs/resource/get.json | 4 +- .../08/bundled/outputs/resource/list.json | 144 +++++++++++------- .../2023/08/bundled/resource/manifest.json | 136 ++++++++++------- schemas/2023/08/config/document.json | 4 +- .../2023/08/config/document.parameter.json | 4 +- schemas/2023/08/outputs/resource/get.json | 4 +- schemas/2023/08/outputs/resource/list.json | 8 +- schemas/2023/08/resource/manifest.export.json | 4 +- schemas/2023/08/resource/manifest.get.json | 4 +- schemas/2023/08/resource/manifest.json | 20 ++- .../2023/08/resource/manifest.provider.json | 30 ++-- schemas/2023/08/resource/manifest.schema.json | 16 +- schemas/2023/08/resource/manifest.set.json | 22 +-- schemas/2023/08/resource/manifest.test.json | 20 +-- .../2023/08/resource/manifest.validate.json | 20 ++- schemas/build.ps1 | 11 +- 17 files changed, 286 insertions(+), 173 deletions(-) diff --git a/schemas/2023/08/bundled/config/document.json b/schemas/2023/08/bundled/config/document.json index b03ace6e..0a0b72c2 100644 --- a/schemas/2023/08/bundled/config/document.json +++ b/schemas/2023/08/bundled/config/document.json @@ -14,7 +14,9 @@ "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", "type": "string", "format": "uri", - "enum": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] }, "parameters": { "title": "DSC Configuration document parameters", @@ -51,7 +53,9 @@ "title": "Parameter", "description": "Defines a runtime option for a DSC Configuration Document.", "type": "object", - "required": "type", + "required": [ + "type" + ], "properties": { "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" diff --git a/schemas/2023/08/bundled/outputs/resource/get.json b/schemas/2023/08/bundled/outputs/resource/get.json index f1b85eb6..8ed6684d 100644 --- a/schemas/2023/08/bundled/outputs/resource/get.json +++ b/schemas/2023/08/bundled/outputs/resource/get.json @@ -4,7 +4,9 @@ "title": "dsc resource get result", "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", "type": "object", - "required": "actualState", + "required": [ + "actualState" + ], "properties": { "actualState": { "title": "Actual state", diff --git a/schemas/2023/08/bundled/outputs/resource/list.json b/schemas/2023/08/bundled/outputs/resource/list.json index 2e93fd77..ba3fc778 100644 --- a/schemas/2023/08/bundled/outputs/resource/list.json +++ b/schemas/2023/08/bundled/outputs/resource/list.json @@ -34,13 +34,17 @@ "title": "Standard implementation", "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", "type": "string", - "enum": "Command" + "enum": [ + "Command" + ] }, { "title": "Custom implementation", "description": "Indicates that the DSC Resource uses a custom implementation.", "type": "object", - "required": "custom", + "required": [ + "custom" + ], "properties": { "custom": { "title": "Custom implementation name", @@ -119,7 +123,9 @@ "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", - "enum": "1.0" + "enum": [ + "1.0" + ] }, "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" @@ -179,13 +185,15 @@ "0": "Success", "1": "Error" }, - "examples": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } + "examples": [ + { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + ] }, "schema": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json" @@ -198,7 +206,9 @@ "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -230,7 +240,9 @@ "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -271,16 +283,18 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "set" - ], - "input": "stdin", - "implementsPretest": true, - "return": "state" - } + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "implementsPretest": true, + "return": "state" + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -308,15 +322,17 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "test" - ], - "input": "stdin", - "return": "state" - } + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -324,7 +340,9 @@ "title": "Validate Method", "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -333,13 +351,15 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" } }, - "examples": { - "executable": "dsc", - "args": [ - "config", - "validate" - ] - } + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -356,7 +376,9 @@ "title": "List Command", "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -376,19 +398,21 @@ ] } }, - "examples": { - "config": "full", - "list": { - "executable": "pwsh", - "args": [ - "-NoLogo", - "-NonInteractive", - "-NoProfile", - "-Command", - "./powershellgroup.resource.ps1 List" - ] + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } } - } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -398,10 +422,14 @@ "type": "object", "oneOf": [ { - "required": "command" + "required": [ + "command" + ] }, { - "required": "embedded" + "required": [ + "embedded" + ] } ], "properties": { @@ -409,7 +437,9 @@ "title": "Instance Schema Command", "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -514,7 +544,9 @@ { "command": { "executable": "registry", - "args": "schema" + "args": [ + "schema" + ] } }, { diff --git a/schemas/2023/08/bundled/resource/manifest.json b/schemas/2023/08/bundled/resource/manifest.json index 9148f835..122a263d 100644 --- a/schemas/2023/08/bundled/resource/manifest.json +++ b/schemas/2023/08/bundled/resource/manifest.json @@ -15,7 +15,9 @@ "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", - "enum": "1.0" + "enum": [ + "1.0" + ] }, "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" @@ -75,13 +77,15 @@ "0": "Success", "1": "Error" }, - "examples": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } + "examples": [ + { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + ] }, "schema": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json" @@ -111,7 +115,9 @@ "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -143,7 +149,9 @@ "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -184,16 +192,18 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "set" - ], - "input": "stdin", - "implementsPretest": true, - "return": "state" - } + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "implementsPretest": true, + "return": "state" + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -221,15 +231,17 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "test" - ], - "input": "stdin", - "return": "state" - } + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -237,7 +249,9 @@ "title": "Validate Method", "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -246,13 +260,15 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" } }, - "examples": { - "executable": "dsc", - "args": [ - "config", - "validate" - ] - } + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -269,7 +285,9 @@ "title": "List Command", "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -289,19 +307,21 @@ ] } }, - "examples": { - "config": "full", - "list": { - "executable": "pwsh", - "args": [ - "-NoLogo", - "-NonInteractive", - "-NoProfile", - "-Command", - "./powershellgroup.resource.ps1 List" - ] + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } } - } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -311,10 +331,14 @@ "type": "object", "oneOf": [ { - "required": "command" + "required": [ + "command" + ] }, { - "required": "embedded" + "required": [ + "embedded" + ] } ], "properties": { @@ -322,7 +346,9 @@ "title": "Instance Schema Command", "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -427,7 +453,9 @@ { "command": { "executable": "registry", - "args": "schema" + "args": [ + "schema" + ] } }, { diff --git a/schemas/2023/08/config/document.json b/schemas/2023/08/config/document.json index 8078b2ba..234c5761 100644 --- a/schemas/2023/08/config/document.json +++ b/schemas/2023/08/config/document.json @@ -14,7 +14,9 @@ "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", "type": "string", "format": "uri", - "enum": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] }, "parameters": { "title": "DSC Configuration document parameters", diff --git a/schemas/2023/08/config/document.parameter.json b/schemas/2023/08/config/document.parameter.json index 86b21705..82966dc9 100644 --- a/schemas/2023/08/config/document.parameter.json +++ b/schemas/2023/08/config/document.parameter.json @@ -4,7 +4,9 @@ "title": "Parameter", "description": "Defines a runtime option for a DSC Configuration Document.", "type": "object", - "required": "type", + "required": [ + "type" + ], "properties": { "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" diff --git a/schemas/2023/08/outputs/resource/get.json b/schemas/2023/08/outputs/resource/get.json index 9c191c86..00a30602 100644 --- a/schemas/2023/08/outputs/resource/get.json +++ b/schemas/2023/08/outputs/resource/get.json @@ -4,7 +4,9 @@ "title": "dsc resource get result", "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", "type": "object", - "required": "actualState", + "required": [ + "actualState" + ], "properties": { "actualState": { "title": "Actual state", diff --git a/schemas/2023/08/outputs/resource/list.json b/schemas/2023/08/outputs/resource/list.json index 88eada11..13b4a509 100644 --- a/schemas/2023/08/outputs/resource/list.json +++ b/schemas/2023/08/outputs/resource/list.json @@ -34,13 +34,17 @@ "title": "Standard implementation", "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", "type": "string", - "enum": "Command" + "enum": [ + "Command" + ] }, { "title": "Custom implementation", "description": "Indicates that the DSC Resource uses a custom implementation.", "type": "object", - "required": "custom", + "required": [ + "custom" + ], "properties": { "custom": { "title": "Custom implementation name", diff --git a/schemas/2023/08/resource/manifest.export.json b/schemas/2023/08/resource/manifest.export.json index e1fc9ed7..5c918b52 100644 --- a/schemas/2023/08/resource/manifest.export.json +++ b/schemas/2023/08/resource/manifest.export.json @@ -4,7 +4,9 @@ "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" diff --git a/schemas/2023/08/resource/manifest.get.json b/schemas/2023/08/resource/manifest.get.json index 8ccfa99b..351aa81d 100644 --- a/schemas/2023/08/resource/manifest.get.json +++ b/schemas/2023/08/resource/manifest.get.json @@ -4,7 +4,9 @@ "title": "Get Method", "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" diff --git a/schemas/2023/08/resource/manifest.json b/schemas/2023/08/resource/manifest.json index 5abfbd96..40185d7c 100644 --- a/schemas/2023/08/resource/manifest.json +++ b/schemas/2023/08/resource/manifest.json @@ -15,7 +15,9 @@ "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", - "enum": "1.0" + "enum": [ + "1.0" + ] }, "type": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" @@ -75,13 +77,15 @@ "0": "Success", "1": "Error" }, - "examples": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } + "examples": [ + { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + ] }, "schema": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json" diff --git a/schemas/2023/08/resource/manifest.provider.json b/schemas/2023/08/resource/manifest.provider.json index 86f51156..efbcbcf3 100644 --- a/schemas/2023/08/resource/manifest.provider.json +++ b/schemas/2023/08/resource/manifest.provider.json @@ -13,7 +13,9 @@ "title": "List Command", "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -33,17 +35,19 @@ ] } }, - "examples": { - "config": "full", - "list": { - "executable": "pwsh", - "args": [ - "-NoLogo", - "-NonInteractive", - "-NoProfile", - "-Command", - "./powershellgroup.resource.ps1 List" - ] + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } } - } + ] } diff --git a/schemas/2023/08/resource/manifest.schema.json b/schemas/2023/08/resource/manifest.schema.json index 39f84bbc..58ab86d5 100644 --- a/schemas/2023/08/resource/manifest.schema.json +++ b/schemas/2023/08/resource/manifest.schema.json @@ -6,10 +6,14 @@ "type": "object", "oneOf": [ { - "required": "command" + "required": [ + "command" + ] }, { - "required": "embedded" + "required": [ + "embedded" + ] } ], "properties": { @@ -17,7 +21,9 @@ "title": "Instance Schema Command", "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -122,7 +128,9 @@ { "command": { "executable": "registry", - "args": "schema" + "args": [ + "schema" + ] } }, { diff --git a/schemas/2023/08/resource/manifest.set.json b/schemas/2023/08/resource/manifest.set.json index d065286a..7484863e 100644 --- a/schemas/2023/08/resource/manifest.set.json +++ b/schemas/2023/08/resource/manifest.set.json @@ -29,14 +29,16 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "set" - ], - "input": "stdin", - "implementsPretest": true, - "return": "state" - } + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "implementsPretest": true, + "return": "state" + } + ] } diff --git a/schemas/2023/08/resource/manifest.test.json b/schemas/2023/08/resource/manifest.test.json index 0cf89b00..c503d570 100644 --- a/schemas/2023/08/resource/manifest.test.json +++ b/schemas/2023/08/resource/manifest.test.json @@ -24,13 +24,15 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" } }, - "examples": { - "executable": "registry", - "args": [ - "config", - "test" - ], - "input": "stdin", - "return": "state" - } + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] } diff --git a/schemas/2023/08/resource/manifest.validate.json b/schemas/2023/08/resource/manifest.validate.json index fbb7b5e5..b646ae48 100644 --- a/schemas/2023/08/resource/manifest.validate.json +++ b/schemas/2023/08/resource/manifest.validate.json @@ -4,7 +4,9 @@ "title": "Validate Method", "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", "type": "object", - "required": "executable", + "required": [ + "executable" + ], "properties": { "executable": { "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" @@ -13,11 +15,13 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" } }, - "examples": { - "executable": "dsc", - "args": [ - "config", - "validate" - ] - } + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] } diff --git a/schemas/build.ps1 b/schemas/build.ps1 index 2f6044c2..1b11a870 100644 --- a/schemas/build.ps1 +++ b/schemas/build.ps1 @@ -90,7 +90,16 @@ begin { if ($_.Value -is [Object[]]) { if ($_.Value.Count -ge 1) { $MungedKeyValue = Remove-JsonSchemaKey -KeyName $KeyName -SchemaList $_.Value - $MungedSchema.Add($_.Key, $MungedKeyValue) + # Need to ensure single-item returns get correctly handled as arays, + # not munged into scalars. + if ( + ($MungedKeyValue.Count -eq 1) -or + ($MungedKeyValue -is [Specialized.OrderedDictionary]) + ) { + $MungedSchema.Add($_.Key, [object[]]$MungedKeyValue) + } else { + $MungedSchema.Add($_.Key, $MungedKeyValue) + } } else { $MungedSchema.Add($_.Key, $_.Value) } From 3d4cf8d556fd37c52ed570bc071528f3b8bff941 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 27 Sep 2023 14:35:59 -0500 Subject: [PATCH 11/16] (SCHEMA) Replace `manifestVersion` with `$schema` This change updates the schema definitions to replace the `manifestVersion` property for resource manifests with the more canonical `$schema` keyword to reflect the changes from #199. --- .../08/bundled/outputs/resource/list.json | 13 +++--- .../2023/08/bundled/resource/manifest.json | 29 +++++++------ .../08/bundled/resource/manifest.vscode.json | 43 ++++++++++--------- schemas/2023/08/resource/manifest.json | 13 +++--- schemas/src/resource/manifest.yaml | 33 +++++++------- 5 files changed, 69 insertions(+), 62 deletions(-) diff --git a/schemas/2023/08/bundled/outputs/resource/list.json b/schemas/2023/08/bundled/outputs/resource/list.json index ba3fc778..ff8f25c8 100644 --- a/schemas/2023/08/bundled/outputs/resource/list.json +++ b/schemas/2023/08/bundled/outputs/resource/list.json @@ -113,18 +113,19 @@ "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.", "type": "object", "required": [ - "manifestVersion", + "$schema", "type", "version", "get" ], "properties": { - "manifestVersion": { - "title": "Manifest Version", - "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", "enum": [ - "1.0" + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json" ] }, "type": { diff --git a/schemas/2023/08/bundled/resource/manifest.json b/schemas/2023/08/bundled/resource/manifest.json index 122a263d..a88f7a36 100644 --- a/schemas/2023/08/bundled/resource/manifest.json +++ b/schemas/2023/08/bundled/resource/manifest.json @@ -5,18 +5,19 @@ "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.", "type": "object", "required": [ - "manifestVersion", + "$schema", "type", "version", "get" ], "properties": { - "manifestVersion": { - "title": "Manifest Version", - "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", "enum": [ - "1.0" + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json" ] }, "type": { @@ -92,6 +93,14 @@ } }, "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", @@ -101,14 +110,6 @@ "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json", diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json index d94af8d0..bed84522 100644 --- a/schemas/2023/08/bundled/resource/manifest.vscode.json +++ b/schemas/2023/08/bundled/resource/manifest.vscode.json @@ -9,7 +9,7 @@ "label": " Define a resource", "markdownDescription": "Defines a standard resource that:\n\n- Can get the current state of an instance\n- Can set an instance to the desired state\n- Relies on DSC's synthetic testing to determine whether an instance is in the desired state\n- Defines an embedded JSON schema.", "body": { - "manifestVersion": "1.0", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", "version": "${3:0.1.0}", "description": "${4:Synopsis for the resource's purpose}", @@ -48,7 +48,7 @@ "label": " Define a resource (group)", "markdownDescription": "Defines a group resource that expects a list of resource instances and operates on them.", "body": { - "manifestVersion": "1.0", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", "version": "${3:0.1.0}", "description": "${4:Synopsis for the resource's purpose}", @@ -103,7 +103,7 @@ "label": " Define a resource (provider)", "markdownDescription": "Defines a provider resource that enables users to define non-command-based DSC Resources in\nthe configuration.", "body": { - "manifestVersion": "1.0", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", "version": "${3:0.1.0}", "description": "${4:Synopsis for the resource's purpose}", @@ -167,7 +167,7 @@ "label": " Define a resource (assertion-only)", "markdownDescription": "Defines an assertion resource that can get the current state of an instance but not configure\nit. By default, the resource relies on DSC's synthetic testing feature. If the resource\nimplements the `test` operation itself, define the `test` property.", "body": { - "manifestVersion": "1.0", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", "version": "${3:0.1.0}", "description": "${4:Synopsis for the resource's purpose}", @@ -196,20 +196,21 @@ ], "type": "object", "required": [ - "manifestVersion", + "$schema", "type", "version", "get" ], "properties": { - "manifestVersion": { - "title": "Manifest Version", - "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", "enum": [ - "1.0" + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json" ], - "markdownDescription": "***\n[_Online Documentation_][01]\n***\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&preserve-view=true#manifestversion\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property must be the canonical URL of the Command-based DSC Resource Manifest schema\nthat the manifest is implemented for.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#schema\n", "markdownEnumDescriptions": [ "_Initial release_\n" ] @@ -311,16 +312,6 @@ "2023": { "08": { "definitions": { - "semver.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", - "type": "string", - "title": "Semantic Version", - "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", - "patternErrorMessage": "Invalid value, must be a semantic version like `..`, such as `1.2.3`.\n\nThe value may also include pre-release version information and build metadata.\n", - "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" - }, "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", @@ -331,6 +322,16 @@ "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe namespaced name of the DSC Resource, using the syntax:\n\n```yaml\nowner[.group][.area]/name\n```\n\nFor example:\n\n- `Microsoft.SqlServer/Database`\n- `Microsoft.SqlServer.Database/User`\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/definitions/resourcetype?view=dsc-3.0&preserve-view=true\n", "patternErrorMessage": "Invalid type name. Valid resource type names always define an owner and a name separated by a\nslash, like `Microsoft/OSInfo`. Type names may optionally include a group and area to namespace\nthe resource under the owner, like `Microsoft.Windows/Registry`.\n" }, + "semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "patternErrorMessage": "Invalid value, must be a semantic version like `..`, such as `1.2.3`.\n\nThe value may also include pre-release version information and build metadata.\n", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" + }, "commandExecutable.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", diff --git a/schemas/2023/08/resource/manifest.json b/schemas/2023/08/resource/manifest.json index 40185d7c..25efc748 100644 --- a/schemas/2023/08/resource/manifest.json +++ b/schemas/2023/08/resource/manifest.json @@ -5,18 +5,19 @@ "description": "Defines the information DSC and integrating require to process and call a command-based DSC Resource.", "type": "object", "required": [ - "manifestVersion", + "$schema", "type", "version", "get" ], "properties": { - "manifestVersion": { - "title": "Manifest Version", - "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", "enum": [ - "1.0" + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json" ] }, "type": { diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index 29ed649e..8c2c13f7 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -30,7 +30,7 @@ defaultSnippets: - Relies on DSC's synthetic testing to determine whether an instance is in the desired state - Defines an embedded JSON schema. body: - manifestVersion: '1.0' + $schema: ///bundled/resource/manifest.yaml type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' version: '${3:0.1.0}' description: ${4:Synopsis for the resource's purpose} @@ -57,10 +57,10 @@ defaultSnippets: markdownDescription: |- Defines a group resource that expects a list of resource instances and operates on them. body: - manifestVersion: '1.0' + $schema: ///bundled/resource/manifest.yaml type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' version: '${3:0.1.0}' - description: ${4:Synopsis for the resource's purpose} + description: ${4:Synopsis for the resource's purpose} get: executable: ${5:executable name} args: ['${6:argument}'] @@ -96,10 +96,10 @@ defaultSnippets: Defines a provider resource that enables users to define non-command-based DSC Resources in the configuration. body: - manifestVersion: '1.0' + $schema: ///bundled/resource/manifest.yaml type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' version: '${3:0.1.0}' - description: ${4:Synopsis for the resource's purpose} + description: ${4:Synopsis for the resource's purpose} get: executable: ${5:executable name} args: ['${6:argument}'] @@ -141,10 +141,10 @@ defaultSnippets: it. By default, the resource relies on DSC's synthetic testing feature. If the resource implements the `test` operation itself, define the `test` property. body: - manifestVersion: '1.0' + $schema: ///bundled/resource/manifest.yaml type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' version: '${3:0.1.0}' - description: ${4:Synopsis for the resource's purpose} + description: ${4:Synopsis for the resource's purpose} get: executable: ${5:executable name} args: ['${6:argument}'] @@ -161,27 +161,30 @@ defaultSnippets: type: object required: - - manifestVersion + - $schema - type - version - get properties: - manifestVersion: - title: Manifest Version + $schema: + title: Manifest Schema description: >- - The semver of the DSC Resource manifest schema to validate this manifest with. - $ref: ///definitions/semver.yaml + This property must be the canonical URL of the Command-based DSC Resource Manifest schema + that the manifest is implemented for. + type: string + format: uri enum: - - '1.0' + - ///bundled/resource/manifest.yaml # VS Code Only markdownDescription: | *** [_Online Documentation_][01] *** - The semver of the DSC Resource manifest schema to validate this manifest with. + This property must be the canonical URL of the Command-based DSC Resource Manifest schema + that the manifest is implemented for. - [01]: /reference/schemas/resource/manifest/root?#manifestversion + [01]: /reference/schemas/resource/manifest/root?#schema markdownEnumDescriptions: - | # 1.0 _Initial release_ From 4f46ab656291f797954647a8d9ebf7424ca99343 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 27 Sep 2023 15:05:14 -0500 Subject: [PATCH 12/16] (MAINT) Fix config output schema references Prior to this change, the config command output schemas referenced the result data subschemas for the `dsc resource *` commands as `///results/resource/.yaml` instead of `///outputs/resource/.yaml`, which is their actual canonical URI. This change fixes the error, ensuring the schemas validate correctly. --- .../2023/08/bundled/outputs/config/get.json | 19 ++++++++- .../2023/08/bundled/outputs/config/set.json | 35 +++++++++++++++- .../2023/08/bundled/outputs/config/test.json | 41 ++++++++++++++++++- schemas/2023/08/outputs/config/get.json | 2 +- schemas/2023/08/outputs/config/set.json | 2 +- schemas/2023/08/outputs/config/test.json | 2 +- schemas/src/outputs/config/get.yaml | 2 +- schemas/src/outputs/config/set.yaml | 2 +- schemas/src/outputs/config/test.yaml | 2 +- 9 files changed, 98 insertions(+), 9 deletions(-) diff --git a/schemas/2023/08/bundled/outputs/config/get.json b/schemas/2023/08/bundled/outputs/config/get.json index 673aa7f0..6ddd148a 100644 --- a/schemas/2023/08/bundled/outputs/config/get.json +++ b/schemas/2023/08/bundled/outputs/config/get.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/get.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json" } } } @@ -60,6 +60,23 @@ "type": "string", "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json", + "title": "dsc resource get result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", + "type": "object", + "required": [ + "actualState" + ], + "properties": { + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json", diff --git a/schemas/2023/08/bundled/outputs/config/set.json b/schemas/2023/08/bundled/outputs/config/set.json index 2cf07b03..7df29415 100644 --- a/schemas/2023/08/bundled/outputs/config/set.json +++ b/schemas/2023/08/bundled/outputs/config/set.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/set.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json" } } } @@ -60,6 +60,39 @@ "type": "string", "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json", + "title": "dsc resource set result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", + "type": "object", + "required": [ + "beforeState", + "afterState", + "changedProperties" + ], + "properties": { + "beforeState": { + "title": "State before enforcing", + "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "afterState": { + "title": "State after enforcing", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "changedProperties": { + "title": "Changed properties", + "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json", diff --git a/schemas/2023/08/bundled/outputs/config/test.json b/schemas/2023/08/bundled/outputs/config/test.json index 372c8bd9..91f98d6b 100644 --- a/schemas/2023/08/bundled/outputs/config/test.json +++ b/schemas/2023/08/bundled/outputs/config/test.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/test.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json" } } } @@ -60,6 +60,45 @@ "type": "string", "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", + "type": "object", + "required": [ + "desiredState", + "actualState", + "inDesiredState", + "differingProperties" + ], + "properties": { + "desiredState": { + "title": "Desired state", + "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", + "type": "object" + }, + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "inDesiredState": { + "title": "Instance is in the desired state", + "description": "This property indicates whether the instance is in the desired state.", + "type": "boolean" + }, + "differingProperties": { + "title": "Differing properties", + "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json", diff --git a/schemas/2023/08/outputs/config/get.json b/schemas/2023/08/outputs/config/get.json index 9c5de7d6..61918db2 100644 --- a/schemas/2023/08/outputs/config/get.json +++ b/schemas/2023/08/outputs/config/get.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/get.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json" } } } diff --git a/schemas/2023/08/outputs/config/set.json b/schemas/2023/08/outputs/config/set.json index 450eb783..8da20f0c 100644 --- a/schemas/2023/08/outputs/config/set.json +++ b/schemas/2023/08/outputs/config/set.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/set.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json" } } } diff --git a/schemas/2023/08/outputs/config/test.json b/schemas/2023/08/outputs/config/test.json index 964c98fd..9e90567e 100644 --- a/schemas/2023/08/outputs/config/test.json +++ b/schemas/2023/08/outputs/config/test.json @@ -30,7 +30,7 @@ "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" }, "result": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/test.json" + "$ref": "/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json" } } } diff --git a/schemas/src/outputs/config/get.yaml b/schemas/src/outputs/config/get.yaml index 491d0b78..6e731a7b 100644 --- a/schemas/src/outputs/config/get.yaml +++ b/schemas/src/outputs/config/get.yaml @@ -31,7 +31,7 @@ properties: type: $ref: ///definitions/resourceType.yaml result: - $ref: ///results/resource/get.yaml + $ref: ///outputs/resource/get.yaml messages: $ref: ///definitions/messages.yaml hadErrors: diff --git a/schemas/src/outputs/config/set.yaml b/schemas/src/outputs/config/set.yaml index d6e97abe..653c1115 100644 --- a/schemas/src/outputs/config/set.yaml +++ b/schemas/src/outputs/config/set.yaml @@ -31,7 +31,7 @@ properties: type: $ref: ///definitions/resourceType.yaml result: - $ref: ///results/resource/set.yaml + $ref: ///outputs/resource/set.yaml messages: $ref: ///definitions/messages.yaml hadErrors: diff --git a/schemas/src/outputs/config/test.yaml b/schemas/src/outputs/config/test.yaml index ba79b740..28201af9 100644 --- a/schemas/src/outputs/config/test.yaml +++ b/schemas/src/outputs/config/test.yaml @@ -31,7 +31,7 @@ properties: type: $ref: ///definitions/resourceType.yaml result: - $ref: ///results/resource/test.yaml + $ref: ///outputs/resource/test.yaml messages: $ref: ///definitions/messages.yaml hadErrors: From fa82875192538a08c69896acba69501321d368af Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 27 Sep 2023 15:32:48 -0500 Subject: [PATCH 13/16] (SCHEMA) Replace `args` inputKind with `env` This change updates the schemas to replace the unimplemented `args` option for command input in the resource manifest with the `env` option. It also updates the schema and documentation to indicate that when the `input` option is not defined for a command in a resource manifest, DSC does not send the resource any input for that command. This update is made to reflect the changes from #198. --- .../08/bundled/outputs/resource/list.json | 7 ++-- .../2023/08/bundled/resource/manifest.json | 7 ++-- .../08/bundled/resource/manifest.vscode.json | 33 +++++++++---------- schemas/2023/08/definitions/inputKind.json | 7 ++-- schemas/src/definitions/inputKind.yaml | 27 ++++++++++----- schemas/src/resource/manifest.get.yaml | 8 +++-- schemas/src/resource/manifest.set.yaml | 12 ++++--- schemas/src/resource/manifest.test.yaml | 12 ++++--- 8 files changed, 63 insertions(+), 50 deletions(-) diff --git a/schemas/2023/08/bundled/outputs/resource/list.json b/schemas/2023/08/bundled/outputs/resource/list.json index ff8f25c8..5b5f4acd 100644 --- a/schemas/2023/08/bundled/outputs/resource/list.json +++ b/schemas/2023/08/bundled/outputs/resource/list.json @@ -632,13 +632,12 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", "title": "Executable Command Input Type", - "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", + "description": "Defines how DSC should pass input to the command, either as environment variables or JSON over stdin. When this value isn't defined, DSC doesn't send the resource any input.", "type": "string", "enum": [ - "args", + "env", "stdin" - ], - "default": "args" + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", diff --git a/schemas/2023/08/bundled/resource/manifest.json b/schemas/2023/08/bundled/resource/manifest.json index a88f7a36..c5d29991 100644 --- a/schemas/2023/08/bundled/resource/manifest.json +++ b/schemas/2023/08/bundled/resource/manifest.json @@ -541,13 +541,12 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", "title": "Executable Command Input Type", - "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", + "description": "Defines how DSC should pass input to the command, either as environment variables or JSON over stdin. When this value isn't defined, DSC doesn't send the resource any input.", "type": "string", "enum": [ - "args", + "env", "stdin" - ], - "default": "args" + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json index bed84522..251ca569 100644 --- a/schemas/2023/08/bundled/resource/manifest.vscode.json +++ b/schemas/2023/08/bundled/resource/manifest.vscode.json @@ -353,15 +353,14 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", "title": "Executable Command Input Type", - "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", + "description": "Defines how DSC should pass input to the command, either as environment variables or JSON over stdin. When this value isn't defined, DSC doesn't send the resource any input.", "type": "string", "enum": [ - "args", + "env", "stdin" ], - "default": "args", "markdownEnumDescriptions": [ - "_Command line arguments_\n\n> Indicates that the resource expects the properties of an instance to be specified with\n> command line arguments. This option isn't implemented yet.\n", + "_Environment variables_\n\n> Indicates that the resource expects the properties of an instance to be specified as\n> environment variables. This option only supports the following data types for instance\n> properties:\n>\n> - `boolean`\n> - `integer`\n> - `number`\n> - `string`\n> - `array` of `integer` values\n> - `array` of `number` values\n> - `array` of `string` values\n>\n> If the resource needs to support complex properties with an `object` value or multi-type\n> arrays, set this to `stdin` instead.\n", "_JSON over `stdin`_\n\n> Indicates that the resource expects a JSON blob representing an instance from `stdin`.\n> The JSON must adhere to the instance schema.\n" ] }, @@ -400,7 +399,7 @@ }, "input": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as arguments or JSON over `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#input\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. If this value isn't defined, DSC doesn't send the resource any input when\ninvoking the `get` operation.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#input\n" } }, "examples": [ @@ -421,7 +420,7 @@ "label": " Define without arguments", "markdownDescription": "Define the get command for the resource when no arguments are required.\n", "body": { - "input": "${1|stdin,args|}", + "input": "${1|stdin,env|}", "executable": "${2:executable_name}" } }, @@ -429,7 +428,7 @@ "label": " Define with arguments", "markdownDescription": "Define the get command for the resource when at least one argument is required.\n", "body": { - "input": "${1|stdin,args|}", + "input": "${1|stdin,env|}", "executable": "${2:executable_name}", "args": [ "${3:--first-argument}" @@ -500,7 +499,7 @@ }, "input": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as arguments or JSON over `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. If this value isn't defined, DSC doesn't send the resource any input when\ninvoking the `set` operation.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" }, "implementsPretest": { "title": "Resource Performs Pre-Test", @@ -536,7 +535,7 @@ "label": " Define without arguments", "markdownDescription": "Define the `set` command for the resource when no arguments are required.\n", "body": { - "input": "${1|input,args|}", + "input": "${1|input,env|}", "implementsPretest": "^${2|true,false|}", "return": "${3|state,stateAndDiff|}", "executable": "${4:executable_name}" @@ -546,9 +545,9 @@ "label": " Define with arguments", "markdownDescription": "Define the `set` command for the resource when at least one argument is required.\n", "body": { - "input": "$1", - "implementsPretest": "^$2", - "return": "$3", + "input": "${1|input,env|}", + "implementsPretest": "^${2|true,false|}", + "return": "${3|state,stateAndDiff|}", "executable": "${4:executable_name}", "args": [ "${5:--first-argument}" @@ -579,7 +578,7 @@ }, "input": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as arguments or JSON over `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. If this value isn't defined, DSC doesn't send the resource any input when\ninvoking the `test` operation.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" }, "return": { "title": "Test Command Return Type", @@ -608,8 +607,8 @@ "label": " Define without arguments", "markdownDescription": "Define the `test` command for the resource when no arguments are required.\n", "body": { - "input": "$1", - "return": "$2", + "input": "${1|input,env|}", + "return": "${2|state,stateAndDiff|}", "executable": "${3:executable_name}" } }, @@ -617,8 +616,8 @@ "label": " Define with arguments", "markdownDescription": "Define the `test` command for the resource when at least one argument is required.\n", "body": { - "input": "$1", - "return": "$2", + "input": "${1|input,env|}", + "return": "${2|state,stateAndDiff|}", "executable": "${3:executable_name}", "args": [ "${4:--first-argument}" diff --git a/schemas/2023/08/definitions/inputKind.json b/schemas/2023/08/definitions/inputKind.json index c6305bd5..5914172f 100644 --- a/schemas/2023/08/definitions/inputKind.json +++ b/schemas/2023/08/definitions/inputKind.json @@ -2,11 +2,10 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", "title": "Executable Command Input Type", - "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", + "description": "Defines how DSC should pass input to the command, either as environment variables or JSON over stdin. When this value isn't defined, DSC doesn't send the resource any input.", "type": "string", "enum": [ - "args", + "env", "stdin" - ], - "default": "args" + ] } diff --git a/schemas/src/definitions/inputKind.yaml b/schemas/src/definitions/inputKind.yaml index 9d5e4e0b..a1b3a1a4 100644 --- a/schemas/src/definitions/inputKind.yaml +++ b/schemas/src/definitions/inputKind.yaml @@ -4,22 +4,33 @@ $id: ///definitions/inputKind.yaml title: Executable Command Input Type description: >- - Defines how DSC should pass input to the command, either as arguments or - JSON over stdin. + Defines how DSC should pass input to the command, either as environment variables or + JSON over stdin. When this value isn't defined, DSC doesn't send the resource any input. type: string enum: - - args + - env - stdin -default: args # VS Code only # Don't define markdownDescription - each schema using this must define it, to link correctly. markdownEnumDescriptions: - - | # args - _Command line arguments_ + - | # env + _Environment variables_ - > Indicates that the resource expects the properties of an instance to be specified with - > command line arguments. This option isn't implemented yet. + > Indicates that the resource expects the properties of an instance to be specified as + > environment variables. This option only supports the following data types for instance + > properties: + > + > - `boolean` + > - `integer` + > - `number` + > - `string` + > - `array` of `integer` values + > - `array` of `number` values + > - `array` of `string` values + > + > If the resource needs to support complex properties with an `object` value or multi-type + > arrays, set this to `stdin` instead. - | # stdin _JSON over `stdin`_ diff --git a/schemas/src/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml index 0b3945be..b6f4bd67 100644 --- a/schemas/src/resource/manifest.get.yaml +++ b/schemas/src/resource/manifest.get.yaml @@ -64,7 +64,9 @@ properties: [_Online Documentation_][01] *** - Defines how DSC should pass input to the command, either as arguments or JSON over `stdin`. + Defines how DSC should pass input to the command, either as environment variables or JSON + over `stdin`. If this value isn't defined, DSC doesn't send the resource any input when + invoking the `get` operation. [01]: /reference/schemas/resource/manifest/get?#input @@ -81,13 +83,13 @@ defaultSnippets: # VS Code only markdownDescription: | Define the get command for the resource when no arguments are required. body: - input: ${1|stdin,args|} + input: ${1|stdin,env|} executable: ${2:executable_name} - label: ' Define with arguments' markdownDescription: | Define the get command for the resource when at least one argument is required. body: - input: ${1|stdin,args|} + input: ${1|stdin,env|} executable: ${2:executable_name} args: - ${3:--first-argument} diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 53f42809..0cf749b0 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -67,7 +67,9 @@ properties: [_Online Documentation_][01] *** - Defines how DSC should pass input to the command, either as arguments or JSON over `stdin`. + Defines how DSC should pass input to the command, either as environment variables or JSON + over `stdin`. If this value isn't defined, DSC doesn't send the resource any input when + invoking the `set` operation. [01]: /reference/schemas/resource/manifest/set?#input @@ -131,7 +133,7 @@ defaultSnippets: # VS Code only markdownDescription: | Define the `set` command for the resource when no arguments are required. body: - input: ${1|input,args|} + input: ${1|input,env|} implementsPretest: ^${2|true,false|} return: ${3|state,stateAndDiff|} executable: ${4:executable_name} @@ -139,9 +141,9 @@ defaultSnippets: # VS Code only markdownDescription: | Define the `set` command for the resource when at least one argument is required. body: - input: $1 - implementsPretest: ^$2 - return: $3 + input: ${1|input,env|} + implementsPretest: ^${2|true,false|} + return: ${3|state,stateAndDiff|} executable: ${4:executable_name} args: - ${5:--first-argument} diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index 2f8c86fa..cce072d3 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -68,7 +68,9 @@ properties: [_Online Documentation_][01] *** - Defines how DSC should pass input to the command, either as arguments or JSON over `stdin`. + Defines how DSC should pass input to the command, either as environment variables or JSON + over `stdin`. If this value isn't defined, DSC doesn't send the resource any input when + invoking the `test` operation. [01]: /reference/schemas/resource/manifest/set?#input return: @@ -111,15 +113,15 @@ defaultSnippets: # VS Code only markdownDescription: | Define the `test` command for the resource when no arguments are required. body: - input: $1 - return: $2 + input: ${1|input,env|} + return: ${2|state,stateAndDiff|} executable: ${3:executable_name} - label: ' Define with arguments' markdownDescription: | Define the `test` command for the resource when at least one argument is required. body: - input: $1 - return: $2 + input: ${1|input,env|} + return: ${2|state,stateAndDiff|} executable: ${3:executable_name} args: - ${4:--first-argument} From d354b80a5c696bd046870417fc247f29796ab086 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 27 Sep 2023 15:55:21 -0500 Subject: [PATCH 14/16] (MAINT) Formatting for schemas This change standardizes formatting for the default snippets definitions in the source schemas and ensures that every snippet label starts with a leading space - this puts them at the top of the IntelliSense list for completions when they are available. --- .../08/bundled/config/document.vscode.json | 14 ++--- .../08/bundled/resource/manifest.vscode.json | 2 +- schemas/src/config/document.parameter.yaml | 8 ++- schemas/src/config/document.resource.yaml | 7 ++- schemas/src/config/document.yaml | 13 +++-- schemas/src/resource/manifest.export.yaml | 5 +- schemas/src/resource/manifest.get.yaml | 5 +- schemas/src/resource/manifest.provider.yaml | 5 +- schemas/src/resource/manifest.schema.yaml | 22 +++++--- schemas/src/resource/manifest.set.yaml | 6 +- schemas/src/resource/manifest.test.yaml | 5 +- schemas/src/resource/manifest.validate.yaml | 5 +- schemas/src/resource/manifest.yaml | 55 ++++++++++--------- 13 files changed, 85 insertions(+), 67 deletions(-) diff --git a/schemas/2023/08/bundled/config/document.vscode.json b/schemas/2023/08/bundled/config/document.vscode.json index c5a55f6e..e844e2b6 100644 --- a/schemas/2023/08/bundled/config/document.vscode.json +++ b/schemas/2023/08/bundled/config/document.vscode.json @@ -112,14 +112,14 @@ "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a set of key-value pairs for the configuration. This metadata isn't validated.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#metadata-1\n", "defaultSnippets": [ { - "label": "New metadata property", + "label": " New metadata property", "markdownDescription": "Defines a key-value pair for the metadata:\n\n```yaml\nmetadataName: value\n```", "body": { "${1:metadataName}": "${2:value}" } }, { - "label": "New metadata property (object)", + "label": " New metadata property (object)", "markdownDescription": "Defines a new key-value pair for the metadata where the value is an object.\n\n```yaml\nmetadataName:\n key: value\n```", "body": { "${1:metadataName}": { @@ -128,7 +128,7 @@ } }, { - "label": "New metadata property (array)", + "label": " New metadata property (array)", "markdownDescription": "Defines a new key-value pair for the metadata where the value is an array.\n\n```yaml\nmetadataName:\n - firstValue\n - secondValue\n```", "body": { "${1:metadataName}": [ @@ -190,14 +190,14 @@ "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a set of key-value pairs for the parameter. This metadata isn't validated.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true#metadata-1\n", "defaultSnippets": [ { - "label": "New metadata property", + "label": " New metadata property", "markdownDescription": "Defines a key-value pair for the metadata:\n\n```yaml\nmetadataName: value\n```", "body": { "${1:metadataName}": "${2:value}" } }, { - "label": "New metadata property (object)", + "label": " New metadata property (object)", "markdownDescription": "Defines a new key-value pair for the metadata where the value is an object.\n\n```yaml\nmetadataName:\n key: value\n```", "body": { "${1:metadataName}": { @@ -206,7 +206,7 @@ } }, { - "label": "New metadata property (array)", + "label": " New metadata property (array)", "markdownDescription": "Defines a new key-value pair for the metadata where the value is an array.\n\n```yaml\nmetadataName:\n - firstValue\n - secondValue\n```", "body": { "${1:metadataName}": [ @@ -441,7 +441,7 @@ "patternErrorMessage": "Invalid value, must be a value like `[resourceId('', '`)], such as\n`[resourceId('Microsoft/OSInfo', 'Foo')]`.\n\nThe `` and `` should be the fully qualified type of the resource and its\nfriendly name in the configuration.\n", "defaultSnippets": [ { - "label": "New dependency", + "label": " New dependency", "markdownDescription": "Defines a new dependency for the resource instance.\n\n```yaml\n\"[resourceId('dependencyInstance/Type', 'dependencyInstanceName')]\"\n```", "bodyText": "\"[resourceId('${3:dependencyInstance/Type}', '${4:dependencyInstanceName}')]\"" } diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json index 251ca569..43c72024 100644 --- a/schemas/2023/08/bundled/resource/manifest.vscode.json +++ b/schemas/2023/08/bundled/resource/manifest.vscode.json @@ -290,7 +290,7 @@ "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property defines a map of valid exit codes for the DSC Resource. DSC always interprets\nexit code `0` as a successful operation and any other exit code as an error. Use this\nproperty to indicate human-readable semantic meanings for the DSC Resource's exit codes.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#exitcodes\n", "defaultSnippets": [ { - "label": "Defined exit codes", + "label": " Defined exit codes", "description": "Defines exit codes with semantic meaning for the resource.", "body": { "0": "Success", diff --git a/schemas/src/config/document.parameter.yaml b/schemas/src/config/document.parameter.yaml index d78be445..2162e055 100644 --- a/schemas/src/config/document.parameter.yaml +++ b/schemas/src/config/document.parameter.yaml @@ -82,7 +82,7 @@ properties: [01]: /reference/schemas/config/parameter?#metadata-1 defaultSnippets: - - label: New metadata property + - label: ' New metadata property' markdownDescription: |- Defines a key-value pair for the metadata: @@ -91,7 +91,8 @@ properties: ``` body: ${1:metadataName}: ${2:value} - - label: New metadata property (object) + + - label: ' New metadata property (object)' markdownDescription: |- Defines a new key-value pair for the metadata where the value is an object. @@ -102,7 +103,8 @@ properties: body: ${1:metadataName}: ${2:key}: ${3:value} - - label: New metadata property (array) + + - label: ' New metadata property (array)' markdownDescription: |- Defines a new key-value pair for the metadata where the value is an array. diff --git a/schemas/src/config/document.resource.yaml b/schemas/src/config/document.resource.yaml index 69353fb6..9f83e6a1 100644 --- a/schemas/src/config/document.resource.yaml +++ b/schemas/src/config/document.resource.yaml @@ -33,7 +33,7 @@ properties: The `` and `` should be the fully qualified type of the resource and its friendly name in the configuration. defaultSnippets: - - label: New dependency + - label: ' New dependency' markdownDescription: |- Defines a new dependency for the resource instance. @@ -96,7 +96,7 @@ markdownDescription: | [01]: /reference/schemas/config/resource? defaultSnippets: - - label: ' New resource instance' + - label: ' New resource instance' markdownDescription: |- Defines a new instance of a DSC Resource for the configuration. @@ -111,7 +111,8 @@ defaultSnippets: name: ${2:instance_name} properties: ${3:propertyName}: ${4:propertyValue} - - label: ' New dependent resource instance' + + - label: ' New dependent resource instance' markdownDescription: |- Defines a new instance of a DSC Resource for the configuration that depends on another instance. diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index 05eb85af..ca5e6b56 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -67,7 +67,7 @@ properties: [01]: /reference/schemas/config/document?#parameters defaultSnippets: - - label: ' New Parameter' + - label: ' New Parameter' markdownDescription: |- Defines a new runtime option for the configuration. @@ -86,7 +86,8 @@ properties: defaultValue: $4 allowedValues: - $5 - - label: ' New Integer Parameter' + + - label: ' New Integer Parameter' markdownDescription: |- Defines a new runtime option for the configuration as an integer value. @@ -192,7 +193,7 @@ properties: [01]: /reference/schemas/config/document?#metadata-1 defaultSnippets: - - label: New metadata property + - label: ' New metadata property' markdownDescription: |- Defines a key-value pair for the metadata: @@ -201,7 +202,8 @@ properties: ``` body: ${1:metadataName}: ${2:value} - - label: New metadata property (object) + + - label: ' New metadata property (object)' markdownDescription: |- Defines a new key-value pair for the metadata where the value is an object. @@ -212,7 +214,8 @@ properties: body: ${1:metadataName}: ${2:key}: ${3:value} - - label: New metadata property (array) + + - label: ' New metadata property (array)' markdownDescription: |- Defines a new key-value pair for the metadata where the value is an array. diff --git a/schemas/src/resource/manifest.export.yaml b/schemas/src/resource/manifest.export.yaml index 961ab233..97da2440 100644 --- a/schemas/src/resource/manifest.export.yaml +++ b/schemas/src/resource/manifest.export.yaml @@ -59,12 +59,13 @@ properties: [01]: /reference/schemas/resource/manifest/export?#args defaultSnippets: # VS Code only - - label: ' Define without arguments' + - label: ' Define without arguments' markdownDescription: | Define the export command for the resource when no arguments are required. body: executable: ${1:executable_name} - - label: ' Define with arguments' + + - label: ' Define with arguments' markdownDescription: | Define the export command for the resource when at least one argument is required. body: diff --git a/schemas/src/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml index b6f4bd67..b84c7682 100644 --- a/schemas/src/resource/manifest.get.yaml +++ b/schemas/src/resource/manifest.get.yaml @@ -79,13 +79,14 @@ examples: - executable: osinfo defaultSnippets: # VS Code only - - label: ' Define without arguments' + - label: ' Define without arguments' markdownDescription: | Define the get command for the resource when no arguments are required. body: input: ${1|stdin,env|} executable: ${2:executable_name} - - label: ' Define with arguments' + + - label: ' Define with arguments' markdownDescription: | Define the get command for the resource when at least one argument is required. body: diff --git a/schemas/src/resource/manifest.provider.yaml b/schemas/src/resource/manifest.provider.yaml index 70c8426f..f1c704f0 100644 --- a/schemas/src/resource/manifest.provider.yaml +++ b/schemas/src/resource/manifest.provider.yaml @@ -123,7 +123,7 @@ examples: - ./powershellgroup.resource.ps1 List defaultSnippets: # VS Code only - - label: ' Define without arguments' + - label: ' Define without arguments' markdownDescription: | Define the provider config kind and `list` command for the resource when no arguments are required. @@ -131,7 +131,8 @@ defaultSnippets: # VS Code only config: $1 list: executable: ${2:executable_name} - - label: ' Define with arguments' + + - label: ' Define with arguments' markdownDescription: | Define the provider config kind and `list` command for the resource when at least one argument is required. diff --git a/schemas/src/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml index 620d08ed..04075460 100644 --- a/schemas/src/resource/manifest.schema.yaml +++ b/schemas/src/resource/manifest.schema.yaml @@ -75,12 +75,13 @@ properties: [01]: /reference/schemas/resource/manifest/schema/property?#command defaultSnippets: - - label: ' Define without arguments' + - label: ' Define without arguments' markdownDescription: | Define the `schema` command for the resource when no arguments are required. body: executable: ${1:executable_name} - - label: ' Define with arguments' + + - label: ' Define with arguments' markdownDescription: | Define the `schema` command for the resource when at least one argument is required. body: @@ -223,14 +224,14 @@ properties: - $ref: http://json-schema.org/draft-07/schema# additionalProperties: defaultSnippets: # VS Code only - - label: ' Define a property' + - label: ' Define a property' markdownDescription: Define a new property for the resource instance schema. body: title: ${1:property title} description: ${2:explanation of property purpose and usage} type: ${3|boolean,string,integer,number,array,object,null|} - - label: ' Define a property (boolean)' + - label: ' Define a property (boolean)' markdownDescription: |- Define a new [boolean][01] property for the resource instance schema, requiring the value to be either `true` or `false`. @@ -241,7 +242,7 @@ properties: description: ${2:explanation of property purpose and usage} type: boolean - - label: ' Define a property (string)' + - label: ' Define a property (string)' markdownDescription: |- Define a new [string][01] property for the resource instance schema, requiring the value to be a blob of text. @@ -315,6 +316,7 @@ properties: enum: - ^${3:"first value"} - ^${4:"second value"} + - label: ' Define a property (const)' markdownDescription: |- Define a new [const][01] property for the resource instance schema that only @@ -322,8 +324,8 @@ properties: [01]: https://json-schema.org/understanding-json-schema/reference/generic.html#constant-values body: - title: ${1:property title} - description: ${2:explanation of property purpose and usage} + title: ${1:property title} + description: ${2:explanation of property purpose and usage} const: ^${3:"constant value"} properties: @@ -409,7 +411,7 @@ properties: markdownDescription: Define a property for the resource instance schema. body: ${1:propertyName}: - title: ${2:property title} + title: ${2:property title} description: ${3:explanation of property purpose and usage} type: ${4|string,integer,number,array,object,null|} url: @@ -497,6 +499,7 @@ defaultSnippets: # VS Code only body: command: executable: ${1:executable_name} + - label: ' Define as command with arguments' markdownDescription: | *** @@ -511,6 +514,7 @@ defaultSnippets: # VS Code only executable: ${1:executable_name} args: - ${2:--first-argument} + - label: ' Define as an embedded schema' markdownDescription: | *** @@ -527,6 +531,6 @@ defaultSnippets: # VS Code only type: object properties: ${2:name}: - title: ${3:property title} + title: ${3:property title} description: ${4:explanation of property purpose and usage} type: ${5|string,integer,number,array,object,null|} diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 0cf749b0..62693afe 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -72,7 +72,6 @@ properties: invoking the `set` operation. [01]: /reference/schemas/resource/manifest/set?#input - implementsPretest: title: Resource Performs Pre-Test description: >- @@ -129,7 +128,7 @@ examples: return: state defaultSnippets: # VS Code only - - label: ' Define without arguments' + - label: ' Define without arguments' markdownDescription: | Define the `set` command for the resource when no arguments are required. body: @@ -137,7 +136,8 @@ defaultSnippets: # VS Code only implementsPretest: ^${2|true,false|} return: ${3|state,stateAndDiff|} executable: ${4:executable_name} - - label: ' Define with arguments' + + - label: ' Define with arguments' markdownDescription: | Define the `set` command for the resource when at least one argument is required. body: diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index cce072d3..0e8e95fc 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -109,14 +109,15 @@ examples: return: state defaultSnippets: # VS Code only - - label: ' Define without arguments' + - label: ' Define without arguments' markdownDescription: | Define the `test` command for the resource when no arguments are required. body: input: ${1|input,env|} return: ${2|state,stateAndDiff|} executable: ${3:executable_name} - - label: ' Define with arguments' + + - label: ' Define with arguments' markdownDescription: | Define the `test` command for the resource when at least one argument is required. body: diff --git a/schemas/src/resource/manifest.validate.yaml b/schemas/src/resource/manifest.validate.yaml index f051a6e3..f40bdacc 100644 --- a/schemas/src/resource/manifest.validate.yaml +++ b/schemas/src/resource/manifest.validate.yaml @@ -68,12 +68,13 @@ examples: - validate defaultSnippets: # VS Code only - - label: ' Define without arguments' + - label: ' Define without arguments' markdownDescription: | Define the `validate` command for the resource when no arguments are required. body: executable: ${1:executable_name} - - label: ' Define with arguments' + + - label: ' Define with arguments' markdownDescription: | Define the `validate` command for the resource when at least one argument is required. body: diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index 8c2c13f7..940b01f9 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -21,7 +21,7 @@ markdownDescription: | # VS Code only [01]: /reference/schemas/resource/manifest/root? defaultSnippets: - - label: ' Define a resource' + - label: ' Define a resource' markdownDescription: |- Defines a standard resource that: @@ -33,11 +33,11 @@ defaultSnippets: $schema: ///bundled/resource/manifest.yaml type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' version: '${3:0.1.0}' - description: ${4:Synopsis for the resource's purpose} + description: ${4:Synopsis for the resource's purpose} get: - executable: ${5:executable name} + executable: ${5:executable name} args: ['${6:argument}'] - input: ${7:stdin} + input: ${7:stdin} set: executable: ${8:executable name} args: ['${9:argument}'] @@ -50,10 +50,11 @@ defaultSnippets: type: object properties: ${14:name}: - title: ${15:property title} + title: ${15:property title} description: ${16:explanation of property purpose and usage} type: ${17|string,integer,number,array,object,null|} - - label: ' Define a resource (group)' + + - label: ' Define a resource (group)' markdownDescription: |- Defines a group resource that expects a list of resource instances and operates on them. body: @@ -62,14 +63,14 @@ defaultSnippets: version: '${3:0.1.0}' description: ${4:Synopsis for the resource's purpose} get: - executable: ${5:executable name} + executable: ${5:executable name} args: ['${6:argument}'] - input: ${7:stdin} + input: ${7:stdin} test: - executable: ${8:executable name} + executable: ${8:executable name} args: ['${9:argument}'] - input: ${10:stdin} - return: ${12:state} + input: ${10:stdin} + return: ${12:state} set: executable: ${13:executable name} args: ['${14:argument}'] @@ -88,10 +89,11 @@ defaultSnippets: items: ${escape_dollar:$}ref: ///config/document.resource.json ${21:name}: - title: ${22:property title} + title: ${22:property title} description: ${23:explanation of property purpose and usage} type: ${24|string,integer,number,array,object,null|} - - label: ' Define a resource (provider)' + + - label: ' Define a resource (provider)' markdownDescription: |- Defines a provider resource that enables users to define non-command-based DSC Resources in the configuration. @@ -101,14 +103,14 @@ defaultSnippets: version: '${3:0.1.0}' description: ${4:Synopsis for the resource's purpose} get: - executable: ${5:executable name} + executable: ${5:executable name} args: ['${6:argument}'] - input: ${7:stdin} + input: ${7:stdin} test: - executable: ${8:executable name} + executable: ${8:executable name} args: ['${9:argument}'] - input: ${10:stdin} - return: ${12:state} + input: ${10:stdin} + return: ${12:state} set: executable: ${13:executable name} args: ['${14:argument}'] @@ -118,7 +120,7 @@ defaultSnippets: provider: config: ${18|full,sequence|} list: - executable: ${19:executable name} + executable: ${19:executable name} args: ['${20:argument}'] schema: embedded: @@ -132,10 +134,11 @@ defaultSnippets: items: ${escape_dollar:$}ref: ///config/document.resource.json ${26:name}: - title: ${27:property title} + title: ${27:property title} description: ${28:explanation of property purpose and usage} type: ${29|string,integer,number,array,object,null|} - - label: ' Define a resource (assertion-only)' + + - label: ' Define a resource (assertion-only)' markdownDescription: |- Defines an assertion resource that can get the current state of an instance but not configure it. By default, the resource relies on DSC's synthetic testing feature. If the resource @@ -146,16 +149,16 @@ defaultSnippets: version: '${3:0.1.0}' description: ${4:Synopsis for the resource's purpose} get: - executable: ${5:executable name} + executable: ${5:executable name} args: ['${6:argument}'] - input: ${7:stdin} + input: ${7:stdin} schema: embedded: ${escape_dollar:$}schema: ${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|} type: object properties: ${14:name}: - title: ${15:property title} + title: ${15:property title} description: ${16:explanation of property purpose and usage} type: ${17|string,integer,number,array,object,null|} @@ -307,11 +310,11 @@ properties: [01]: /reference/schemas/resource/manifest/root?#exitcodes defaultSnippets: - - label: Defined exit codes + - label: ' Defined exit codes' description: Defines exit codes with semantic meaning for the resource. body: '0': Success - ${1:first exit code number}: ${2:first exit code meaning} + ${1:first exit code number}: ${2:first exit code meaning} ${3:second exit code number}: ${4:second exit code meaning} schema: $ref: ///resource/manifest.schema.yaml From bdcd296e31164a5bd9687373e15535f15f377ed3 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 29 Sep 2023 08:47:26 -0500 Subject: [PATCH 15/16] (MAINT) Clarify `env` input handling Prior to this change, the enum documentation for the enhanced schema didn't clarify how the environment variables are named or their values passed. This change clarifies both, making it easier for manifest authors to determine whether the input option is right for them and how they should expect to handle the input in their resource without consulting the online documentation. --- schemas/2023/08/bundled/resource/manifest.vscode.json | 2 +- schemas/src/definitions/inputKind.yaml | 10 ++++++++-- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json index 43c72024..b803bcf0 100644 --- a/schemas/2023/08/bundled/resource/manifest.vscode.json +++ b/schemas/2023/08/bundled/resource/manifest.vscode.json @@ -360,7 +360,7 @@ "stdin" ], "markdownEnumDescriptions": [ - "_Environment variables_\n\n> Indicates that the resource expects the properties of an instance to be specified as\n> environment variables. This option only supports the following data types for instance\n> properties:\n>\n> - `boolean`\n> - `integer`\n> - `number`\n> - `string`\n> - `array` of `integer` values\n> - `array` of `number` values\n> - `array` of `string` values\n>\n> If the resource needs to support complex properties with an `object` value or multi-type\n> arrays, set this to `stdin` instead.\n", + "_Environment variables_\n\n> Indicates that the resource expects the properties of an instance to be specified as\n> environment variables with the same names and casing.\n>\n> This option only supports the following data types for instance properties:\n>\n> - `boolean`\n> - `integer`\n> - `number`\n> - `string`\n> - `array` of `integer` values\n> - `array` of `number` values\n> - `array` of `string` values\n>\n> For non-array values, DSC sets the environment variable to the specified value as-is. When\n> the data type is an array of values, DSC sets the environment variable as a comma-delimited\n> string. For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo`\n> environment variable as `\"1,2,3\"`.\n>\n> If the resource needs to support complex properties with an `object` value or multi-type\n> arrays, set this to `stdin` instead.\n", "_JSON over `stdin`_\n\n> Indicates that the resource expects a JSON blob representing an instance from `stdin`.\n> The JSON must adhere to the instance schema.\n" ] }, diff --git a/schemas/src/definitions/inputKind.yaml b/schemas/src/definitions/inputKind.yaml index a1b3a1a4..c3c4bb4f 100644 --- a/schemas/src/definitions/inputKind.yaml +++ b/schemas/src/definitions/inputKind.yaml @@ -18,8 +18,9 @@ markdownEnumDescriptions: _Environment variables_ > Indicates that the resource expects the properties of an instance to be specified as - > environment variables. This option only supports the following data types for instance - > properties: + > environment variables with the same names and casing. + > + > This option only supports the following data types for instance properties: > > - `boolean` > - `integer` @@ -29,6 +30,11 @@ markdownEnumDescriptions: > - `array` of `number` values > - `array` of `string` values > + > For non-array values, DSC sets the environment variable to the specified value as-is. When + > the data type is an array of values, DSC sets the environment variable as a comma-delimited + > string. For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo` + > environment variable as `"1,2,3"`. + > > If the resource needs to support complex properties with an `object` value or multi-type > arrays, set this to `stdin` instead. - | # stdin From 45958c367b00551de816b930b9d28a962c74650b Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 29 Sep 2023 08:55:40 -0500 Subject: [PATCH 16/16] (MAINT) Fix schema docs for `input` in set/test Prior to this change, the schema docs erroneously noted that when `input` is not defined in a resource manifest for the `set` and `test` definitions that DSC doesn't send any input. This is _technically_ true, but the `input` property is included in the list of `required` properties for `set` and `test`, unlike `get`. This change removes the misleading sentence, since those properties can't be undefined in a valid manifest. --- schemas/2023/08/bundled/resource/manifest.vscode.json | 4 ++-- schemas/src/resource/manifest.set.yaml | 3 +-- schemas/src/resource/manifest.test.yaml | 3 +-- 3 files changed, 4 insertions(+), 6 deletions(-) diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json index b803bcf0..9fc6ff97 100644 --- a/schemas/2023/08/bundled/resource/manifest.vscode.json +++ b/schemas/2023/08/bundled/resource/manifest.vscode.json @@ -499,7 +499,7 @@ }, "input": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. If this value isn't defined, DSC doesn't send the resource any input when\ninvoking the `set` operation.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" }, "implementsPretest": { "title": "Resource Performs Pre-Test", @@ -578,7 +578,7 @@ }, "input": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. If this value isn't defined, DSC doesn't send the resource any input when\ninvoking the `test` operation.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" }, "return": { "title": "Test Command Return Type", diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 62693afe..1f3b2415 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -68,8 +68,7 @@ properties: *** Defines how DSC should pass input to the command, either as environment variables or JSON - over `stdin`. If this value isn't defined, DSC doesn't send the resource any input when - invoking the `set` operation. + over `stdin`. [01]: /reference/schemas/resource/manifest/set?#input implementsPretest: diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index 0e8e95fc..99e68138 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -69,8 +69,7 @@ properties: *** Defines how DSC should pass input to the command, either as environment variables or JSON - over `stdin`. If this value isn't defined, DSC doesn't send the resource any input when - invoking the `test` operation. + over `stdin`. [01]: /reference/schemas/resource/manifest/set?#input return: