From de33b4e94911f36549bc132e3bd51da413f27a7a Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 10 Apr 2024 10:26:50 -0500 Subject: [PATCH 01/15] (SCHEMA) Update schemas for the provider->adapter rename This change updates the source schemas to account for renaming DSC Resource Providers to DSC Resource Adapters in #334. This is a breaking schema change that requires a new canonical URI, so the change also adds new schema URIs to DSC to account for the changes. The regenerated schemas will be added in the next commit. --- dsc_lib/src/configure/config_doc.rs | 10 ++- dsc_lib/src/dscresources/resource_manifest.rs | 6 ++ schemas/build.ps1 | 6 ++ schemas/schemas.config.yaml | 2 +- schemas/src/config/document.yaml | 66 ++++++++++++++-- schemas/src/outputs/resource/list.yaml | 4 +- ...st.provider.yaml => manifest.adapter.yaml} | 34 ++++---- schemas/src/resource/manifest.yaml | 77 ++++++++++++++++--- 8 files changed, 165 insertions(+), 40 deletions(-) rename schemas/src/resource/{manifest.provider.yaml => manifest.adapter.yaml} (72%) diff --git a/dsc_lib/src/configure/config_doc.rs b/dsc_lib/src/configure/config_doc.rs index d48f35621..693b86eea 100644 --- a/dsc_lib/src/configure/config_doc.rs +++ b/dsc_lib/src/configure/config_doc.rs @@ -142,6 +142,12 @@ pub struct Resource { #[derive(Debug, Default, Clone, Copy, Hash, Eq, PartialEq, Deserialize, Serialize, JsonSchema)] pub enum DocumentSchemaUri { #[default] + #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json")] + Version2024_04, + #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json")] + Bundled2024_04, + #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json")] + VSCode2024_04, #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json")] Version2023_10, #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.json")] @@ -159,7 +165,7 @@ pub enum DocumentSchemaUri { impl Default for Configuration { fn default() -> Self { Self { - schema: DocumentSchemaUri::Version2023_08, + schema: DocumentSchemaUri::Version2024_04, parameters: None, variables: None, resources: Vec::new(), @@ -172,7 +178,7 @@ impl Configuration { #[must_use] pub fn new() -> Self { Self { - schema: DocumentSchemaUri::Version2023_08, + schema: DocumentSchemaUri::Version2024_04, parameters: None, variables: None, resources: Vec::new(), diff --git a/dsc_lib/src/dscresources/resource_manifest.rs b/dsc_lib/src/dscresources/resource_manifest.rs index b23637741..974a37000 100644 --- a/dsc_lib/src/dscresources/resource_manifest.rs +++ b/dsc_lib/src/dscresources/resource_manifest.rs @@ -66,6 +66,12 @@ pub struct ResourceManifest { #[derive(Debug, Default, Clone, Copy, Hash, Eq, PartialEq, Deserialize, Serialize, JsonSchema)] pub enum ManifestSchemaUri { #[default] + #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json")] + Version2024_04, + #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json")] + Bundled2024_04, + #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json")] + VSCode2024_04, #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json")] Version2023_10, #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json")] diff --git a/schemas/build.ps1 b/schemas/build.ps1 index 75e3d06a3..fd996ef66 100644 --- a/schemas/build.ps1 +++ b/schemas/build.ps1 @@ -3,6 +3,12 @@ using namespace System.Collections <# .SYNOPSIS + Build the DSC schema files from the source YAML files. + + .DESCRIPTION + This build script composes the JSON Schema files from the source YAML files, creating new + files in the specified output directory. It creates a schema registry to analyze the source + schemas and resolve references for bundling. #> [cmdletbinding(DefaultParameterSetName='ByConfig')] diff --git a/schemas/schemas.config.yaml b/schemas/schemas.config.yaml index 7715bf0e3..3f4ced149 100644 --- a/schemas/schemas.config.yaml +++ b/schemas/schemas.config.yaml @@ -1,6 +1,6 @@ host: https://raw.githubusercontent.com prefix: PowerShell/DSC/main/schemas -version: 2023/10 +version: 2024/04 docs_base_url: https://learn.microsoft.com/powershell/dsc docs_version_pin: view=dsc-3.0&preserve-view=true bundle_schemas: diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index a6d41b1df..c311bd188 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -34,6 +34,9 @@ properties: - ///config/document.yaml - ///bundled/config/document.yaml - ///bundled/config/document.vscode.yaml + - //2023/10/config/document.yaml + - //2023/10/bundled/config/document.yaml + - //2023/10/bundled/config/document.vscode.yaml - //2023/08/config/document.yaml - //2023/08/bundled/config/document.yaml - //2023/08/bundled/config/document.vscode.yaml @@ -113,6 +116,51 @@ properties: > This schema uses keywords that are only recognized by VS Code. While DSC can still > validate the document when it uses this schema, other tools may error or behave in > unexpected ways. + - | # //2023/10/config/document.yaml + + + > #### `2023/10` non-bundled + > + > Indicates that the configuration document adheres to the `2023/10` schema. This version + > is deprecated, and should only be used for compatibility with `alpha.5` and earlier. + > Migrate to using the `` of the schema + > + > This URL points to the canonical non-bundled schema. When it's used for validation, the + > validating client needs to retrieve this schema and every schema it references. + + - | # //2023/10/bundled/config/document.yaml + + + > #### `2023/10` bundled + > + > Indicates that the configuration document adheres to the `2023/10` schema. This version + > is deprecated, and should only be used for compatibility with `alpha.5` and earlier. + > Migrate to using the `` of the schema + > + > This URL points to the bundled schema. When it's used for validation, the validating + > client only needs to retrieve this schema. + > + > This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can + > still validate the document when it uses this schema, other tools may error or behave + > in unexpected ways. + - | # //2023/10/bundled/config/document.vscode.yaml + + + > #### `2023/10` enhanced authoring + > + > Indicates that the configuration document adheres to the `2023/10` schema. This version + > is deprecated, and should only be used for compatibility with `alpha.5` and earlier. + > Migrate to using the `` of the schema + > + > This URL points to the enhanced authoring schema. This schema is much larger than the + > other schemas, as it includes additional definitions that provide contextual help and + > snippets that the others don't include. + > + > This schema uses keywords that are only recognized by VS Code. While DSC can still + > validate the document when it uses this schema, other tools may error or behave in + > unexpected ways. + +# Old Schema - | # //2023/08/config/document.yaml @@ -130,9 +178,12 @@ properties: > #### `2023/08` bundled > - > Indicates that the configuration document adheres to the `2023/08` schema. This URL - > points to the bundled schema. When it's used for validation, the validating client - > only needs to retrieve this schema. + > Indicates that the configuration document adheres to the `2023/08` schema. This version + > is deprecated, and should only be used for compatibility with `alpha.3` and earlier. + > Migrate to using the `` of the schema + > + > This URL points to the bundled schema. When it's used for validation, the validating + > client only needs to retrieve this schema. > > This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can > still validate the document when it uses this schema, other tools may error or behave @@ -142,9 +193,12 @@ properties: > #### `2023/08` enhanced authoring > - > Indicates that the configuration document adheres to the `2023/08` schema. This URL - > points to the enhanced authoring schema. This schema is much larger than the other - > schemas, as it includes additional definitions that provide contextual help and + > Indicates that the configuration document adheres to the `2023/08` schema. This version + > is deprecated, and should only be used for compatibility with `alpha.3` and earlier. + > Migrate to using the `` of the schema + > + > This URL points to the enhanced authoring schema. This schema is much larger than the + > other schemas, as it includes additional definitions that provide contextual help and > snippets that the others don't include. > > This schema uses keywords that are only recognized by VS Code. While DSC can still diff --git a/schemas/src/outputs/resource/list.yaml b/schemas/src/outputs/resource/list.yaml index f6a09bc9d..79ad6c073 100644 --- a/schemas/src/outputs/resource/list.yaml +++ b/schemas/src/outputs/resource/list.yaml @@ -82,9 +82,9 @@ properties: type: string pattern: ^\w+$ requires: - title: Required DSC Resource Provider + title: Required DSC Resource Adapter description: >- - Defines the fully qualified type name of the DSC Resource Provider the + Defines the fully qualified type name of the DSC Resource Adapter the DSC Resource depends on. oneOf: - $ref: ///definitions/resourceType.yaml diff --git a/schemas/src/resource/manifest.provider.yaml b/schemas/src/resource/manifest.adapter.yaml similarity index 72% rename from schemas/src/resource/manifest.provider.yaml rename to schemas/src/resource/manifest.adapter.yaml index f1c704f09..39cf0f938 100644 --- a/schemas/src/resource/manifest.provider.yaml +++ b/schemas/src/resource/manifest.adapter.yaml @@ -1,20 +1,20 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: ///resource/manifest.provider.yaml +$id: ///resource/manifest.adapter.yaml -title: Provider +title: Adapter description: >- - Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to + Defines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter enables users to manage resources that don't have their own manifests with DSC. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to + Defines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter enables users to manage resources that don't have their own manifests with DSC. - [01]: /reference/schemas/resource/manifest/provider? + [01]: /reference/schemas/resource/manifest/adapter? type: object required: @@ -24,15 +24,15 @@ properties: list: title: List Command description: >- - Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources. + Defines how DSC must call the DSC Resource Adapter to list its supported DSC Resources. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources. + Defines how DSC must call the DSC Resource Adapter to list its supported DSC Resources. - [01]: /reference/schemas/resource/manifest/provider?#list + [01]: /reference/schemas/resource/manifest/adapter?#list type: object required: - executable @@ -49,7 +49,7 @@ properties: is only required when the command isn't recognizable by the operating system as an executable. - [01]: /reference/schemas/resource/manifest/provider?#executable + [01]: /reference/schemas/resource/manifest/adapter?#executable args: $ref: ///definitions/commandArgs.yaml markdownDescription: | @@ -75,11 +75,11 @@ properties: registry resources list ``` - [01]: /reference/schemas/resource/manifest/provider?#args + [01]: /reference/schemas/resource/manifest/adapter?#args config: title: Expected Configuration description: >- - Defines whether the provider expects to receive a full and unprocessed configuration as a + Defines whether the adapter expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations. type: string @@ -92,21 +92,21 @@ properties: [_Online Documentation_][01] *** - Defines whether the provider expects to receive a full and unprocessed configuration as a + Defines whether the adapter 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]: /reference/schemas/resource/manifest/provider?#config + [01]: /reference/schemas/resource/manifest/adapter?#config markdownEnumDescriptions: - | # full _Full and unprocessed config as a JSON blob_ - > Indicates that the provider expects a JSON blob containing the full and unprocessed + > Indicates that the adapter 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] + > Indicates that the adapter expects each resource's configuration as a [JSON Line][01] > over `stdin`. [01]: https://jsonlines.org/ @@ -125,7 +125,7 @@ examples: defaultSnippets: # VS Code only - label: ' Define without arguments' markdownDescription: | - Define the provider config kind and `list` command for the resource when no arguments are + Define the adapter config kind and `list` command for the resource when no arguments are required. body: config: $1 @@ -134,7 +134,7 @@ defaultSnippets: # VS Code only - label: ' Define with arguments' markdownDescription: | - Define the provider config kind and `list` command for the resource when at least one + Define the adapter config kind and `list` command for the resource when at least one argument is required. body: config: $1 diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index 5aaedf327..6f63b6462 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -93,9 +93,9 @@ defaultSnippets: 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 (adapter)' markdownDescription: |- - Defines a provider resource that enables users to define non-command-based DSC Resources in + Defines an adapter resource that enables users to define non-command-based DSC Resources in the configuration. body: $schema: ///bundled/resource/manifest.yaml @@ -117,7 +117,7 @@ defaultSnippets: input: ${15:stdin} implementsPretest: ^${16:false} return: ${17:state} - provider: + adapter: config: ${18|full,sequence|} list: executable: ${19:executable name} @@ -180,6 +180,9 @@ properties: - ///resource/manifest.yaml - ///bundled/resource/manifest.yaml - ///bundled/resource/manifest.vscode.yaml + - //2023/10/resource/manifest.yaml + - //2023/10/bundled/resource/manifest.yaml + - //2023/10/bundled/resource/manifest.vscode.yaml - //2023/08/resource/manifest.yaml - //2023/08/bundled/resource/manifest.yaml - //2023/08/bundled/resource/manifest.vscode.yaml @@ -259,6 +262,50 @@ properties: > This schema uses keywords that are only recognized by VS Code. While DSC can still > validate the document when it uses this schema, other tools may error or behave in > unexpected ways. + + - | # //2023/10/resource/manifest.yaml + + + > #### `2023/10` non-bundled + > + > Indicates that the resource manifest adheres to the `2023/10` schema. This version + > is deprecated, and should only be used for compatibility with `alpha.5` and earlier. + > Migrate to using the `` of the schema + > + > This URL points to the canonical non-bundled schema. When it's used for validation, the + > validating client needs to retrieve this schema and every schema it references. + + - | # //2023/10/bundled/resource/manifest.yaml + + + > #### `2023/10` bundled + > + >Indicates that the resource manifest adheres to the `2023/10` schema. This version + > is deprecated, and should only be used for compatibility with `alpha.5` and earlier. + > Migrate to using the `` of the schema. + > + > This URL points to the bundled schema. When it's used for validation, the validating + > client only needs to retrieve this schema. + > + > This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can + > still validate the document when it uses this schema, other tools may error or behave + > in unexpected ways. + - | # //2023/10/bundled/resource/manifest.vscode.yaml + + + > #### `2023/10` enhanced authoring + > + >Indicates that the resource manifest adheres to the `2023/10` schema. This version + > is deprecated, and should only be used for compatibility with `alpha.5` and earlier. + > Migrate to using the `` of the schema. + > + > This URL points to the enhanced authoring schema. This schema is much larger than the + > other schemas, as it includes additional definitions that provide contextual help and + > snippets that the others don't include. + > + > This schema uses keywords that are only recognized by VS Code. While DSC can still + > validate the document when it uses this schema, other tools may error or behave in + > unexpected ways. - | # //2023/08/resource/manifest.yaml @@ -267,7 +314,7 @@ properties: > Indicates that the resource manifest adheres to the `2023/08` schema. This version > is deprecated, and should only be used for compatibility with `alpha.3` and earlier. > Migrate to using the `` of the schema - + > > This URL points to the canonical non-bundled schema. When it's used for validation, the > validating client needs to retrieve this schema and every schema it references. @@ -276,9 +323,12 @@ properties: > #### `2023/08` bundled > - > Indicates that the resource manifest adheres to the `2023/08` schema. This URL - > points to the bundled schema. When it's used for validation, the validating client - > only needs to retrieve this schema. + > Indicates that the resource manifest adheres to the `2023/08` schema. This version + > is deprecated, and should only be used for compatibility with `alpha.3` and earlier. + > Migrate to using the `` of the schema + > + > This URL points to the bundled schema. When it's used for validation, the validating + > client only needs to retrieve this schema. > > This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can > still validate the document when it uses this schema, other tools may error or behave @@ -288,9 +338,12 @@ properties: > #### `2023/08` enhanced authoring > - > Indicates that the resource manifest adheres to the `2023/08` schema. This URL - > points to the enhanced authoring schema. This schema is much larger than the other - > schemas, as it includes additional definitions that provide contextual help and + > Indicates that the resource manifest adheres to the `2023/08` schema. This version + > is deprecated, and should only be used for compatibility with `alpha.3` and earlier. + > Migrate to using the `` of the schema + > + > This URL points to the enhanced authoring schema. This schema is much larger than the + > other schemas, as it includes additional definitions that provide contextual help and > snippets that the others don't include. > > This schema uses keywords that are only recognized by VS Code. While DSC can still @@ -373,8 +426,8 @@ properties: $ref: ///resource/manifest.test.yaml validate: $ref: ///resource/manifest.validate.yaml - provider: - $ref: ///resource/manifest.provider.yaml + adapter: + $ref: ///resource/manifest.adapter.yaml exitCodes: # This setting in the root of the schema implies exit codes must have the # same meaning across all executions. What about implementations that From 9ebc715ec847a22533f269d55f9ff5545da7acf0 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 10 Apr 2024 10:28:43 -0500 Subject: [PATCH 02/15] (SCHEMA) Generate 2024/04 schemas This commit generates the canonical schemas from source using the new canonical URI for `2024/04`, as the changes include a break from the prior `2023/08` schemas. It also updates the VS Code settings to use the newest schemas for IntelliSense and validation. --- .vscode/settings.json | 6 +- schemas/2024/04/bundled/config/document.json | 366 +++++ .../04/bundled/config/document.vscode.json | 575 ++++++++ .../2024/04/bundled/outputs/config/get.json | 160 +++ .../2024/04/bundled/outputs/config/set.json | 176 +++ .../2024/04/bundled/outputs/config/test.json | 182 +++ .../2024/04/bundled/outputs/resource/get.json | 93 ++ .../04/bundled/outputs/resource/list.json | 708 ++++++++++ .../04/bundled/outputs/resource/schema.json | 8 + .../2024/04/bundled/outputs/resource/set.json | 109 ++ .../04/bundled/outputs/resource/test.json | 115 ++ schemas/2024/04/bundled/outputs/schema.json | 8 + .../2024/04/bundled/resource/manifest.json | 617 +++++++++ .../04/bundled/resource/manifest.vscode.json | 1173 +++++++++++++++++ schemas/2024/04/config/document.json | 57 + .../2024/04/config/document.parameter.json | 228 ++++ schemas/2024/04/config/document.resource.json | 34 + schemas/2024/04/definitions/commandArgs.json | 10 + .../04/definitions/commandExecutable.json | 7 + schemas/2024/04/definitions/hadErrors.json | 7 + schemas/2024/04/definitions/inputKind.json | 11 + schemas/2024/04/definitions/instanceName.json | 9 + schemas/2024/04/definitions/message.json | 39 + schemas/2024/04/definitions/messages.json | 10 + .../04/definitions/parameters/dataTypes.json | 16 + .../parameters/validValueTypes.json | 12 + schemas/2024/04/definitions/resourceType.json | 8 + schemas/2024/04/definitions/returnKind.json | 12 + schemas/2024/04/definitions/semver.json | 9 + schemas/2024/04/outputs/config/get.json | 28 + schemas/2024/04/outputs/config/set.json | 28 + schemas/2024/04/outputs/config/test.json | 28 + .../2024/04/outputs/resource/get.full.json | 23 + schemas/2024/04/outputs/resource/get.json | 17 + .../2024/04/outputs/resource/get.simple.json | 17 + schemas/2024/04/outputs/resource/list.json | 91 ++ schemas/2024/04/outputs/resource/schema.json | 7 + .../2024/04/outputs/resource/set.full.json | 23 + schemas/2024/04/outputs/resource/set.json | 17 + .../2024/04/outputs/resource/set.simple.json | 33 + .../2024/04/outputs/resource/test.full.json | 23 + schemas/2024/04/outputs/resource/test.json | 17 + .../2024/04/outputs/resource/test.simple.json | 39 + schemas/2024/04/outputs/schema.json | 7 + .../2024/04/resource/manifest.adapter.json | 53 + schemas/2024/04/resource/manifest.export.json | 18 + schemas/2024/04/resource/manifest.get.json | 34 + schemas/2024/04/resource/manifest.json | 103 ++ schemas/2024/04/resource/manifest.schema.json | 196 +++ schemas/2024/04/resource/manifest.set.json | 44 + schemas/2024/04/resource/manifest.test.json | 38 + .../2024/04/resource/manifest.validate.json | 27 + .../2024/04/resource/properties/exist.json | 12 + .../resource/properties/inDesiredState.json | 11 + .../2024/04/resource/properties/purge.json | 11 + .../resource/properties/rebootRequested.json | 11 + 56 files changed, 5718 insertions(+), 3 deletions(-) create mode 100644 schemas/2024/04/bundled/config/document.json create mode 100644 schemas/2024/04/bundled/config/document.vscode.json create mode 100644 schemas/2024/04/bundled/outputs/config/get.json create mode 100644 schemas/2024/04/bundled/outputs/config/set.json create mode 100644 schemas/2024/04/bundled/outputs/config/test.json create mode 100644 schemas/2024/04/bundled/outputs/resource/get.json create mode 100644 schemas/2024/04/bundled/outputs/resource/list.json create mode 100644 schemas/2024/04/bundled/outputs/resource/schema.json create mode 100644 schemas/2024/04/bundled/outputs/resource/set.json create mode 100644 schemas/2024/04/bundled/outputs/resource/test.json create mode 100644 schemas/2024/04/bundled/outputs/schema.json create mode 100644 schemas/2024/04/bundled/resource/manifest.json create mode 100644 schemas/2024/04/bundled/resource/manifest.vscode.json create mode 100644 schemas/2024/04/config/document.json create mode 100644 schemas/2024/04/config/document.parameter.json create mode 100644 schemas/2024/04/config/document.resource.json create mode 100644 schemas/2024/04/definitions/commandArgs.json create mode 100644 schemas/2024/04/definitions/commandExecutable.json create mode 100644 schemas/2024/04/definitions/hadErrors.json create mode 100644 schemas/2024/04/definitions/inputKind.json create mode 100644 schemas/2024/04/definitions/instanceName.json create mode 100644 schemas/2024/04/definitions/message.json create mode 100644 schemas/2024/04/definitions/messages.json create mode 100644 schemas/2024/04/definitions/parameters/dataTypes.json create mode 100644 schemas/2024/04/definitions/parameters/validValueTypes.json create mode 100644 schemas/2024/04/definitions/resourceType.json create mode 100644 schemas/2024/04/definitions/returnKind.json create mode 100644 schemas/2024/04/definitions/semver.json create mode 100644 schemas/2024/04/outputs/config/get.json create mode 100644 schemas/2024/04/outputs/config/set.json create mode 100644 schemas/2024/04/outputs/config/test.json create mode 100644 schemas/2024/04/outputs/resource/get.full.json create mode 100644 schemas/2024/04/outputs/resource/get.json create mode 100644 schemas/2024/04/outputs/resource/get.simple.json create mode 100644 schemas/2024/04/outputs/resource/list.json create mode 100644 schemas/2024/04/outputs/resource/schema.json create mode 100644 schemas/2024/04/outputs/resource/set.full.json create mode 100644 schemas/2024/04/outputs/resource/set.json create mode 100644 schemas/2024/04/outputs/resource/set.simple.json create mode 100644 schemas/2024/04/outputs/resource/test.full.json create mode 100644 schemas/2024/04/outputs/resource/test.json create mode 100644 schemas/2024/04/outputs/resource/test.simple.json create mode 100644 schemas/2024/04/outputs/schema.json create mode 100644 schemas/2024/04/resource/manifest.adapter.json create mode 100644 schemas/2024/04/resource/manifest.export.json create mode 100644 schemas/2024/04/resource/manifest.get.json create mode 100644 schemas/2024/04/resource/manifest.json create mode 100644 schemas/2024/04/resource/manifest.schema.json create mode 100644 schemas/2024/04/resource/manifest.set.json create mode 100644 schemas/2024/04/resource/manifest.test.json create mode 100644 schemas/2024/04/resource/manifest.validate.json create mode 100644 schemas/2024/04/resource/properties/exist.json create mode 100644 schemas/2024/04/resource/properties/inDesiredState.json create mode 100644 schemas/2024/04/resource/properties/purge.json create mode 100644 schemas/2024/04/resource/properties/rebootRequested.json diff --git a/.vscode/settings.json b/.vscode/settings.json index 237c7a221..09a06fd62 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -13,12 +13,12 @@ "json.schemas": [ { "fileMatch": ["**/*.dsc.resource.json"], - "url": "/schemas/2023/10/bundled/resource/manifest.vscode.json" + "url": "/schemas/2024/04/bundled/resource/manifest.vscode.json" } ], "yaml.schemas": { - "schemas/2023/10/bundled/config/document.vscode.json": "**.dsc.{yaml,yml,config.yaml,config.yml}", - "schemas/2023/10/bundled/resource/manifest.vscode.json": "**.dsc.resource.{yaml,yml}" + "schemas/2024/04/bundled/config/document.vscode.json": "**.dsc.{yaml,yml,config.yaml,config.yml}", + "schemas/2024/04/bundled/resource/manifest.vscode.json": "**.dsc.resource.{yaml,yml}" }, "sarif-viewer.connectToGithubCodeScanning": "off" } \ No newline at end of file diff --git a/schemas/2024/04/bundled/config/document.json b/schemas/2024/04/bundled/config/document.json new file mode 100644 index 000000000..befd46db2 --- /dev/null +++ b/schemas/2024/04/bundled/config/document.json @@ -0,0 +1,366 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "properties": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "properties": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "string" + }, + "allowedValues": { + "items": { + "type": "string" + } + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "object" + } + } + }, + { + "properties": { + "type": { + "const": "secureobject" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "object" + }, + "allowedValues": { + "items": { + "type": "object" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "integer" + }, + "allowedValues": { + "items": { + "type": "integer" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "array" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "array" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "bool" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "boolean" + }, + "allowedValues": { + "items": { + "type": "boolean" + } + } + } + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json", + "title": "DSC Resource instance", + "description": "Defines an instance of a DSC Resource in a configuration.", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the `resourceID()` lookup for another instance in the configuration. Multiple instances can depend on the same instance, but every dependency for an instance must be unique in that instance's `dependsOn` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[resourceId\\(\\s*'\\w+(\\.\\w+){0,2}\\/\\w+'\\s*,\\s*'[a-zA-Z0-9 ]+'\\s*\\)\\]$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/dataTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the parameter value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/validValueTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/validValueTypes.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. As-written, values must be one of\nthose on this list - the schema definition for dataType excludes `null` and\nnumbers with fractional parts, like `3.5`.\n", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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/2024/04/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "pattern": "^[a-zA-Z0-9 ]+$", + "minLength": 1 + } + } +} diff --git a/schemas/2024/04/bundled/config/document.vscode.json b/schemas/2024/04/bundled/config/document.vscode.json new file mode 100644 index 000000000..000d3870d --- /dev/null +++ b/schemas/2024/04/bundled/config/document.vscode.json @@ -0,0 +1,575 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "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", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json" + ], + "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\nFor every version of the schema, there are three valid urls:\n\n```yaml\n.../config/document.json\n```\n\n> The URL to the canonical non-bundled schema. When it's used for validation, the validating\n> client needs to retrieve this schema and every schema it references.\n \n```yaml\n.../bundled/config/document.json\n```\n\n> The URL to the bundled schema. When it's used for validation, the validating client only\n> needs to retrieve this schema.\n>\n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n\n```yaml\n.../bundled/config/document.vscode.json\n```\n\n> The URL to the enhanced authoring schema. This schema is much larger than the other\n> schemas, as it includes additional definitions that provide contextual help and snippets\n> that the others don't include.\n>\n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/document?view=dsc-3.0&preserve-view=true#schema\n", + "markdownEnumDescriptions": [ + "\n\n> #### `2024/04` non-bundled\n>\n> Indicates that the configuration document adheres to the `2024/04` schema. This URL\n> points to the canonical non-bundled schema. When it's used for validation, the\n> validating client needs to retrieve this schema and every schema it references.\n", + "\n\n> #### `2024/04` bundled\n>\n> Indicates that the configuration document adheres to the `2024/04` schema. This URL\n> points to the bundled schema. When it's used for validation, the validating client\n> only needs to retrieve this schema.\n>\n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n", + "\n\n> #### `2024/04` enhanced authoring\n>\n> Indicates that the configuration document adheres to the `2024/04` schema. This URL\n> points to the enhanced authoring schema. This schema is much larger than the other\n> schemas, as it includes additional definitions that provide contextual help and\n> snippets that the others don't include.\n>\n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n", + "\n\n> #### `2023/10` non-bundled\n>\n> Indicates that the configuration document adheres to the `2023/10` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.5` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the canonical non-bundled schema. When it's used for validation, the\n> validating client needs to retrieve this schema and every schema it references.\n", + "\n\n> #### `2023/10` bundled\n>\n> Indicates that the configuration document adheres to the `2023/10` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.5` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the bundled schema. When it's used for validation, the validating\n> client only needs to retrieve this schema.\n>\n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n", + "\n\n> #### `2023/10` enhanced authoring\n>\n> Indicates that the configuration document adheres to the `2023/10` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.5` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the enhanced authoring schema. This schema is much larger than the\n> other schemas, as it includes additional definitions that provide contextual help and\n> snippets that the others don't include.\n>\n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n", + "\n\n> #### `2023/08` non-bundled\n>\n> Indicates that the configuration document adheres to the `2023/08` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.3` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the canonical non-bundled schema. When it's used for validation, the\n> validating client needs to retrieve this schema and every schema it references.\n", + "\n\n> #### `2023/08` bundled\n>\n> Indicates that the configuration document adheres to the `2023/08` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.3` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the bundled schema. When it's used for validation, the validating\n> client only needs to retrieve this schema.\n>\n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n", + "\n\n> #### `2023/08` enhanced authoring\n>\n> Indicates that the configuration document adheres to the `2023/08` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.3` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the enhanced authoring schema. This schema is much larger than the\n> other schemas, as it includes additional definitions that provide contextual help and\n> snippets that the others don't include.\n>\n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json" + }, + "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", + "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", + "description": "$3", + "defaultValue": "$4", + "allowedValues": [ + "$5" + ] + } + } + }, + { + "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:parameterId}": { + "type": "int", + "description": "$2", + "defaultValue": "$3", + "minValue": "$4", + "maxValue": "$5" + } + } + } + ] + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object", + "markdownDescription": "***\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", + "markdownDescription": "Defines a new variable as a key-value pair.\n\n```yaml\nvariableName: variableValue\n```", + "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.\n\n```yaml\nvariableName:\n key: value\n```", + "body": { + "${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.\n\n```yaml\nvariableName:\n - firstValue\n - secondValue\n```", + "body": { + "${1:variableName}": [ + "${2:firstValue}", + "${3:secondValue}" + ] + } + } + ] + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json" + }, + "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": "***\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", + "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)", + "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}" + } + } + }, + { + "label": " New metadata property (array)", + "markdownDescription": "Defines a new key-value pair for the metadata where the value is an array.\n\n```yaml\nmetadataName:\n - firstValue\n - secondValue\n```", + "body": { + "${1:metadataName}": [ + "${2:firstValue}", + "${3:secondValue}" + ] + } + } + ] + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2024": { + "04": { + "config": { + "document.parameter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "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" + ], + "properties": { + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/validValueTypes.json", + "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", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/validValueTypes.json" + }, + "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": "***\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": "***\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", + "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)", + "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}" + } + } + }, + { + "label": " New metadata property (array)", + "markdownDescription": "Defines a new key-value pair for the metadata where the value is an array.\n\n```yaml\nmetadataName:\n - firstValue\n - secondValue\n```", + "body": { + "${1:metadataName}": [ + "${2:firstValue}", + "${3:secondValue}" + ] + } + } + ] + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "properties": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer", + "markdownDescription": "***\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": "***\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" + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "properties": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0, + "markdownDescription": "***\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": "***\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" + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "string" + }, + "allowedValues": { + "items": { + "type": "string" + } + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "object" + } + } + }, + { + "properties": { + "type": { + "const": "secureobject" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "object" + }, + "allowedValues": { + "items": { + "type": "object" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "integer" + }, + "allowedValues": { + "items": { + "type": "integer" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "array" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "array" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "bool" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "boolean" + }, + "allowedValues": { + "items": { + "type": "boolean" + } + } + } + } + } + ] + }, + "document.resource.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json", + "title": "DSC Resource instance", + "description": "Defines an instance of a DSC Resource in a configuration.", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "name": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the `resourceID()` lookup for another instance in the configuration. Multiple instances can depend on the same instance, but every dependency for an instance must be unique in that instance's `dependsOn` property.", + "type": "array", + "items": { + "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", + "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": "***\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": "***\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": "***\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", + "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:owner[.group][.area]/name}", + "name": "${2:instance_name}", + "properties": { + "${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\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:owner[.group][.area]/name}", + "name": "${2:instance_name}", + "dependsOn": [ + "\"[resourceId('${3:dependencyInstance/Type}', '${4:dependencyInstanceName}')]\"" + ], + "properties": { + "${5:propertyName}": "${6:propertyValue}" + } + } + } + ] + } + }, + "definitions": { + "parameters": { + "dataTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the parameter value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ], + "markdownDescription": "***\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": [ + "_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": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/validValueTypes.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. As-written, values must be one of\nthose on this list - the schema definition for dataType excludes `null` and\nnumbers with fractional parts, like `3.5`.\n", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + } + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", + "markdownDescription": "***\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": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "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": "***\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/2024/04/bundled/outputs/config/get.json b/schemas/2024/04/bundled/outputs/config/get.json new file mode 100644 index 000000000..93756eadc --- /dev/null +++ b/schemas/2024/04/bundled/outputs/config/get.json @@ -0,0 +1,160 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/get.json", + "title": "DSC Configuration get command result", + "description": "Represents the data structure returned by the `dsc config get` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json" + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json", + "title": "dsc resource get result (full)", + "description": "Describes the return data for the full result of the `get` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config get` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource get` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "pattern": "^[a-zA-Z0-9 ]+$", + "minLength": 1 + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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/2024/04/outputs/resource/get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the actual state of a non-nested instance or an array of objects that describe the actual state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json" + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json", + "title": "dsc resource get result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource get` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource get` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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/2024/04/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } +} diff --git a/schemas/2024/04/bundled/outputs/config/set.json b/schemas/2024/04/bundled/outputs/config/set.json new file mode 100644 index 000000000..b9431577e --- /dev/null +++ b/schemas/2024/04/bundled/outputs/config/set.json @@ -0,0 +1,176 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/set.json", + "title": "DSC Configuration set command result", + "description": "Represents the data structure returned by the `dsc config set` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json" + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json", + "title": "dsc resource set result (full)", + "description": "Describes the return data for the full result of the `set` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config set` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource set` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "pattern": "^[a-zA-Z0-9 ]+$", + "minLength": 1 + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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/2024/04/outputs/resource/set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the enforced state of a non-nested instance or an array of objects that describe the enforced state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json" + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json", + "title": "dsc resource set result (simple)", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource set` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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/2024/04/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } +} diff --git a/schemas/2024/04/bundled/outputs/config/test.json b/schemas/2024/04/bundled/outputs/config/test.json new file mode 100644 index 000000000..fbe17a556 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/config/test.json @@ -0,0 +1,182 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/test.json", + "title": "DSC Configuration test command result", + "description": "Represents the data structure returned by the `dsc config test` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json" + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json", + "title": "dsc resource test result (full)", + "description": "Describes the return data for the full result of the `test` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config test` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource test` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "pattern": "^[a-zA-Z0-9 ]+$", + "minLength": 1 + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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/2024/04/outputs/resource/test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command. The return data is either a single object that describes the tested state of a non-nested instance or an array of objects that describe the tested state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json" + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json", + "title": "dsc resource test result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource test` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource test` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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/2024/04/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } +} diff --git a/schemas/2024/04/bundled/outputs/resource/get.json b/schemas/2024/04/bundled/outputs/resource/get.json new file mode 100644 index 000000000..4ae0a08e3 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/resource/get.json @@ -0,0 +1,93 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the actual state of a non-nested instance or an array of objects that describe the actual state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json" + } + } + ], + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json", + "title": "dsc resource get result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource get` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource get` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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/2024/04/outputs/resource/get.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json", + "title": "dsc resource get result (full)", + "description": "Describes the return data for the full result of the `get` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config get` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource get` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "pattern": "^[a-zA-Z0-9 ]+$", + "minLength": 1 + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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/2024/04/outputs/resource/get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the actual state of a non-nested instance or an array of objects that describe the actual state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json" + } + } + ] + } + } +} diff --git a/schemas/2024/04/bundled/outputs/resource/list.json b/schemas/2024/04/bundled/outputs/resource/list.json new file mode 100644 index 000000000..9db58db06 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/resource/list.json @@ -0,0 +1,708 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/list.json", + "title": "dsc resource list result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource list` command.", + "type": "object", + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "version": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "path": { + "title": "Path", + "description": "Indicates the path to the DSC Resource on the file system.", + "type": "string" + }, + "directory": { + "title": "Directory", + "description": "Indicates the path to the folder containing the DSC Resource on the file system.", + "type": "string" + }, + "implementedAs": { + "title": "Implemented as", + "description": "Indicates how the DSC Resource was implemented.", + "oneOf": [ + { + "title": "Standard implementation", + "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", + "type": "string", + "enum": [ + "Command" + ] + }, + { + "title": "Custom implementation", + "description": "Indicates that the DSC Resource uses a custom implementation.", + "type": "object", + "required": [ + "custom" + ], + "properties": { + "custom": { + "title": "Custom implementation name", + "description": "The name of the custom implementation.", + "type": "string" + } + } + } + ] + }, + "author": { + "title": "Author", + "description": "Indicates the name of the person or organization that developed and maintains the DSC Resource.", + "type": [ + "string", + "null" + ] + }, + "properties": { + "title": "Properties", + "description": "Defines the DSC Resource's property names.", + "type": "array", + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "requires": { + "title": "Required DSC Resource Adapter", + "description": "Defines the fully qualified type name of the DSC Resource Adapter the DSC Resource depends on.", + "oneOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + { + "type": "null" + } + ] + }, + "manifest": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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/2024/04/definitions/semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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.", + "type": "object", + "required": [ + "$schema", + "type", + "version", + "get" + ], + "properties": { + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json" + ] + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "Defines a list of searchable terms for the resource.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json" + }, + "export": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" + }, + "set": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json" + }, + "test": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json" + }, + "validate": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json" + }, + "adapter": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + }, + "unevaluatedProperties": false, + "default": { + "0": "Success", + "1": "Error" + }, + "examples": [ + { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + ] + }, + "schema": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json", + "title": "Set Method", + "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + }, + "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 + }, + "return": { + "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "implementsPretest": true, + "return": "state" + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json", + "title": "Test Method", + "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + }, + "return": { + "title": "Test Command Return Type", + "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json", + "title": "Validate Method", + "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + }, + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json", + "title": "Adapter", + "description": "Defines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter enables users to manage resources that don't have their own manifests with DSC.", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Adapter to list its supported DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the adapter expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ] + } + }, + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": [ + "command" + ] + }, + { + "required": [ + "embedded" + ] + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + } + }, + "embedded": { + "title": "Embedded Instance Schema", + "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema. If the instance schema is published to its own public URI, set this keyword to that URI.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the properties that DSC can retrieve and manage for the resource's instances. This keyword must define at least one property as a key-value pair. The key is the property's name. The value is a subschema that validates the property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "additionalProperties": {}, + "properties": { + "_exist": { + "title": "Standard Property: _exist", + "description": "Indicates that the DSC Resource uses the standard `_exist` property to specify whether an instance should exist as a boolean value that defaults to `true`.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "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/2024/04/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "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/2024/04/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + }, + "examples": [ + { + "command": { + "executable": "registry", + "args": [ + "schema" + ] + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json", + "title": "Executable Command Input Type", + "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": [ + "env", + "stdin" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json", + "title": "Instance should exist", + "description": "Indicates whether the DSC Resource instance should exist.", + "type": "boolean", + "default": true, + "enum": [ + false, + true + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/inDesiredState.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/inDesiredState.json", + "title": "Instance is in the Desired State", + "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json", + "title": "Purge", + "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", + "type": [ + "boolean", + "null" + ], + "writeOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/rebootRequested.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/rebootRequested.json", + "title": "Reboot Requested", + "description": "Indicates that the set operation requires a reboot before it's fully complete.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + } + } +} diff --git a/schemas/2024/04/bundled/outputs/resource/schema.json b/schemas/2024/04/bundled/outputs/resource/schema.json new file mode 100644 index 000000000..46a2bd905 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/resource/schema.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc resource schema` command. This command always returns the DSC Resource's JSON schema document.", + "type": "object", + "$defs": {} +} diff --git a/schemas/2024/04/bundled/outputs/resource/set.json b/schemas/2024/04/bundled/outputs/resource/set.json new file mode 100644 index 000000000..efe0397df --- /dev/null +++ b/schemas/2024/04/bundled/outputs/resource/set.json @@ -0,0 +1,109 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the enforced state of a non-nested instance or an array of objects that describe the enforced state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json" + } + } + ], + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json", + "title": "dsc resource set result (simple)", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource set` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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/2024/04/outputs/resource/set.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json", + "title": "dsc resource set result (full)", + "description": "Describes the return data for the full result of the `set` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config set` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource set` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "pattern": "^[a-zA-Z0-9 ]+$", + "minLength": 1 + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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/2024/04/outputs/resource/set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the enforced state of a non-nested instance or an array of objects that describe the enforced state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json" + } + } + ] + } + } +} diff --git a/schemas/2024/04/bundled/outputs/resource/test.json b/schemas/2024/04/bundled/outputs/resource/test.json new file mode 100644 index 000000000..4eedeaa80 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/resource/test.json @@ -0,0 +1,115 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command. The return data is either a single object that describes the tested state of a non-nested instance or an array of objects that describe the tested state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json" + } + } + ], + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json", + "title": "dsc resource test result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource test` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource test` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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/2024/04/outputs/resource/test.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json", + "title": "dsc resource test result (full)", + "description": "Describes the return data for the full result of the `test` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config test` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource test` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "pattern": "^[a-zA-Z0-9 ]+$", + "minLength": 1 + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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/2024/04/outputs/resource/test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command. The return data is either a single object that describes the tested state of a non-nested instance or an array of objects that describe the tested state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json" + } + } + ] + } + } +} diff --git a/schemas/2024/04/bundled/outputs/schema.json b/schemas/2024/04/bundled/outputs/schema.json new file mode 100644 index 000000000..2214fb830 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/schema.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc schema` command. This command always returns a JSON schema document.", + "type": "object", + "$defs": {} +} diff --git a/schemas/2024/04/bundled/resource/manifest.json b/schemas/2024/04/bundled/resource/manifest.json new file mode 100644 index 000000000..e06b9cfe0 --- /dev/null +++ b/schemas/2024/04/bundled/resource/manifest.json @@ -0,0 +1,617 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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.", + "type": "object", + "required": [ + "$schema", + "type", + "version", + "get" + ], + "properties": { + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json" + ] + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "Defines a list of searchable terms for the resource.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json" + }, + "export": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" + }, + "set": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json" + }, + "test": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json" + }, + "validate": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json" + }, + "adapter": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + }, + "unevaluatedProperties": false, + "default": { + "0": "Success", + "1": "Error" + }, + "examples": [ + { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + ] + }, + "schema": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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/2024/04/definitions/semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json", + "title": "Set Method", + "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + }, + "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 + }, + "return": { + "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "implementsPretest": true, + "return": "state" + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json", + "title": "Test Method", + "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + }, + "return": { + "title": "Test Command Return Type", + "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json", + "title": "Validate Method", + "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + }, + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json", + "title": "Adapter", + "description": "Defines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter enables users to manage resources that don't have their own manifests with DSC.", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Adapter to list its supported DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the adapter expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ] + } + }, + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": [ + "command" + ] + }, + { + "required": [ + "embedded" + ] + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + } + }, + "embedded": { + "title": "Embedded Instance Schema", + "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema. If the instance schema is published to its own public URI, set this keyword to that URI.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the properties that DSC can retrieve and manage for the resource's instances. This keyword must define at least one property as a key-value pair. The key is the property's name. The value is a subschema that validates the property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "additionalProperties": {}, + "properties": { + "_exist": { + "title": "Standard Property: _exist", + "description": "Indicates that the DSC Resource uses the standard `_exist` property to specify whether an instance should exist as a boolean value that defaults to `true`.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "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/2024/04/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "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/2024/04/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + }, + "examples": [ + { + "command": { + "executable": "registry", + "args": [ + "schema" + ] + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json", + "title": "Executable Command Input Type", + "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": [ + "env", + "stdin" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json", + "title": "Instance should exist", + "description": "Indicates whether the DSC Resource instance should exist.", + "type": "boolean", + "default": true, + "enum": [ + false, + true + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/inDesiredState.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/inDesiredState.json", + "title": "Instance is in the Desired State", + "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json", + "title": "Purge", + "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", + "type": [ + "boolean", + "null" + ], + "writeOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/rebootRequested.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/rebootRequested.json", + "title": "Reboot Requested", + "description": "Indicates that the set operation requires a reboot before it's fully complete.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + } + } +} diff --git a/schemas/2024/04/bundled/resource/manifest.vscode.json b/schemas/2024/04/bundled/resource/manifest.vscode.json new file mode 100644 index 000000000..4c9e39c48 --- /dev/null +++ b/schemas/2024/04/bundled/resource/manifest.vscode.json @@ -0,0 +1,1173 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\n[_Online Documentation_][01]\n***\n\nDefines the information DSC and integrating require to process and call a command-based DSC\nResource. For DSC to use a manifest on a system, the manifest file must:\n\n1. Be discoverable in the `PATH` environment variable.\n1. Follow the naming convention `.dsc.resource.json`.\n1. Be valid for this schema.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true\n", + "defaultSnippets": [ + { + "label": " Define a resource", + "markdownDescription": "Defines a standard resource that:\n\n- Can get the current state of an instance\n- Can set an instance to the desired state\n- Relies on DSC's synthetic testing to determine whether an instance is in the desired state\n- Defines an embedded JSON schema.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "set": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "implementsPretest": "^${11:false}", + "return": "${12:state}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "${14:name}": { + "title": "${15:property title}", + "description": "${16:explanation of property purpose and usage}", + "type": "${17|string,integer,number,array,object,null|}" + } + } + } + } + } + }, + { + "label": " Define a resource (group)", + "markdownDescription": "Defines a group resource that expects a list of resource instances and operates on them.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "test": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "return": "${12:state}" + }, + "set": { + "executable": "${13:executable name}", + "args": [ + "${14:argument}" + ], + "input": "${15:stdin}", + "implementsPretest": "^${16:false}", + "return": "${17:state}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${18|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "resources": { + "title": "${19:Resources}", + "description": "${20:Defines a list of resource instances to process}", + "type": "array", + "items": { + "${escape_dollar:$}ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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 (adapter)", + "markdownDescription": "Defines an adapter resource that enables users to define non-command-based DSC Resources in\nthe configuration.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "test": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "return": "${12:state}" + }, + "set": { + "executable": "${13:executable name}", + "args": [ + "${14:argument}" + ], + "input": "${15:stdin}", + "implementsPretest": "^${16:false}", + "return": "${17:state}" + }, + "adapter": { + "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/2024/04/config/document.resource.json" + } + }, + "${26:name}": { + "title": "${27:property title}", + "description": "${28:explanation of property purpose and usage}", + "type": "${29|string,integer,number,array,object,null|}" + } + } + } + } + } + }, + { + "label": " Define a resource (assertion-only)", + "markdownDescription": "Defines an assertion resource that can get the current state of an instance but not configure\nit. By default, the resource relies on DSC's synthetic testing feature. If the resource\nimplements the `test` operation itself, define the `test` property.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "${14:name}": { + "title": "${15:property title}", + "description": "${16:explanation of property purpose and usage}", + "type": "${17|string,integer,number,array,object,null|}" + } + } + } + } + } + } + ], + "type": "object", + "required": [ + "$schema", + "type", + "version", + "get" + ], + "properties": { + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json" + ], + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property must be one of the canonical URLs for the version of the Command-based DSC\nResource Manifest schema that the manifest is implemented for.\n\nFor every version of the schema, there are three valid urls:\n\n```yaml\n.../resource/manifest.json\n```\n\n> The URL to the canonical non-bundled schema. When it's used for validation, the validating\n> client needs to retrieve this schema and every schema it references.\n\n```yaml\n.../bundled/resource/manifest.json\n```\n\n> The URL to the bundled schema. When it's used for validation, the validating client only\n> needs to retrieve this schema.\n> \n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n\n```yaml\n.../bundled/resource/manifest.vscode.json\n```\n\n> The URL to the enhanced authoring schema. This schema is much larger than the other\n> schemas, as it includes additional definitions that provide contextual help and snippets\n> that the others don't include.\n> \n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#schema\n", + "markdownEnumDescriptions": [ + "\n\n> #### `2024/04` non-bundled\n>\n> Indicates that the resource manifest adheres to the `2024/04` schema. This URL\n> points to the canonical non-bundled schema. When it's used for validation, the\n> validating client needs to retrieve this schema and every schema it references.\n", + "\n\n> #### `2024/04` bundled\n>\n> Indicates that the resource manifest adheres to the `2024/04` schema. This URL\n> points to the bundled schema. When it's used for validation, the validating client\n> only needs to retrieve this schema.\n>\n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n", + "\n\n> #### `2024/04` enhanced authoring\n>\n> Indicates that the resource manifest adheres to the `2024/04` schema. This URL\n> points to the enhanced authoring schema. This schema is much larger than the other\n> schemas, as it includes additional definitions that provide contextual help and\n> snippets that the others don't include.\n>\n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n", + "\n\n> #### `2023/10` non-bundled\n>\n> Indicates that the resource manifest adheres to the `2023/10` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.5` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the canonical non-bundled schema. When it's used for validation, the\n> validating client needs to retrieve this schema and every schema it references.\n", + "\n\n> #### `2023/10` bundled\n>\n>Indicates that the resource manifest adheres to the `2023/10` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.5` and earlier.\n> Migrate to using the `2024/04` of the schema.\n>\n> This URL points to the bundled schema. When it's used for validation, the validating\n> client only needs to retrieve this schema.\n>\n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n", + "\n\n> #### `2023/10` enhanced authoring\n>\n>Indicates that the resource manifest adheres to the `2023/10` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.5` and earlier.\n> Migrate to using the `2024/04` of the schema.\n>\n> This URL points to the enhanced authoring schema. This schema is much larger than the\n> other schemas, as it includes additional definitions that provide contextual help and\n> snippets that the others don't include.\n>\n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n", + "\n\n> #### `2023/08` non-bundled\n>\n> Indicates that the resource manifest adheres to the `2023/08` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.3` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the canonical non-bundled schema. When it's used for validation, the\n> validating client needs to retrieve this schema and every schema it references.\n", + "\n\n> #### `2023/08` bundled\n>\n> Indicates that the resource manifest adheres to the `2023/08` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.3` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the bundled schema. When it's used for validation, the validating\n> client only needs to retrieve this schema.\n>\n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n", + "\n\n> #### `2023/08` enhanced authoring\n>\n> Indicates that the resource manifest adheres to the `2023/08` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.3` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the enhanced authoring schema. This schema is much larger than the\n> other schemas, as it includes additional definitions that provide contextual help and\n> snippets that the others don't include.\n>\n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n" + ] + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json", + "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": "***\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": "***\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": { + "type": "string", + "pattern": "^\\w+$", + "patternErrorMessage": "Invalid tag. Tags must be a string of alphanumeric characters and underscores. No other\ncharacters are permitted.\n" + } + }, + "get": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json" + }, + "export": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" + }, + "set": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json" + }, + "test": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json" + }, + "validate": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json" + }, + "adapter": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$", + "patternErrorMessage": "Invalid exit code. Must be a string representing an integer greater than or equal to `0`.\n" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + }, + "unevaluatedProperties": false, + "default": { + "0": "Success", + "1": "Error" + }, + "examples": [ + { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "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": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json" + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2024": { + "04": { + "definitions": { + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", + "markdownDescription": "***\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/2024/04/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/2024/04/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json", + "title": "Executable Command Input Type", + "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": [ + "env", + "stdin" + ], + "markdownEnumDescriptions": [ + "_Environment variables_\n\n> Indicates that the resource expects the properties of an instance to be specified as\n> environment variables with the same names and casing.\n>\n> This option only supports the following data types for instance properties:\n>\n> - `boolean`\n> - `integer`\n> - `number`\n> - `string`\n> - `array` of `integer` values\n> - `array` of `number` values\n> - `array` of `string` values\n>\n> For non-array values, DSC sets the environment variable to the specified value as-is. When\n> the data type is an array of values, DSC sets the environment variable as a comma-delimited\n> string. For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo`\n> environment variable as `\"1,2,3\"`.\n>\n> If the resource needs to support complex properties with an `object` value or multi-type\n> arrays, set this to `stdin` instead.\n", + "_JSON over `stdin`_\n\n> Indicates that the resource expects a JSON blob representing an instance from `stdin`.\n> The JSON must adhere to the instance schema.\n" + ] + }, + "returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." + } + }, + "resource": { + "manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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/2024/04/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/2024/04/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/2024/04/definitions/inputKind.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. If this value isn't defined, DSC doesn't send the resource any input when\ninvoking the `get` operation.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#input\n" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the get command for the resource when no arguments are required.\n", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the get command for the resource when at least one argument is required.\n", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + } + ] + }, + "manifest.export.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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/2024/04/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/2024/04/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/2024/04/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": "***\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", + "input" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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/2024/04/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/2024/04/definitions/inputKind.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" + }, + "implementsPretest": { + "title": "Resource Performs Pre-Test", + "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", + "type": "boolean", + "default": false, + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the DSC Resource performs its own test to ensure idempotency when calling the\n`set` command. Set this value to `true` if the DSC Resource tests input before modifying\nsystem state.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#implementspretest\n" + }, + "return": { + "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json", + "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": [ + "_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" + ] + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "implementsPretest": true, + "return": "state" + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `set` command for the resource when no arguments are required.\n", + "body": { + "input": "${1|input,env|}", + "implementsPretest": "^${2|true,false|}", + "return": "${3|state,stateAndDiff|}", + "executable": "${4:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the `set` command for the resource when at least one argument is required.\n", + "body": { + "input": "${1|input,env|}", + "implementsPretest": "^${2|true,false|}", + "return": "${3|state,stateAndDiff|}", + "executable": "${4:executable_name}", + "args": [ + "${5:--first-argument}" + ] + } + } + ] + }, + "manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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", + "input" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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/2024/04/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/2024/04/definitions/inputKind.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" + }, + "return": { + "title": "Test Command Return Type", + "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json", + "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": [ + "_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" + ] + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `test` command for the resource when no arguments are required.\n", + "body": { + "input": "${1|input,env|}", + "return": "${2|state,stateAndDiff|}", + "executable": "${3:executable_name}" + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the `test` command for the resource when at least one argument is required.\n", + "body": { + "input": "${1|input,env|}", + "return": "${2|state,stateAndDiff|}", + "executable": "${3:executable_name}", + "args": [ + "${4:--first-argument}" + ] + } + } + ] + }, + "manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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/2024/04/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/2024/04/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": [ + { + "executable": "dsc", + "args": [ + "config", + "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.adapter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json", + "title": "Adapter", + "description": "Defines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter enables users to manage resources that don't have their own manifests with DSC.", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter 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/adapter?view=dsc-3.0&preserve-view=true\n", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Adapter to list its supported DSC Resources.", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource Adapter to list its supported DSC Resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/adapter?view=dsc-3.0&preserve-view=true#list\n", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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/adapter?view=dsc-3.0&preserve-view=true#executable\n" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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/adapter?view=dsc-3.0&preserve-view=true#args\n" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the adapter expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ], + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the adapter 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/adapter?view=dsc-3.0&preserve-view=true#config\n", + "markdownEnumDescriptions": [ + "_Full and unprocessed config as a JSON blob_\n\n> Indicates that the adapter 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 adapter expects each resource's configuration as a [JSON Line][01]\n> over `stdin`.\n\n[01]: https://jsonlines.org/\n" + ] + } + }, + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the adapter 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 adapter 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": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": [ + "command" + ] + }, + { + "required": [ + "embedded" + ] + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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/2024/04/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": "***\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": "***\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", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object", + "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", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ], + "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": [ + "_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": { + "title": "DSC Resource instance schema ID", + "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": "***\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": "***\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": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "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": { + "_exist": { + "title": "Standard Property: _exist", + "description": "Indicates that the DSC Resource uses the standard `_exist` property to specify whether an instance should exist as a boolean value that defaults to `true`.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json" + }, + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nIndicates that the resource can enforce whether instances exist, handling whether an\ninstance should be added, updated, or removed during a set operation. The default\nvalue is `true`.\n\nResources that define this property declare that the implementation adheres to the\nfollowing behavior contract:\n\n1. When the desired state for `_exist` is `true`, the resource expects the instance\n to exist. If it doesn't exist, the resource creates or adds the instance during\n the set operation.\n1. When the desired state for `_exist` is `false`, the resource expects the instance\n to not exist. If it does exist, the resource deletes or removes the instance\n during the set operation.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?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 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/2024/04/resource/properties/inDesiredState.json" + }, + "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", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json" + }, + "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 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/2024/04/resource/properties/rebootRequested.json" + }, + "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|}" + } + } + } + ] + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri", + "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": [ + { + "command": { + "executable": "registry", + "args": [ + "schema" + ] + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ], + "markdownDescription": "***\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|}" + } + } + } + } + } + ] + } + } + } + } + } + } + } + } + } +} diff --git a/schemas/2024/04/config/document.json b/schemas/2024/04/config/document.json new file mode 100644 index 000000000..7a428085d --- /dev/null +++ b/schemas/2024/04/config/document.json @@ -0,0 +1,57 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + } +} diff --git a/schemas/2024/04/config/document.parameter.json b/schemas/2024/04/config/document.parameter.json new file mode 100644 index 000000000..642a36cf3 --- /dev/null +++ b/schemas/2024/04/config/document.parameter.json @@ -0,0 +1,228 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "properties": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "properties": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "string" + }, + "allowedValues": { + "items": { + "type": "string" + } + } + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "object" + } + } + }, + { + "properties": { + "type": { + "const": "secureobject" + } + } + } + ] + }, + "then": { + "properties": { + "defaultValue": { + "type": "object" + }, + "allowedValues": { + "items": { + "type": "object" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "integer" + }, + "allowedValues": { + "items": { + "type": "integer" + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "array" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "array" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "const": "bool" + } + } + }, + "then": { + "properties": { + "defaultValue": { + "type": "boolean" + }, + "allowedValues": { + "items": { + "type": "boolean" + } + } + } + } + } + ] +} diff --git a/schemas/2024/04/config/document.resource.json b/schemas/2024/04/config/document.resource.json new file mode 100644 index 000000000..e6841557a --- /dev/null +++ b/schemas/2024/04/config/document.resource.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json", + "title": "DSC Resource instance", + "description": "Defines an instance of a DSC Resource in a configuration.", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the `resourceID()` lookup for another instance in the configuration. Multiple instances can depend on the same instance, but every dependency for an instance must be unique in that instance's `dependsOn` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[resourceId\\(\\s*'\\w+(\\.\\w+){0,2}\\/\\w+'\\s*,\\s*'[a-zA-Z0-9 ]+'\\s*\\)\\]$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } +} diff --git a/schemas/2024/04/definitions/commandArgs.json b/schemas/2024/04/definitions/commandArgs.json new file mode 100644 index 000000000..c4d08edf8 --- /dev/null +++ b/schemas/2024/04/definitions/commandArgs.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } +} diff --git a/schemas/2024/04/definitions/commandExecutable.json b/schemas/2024/04/definitions/commandExecutable.json new file mode 100644 index 000000000..c6e5f40a2 --- /dev/null +++ b/schemas/2024/04/definitions/commandExecutable.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" +} diff --git a/schemas/2024/04/definitions/hadErrors.json b/schemas/2024/04/definitions/hadErrors.json new file mode 100644 index 000000000..28da5d152 --- /dev/null +++ b/schemas/2024/04/definitions/hadErrors.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" +} diff --git a/schemas/2024/04/definitions/inputKind.json b/schemas/2024/04/definitions/inputKind.json new file mode 100644 index 000000000..722dfb220 --- /dev/null +++ b/schemas/2024/04/definitions/inputKind.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json", + "title": "Executable Command Input Type", + "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": [ + "env", + "stdin" + ] +} diff --git a/schemas/2024/04/definitions/instanceName.json b/schemas/2024/04/definitions/instanceName.json new file mode 100644 index 000000000..faf4de581 --- /dev/null +++ b/schemas/2024/04/definitions/instanceName.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "pattern": "^[a-zA-Z0-9 ]+$", + "minLength": 1 +} diff --git a/schemas/2024/04/definitions/message.json b/schemas/2024/04/definitions/message.json new file mode 100644 index 000000000..b65cb91c7 --- /dev/null +++ b/schemas/2024/04/definitions/message.json @@ -0,0 +1,39 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } +} diff --git a/schemas/2024/04/definitions/messages.json b/schemas/2024/04/definitions/messages.json new file mode 100644 index 000000000..5d5d02051 --- /dev/null +++ b/schemas/2024/04/definitions/messages.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/message.json" + } +} diff --git a/schemas/2024/04/definitions/parameters/dataTypes.json b/schemas/2024/04/definitions/parameters/dataTypes.json new file mode 100644 index 000000000..07143abbd --- /dev/null +++ b/schemas/2024/04/definitions/parameters/dataTypes.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the parameter value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] +} diff --git a/schemas/2024/04/definitions/parameters/validValueTypes.json b/schemas/2024/04/definitions/parameters/validValueTypes.json new file mode 100644 index 000000000..a92573009 --- /dev/null +++ b/schemas/2024/04/definitions/parameters/validValueTypes.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/validValueTypes.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. As-written, values must be one of\nthose on this list - the schema definition for dataType excludes `null` and\nnumbers with fractional parts, like `3.5`.\n", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] +} diff --git a/schemas/2024/04/definitions/resourceType.json b/schemas/2024/04/definitions/resourceType.json new file mode 100644 index 000000000..68041b8d6 --- /dev/null +++ b/schemas/2024/04/definitions/resourceType.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" +} diff --git a/schemas/2024/04/definitions/returnKind.json b/schemas/2024/04/definitions/returnKind.json new file mode 100644 index 000000000..285a80bb9 --- /dev/null +++ b/schemas/2024/04/definitions/returnKind.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." +} diff --git a/schemas/2024/04/definitions/semver.json b/schemas/2024/04/definitions/semver.json new file mode 100644 index 000000000..7ad7c56ae --- /dev/null +++ b/schemas/2024/04/definitions/semver.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" +} diff --git a/schemas/2024/04/outputs/config/get.json b/schemas/2024/04/outputs/config/get.json new file mode 100644 index 000000000..f57221eb4 --- /dev/null +++ b/schemas/2024/04/outputs/config/get.json @@ -0,0 +1,28 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/get.json", + "title": "DSC Configuration get command result", + "description": "Represents the data structure returned by the `dsc config get` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json" + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json" + } + } +} diff --git a/schemas/2024/04/outputs/config/set.json b/schemas/2024/04/outputs/config/set.json new file mode 100644 index 000000000..8aba9d68c --- /dev/null +++ b/schemas/2024/04/outputs/config/set.json @@ -0,0 +1,28 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/set.json", + "title": "DSC Configuration set command result", + "description": "Represents the data structure returned by the `dsc config set` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json" + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json" + } + } +} diff --git a/schemas/2024/04/outputs/config/test.json b/schemas/2024/04/outputs/config/test.json new file mode 100644 index 000000000..4e5cfc5a8 --- /dev/null +++ b/schemas/2024/04/outputs/config/test.json @@ -0,0 +1,28 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/test.json", + "title": "DSC Configuration test command result", + "description": "Represents the data structure returned by the `dsc config test` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json" + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json" + } + } +} diff --git a/schemas/2024/04/outputs/resource/get.full.json b/schemas/2024/04/outputs/resource/get.full.json new file mode 100644 index 000000000..54bb4336d --- /dev/null +++ b/schemas/2024/04/outputs/resource/get.full.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json", + "title": "dsc resource get result (full)", + "description": "Describes the return data for the full result of the `get` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config get` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource get` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.json" + } + } +} diff --git a/schemas/2024/04/outputs/resource/get.json b/schemas/2024/04/outputs/resource/get.json new file mode 100644 index 000000000..ac486a323 --- /dev/null +++ b/schemas/2024/04/outputs/resource/get.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the actual state of a non-nested instance or an array of objects that describe the actual state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json" + } + } + ] +} diff --git a/schemas/2024/04/outputs/resource/get.simple.json b/schemas/2024/04/outputs/resource/get.simple.json new file mode 100644 index 000000000..56fe89cb7 --- /dev/null +++ b/schemas/2024/04/outputs/resource/get.simple.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json", + "title": "dsc resource get result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource get` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource get` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "type": "object", + "required": [ + "actualState" + ], + "properties": { + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + } + } +} diff --git a/schemas/2024/04/outputs/resource/list.json b/schemas/2024/04/outputs/resource/list.json new file mode 100644 index 000000000..c5fea3d92 --- /dev/null +++ b/schemas/2024/04/outputs/resource/list.json @@ -0,0 +1,91 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/list.json", + "title": "dsc resource list result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource list` command.", + "type": "object", + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "version": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "path": { + "title": "Path", + "description": "Indicates the path to the DSC Resource on the file system.", + "type": "string" + }, + "directory": { + "title": "Directory", + "description": "Indicates the path to the folder containing the DSC Resource on the file system.", + "type": "string" + }, + "implementedAs": { + "title": "Implemented as", + "description": "Indicates how the DSC Resource was implemented.", + "oneOf": [ + { + "title": "Standard implementation", + "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", + "type": "string", + "enum": [ + "Command" + ] + }, + { + "title": "Custom implementation", + "description": "Indicates that the DSC Resource uses a custom implementation.", + "type": "object", + "required": [ + "custom" + ], + "properties": { + "custom": { + "title": "Custom implementation name", + "description": "The name of the custom implementation.", + "type": "string" + } + } + } + ] + }, + "author": { + "title": "Author", + "description": "Indicates the name of the person or organization that developed and maintains the DSC Resource.", + "type": [ + "string", + "null" + ] + }, + "properties": { + "title": "Properties", + "description": "Defines the DSC Resource's property names.", + "type": "array", + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "requires": { + "title": "Required DSC Resource Adapter", + "description": "Defines the fully qualified type name of the DSC Resource Adapter the DSC Resource depends on.", + "oneOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + { + "type": "null" + } + ] + }, + "manifest": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json" + } + } +} diff --git a/schemas/2024/04/outputs/resource/schema.json b/schemas/2024/04/outputs/resource/schema.json new file mode 100644 index 000000000..0c4ffe21e --- /dev/null +++ b/schemas/2024/04/outputs/resource/schema.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc resource schema` command. This command always returns the DSC Resource's JSON schema document.", + "type": "object" +} diff --git a/schemas/2024/04/outputs/resource/set.full.json b/schemas/2024/04/outputs/resource/set.full.json new file mode 100644 index 000000000..20349d948 --- /dev/null +++ b/schemas/2024/04/outputs/resource/set.full.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json", + "title": "dsc resource set result (full)", + "description": "Describes the return data for the full result of the `set` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config set` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource set` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.json" + } + } +} diff --git a/schemas/2024/04/outputs/resource/set.json b/schemas/2024/04/outputs/resource/set.json new file mode 100644 index 000000000..feedae716 --- /dev/null +++ b/schemas/2024/04/outputs/resource/set.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the enforced state of a non-nested instance or an array of objects that describe the enforced state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json" + } + } + ] +} diff --git a/schemas/2024/04/outputs/resource/set.simple.json b/schemas/2024/04/outputs/resource/set.simple.json new file mode 100644 index 000000000..03d48a788 --- /dev/null +++ b/schemas/2024/04/outputs/resource/set.simple.json @@ -0,0 +1,33 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json", + "title": "dsc resource set result (simple)", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource set` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "type": "object", + "required": [ + "beforeState", + "afterState", + "changedProperties" + ], + "properties": { + "beforeState": { + "title": "State before enforcing", + "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "afterState": { + "title": "State after enforcing", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "changedProperties": { + "title": "Changed properties", + "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } +} diff --git a/schemas/2024/04/outputs/resource/test.full.json b/schemas/2024/04/outputs/resource/test.full.json new file mode 100644 index 000000000..144de4053 --- /dev/null +++ b/schemas/2024/04/outputs/resource/test.full.json @@ -0,0 +1,23 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json", + "title": "dsc resource test result (full)", + "description": "Describes the return data for the full result of the `test` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config test` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource test` command.", + "type": "object", + "required": [ + "name", + "result", + "type" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json" + } + } +} diff --git a/schemas/2024/04/outputs/resource/test.json b/schemas/2024/04/outputs/resource/test.json new file mode 100644 index 000000000..8d87882b8 --- /dev/null +++ b/schemas/2024/04/outputs/resource/test.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command. The return data is either a single object that describes the tested state of a non-nested instance or an array of objects that describe the tested state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json" + } + } + ] +} diff --git a/schemas/2024/04/outputs/resource/test.simple.json b/schemas/2024/04/outputs/resource/test.simple.json new file mode 100644 index 000000000..0ec8cf4a4 --- /dev/null +++ b/schemas/2024/04/outputs/resource/test.simple.json @@ -0,0 +1,39 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json", + "title": "dsc resource test result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource test` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource test` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "type": "object", + "required": [ + "desiredState", + "actualState", + "inDesiredState", + "differingProperties" + ], + "properties": { + "desiredState": { + "title": "Desired state", + "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", + "type": "object" + }, + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "inDesiredState": { + "title": "Instance is in the desired state", + "description": "This property indicates whether the instance is in the desired state.", + "type": "boolean" + }, + "differingProperties": { + "title": "Differing properties", + "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } +} diff --git a/schemas/2024/04/outputs/schema.json b/schemas/2024/04/outputs/schema.json new file mode 100644 index 000000000..a34600ac3 --- /dev/null +++ b/schemas/2024/04/outputs/schema.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc schema` command. This command always returns a JSON schema document.", + "type": "object" +} diff --git a/schemas/2024/04/resource/manifest.adapter.json b/schemas/2024/04/resource/manifest.adapter.json new file mode 100644 index 000000000..7dd76ac33 --- /dev/null +++ b/schemas/2024/04/resource/manifest.adapter.json @@ -0,0 +1,53 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json", + "title": "Adapter", + "description": "Defines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter enables users to manage resources that don't have their own manifests with DSC.", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Adapter to list its supported DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the adapter expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ] + } + }, + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } + } + ] +} diff --git a/schemas/2024/04/resource/manifest.export.json b/schemas/2024/04/resource/manifest.export.json new file mode 100644 index 000000000..bfcca164a --- /dev/null +++ b/schemas/2024/04/resource/manifest.export.json @@ -0,0 +1,18 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + } +} diff --git a/schemas/2024/04/resource/manifest.get.json b/schemas/2024/04/resource/manifest.get.json new file mode 100644 index 000000000..3764ded7c --- /dev/null +++ b/schemas/2024/04/resource/manifest.get.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ] +} diff --git a/schemas/2024/04/resource/manifest.json b/schemas/2024/04/resource/manifest.json new file mode 100644 index 000000000..5cbf72235 --- /dev/null +++ b/schemas/2024/04/resource/manifest.json @@ -0,0 +1,103 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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.", + "type": "object", + "required": [ + "$schema", + "type", + "version", + "get" + ], + "properties": { + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json" + ] + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "Defines a list of searchable terms for the resource.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json" + }, + "export": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" + }, + "set": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json" + }, + "test": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json" + }, + "validate": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json" + }, + "adapter": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + }, + "unevaluatedProperties": false, + "default": { + "0": "Success", + "1": "Error" + }, + "examples": [ + { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + ] + }, + "schema": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json" + } + } +} diff --git a/schemas/2024/04/resource/manifest.schema.json b/schemas/2024/04/resource/manifest.schema.json new file mode 100644 index 000000000..2f1590ceb --- /dev/null +++ b/schemas/2024/04/resource/manifest.schema.json @@ -0,0 +1,196 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": [ + "command" + ] + }, + { + "required": [ + "embedded" + ] + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + } + }, + "embedded": { + "title": "Embedded Instance Schema", + "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema. If the instance schema is published to its own public URI, set this keyword to that URI.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the properties that DSC can retrieve and manage for the resource's instances. This keyword must define at least one property as a key-value pair. The key is the property's name. The value is a subschema that validates the property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "additionalProperties": {}, + "properties": { + "_exist": { + "title": "Standard Property: _exist", + "description": "Indicates that the DSC Resource uses the standard `_exist` property to specify whether an instance should exist as a boolean value that defaults to `true`.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "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/2024/04/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "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/2024/04/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + }, + "examples": [ + { + "command": { + "executable": "registry", + "args": [ + "schema" + ] + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ] +} diff --git a/schemas/2024/04/resource/manifest.set.json b/schemas/2024/04/resource/manifest.set.json new file mode 100644 index 000000000..8710848fb --- /dev/null +++ b/schemas/2024/04/resource/manifest.set.json @@ -0,0 +1,44 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json", + "title": "Set Method", + "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + }, + "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 + }, + "return": { + "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "implementsPretest": true, + "return": "state" + } + ] +} diff --git a/schemas/2024/04/resource/manifest.test.json b/schemas/2024/04/resource/manifest.test.json new file mode 100644 index 000000000..1426f44e4 --- /dev/null +++ b/schemas/2024/04/resource/manifest.test.json @@ -0,0 +1,38 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json", + "title": "Test Method", + "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + }, + "return": { + "title": "Test Command Return Type", + "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] +} diff --git a/schemas/2024/04/resource/manifest.validate.json b/schemas/2024/04/resource/manifest.validate.json new file mode 100644 index 000000000..ebb64e3d4 --- /dev/null +++ b/schemas/2024/04/resource/manifest.validate.json @@ -0,0 +1,27 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json", + "title": "Validate Method", + "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + }, + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] +} diff --git a/schemas/2024/04/resource/properties/exist.json b/schemas/2024/04/resource/properties/exist.json new file mode 100644 index 000000000..b2e4835e9 --- /dev/null +++ b/schemas/2024/04/resource/properties/exist.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json", + "title": "Instance should exist", + "description": "Indicates whether the DSC Resource instance should exist.", + "type": "boolean", + "default": true, + "enum": [ + false, + true + ] +} diff --git a/schemas/2024/04/resource/properties/inDesiredState.json b/schemas/2024/04/resource/properties/inDesiredState.json new file mode 100644 index 000000000..5b922e716 --- /dev/null +++ b/schemas/2024/04/resource/properties/inDesiredState.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/inDesiredState.json", + "title": "Instance is in the Desired State", + "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", + "type": [ + "boolean", + "null" + ], + "readOnly": true +} diff --git a/schemas/2024/04/resource/properties/purge.json b/schemas/2024/04/resource/properties/purge.json new file mode 100644 index 000000000..dcd4c505d --- /dev/null +++ b/schemas/2024/04/resource/properties/purge.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json", + "title": "Purge", + "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", + "type": [ + "boolean", + "null" + ], + "writeOnly": true +} diff --git a/schemas/2024/04/resource/properties/rebootRequested.json b/schemas/2024/04/resource/properties/rebootRequested.json new file mode 100644 index 000000000..063f44f4f --- /dev/null +++ b/schemas/2024/04/resource/properties/rebootRequested.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/rebootRequested.json", + "title": "Reboot Requested", + "description": "Indicates that the set operation requires a reboot before it's fully complete.", + "type": [ + "boolean", + "null" + ], + "readOnly": true +} From da0019768f2f8f4cce0d731cbcb35be0c07ac52b Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Wed, 10 Apr 2024 15:18:51 -0500 Subject: [PATCH 03/15] (SCHEMA) Update examples, manifests, and tests for latest schema URI This change updates the existing tests, example configuration documents, and resource manifests to use the latest canonical schema URIs that are compatible with `preview.7`. --- dsc/assertion.dsc.resource.json | 2 +- dsc/examples/assertion.dsc.yaml | 4 +-- dsc/examples/brew.dsc.yaml | 4 +-- dsc/examples/brew_export.dsc.yaml | 2 +- dsc/examples/brew_uninstall.dsc.yaml | 4 +-- dsc/examples/groups.dsc.yaml | 8 +++--- dsc/examples/invalid_schema.dsc.yaml | 2 +- dsc/examples/osinfo.dsc.json | 2 +- dsc/examples/osinfo_parameters.dsc.yaml | 2 +- dsc/examples/osinfo_registry.dsc.json | 2 +- dsc/examples/osinfo_registry.dsc.yaml | 2 +- dsc/examples/parallel.dsc.yaml | 2 +- dsc/examples/powershell.dsc.yaml | 2 +- dsc/examples/reference.dsc.yaml | 2 +- dsc/examples/require_admin.yaml | 2 +- dsc/examples/require_nonadmin.yaml | 2 +- dsc/examples/secure_parameters.dsc.yaml | 2 +- dsc/group.dsc.resource.json | 2 +- dsc/parallel.dsc.resource.json | 2 +- dsc/tests/dsc_args.tests.ps1 | 6 ++--- dsc/tests/dsc_config_get.tests.ps1 | 2 +- dsc/tests/dsc_config_set.tests.ps1 | 2 +- dsc/tests/dsc_discovery.tests.ps1 | 8 +++--- dsc/tests/dsc_export.tests.ps1 | 16 ++++++------ dsc/tests/dsc_functions.tests.ps1 | 2 +- dsc/tests/dsc_parameters.tests.ps1 | 20 +++++++-------- dsc/tests/dsc_resource_input.tests.ps1 | 2 +- dsc/tests/dsc_set.tests.ps1 | 2 +- dsc_lib/src/configure/depends_on.rs | 16 ++++++------ dsc_lib/src/dscresources/resource_manifest.rs | 2 +- osinfo/osinfo.dsc.resource.json | 2 +- osinfo/tests/osinfo.tests.ps1 | 2 +- .../Tests/class_ps_resources.dsc.yaml | 2 +- .../Tests/native_and_powershell.dsc.yaml | 2 +- .../Tests/powershellgroup.config.tests.ps1 | 12 ++++----- .../Tests/winps_resource.dsc.yaml | 2 +- .../powershell.dsc.resource.json | 2 +- process/ExportTest.dsc.yaml | 2 +- process/process.dsc.resource.json | 2 +- .../reboot_pending.dsc.resource.json | 2 +- registry/registry.dsc.resource.json | 2 +- registry/tests/registry.config.set.tests.ps1 | 2 +- resources/brew/brew.dsc.resource.json | 2 +- .../RunCommandOnSet.dsc.resource.json | 2 +- schemas/src/resource/manifest.yaml | 25 +++++++++++++++++++ tools/dsctest/dscdelete.dsc.resource.json | 2 +- tools/dsctest/dscecho.dsc.resource.json | 2 +- tools/dsctest/dscexist.dsc.resource.json | 2 +- tools/dsctest/dscsleep.dsc.resource.json | 2 +- .../testGroup.dsc.resource.json | 2 +- .../tests/provider.tests.ps1 | 2 +- wmi-adapter/Tests/test_wmi_config.dsc.yaml | 2 +- wmi-adapter/wmi.dsc.resource.json | 2 +- 53 files changed, 116 insertions(+), 91 deletions(-) diff --git a/dsc/assertion.dsc.resource.json b/dsc/assertion.dsc.resource.json index 4aa67db47..b567bad2f 100644 --- a/dsc/assertion.dsc.resource.json +++ b/dsc/assertion.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Microsoft.DSC/Assertion", "version": "0.1.0", "description": "`test` will be invoked for all resources in the supplied configuration.", diff --git a/dsc/examples/assertion.dsc.yaml b/dsc/examples/assertion.dsc.yaml index 0f50de322..a746bcb33 100644 --- a/dsc/examples/assertion.dsc.yaml +++ b/dsc/examples/assertion.dsc.yaml @@ -1,5 +1,5 @@ # Example configuration that uses assertions to validate the environment before running the configuration. -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: current user registry type: Microsoft.Windows/Registry @@ -11,7 +11,7 @@ resources: - name: my assertions type: Microsoft.DSC/Assertion properties: - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os type: Microsoft/OSInfo diff --git a/dsc/examples/brew.dsc.yaml b/dsc/examples/brew.dsc.yaml index 6d5db1ded..654f9bb40 100644 --- a/dsc/examples/brew.dsc.yaml +++ b/dsc/examples/brew.dsc.yaml @@ -1,10 +1,10 @@ # Example to see if PowerShell 7 is installed, install it, or get all installed packages -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: assertions type: Microsoft.DSC/Assertion properties: - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os_check type: Microsoft/OSInfo diff --git a/dsc/examples/brew_export.dsc.yaml b/dsc/examples/brew_export.dsc.yaml index 1181c85dc..b652affc8 100644 --- a/dsc/examples/brew_export.dsc.yaml +++ b/dsc/examples/brew_export.dsc.yaml @@ -1,5 +1,5 @@ # Example to see if PowerShell 7 is installed, install it, or get all installed packages -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: brew type: DSC.PackageManagement/Brew diff --git a/dsc/examples/brew_uninstall.dsc.yaml b/dsc/examples/brew_uninstall.dsc.yaml index 86f9f6e16..d37e6b1c5 100644 --- a/dsc/examples/brew_uninstall.dsc.yaml +++ b/dsc/examples/brew_uninstall.dsc.yaml @@ -1,10 +1,10 @@ # Example to see if PowerShell 7 is installed, install it, or get all installed packages -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: assertions type: Microsoft.DSC/Assertion properties: - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os_check type: Microsoft/OSInfo diff --git a/dsc/examples/groups.dsc.yaml b/dsc/examples/groups.dsc.yaml index 7955080ab..f755e449b 100644 --- a/dsc/examples/groups.dsc.yaml +++ b/dsc/examples/groups.dsc.yaml @@ -1,5 +1,5 @@ # Example for grouping and groups in groups -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json metadata: Microsoft.DSC: requiredSecurityContext: Current # this is the default and just used as an example indicating this config works for admins and non-admins @@ -7,7 +7,7 @@ resources: - name: Last Group type: Microsoft.DSC/Group properties: - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Last type: Test/Echo @@ -18,7 +18,7 @@ resources: - name: First Group type: Microsoft.DSC/Group properties: - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: First type: Test/Echo @@ -27,7 +27,7 @@ resources: - name: Nested Group type: Microsoft.DSC/Group properties: - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Nested Second type: Test/Echo diff --git a/dsc/examples/invalid_schema.dsc.yaml b/dsc/examples/invalid_schema.dsc.yaml index dbb6789cc..566a96efa 100644 --- a/dsc/examples/invalid_schema.dsc.yaml +++ b/dsc/examples/invalid_schema.dsc.yaml @@ -1,5 +1,5 @@ # Sample configuration with invalid properties that don't match the resource schema. -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os type: Microsoft/OSInfo diff --git a/dsc/examples/osinfo.dsc.json b/dsc/examples/osinfo.dsc.json index 541349814..b0ae4d6f2 100644 --- a/dsc/examples/osinfo.dsc.json +++ b/dsc/examples/osinfo.dsc.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json", "resources": [ { "name": "os", diff --git a/dsc/examples/osinfo_parameters.dsc.yaml b/dsc/examples/osinfo_parameters.dsc.yaml index 17fe9aab8..a5bb49fc1 100644 --- a/dsc/examples/osinfo_parameters.dsc.yaml +++ b/dsc/examples/osinfo_parameters.dsc.yaml @@ -1,4 +1,4 @@ -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: osFamily: type: string diff --git a/dsc/examples/osinfo_registry.dsc.json b/dsc/examples/osinfo_registry.dsc.json index f31031979..5c2faa2b2 100644 --- a/dsc/examples/osinfo_registry.dsc.json +++ b/dsc/examples/osinfo_registry.dsc.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json", "metadata": { "description": "Simple example using two different resources and one of them twice." }, diff --git a/dsc/examples/osinfo_registry.dsc.yaml b/dsc/examples/osinfo_registry.dsc.yaml index 612e8c967..a1698564a 100644 --- a/dsc/examples/osinfo_registry.dsc.yaml +++ b/dsc/examples/osinfo_registry.dsc.yaml @@ -1,5 +1,5 @@ # Simple example using two different resources and one of them twice. -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os type: Microsoft/OSInfo diff --git a/dsc/examples/parallel.dsc.yaml b/dsc/examples/parallel.dsc.yaml index 332f5e5b9..f9be63db4 100644 --- a/dsc/examples/parallel.dsc.yaml +++ b/dsc/examples/parallel.dsc.yaml @@ -1,5 +1,5 @@ # Example on how concurrency would be defined in the configuration. -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json metadata: _timeoutSeconds: 600 # example of setting timeout for orchestration, should be namespaced? resources: diff --git a/dsc/examples/powershell.dsc.yaml b/dsc/examples/powershell.dsc.yaml index 12483d2c2..ddce88d4f 100644 --- a/dsc/examples/powershell.dsc.yaml +++ b/dsc/examples/powershell.dsc.yaml @@ -1,5 +1,5 @@ # Example configuration mixing native app resources with classic PS resources -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Use class PowerShell resources type: Microsoft.DSC/PowerShell diff --git a/dsc/examples/reference.dsc.yaml b/dsc/examples/reference.dsc.yaml index aa5977f01..6591adba3 100644 --- a/dsc/examples/reference.dsc.yaml +++ b/dsc/examples/reference.dsc.yaml @@ -1,5 +1,5 @@ # Simple example showing how to reference output from a resource to use in another -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os type: Microsoft/OSInfo diff --git a/dsc/examples/require_admin.yaml b/dsc/examples/require_admin.yaml index 90afa5b8b..6927a4d77 100644 --- a/dsc/examples/require_admin.yaml +++ b/dsc/examples/require_admin.yaml @@ -1,7 +1,7 @@ # example showing use of specific metadata to indicate this config requires admin to run # note that the resource doesn't require admin, but this will fail to even try to run the # config if the user is not root or elevated as administrator -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json metadata: Microsoft.DSC: securityContext: Elevated diff --git a/dsc/examples/require_nonadmin.yaml b/dsc/examples/require_nonadmin.yaml index cf3f0e058..5bb9a5f54 100644 --- a/dsc/examples/require_nonadmin.yaml +++ b/dsc/examples/require_nonadmin.yaml @@ -1,6 +1,6 @@ # example showing use of specific metadata to indicate this config requires admin to run # this will fail to even try to run the config if the user is root or elevated as administrator -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json metadata: Microsoft.DSC: securityContext: Restricted diff --git a/dsc/examples/secure_parameters.dsc.yaml b/dsc/examples/secure_parameters.dsc.yaml index 061238837..b88e68031 100644 --- a/dsc/examples/secure_parameters.dsc.yaml +++ b/dsc/examples/secure_parameters.dsc.yaml @@ -1,4 +1,4 @@ -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: myString: type: secureString diff --git a/dsc/group.dsc.resource.json b/dsc/group.dsc.resource.json index 8eccaa9a6..b71923b85 100644 --- a/dsc/group.dsc.resource.json +++ b/dsc/group.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Microsoft.DSC/Group", "version": "0.1.0", "description": "All resources in the supplied configuration is treated as a group.", diff --git a/dsc/parallel.dsc.resource.json b/dsc/parallel.dsc.resource.json index 79f081aa8..d3de7f616 100644 --- a/dsc/parallel.dsc.resource.json +++ b/dsc/parallel.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Microsoft.DSC/Parallel", "version": "0.1.0", "description": "All resources in the supplied configuration run concurrently.", diff --git a/dsc/tests/dsc_args.tests.ps1 b/dsc/tests/dsc_args.tests.ps1 index 6a7e48aee..2135d0442 100644 --- a/dsc/tests/dsc_args.tests.ps1 +++ b/dsc/tests/dsc_args.tests.ps1 @@ -5,7 +5,7 @@ Describe 'config argument tests' { BeforeAll { $manifest = @' { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Test/Hello", "version": "0.1.0", "get": { @@ -107,7 +107,7 @@ actualState: param($parameter) $yaml = @' -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os type: Microsoft/OSInfo @@ -127,7 +127,7 @@ resources: param($parameter) $yaml = @' -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os type: Microsoft/OSInfo diff --git a/dsc/tests/dsc_config_get.tests.ps1 b/dsc/tests/dsc_config_get.tests.ps1 index 381e4cf7f..ea9f25baf 100644 --- a/dsc/tests/dsc_config_get.tests.ps1 +++ b/dsc/tests/dsc_config_get.tests.ps1 @@ -34,7 +34,7 @@ Describe 'dsc config get tests' { It 'can accept the use of --format as a subcommand' { $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo type: Test/Echo diff --git a/dsc/tests/dsc_config_set.tests.ps1 b/dsc/tests/dsc_config_set.tests.ps1 index b740a09f7..d749a694b 100644 --- a/dsc/tests/dsc_config_set.tests.ps1 +++ b/dsc/tests/dsc_config_set.tests.ps1 @@ -4,7 +4,7 @@ Describe 'dsc config set tests' { It 'can use _exist with resources that support and do not support it' { $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Exist type: Test/Exist diff --git a/dsc/tests/dsc_discovery.tests.ps1 b/dsc/tests/dsc_discovery.tests.ps1 index b95cd7436..e941540f0 100644 --- a/dsc/tests/dsc_discovery.tests.ps1 +++ b/dsc/tests/dsc_discovery.tests.ps1 @@ -17,7 +17,7 @@ Describe 'tests for resource discovery' { It 'Use DSC_RESOURCE_PATH instead of PATH when defined' { $resourceJson = @' { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "DSC/TestPathResource", "version": "0.1.0", "get": { @@ -39,7 +39,7 @@ Describe 'tests for resource discovery' { param($extension) $resourceYaml = @' - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json type: DSC/TestYamlResource version: 0.1.0 get: @@ -56,7 +56,7 @@ Describe 'tests for resource discovery' { param($extension) $resourceInput = @' - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json type: DSC/TestYamlResource version: 0.1.0 get: @@ -71,7 +71,7 @@ Describe 'tests for resource discovery' { It 'warns on invalid semver' { $manifest = @' { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Test/InvalidSemver", "version": "1.1.0..1", "get": { diff --git a/dsc/tests/dsc_export.tests.ps1 b/dsc/tests/dsc_export.tests.ps1 index b837b11ba..b6ac78997 100644 --- a/dsc/tests/dsc_export.tests.ps1 +++ b/dsc/tests/dsc_export.tests.ps1 @@ -8,7 +8,7 @@ Describe 'resource export tests' { $out = dsc resource export -r Microsoft/Process $LASTEXITCODE | Should -Be 0 $config_with_process_list = $out | ConvertFrom-Json - $config_with_process_list.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json' + $config_with_process_list.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json' $config_with_process_list.'resources' | Should -Not -BeNullOrEmpty $config_with_process_list.resources.count | Should -BeGreaterThan 1 } @@ -25,7 +25,7 @@ Describe 'resource export tests' { It 'Export can be called on a configuration' { $yaml = @' - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Processes type: Microsoft/Process @@ -35,7 +35,7 @@ Describe 'resource export tests' { $out = $yaml | dsc config export $LASTEXITCODE | Should -Be 0 $config_with_process_list = $out | ConvertFrom-Json - $config_with_process_list.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json' + $config_with_process_list.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json' $config_with_process_list.'resources' | Should -Not -BeNullOrEmpty $config_with_process_list.resources.count | Should -BeGreaterThan 1 $config_with_process_list.metadata.'Microsoft.DSC'.operation | Should -BeExactly 'Export' @@ -44,7 +44,7 @@ Describe 'resource export tests' { It 'Configuration Export can be piped to configuration Set' -Skip:(!$IsWindows) { $yaml = @' - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Processes type: Microsoft/Process @@ -60,7 +60,7 @@ Describe 'resource export tests' { It 'Duplicate resource types in Configuration Export should not result in error' { $yaml = @' - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Processes type: Microsoft/Process @@ -80,7 +80,7 @@ Describe 'resource export tests' { $out = dsc resource export -r Microsoft/Process -f pretty-json $LASTEXITCODE | Should -Be 0 $config_with_process_list = $out | ConvertFrom-Json - $config_with_process_list.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json' + $config_with_process_list.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json' $config_with_process_list.'resources' | Should -Not -BeNullOrEmpty $config_with_process_list.resources.count | Should -BeGreaterThan 1 } @@ -88,7 +88,7 @@ Describe 'resource export tests' { It 'Export can be called on a configuration with the use of --format as a subcommand' { $yaml = @' - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Processes type: Microsoft/Process @@ -98,7 +98,7 @@ Describe 'resource export tests' { $out = $yaml | dsc config export -f pretty-json $LASTEXITCODE | Should -Be 0 $config_with_process_list = $out | ConvertFrom-Json - $config_with_process_list.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json' + $config_with_process_list.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json' $config_with_process_list.'resources' | Should -Not -BeNullOrEmpty $config_with_process_list.resources.count | Should -BeGreaterThan 1 } diff --git a/dsc/tests/dsc_functions.tests.ps1 b/dsc/tests/dsc_functions.tests.ps1 index a305575d8..c625b0081 100644 --- a/dsc/tests/dsc_functions.tests.ps1 +++ b/dsc/tests/dsc_functions.tests.ps1 @@ -14,7 +14,7 @@ Describe 'tests for function expressions' { $escapedText = $text -replace "'", "''" $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo type: Test/Echo diff --git a/dsc/tests/dsc_parameters.tests.ps1 b/dsc/tests/dsc_parameters.tests.ps1 index dd22be439..cd6586fc2 100644 --- a/dsc/tests/dsc_parameters.tests.ps1 +++ b/dsc/tests/dsc_parameters.tests.ps1 @@ -9,7 +9,7 @@ Describe 'Parameters tests' { param($inputType) $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: param1: type: string @@ -43,7 +43,7 @@ Describe 'Parameters tests' { param($type, $value) $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: param1: type: $type @@ -69,7 +69,7 @@ Describe 'Parameters tests' { param($type, $value) $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: param1: type: $type @@ -95,7 +95,7 @@ Describe 'Parameters tests' { param($type, $value) $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: param1: type: $type @@ -122,7 +122,7 @@ Describe 'Parameters tests' { param($type, $value, $min, $max) $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: param1: type: int @@ -148,7 +148,7 @@ Describe 'Parameters tests' { param($type, $value, $allowed) $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: param1: type: $type @@ -175,7 +175,7 @@ Describe 'Parameters tests' { param($type, $value, $constraint) $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: param1: type: $type @@ -195,7 +195,7 @@ Describe 'Parameters tests' { It 'Default value is used when not provided' { $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: paramString: type: string @@ -252,7 +252,7 @@ Describe 'Parameters tests' { } | ConvertTo-Json $config_yaml = @' - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: osFamily: type: string @@ -293,7 +293,7 @@ Describe 'Parameters tests' { param($type, $value) $config_yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: param: type: $type diff --git a/dsc/tests/dsc_resource_input.tests.ps1 b/dsc/tests/dsc_resource_input.tests.ps1 index 862b74414..b34d26ecc 100644 --- a/dsc/tests/dsc_resource_input.tests.ps1 +++ b/dsc/tests/dsc_resource_input.tests.ps1 @@ -5,7 +5,7 @@ Describe 'tests for resource input' { BeforeAll { $manifest = @' { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Test/EnvVarInput", "version": "0.1.0", "get": { diff --git a/dsc/tests/dsc_set.tests.ps1 b/dsc/tests/dsc_set.tests.ps1 index bffdf1950..0323cf4be 100644 --- a/dsc/tests/dsc_set.tests.ps1 +++ b/dsc/tests/dsc_set.tests.ps1 @@ -5,7 +5,7 @@ Describe 'resource set tests' { BeforeAll { $manifest = @' { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Test/SetNoTest", "version": "0.1.0", "get": { diff --git a/dsc_lib/src/configure/depends_on.rs b/dsc_lib/src/configure/depends_on.rs index ff34375d4..46a0f0d77 100644 --- a/dsc_lib/src/configure/depends_on.rs +++ b/dsc_lib/src/configure/depends_on.rs @@ -108,7 +108,7 @@ mod tests { #[test] fn test_simple_order() { let config_yaml: &str = r#" - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Second type: Test/Null @@ -128,7 +128,7 @@ mod tests { #[test] fn test_duplicate_name() { let config_yaml: &str = r#" - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: First type: Test/Null @@ -149,7 +149,7 @@ mod tests { #[test] fn test_missing_dependency() { let config_yaml: &str = r#" - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Second type: Test/Null @@ -166,7 +166,7 @@ mod tests { #[test] fn test_multiple_same_dependency() { let config_yaml: &str = r#" - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Second type: Test/Null @@ -191,7 +191,7 @@ mod tests { #[test] fn test_circular_dependency() { let config_yaml: &str = r#" - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Second type: Test/Null @@ -212,7 +212,7 @@ mod tests { #[test] fn test_multiple_dependencies() { let config_yaml: &str = r#" - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Third type: Test/Null @@ -236,7 +236,7 @@ mod tests { #[test] fn test_complex_circular_dependency() { let config_yaml: &str = r#" - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Third type: Test/Null @@ -262,7 +262,7 @@ mod tests { #[test] fn test_complex_dependency() { let config_yaml: &str = r#" - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Third type: Test/Null diff --git a/dsc_lib/src/dscresources/resource_manifest.rs b/dsc_lib/src/dscresources/resource_manifest.rs index 974a37000..e54b39449 100644 --- a/dsc_lib/src/dscresources/resource_manifest.rs +++ b/dsc_lib/src/dscresources/resource_manifest.rs @@ -256,7 +256,7 @@ pub struct ListMethod { /// * `DscError` - The JSON value is invalid or the schema version is not supported. pub fn import_manifest(manifest: Value) -> Result { // TODO: enable schema version validation, if not provided, use the latest - // const MANIFEST_SCHEMA_VERSION: &str = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json"; + // const MANIFEST_SCHEMA_VERSION: &str = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json"; let manifest = serde_json::from_value::(manifest)?; // if !manifest.schema_version.eq(MANIFEST_SCHEMA_VERSION) { // return Err(DscError::InvalidManifestSchemaVersion(manifest.schema_version, MANIFEST_SCHEMA_VERSION.to_string())); diff --git a/osinfo/osinfo.dsc.resource.json b/osinfo/osinfo.dsc.resource.json index d5de7917f..d4d8f57e3 100644 --- a/osinfo/osinfo.dsc.resource.json +++ b/osinfo/osinfo.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "description": "Returns information about the operating system.", "tags": [ "os", diff --git a/osinfo/tests/osinfo.tests.ps1 b/osinfo/tests/osinfo.tests.ps1 index 3148dffd0..8d75cc985 100644 --- a/osinfo/tests/osinfo.tests.ps1 +++ b/osinfo/tests/osinfo.tests.ps1 @@ -42,7 +42,7 @@ Describe 'osinfo resource tests' { It 'should support export' { $out = dsc resource export -r Microsoft/osinfo | ConvertFrom-Json - $out.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json' + $out.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json' if ($IsWindows) { $out.resources[0].properties.family | Should -BeExactly 'Windows' } diff --git a/powershell-adapter/Tests/class_ps_resources.dsc.yaml b/powershell-adapter/Tests/class_ps_resources.dsc.yaml index a6692b6ce..496845abf 100644 --- a/powershell-adapter/Tests/class_ps_resources.dsc.yaml +++ b/powershell-adapter/Tests/class_ps_resources.dsc.yaml @@ -1,7 +1,7 @@ # Copyright (c) Microsoft Corporation. # Licensed under the MIT License. -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Working with classic DSC resources type: Microsoft.DSC/PowerShell diff --git a/powershell-adapter/Tests/native_and_powershell.dsc.yaml b/powershell-adapter/Tests/native_and_powershell.dsc.yaml index 9c5664b58..c39b03c36 100644 --- a/powershell-adapter/Tests/native_and_powershell.dsc.yaml +++ b/powershell-adapter/Tests/native_and_powershell.dsc.yaml @@ -2,7 +2,7 @@ # Licensed under the MIT License. # Example configuration mixing native app resources with classic PS resources -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Get info from classic DSC resources type: Microsoft.DSC/PowerShell diff --git a/powershell-adapter/Tests/powershellgroup.config.tests.ps1 b/powershell-adapter/Tests/powershellgroup.config.tests.ps1 index 6ff9ac76b..e1c8d0960 100644 --- a/powershell-adapter/Tests/powershellgroup.config.tests.ps1 +++ b/powershell-adapter/Tests/powershellgroup.config.tests.ps1 @@ -59,7 +59,7 @@ Describe 'PowerShell adapter resource tests' { It 'Export works on config with class-based resources' -Skip:(!$IsWindows){ $yaml = @' - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Working with class-based resources type: Microsoft.DSC/PowerShell @@ -71,7 +71,7 @@ Describe 'PowerShell adapter resource tests' { $out = $yaml | dsc config export $LASTEXITCODE | Should -Be 0 $res = $out | ConvertFrom-Json - $res.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json' + $res.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json' $res.'resources' | Should -Not -BeNullOrEmpty $res.resources.count | Should -Be 5 $res.resources[0].properties.Name | Should -Be "Object1" @@ -88,7 +88,7 @@ Describe 'PowerShell adapter resource tests' { try { $yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Working with class-based resources type: Microsoft.DSC/PowerShell @@ -102,7 +102,7 @@ Describe 'PowerShell adapter resource tests' { $out = $yaml | dsc config export $LASTEXITCODE | Should -Be 0 $res = $out | ConvertFrom-Json - $res.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json' + $res.'$schema' | Should -BeExactly 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json' $res.'resources' | Should -Not -BeNullOrEmpty $res.resources.count | Should -Be 5 $res.resources[0].properties.Name | Should -Be "Object1" @@ -118,7 +118,7 @@ Describe 'PowerShell adapter resource tests' { It 'DSCConfigRoot macro is working when config is from a file' -Skip:(!$IsWindows){ $yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Working with class-based resources type: Microsoft.DSC/PowerShell @@ -143,7 +143,7 @@ Describe 'PowerShell adapter resource tests' { It 'DSC_CONFIG_ROOT env var does not exist when config is piped from stdin' -Skip:(!$IsWindows){ $yaml = @" - `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + `$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Working with class-based resources type: Microsoft.DSC/PowerShell diff --git a/powershell-adapter/Tests/winps_resource.dsc.yaml b/powershell-adapter/Tests/winps_resource.dsc.yaml index 8d123aa0f..aca685e1b 100644 --- a/powershell-adapter/Tests/winps_resource.dsc.yaml +++ b/powershell-adapter/Tests/winps_resource.dsc.yaml @@ -1,7 +1,7 @@ # Copyright (c) Microsoft Corporation. # Licensed under the MIT License. -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Get info from classic DSC resources type: Microsoft.Windows/WindowsPowerShell diff --git a/powershell-adapter/powershell.dsc.resource.json b/powershell-adapter/powershell.dsc.resource.json index 3691aa8f0..35d372b66 100644 --- a/powershell-adapter/powershell.dsc.resource.json +++ b/powershell-adapter/powershell.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Microsoft.DSC/PowerShell", "version": "0.1.0", "kind": "Adapter", diff --git a/process/ExportTest.dsc.yaml b/process/ExportTest.dsc.yaml index 9cbe88380..941b9500f 100644 --- a/process/ExportTest.dsc.yaml +++ b/process/ExportTest.dsc.yaml @@ -1,5 +1,5 @@ # Example configuration mixing native app resources with classic PS resources -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Processes type: Microsoft/Process diff --git a/process/process.dsc.resource.json b/process/process.dsc.resource.json index 88c70a2ee..cb1b26356 100644 --- a/process/process.dsc.resource.json +++ b/process/process.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "description": "Returns information about running processes.", "type": "Microsoft/Process", "version": "0.1.0", diff --git a/reboot_pending/reboot_pending.dsc.resource.json b/reboot_pending/reboot_pending.dsc.resource.json index d0448b829..3f474f14c 100644 --- a/reboot_pending/reboot_pending.dsc.resource.json +++ b/reboot_pending/reboot_pending.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "description": "Returns info about pending reboot.", "type": "Microsoft.Windows/RebootPending", "version": "0.1.0", diff --git a/registry/registry.dsc.resource.json b/registry/registry.dsc.resource.json index b989ba94a..40a19885d 100644 --- a/registry/registry.dsc.resource.json +++ b/registry/registry.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Microsoft.Windows/Registry", "description": "Manage Windows Registry keys and values", "tags": [ diff --git a/registry/tests/registry.config.set.tests.ps1 b/registry/tests/registry.config.set.tests.ps1 index 96716a9c4..3950c6cff 100644 --- a/registry/tests/registry.config.set.tests.ps1 +++ b/registry/tests/registry.config.set.tests.ps1 @@ -38,7 +38,7 @@ Describe 'registry config set tests' { It 'delete called when _exist is false' -Skip:(!$IsWindows) { $config = @{ - '$schema' = 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json' + '$schema' = 'https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json' resources = @( @{ name = 'reg' diff --git a/resources/brew/brew.dsc.resource.json b/resources/brew/brew.dsc.resource.json index bc4b2acbe..1ee493172 100644 --- a/resources/brew/brew.dsc.resource.json +++ b/resources/brew/brew.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "DSC.PackageManagement/Brew", "description": "DSC resource to manage Homebrew packages", "tags": [ diff --git a/runcommandonset/RunCommandOnSet.dsc.resource.json b/runcommandonset/RunCommandOnSet.dsc.resource.json index 17d2e9e13..5f60f3536 100644 --- a/runcommandonset/RunCommandOnSet.dsc.resource.json +++ b/runcommandonset/RunCommandOnSet.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "description": "Takes a single-command line to execute on DSC set operation", "type": "Microsoft.DSC.Transitional/RunCommandOnSet", "version": "0.1.0", diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index 6f63b6462..bf4256a0e 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -396,6 +396,31 @@ properties: Defines a short synopsis of the DSC Resource's purpose. [01]: /reference/schemas/resource/manifest/root?#description-1 + kind: + title: Resource kind + description: >- + Defines whether the resource is a normal DSC Resource, a group resource, or an adapter + resource. This property is only required for group resources. + markdownDescription: | # VS Code only + *** + [_Online Documentation_][01] + *** + + Defines whether the resource is a normal DSC Resource, a group resource, or an adapter + resource. This property is only required for group resources. + + DSC infers the default value for this property based on whether the [adapter][02] property is + defined in the manifest: + + - If the `adapter` property is defined in the manifest, the default `kind` is `Adapter`. + - If the `adapter` property is not defined in the manifest, the default `kind` is `Resource`. + + [01]: /reference/schemas/resource/manifest/root?#kind + type: string + enum: + - Resource + - Adapter + - Group tags: title: Tags description: >- diff --git a/tools/dsctest/dscdelete.dsc.resource.json b/tools/dsctest/dscdelete.dsc.resource.json index 317bc7c85..2a44a6571 100644 --- a/tools/dsctest/dscdelete.dsc.resource.json +++ b/tools/dsctest/dscdelete.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Test/Delete", "version": "0.1.0", "get": { diff --git a/tools/dsctest/dscecho.dsc.resource.json b/tools/dsctest/dscecho.dsc.resource.json index ae0069da7..e7b3d2014 100644 --- a/tools/dsctest/dscecho.dsc.resource.json +++ b/tools/dsctest/dscecho.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Test/Echo", "version": "0.1.0", "get": { diff --git a/tools/dsctest/dscexist.dsc.resource.json b/tools/dsctest/dscexist.dsc.resource.json index 50b0ac1e3..9ef80f2be 100644 --- a/tools/dsctest/dscexist.dsc.resource.json +++ b/tools/dsctest/dscexist.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Test/Exist", "version": "0.1.0", "get": { diff --git a/tools/dsctest/dscsleep.dsc.resource.json b/tools/dsctest/dscsleep.dsc.resource.json index bc5d61df9..d4f0f9758 100644 --- a/tools/dsctest/dscsleep.dsc.resource.json +++ b/tools/dsctest/dscsleep.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Test/Sleep", "version": "0.1.0", "get": { diff --git a/tools/test_group_resource/testGroup.dsc.resource.json b/tools/test_group_resource/testGroup.dsc.resource.json index a7f1fb138..91944e5d1 100644 --- a/tools/test_group_resource/testGroup.dsc.resource.json +++ b/tools/test_group_resource/testGroup.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Test/TestGroup", "kind": "Adapter", "version": "0.1.0", diff --git a/tools/test_group_resource/tests/provider.tests.ps1 b/tools/test_group_resource/tests/provider.tests.ps1 index 2b80e5b31..06dbffab1 100644 --- a/tools/test_group_resource/tests/provider.tests.ps1 +++ b/tools/test_group_resource/tests/provider.tests.ps1 @@ -22,7 +22,7 @@ Describe 'Resource adapter tests' { It 'Error if adapter resource is missing "requireAdapter" member' { $invalid_manifest = @' { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Test/InvalidTestGroup", "kind": "Adapter", "version": "0.1.0", diff --git a/wmi-adapter/Tests/test_wmi_config.dsc.yaml b/wmi-adapter/Tests/test_wmi_config.dsc.yaml index 2907c4c51..225c87f60 100644 --- a/wmi-adapter/Tests/test_wmi_config.dsc.yaml +++ b/wmi-adapter/Tests/test_wmi_config.dsc.yaml @@ -1,5 +1,5 @@ # Example configuration for reading data from Windows WMI -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Get info from WMI type: Microsoft.Windows/WMI diff --git a/wmi-adapter/wmi.dsc.resource.json b/wmi-adapter/wmi.dsc.resource.json index eac236be7..5b63c7d37 100644 --- a/wmi-adapter/wmi.dsc.resource.json +++ b/wmi-adapter/wmi.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", "type": "Microsoft.Windows/WMI", "version": "0.1.0", "kind": "Adapter", From 3c3d4a1817fcb93688004d025bb3ea21db15d602 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 12 Apr 2024 10:02:18 -0500 Subject: [PATCH 04/15] (SCHEMA) Add `kind` to resource manifest schema This change adds the `kind` property to the resource manifest schema, as implemented in #338. It updates the source schema and regenerates the composed schemas. --- .../04/bundled/outputs/resource/list.json | 18 +++++++ .../2024/04/bundled/resource/manifest.json | 15 ++++++ .../04/bundled/resource/manifest.vscode.json | 21 ++++++++ schemas/2024/04/definitions/resourceKind.json | 12 +++++ schemas/2024/04/outputs/resource/list.json | 3 ++ schemas/2024/04/resource/manifest.json | 3 ++ schemas/src/definitions/resourceKind.yaml | 48 +++++++++++++++++++ schemas/src/outputs/resource/list.yaml | 2 + schemas/src/resource/manifest.yaml | 25 +--------- 9 files changed, 123 insertions(+), 24 deletions(-) create mode 100644 schemas/2024/04/definitions/resourceKind.json create mode 100644 schemas/src/definitions/resourceKind.yaml diff --git a/schemas/2024/04/bundled/outputs/resource/list.json b/schemas/2024/04/bundled/outputs/resource/list.json index 9db58db06..a989274de 100644 --- a/schemas/2024/04/bundled/outputs/resource/list.json +++ b/schemas/2024/04/bundled/outputs/resource/list.json @@ -8,6 +8,9 @@ "type": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" }, + "kind": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json" + }, "version": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" }, @@ -97,6 +100,18 @@ "type": "string", "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json", + "title": "Resource kind", + "description": "Defines whether the resource is a normal DSC Resource, a group resource, or an adapter resource. This property is only required for group resources.", + "type": "string", + "enum": [ + "Resource", + "Adapter", + "Group" + ] + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json", @@ -149,6 +164,9 @@ "description": "A short synopsis of the DSC Resource's purpose.", "type": "string" }, + "kind": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json" + }, "tags": { "title": "Tags", "description": "Defines a list of searchable terms for the resource.", diff --git a/schemas/2024/04/bundled/resource/manifest.json b/schemas/2024/04/bundled/resource/manifest.json index e06b9cfe0..d6c7b7ed6 100644 --- a/schemas/2024/04/bundled/resource/manifest.json +++ b/schemas/2024/04/bundled/resource/manifest.json @@ -41,6 +41,9 @@ "description": "A short synopsis of the DSC Resource's purpose.", "type": "string" }, + "kind": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json" + }, "tags": { "title": "Tags", "description": "Defines a list of searchable terms for the resource.", @@ -118,6 +121,18 @@ "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/2024/04/definitions/resourceKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json", + "title": "Resource kind", + "description": "Defines whether the resource is a normal DSC Resource, a group resource, or an adapter resource. This property is only required for group resources.", + "type": "string", + "enum": [ + "Resource", + "Adapter", + "Group" + ] + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json", diff --git a/schemas/2024/04/bundled/resource/manifest.vscode.json b/schemas/2024/04/bundled/resource/manifest.vscode.json index 4c9e39c48..f6f353940 100644 --- a/schemas/2024/04/bundled/resource/manifest.vscode.json +++ b/schemas/2024/04/bundled/resource/manifest.vscode.json @@ -246,6 +246,9 @@ "type": "string", "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" }, + "kind": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json" + }, "tags": { "title": "Tags", "description": "Defines a list of searchable terms for the resource.", @@ -348,6 +351,24 @@ "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" }, + "resourceKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json", + "title": "Resource kind", + "description": "Defines whether the resource is a normal DSC Resource, a group resource, or an adapter resource. This property is only required for group resources.", + "type": "string", + "enum": [ + "Resource", + "Adapter", + "Group" + ], + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the resource is a normal DSC Resource, a group resource, or an adapter\nresource. This property is only required for group resources.\n\nDSC infers the default value for this property based on whether the [adapter][02] property is\ndefined in the manifest:\n\n- If the `adapter` property is defined in the manifest, the default `kind` is `Adapter`.\n- If the `adapter` property is not defined in the manifest, the default `kind` is `Resource`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#kind\n", + "markdownEnumDescriptions": [ + "\n\nIndicates that the manifest is for a standard command-based DSC Resource.\n", + "\n\nIndicates that the manifest is for an adapter resource that enables the use of\nnon-command-based resources with DSC.\n", + "\n\nIndicates that the manifest is for a group resource that processes an array of nested\nresource instances.\n" + ] + }, "commandExecutable.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json", diff --git a/schemas/2024/04/definitions/resourceKind.json b/schemas/2024/04/definitions/resourceKind.json new file mode 100644 index 000000000..0ec0e0ca4 --- /dev/null +++ b/schemas/2024/04/definitions/resourceKind.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json", + "title": "Resource kind", + "description": "Defines whether the resource is a normal DSC Resource, a group resource, or an adapter resource. This property is only required for group resources.", + "type": "string", + "enum": [ + "Resource", + "Adapter", + "Group" + ] +} diff --git a/schemas/2024/04/outputs/resource/list.json b/schemas/2024/04/outputs/resource/list.json index c5fea3d92..db86858a9 100644 --- a/schemas/2024/04/outputs/resource/list.json +++ b/schemas/2024/04/outputs/resource/list.json @@ -8,6 +8,9 @@ "type": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" }, + "kind": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json" + }, "version": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" }, diff --git a/schemas/2024/04/resource/manifest.json b/schemas/2024/04/resource/manifest.json index 5cbf72235..91a2c1858 100644 --- a/schemas/2024/04/resource/manifest.json +++ b/schemas/2024/04/resource/manifest.json @@ -41,6 +41,9 @@ "description": "A short synopsis of the DSC Resource's purpose.", "type": "string" }, + "kind": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json" + }, "tags": { "title": "Tags", "description": "Defines a list of searchable terms for the resource.", diff --git a/schemas/src/definitions/resourceKind.yaml b/schemas/src/definitions/resourceKind.yaml new file mode 100644 index 000000000..0de1645ba --- /dev/null +++ b/schemas/src/definitions/resourceKind.yaml @@ -0,0 +1,48 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/resourceKind.yaml + +title: Resource kind +description: >- + Defines whether the resource is a normal DSC Resource, a group resource, or an adapter + resource. This property is only required for group resources. + +type: string +enum: + - Resource + - Adapter + - Group + +# VS Code only + +markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines whether the resource is a normal DSC Resource, a group resource, or an adapter + resource. This property is only required for group resources. + + DSC infers the default value for this property based on whether the [adapter][02] property is + defined in the manifest: + + - If the `adapter` property is defined in the manifest, the default `kind` is `Adapter`. + - If the `adapter` property is not defined in the manifest, the default `kind` is `Resource`. + + [01]: /reference/schemas/resource/manifest/root?#kind + +markdownEnumDescriptions: + - | # Resource + + + Indicates that the manifest is for a standard command-based DSC Resource. + - | # Adapter + + + Indicates that the manifest is for an adapter resource that enables the use of + non-command-based resources with DSC. + - | # Group + + + Indicates that the manifest is for a group resource that processes an array of nested + resource instances. diff --git a/schemas/src/outputs/resource/list.yaml b/schemas/src/outputs/resource/list.yaml index 79ad6c073..77d1839cc 100644 --- a/schemas/src/outputs/resource/list.yaml +++ b/schemas/src/outputs/resource/list.yaml @@ -15,6 +15,8 @@ properties: # no prefix. Should we have a different schema for those, or should this # be relaxed? $ref: ///definitions/resourceType.yaml + kind: + $ref: ///definitions/resourceKind.yaml version: # Only the Test* resources seem to have this field populated. $ref: ///definitions/semver.yaml diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index bf4256a0e..30fdd9585 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -397,30 +397,7 @@ properties: [01]: /reference/schemas/resource/manifest/root?#description-1 kind: - title: Resource kind - description: >- - Defines whether the resource is a normal DSC Resource, a group resource, or an adapter - resource. This property is only required for group resources. - markdownDescription: | # VS Code only - *** - [_Online Documentation_][01] - *** - - Defines whether the resource is a normal DSC Resource, a group resource, or an adapter - resource. This property is only required for group resources. - - DSC infers the default value for this property based on whether the [adapter][02] property is - defined in the manifest: - - - If the `adapter` property is defined in the manifest, the default `kind` is `Adapter`. - - If the `adapter` property is not defined in the manifest, the default `kind` is `Resource`. - - [01]: /reference/schemas/resource/manifest/root?#kind - type: string - enum: - - Resource - - Adapter - - Group + $ref: ///definitions/resourceKind.yaml tags: title: Tags description: >- From 19b76de5c5651bbc013814d60a6abaa6a5a59433 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 12 Apr 2024 10:03:39 -0500 Subject: [PATCH 05/15] (SCHEMAS) Update examples to latest URI This change updates the example configuration document and resource manifests to use the `2024/04` URI instead of older versions. --- schemas/examples/foo.dsc.config.yaml | 6 +++++- schemas/examples/foo.dsc.resource.json | 2 +- schemas/examples/foo.dsc.resource.yaml | 4 ++-- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/schemas/examples/foo.dsc.config.yaml b/schemas/examples/foo.dsc.config.yaml index 636d2bb9d..fcca79bc6 100644 --- a/schemas/examples/foo.dsc.config.yaml +++ b/schemas/examples/foo.dsc.config.yaml @@ -1,4 +1,8 @@ -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +# For testing outside of the repository, set the schema in the yaml server directive to: +# https://raw.githubusercontent.com/PowerShell/DSC/main/2024/04/resource/manifest.json +# +# Hover on the keys to see the documentation. Try changing values and adding new settings. +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json # Try adding the variables, metadata, and parameters properties, # then use IntelliSense to define a few entries. diff --git a/schemas/examples/foo.dsc.resource.json b/schemas/examples/foo.dsc.resource.json index 72695c902..eac50d5a3 100644 --- a/schemas/examples/foo.dsc.resource.json +++ b/schemas/examples/foo.dsc.resource.json @@ -1,5 +1,5 @@ { - "$schema": "../2023/10/bundled/resource/manifest.vscode.json", + "$schema": "../2024/04/bundled/resource/manifest.vscode.json", "type": "Example/Resource", "description": "An example resource using the schema.", "version": "0.1.0", diff --git a/schemas/examples/foo.dsc.resource.yaml b/schemas/examples/foo.dsc.resource.yaml index 2dbb84e57..bce0a822c 100644 --- a/schemas/examples/foo.dsc.resource.yaml +++ b/schemas/examples/foo.dsc.resource.yaml @@ -1,8 +1,8 @@ # For testing outside of the repository, set the schema in the yaml server directive to: -# https://raw.githubusercontent.com/PowerShell/DSC/main/2023/08/resource/manifest.json +# https://raw.githubusercontent.com/PowerShell/DSC/main/2024/04/resource/manifest.json # # Hover on the keys to see the documentation. Try changing values and adding new settings. -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json type: Example/Foo version: 0.1.0 description: An example resource to manage the foo application. From 5f55dc9922e096b2a3a015ce1799f769dc9ae329 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 12 Apr 2024 10:11:20 -0500 Subject: [PATCH 06/15] (SCHEMA) Rename `requires` to `requireAdapter` in `list` output schema This change updates the output schema for the `dsc resource list` command to rename the `requires` property to the more semantically correct and unambiguous `requireAdapter` property, as implemented in #373. It updates both the source and composed schemas. --- schemas/2024/04/bundled/outputs/resource/list.json | 2 +- schemas/2024/04/outputs/resource/list.json | 2 +- schemas/src/outputs/resource/list.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/schemas/2024/04/bundled/outputs/resource/list.json b/schemas/2024/04/bundled/outputs/resource/list.json index a989274de..ae332eccd 100644 --- a/schemas/2024/04/bundled/outputs/resource/list.json +++ b/schemas/2024/04/bundled/outputs/resource/list.json @@ -75,7 +75,7 @@ "pattern": "^\\w+$" } }, - "requires": { + "requireAdapter": { "title": "Required DSC Resource Adapter", "description": "Defines the fully qualified type name of the DSC Resource Adapter the DSC Resource depends on.", "oneOf": [ diff --git a/schemas/2024/04/outputs/resource/list.json b/schemas/2024/04/outputs/resource/list.json index db86858a9..537420e24 100644 --- a/schemas/2024/04/outputs/resource/list.json +++ b/schemas/2024/04/outputs/resource/list.json @@ -75,7 +75,7 @@ "pattern": "^\\w+$" } }, - "requires": { + "requireAdapter": { "title": "Required DSC Resource Adapter", "description": "Defines the fully qualified type name of the DSC Resource Adapter the DSC Resource depends on.", "oneOf": [ diff --git a/schemas/src/outputs/resource/list.yaml b/schemas/src/outputs/resource/list.yaml index 77d1839cc..80686568a 100644 --- a/schemas/src/outputs/resource/list.yaml +++ b/schemas/src/outputs/resource/list.yaml @@ -83,7 +83,7 @@ properties: items: type: string pattern: ^\w+$ - requires: + requireAdapter: title: Required DSC Resource Adapter description: >- Defines the fully qualified type name of the DSC Resource Adapter the From f728010471e7dbb419d823e6bc2b38a625c64e2f Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 12 Apr 2024 10:17:22 -0500 Subject: [PATCH 07/15] (SCHEMA) Update casing for `secureString` and `secureObject` This change updates the casing for the secure parameter types from `securestring` and `secureobject` to `secureString` and `secureObject`, as implemented in #364. It updates both the source and composed schemas. --- schemas/2024/04/bundled/config/document.json | 14 ++++++------- .../04/bundled/config/document.vscode.json | 20 +++++++++---------- .../2024/04/config/document.parameter.json | 10 +++++----- .../04/definitions/parameters/dataTypes.json | 4 ++-- schemas/src/config/document.parameter.yaml | 14 ++++++------- .../src/definitions/parameters/dataTypes.yaml | 12 +++++------ 6 files changed, 37 insertions(+), 37 deletions(-) diff --git a/schemas/2024/04/bundled/config/document.json b/schemas/2024/04/bundled/config/document.json index befd46db2..cde4f9cb4 100644 --- a/schemas/2024/04/bundled/config/document.json +++ b/schemas/2024/04/bundled/config/document.json @@ -129,7 +129,7 @@ { "properties": { "type": { - "const": "securestring" + "const": "secureString" } } }, @@ -146,13 +146,13 @@ "properties": { "minLength": { "title": "Minimum length", - "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "description": "The minimum valid length for a `string`, `secureString`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", "type": "integer", "minimum": 0 }, "maxLength": { "title": "Maximum length", - "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "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 } @@ -172,7 +172,7 @@ { "properties": { "type": { - "const": "securestring" + "const": "secureString" } } } @@ -204,7 +204,7 @@ { "properties": { "type": { - "const": "secureobject" + "const": "secureObject" } } } @@ -325,11 +325,11 @@ "type": "string", "enum": [ "string", - "securestring", + "secureString", "int", "bool", "object", - "secureobject", + "secureObject", "array" ] }, diff --git a/schemas/2024/04/bundled/config/document.vscode.json b/schemas/2024/04/bundled/config/document.vscode.json index 000d3870d..a7e9e71f4 100644 --- a/schemas/2024/04/bundled/config/document.vscode.json +++ b/schemas/2024/04/bundled/config/document.vscode.json @@ -273,7 +273,7 @@ { "properties": { "type": { - "const": "securestring" + "const": "secureString" } } }, @@ -290,17 +290,17 @@ "properties": { "minLength": { "title": "Minimum length", - "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "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": "***\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" + "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`.", + "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": "***\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" + "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" } } } @@ -318,7 +318,7 @@ { "properties": { "type": { - "const": "securestring" + "const": "secureString" } } } @@ -350,7 +350,7 @@ { "properties": { "type": { - "const": "secureobject" + "const": "secureObject" } } } @@ -512,14 +512,14 @@ "type": "string", "enum": [ "string", - "securestring", + "secureString", "int", "bool", "object", - "secureobject", + "secureObject", "array" ], - "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", + "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": [ "_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", diff --git a/schemas/2024/04/config/document.parameter.json b/schemas/2024/04/config/document.parameter.json index 642a36cf3..88fb61e97 100644 --- a/schemas/2024/04/config/document.parameter.json +++ b/schemas/2024/04/config/document.parameter.json @@ -72,7 +72,7 @@ { "properties": { "type": { - "const": "securestring" + "const": "secureString" } } }, @@ -89,13 +89,13 @@ "properties": { "minLength": { "title": "Minimum length", - "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "description": "The minimum valid length for a `string`, `secureString`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", "type": "integer", "minimum": 0 }, "maxLength": { "title": "Maximum length", - "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "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 } @@ -115,7 +115,7 @@ { "properties": { "type": { - "const": "securestring" + "const": "secureString" } } } @@ -147,7 +147,7 @@ { "properties": { "type": { - "const": "secureobject" + "const": "secureObject" } } } diff --git a/schemas/2024/04/definitions/parameters/dataTypes.json b/schemas/2024/04/definitions/parameters/dataTypes.json index 07143abbd..beaaa71d8 100644 --- a/schemas/2024/04/definitions/parameters/dataTypes.json +++ b/schemas/2024/04/definitions/parameters/dataTypes.json @@ -6,11 +6,11 @@ "type": "string", "enum": [ "string", - "securestring", + "secureString", "int", "bool", "object", - "secureobject", + "secureObject", "array" ] } diff --git a/schemas/src/config/document.parameter.yaml b/schemas/src/config/document.parameter.yaml index 2162e0553..f543cfb56 100644 --- a/schemas/src/config/document.parameter.yaml +++ b/schemas/src/config/document.parameter.yaml @@ -165,14 +165,14 @@ allOf: - if: oneOf: - properties: { type: { const: string } } - - properties: { type: { const: securestring } } + - properties: { type: { const: secureString } } - properties: { type: { const: array } } then: properties: minLength: title: Minimum length description: >- - The minimum valid length for a `string`, `securestring`, or `array`. If defined with + The 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 @@ -182,14 +182,14 @@ allOf: [_Online Documentation_][01] *** - The minimum valid length for a `string`, `securestring`, or `array`. If defined with + 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]: /reference/schemas/config/parameter?#minLength maxLength: title: Maximum length description: >- - The maximum valid length for a `string`, `securestring`, or `array`. If defined with + 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 @@ -199,7 +199,7 @@ allOf: [_Online Documentation_][01] *** - The maximum valid length for a `string`, `securestring`, or `array`. If defined with + 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]: /reference/schemas/config/parameter?#maxLength @@ -207,7 +207,7 @@ allOf: - if: oneOf: - properties: { type: { const: string } } - - properties: { type: { const: securestring } } + - properties: { type: { const: secureString } } then: properties: defaultValue: { type: string } @@ -215,7 +215,7 @@ allOf: - if: oneOf: - properties: { type: { const: object } } - - properties: { type: { const: secureobject } } + - properties: { type: { const: secureObject } } then: properties: defaultValue: { type: object } diff --git a/schemas/src/definitions/parameters/dataTypes.yaml b/schemas/src/definitions/parameters/dataTypes.yaml index e73b1eab2..da25c9573 100644 --- a/schemas/src/definitions/parameters/dataTypes.yaml +++ b/schemas/src/definitions/parameters/dataTypes.yaml @@ -8,11 +8,11 @@ description: >- type: string enum: - string - - securestring + - secureString - int - bool - object - - secureobject + - secureObject - array # VS Code only @@ -30,8 +30,8 @@ markdownDescription: | - `int` for integers - `object` for objects - `string` for strings - - `secureobject` for secure objects - - `securestring` for secure strings + - `secureObject` for secure objects + - `secureString` for secure strings Access parameters in a configuration using this syntax: @@ -56,7 +56,7 @@ markdownEnumDescriptions: [01]: /reference/schemas/definitions/parameters/datatypes?#strings - - | # securestring + - | # secureString _Secure strings are text that needs to be handled securely._ > Secure strings are an arbitrary set of text that DSC and integrating tools shouldn't log or @@ -105,7 +105,7 @@ markdownEnumDescriptions: [01]: /reference/schemas/definitions/parameters/datatypes?#objects - - | # secureobject + - | # secureObject _Secure objects are key-value pairs that need to be handled securely._ > Secure objects define a set of key-value pairs that DSC and integrating tools shouldn't log From ca4e0ee06d63cec1e21d5a4691f4969585e77865 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 12 Apr 2024 10:44:21 -0500 Subject: [PATCH 08/15] (SCHEMA) Add capabilities to `list` output schema This change adds the `capabilities` property to the output schema for the `dsc resource list` command, as implemented in #357. It updates both the source and composed schemas. --- .../2024/04/bundled/outputs/resource/list.json | 14 ++++++++++++++ schemas/2024/04/outputs/resource/list.json | 14 ++++++++++++++ schemas/src/outputs/resource/list.yaml | 15 +++++++++++++++ 3 files changed, 43 insertions(+) diff --git a/schemas/2024/04/bundled/outputs/resource/list.json b/schemas/2024/04/bundled/outputs/resource/list.json index ae332eccd..77d04d1c7 100644 --- a/schemas/2024/04/bundled/outputs/resource/list.json +++ b/schemas/2024/04/bundled/outputs/resource/list.json @@ -14,6 +14,20 @@ "version": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" }, + "capabilities": { + "title": "Resource capabilities", + "description": "Defines the list of DSC operations the resource is compatible with. If the resource doesn't list a given operation, like `Set` or `Export`, the resource can't be used for those operations. The exception to this is `Test` - DSC uses synthetic testing for resources that don't have the `Test` capability.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "Get", + "Set", + "Test", + "Export" + ] + } + }, "description": { "title": "Resource Description", "description": "A short synopsis of the DSC Resource's purpose.", diff --git a/schemas/2024/04/outputs/resource/list.json b/schemas/2024/04/outputs/resource/list.json index 537420e24..abb0405fd 100644 --- a/schemas/2024/04/outputs/resource/list.json +++ b/schemas/2024/04/outputs/resource/list.json @@ -14,6 +14,20 @@ "version": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" }, + "capabilities": { + "title": "Resource capabilities", + "description": "Defines the list of DSC operations the resource is compatible with. If the resource doesn't list a given operation, like `Set` or `Export`, the resource can't be used for those operations. The exception to this is `Test` - DSC uses synthetic testing for resources that don't have the `Test` capability.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "Get", + "Set", + "Test", + "Export" + ] + } + }, "description": { "title": "Resource Description", "description": "A short synopsis of the DSC Resource's purpose.", diff --git a/schemas/src/outputs/resource/list.yaml b/schemas/src/outputs/resource/list.yaml index 80686568a..4d9c70ddc 100644 --- a/schemas/src/outputs/resource/list.yaml +++ b/schemas/src/outputs/resource/list.yaml @@ -20,6 +20,21 @@ properties: version: # Only the Test* resources seem to have this field populated. $ref: ///definitions/semver.yaml + capabilities: + title: Resource capabilities + description: >- + Defines the list of DSC operations the resource is compatible with. If the resource doesn't + list a given operation, like `Set` or `Export`, the resource can't be used for those + operations. The exception to this is `Test` - DSC uses synthetic testing for resources that + don't have the `Test` capability. + type: array + items: + type: string + enum: + - Get + - Set + - Test + - Export description: title: Resource Description description: >- From 2d14880a1251ccda73dedf0f8eccbb3e91911b60 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 12 Apr 2024 11:21:22 -0500 Subject: [PATCH 09/15] (SCHEMA) Add `delete` method and related capabilities to schemas This change adds the `delete` method-defining property to the resource manifest schema and updates the `capabilities` enumeration to include `SetHandlesExist` and `Delete`, as implemented in #379. It updates both the source and composed schemas. --- .../04/bundled/outputs/resource/list.json | 89 +++++++--- .../2024/04/bundled/resource/manifest.json | 87 +++++++--- .../04/bundled/resource/manifest.vscode.json | 157 +++++++++++++----- schemas/2024/04/outputs/resource/list.json | 2 + schemas/2024/04/resource/manifest.delete.json | 36 ++++ schemas/2024/04/resource/manifest.json | 9 +- schemas/2024/04/resource/manifest.set.json | 6 + schemas/src/outputs/resource/list.yaml | 2 + schemas/src/resource/manifest.delete.yaml | 109 ++++++++++++ schemas/src/resource/manifest.set.yaml | 20 +++ schemas/src/resource/manifest.yaml | 6 +- 11 files changed, 433 insertions(+), 90 deletions(-) create mode 100644 schemas/2024/04/resource/manifest.delete.json create mode 100644 schemas/src/resource/manifest.delete.yaml diff --git a/schemas/2024/04/bundled/outputs/resource/list.json b/schemas/2024/04/bundled/outputs/resource/list.json index 77d04d1c7..edcf8da8b 100644 --- a/schemas/2024/04/bundled/outputs/resource/list.json +++ b/schemas/2024/04/bundled/outputs/resource/list.json @@ -23,7 +23,9 @@ "enum": [ "Get", "Set", + "SetHandlesExist", "Test", + "Delete", "Export" ] } @@ -194,15 +196,18 @@ "get": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json" }, - "export": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" - }, "set": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json" }, "test": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json" }, + "delete": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json" + }, + "export": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" + }, "validate": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json" }, @@ -275,24 +280,6 @@ } ] }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", - "title": "Get Method", - "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" - } - } - }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json", @@ -319,6 +306,12 @@ "type": "boolean", "default": false }, + "handlesExist": { + "title": "Resource handles _exist property", + "description": "Defines whether the DSC Resource has its own built-in handling for the `_exist` common property. Set this value to `true` if the DSC Resource handles instance deletion internally when receiving a `set` command where the instance defines the `_exist` property as `false`.", + "type": "boolean", + "default": false + }, "return": { "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" @@ -375,6 +368,60 @@ } ] }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json", + "title": "Delete method", + "description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "delete", + "--input", + "{json}" + ], + "input": { + "arg": "{json}" + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json", diff --git a/schemas/2024/04/bundled/resource/manifest.json b/schemas/2024/04/bundled/resource/manifest.json index d6c7b7ed6..01e26c9d1 100644 --- a/schemas/2024/04/bundled/resource/manifest.json +++ b/schemas/2024/04/bundled/resource/manifest.json @@ -57,15 +57,18 @@ "get": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json" }, - "export": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" - }, "set": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json" }, "test": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json" }, + "delete": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json" + }, + "export": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" + }, "validate": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json" }, @@ -167,24 +170,6 @@ } ] }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", - "title": "Get Method", - "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" - } - } - }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json", @@ -211,6 +196,12 @@ "type": "boolean", "default": false }, + "handlesExist": { + "title": "Resource handles _exist property", + "description": "Defines whether the DSC Resource has its own built-in handling for the `_exist` common property. Set this value to `true` if the DSC Resource handles instance deletion internally when receiving a `set` command where the instance defines the `_exist` property as `false`.", + "type": "boolean", + "default": false + }, "return": { "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" @@ -267,6 +258,60 @@ } ] }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json", + "title": "Delete method", + "description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "delete", + "--input", + "{json}" + ], + "input": { + "arg": "{json}" + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json", diff --git a/schemas/2024/04/bundled/resource/manifest.vscode.json b/schemas/2024/04/bundled/resource/manifest.vscode.json index f6f353940..9af97a9a3 100644 --- a/schemas/2024/04/bundled/resource/manifest.vscode.json +++ b/schemas/2024/04/bundled/resource/manifest.vscode.json @@ -264,15 +264,18 @@ "get": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json" }, - "export": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" - }, "set": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json" }, "test": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json" }, + "delete": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json" + }, + "export": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" + }, "validate": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json" }, @@ -474,46 +477,6 @@ } ] }, - "manifest.export.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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/2024/04/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/2024/04/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/2024/04/resource/manifest.set.json", @@ -545,6 +508,13 @@ "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#implementspretest\n" }, + "handlesExist": { + "title": "Resource handles _exist property", + "description": "Defines whether the DSC Resource has its own built-in handling for the `_exist` common property. Set this value to `true` if the DSC Resource handles instance deletion internally when receiving a `set` command where the instance defines the `_exist` property as `false`.", + "type": "boolean", + "default": false, + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the DSC Resource has its own built-in handling for the [`_exist`][02] common\nproperty. Set this value to `true` if the DSC Resource handles instance deletion internally\nwhen receiving a `set` command where the instance defines the `_exist` property as `false`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#handlesExist\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?view=dsc-3.0&preserve-view=true\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/2024/04/definitions/returnKind.json", @@ -663,6 +633,107 @@ } ] }, + "manifest.delete.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json", + "title": "Delete method", + "description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to delete an instance. Define this method for\nresources as an alternative to handling the [`_exist`][02] property in a `set` operation, which\ncan lead to highly complex code. If the `set` method for the resource is able to handle deleting\nan instance when `_exist` is `false`, set the [`handlesExist`][03] property of the set method\ndefinition to `true` instead.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?view=dsc-3.0&preserve-view=true\n[03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#handlesExist\n", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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/delete?view=dsc-3.0&preserve-view=true#executable\n" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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\", \"delete\"]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config delete\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true#args\n" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true#input\n" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "delete", + "--input", + "{json}" + ], + "input": { + "arg": "{json}" + } + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `validate` command for the resource when no arguments are required.\n", + "body": { + "executable": "${1:executable_name}", + "input": "${2:stdin}" + } + }, + { + "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}" + ], + "input": "${3:stdin}" + } + } + ] + }, + "manifest.export.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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/2024/04/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/2024/04/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.validate.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json", diff --git a/schemas/2024/04/outputs/resource/list.json b/schemas/2024/04/outputs/resource/list.json index abb0405fd..87df8d731 100644 --- a/schemas/2024/04/outputs/resource/list.json +++ b/schemas/2024/04/outputs/resource/list.json @@ -23,7 +23,9 @@ "enum": [ "Get", "Set", + "SetHandlesExist", "Test", + "Delete", "Export" ] } diff --git a/schemas/2024/04/resource/manifest.delete.json b/schemas/2024/04/resource/manifest.delete.json new file mode 100644 index 000000000..02c160e5b --- /dev/null +++ b/schemas/2024/04/resource/manifest.delete.json @@ -0,0 +1,36 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json", + "title": "Delete method", + "description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "delete", + "--input", + "{json}" + ], + "input": { + "arg": "{json}" + } + } + ] +} diff --git a/schemas/2024/04/resource/manifest.json b/schemas/2024/04/resource/manifest.json index 91a2c1858..89957bab7 100644 --- a/schemas/2024/04/resource/manifest.json +++ b/schemas/2024/04/resource/manifest.json @@ -57,15 +57,18 @@ "get": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json" }, - "export": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" - }, "set": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json" }, "test": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json" }, + "delete": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json" + }, + "export": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" + }, "validate": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json" }, diff --git a/schemas/2024/04/resource/manifest.set.json b/schemas/2024/04/resource/manifest.set.json index 8710848fb..d8889ff31 100644 --- a/schemas/2024/04/resource/manifest.set.json +++ b/schemas/2024/04/resource/manifest.set.json @@ -24,6 +24,12 @@ "type": "boolean", "default": false }, + "handlesExist": { + "title": "Resource handles _exist property", + "description": "Defines whether the DSC Resource has its own built-in handling for the `_exist` common property. Set this value to `true` if the DSC Resource handles instance deletion internally when receiving a `set` command where the instance defines the `_exist` property as `false`.", + "type": "boolean", + "default": false + }, "return": { "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" diff --git a/schemas/src/outputs/resource/list.yaml b/schemas/src/outputs/resource/list.yaml index 4d9c70ddc..588ad43a5 100644 --- a/schemas/src/outputs/resource/list.yaml +++ b/schemas/src/outputs/resource/list.yaml @@ -33,7 +33,9 @@ properties: enum: - Get - Set + - SetHandlesExist - Test + - Delete - Export description: title: Resource Description diff --git a/schemas/src/resource/manifest.delete.yaml b/schemas/src/resource/manifest.delete.yaml new file mode 100644 index 000000000..cf630f355 --- /dev/null +++ b/schemas/src/resource/manifest.delete.yaml @@ -0,0 +1,109 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/manifest.delete.yaml + +title: Delete method +description: >- + Defines how DSC must call the DSC Resource to delete an instance. Define this method for + resources as an alternative to handling the `_exist` property in a `set` operation, which can + lead to highly complex code. If the `set` operation for the resource is able to handle deleting + an instance when `_exist` is `false`, set the `handlesExist` property of the set method + definition to `true` instead. + +markdownDescription: | # VS Code only + *** + [_Online Documentation_][01] + *** + + Defines how DSC must call the DSC Resource to delete an instance. Define this method for + resources as an alternative to handling the [`_exist`][02] property in a `set` operation, which + can lead to highly complex code. If the `set` method for the resource is able to handle deleting + an instance when `_exist` is `false`, set the [`handlesExist`][03] property of the set method + definition to `true` instead. + + [01]: /reference/schemas/resource/manifest/delete? + [02]: /reference/schemas/resource/properties/exist? + [03]: /reference/schemas/resource/manifest/set?#handlesExist + +type: object +required: + - executable + - input +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/delete?#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", "delete"] + } + ``` + + DSC invokes the command for the resource as: + + ```bash + registry config delete + ``` + + [01]: /reference/schemas/resource/manifest/delete?#args + input: + $ref: ///definitions/inputKind.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines how DSC should pass input to the command, either as environment variables or JSON + over `stdin`. + + [01]: /reference/schemas/resource/manifest/delete?#input + +examples: + - executable: registry + args: + - config + - delete + - --input + - '{json}' + input: + arg: '{json}' + +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} + input: ${2:stdin} + + - 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} + input: ${3:stdin} diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 1f3b2415b..8bdf233cd 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -90,6 +90,26 @@ properties: system state. [01]: /reference/schemas/resource/manifest/set?#implementspretest + handlesExist: + title: Resource handles _exist property + description: >- + Defines whether the DSC Resource has its own built-in handling for the `_exist` common + property. Set this value to `true` if the DSC Resource handles instance deletion internally + when receiving a `set` command where the instance defines the `_exist` property as `false`. + type: boolean + default: false + # VS Code only + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines whether the DSC Resource has its own built-in handling for the [`_exist`][02] common + property. Set this value to `true` if the DSC Resource handles instance deletion internally + when receiving a `set` command where the instance defines the `_exist` property as `false`. + + [01]: /reference/schemas/resource/manifest/set?#handlesExist + [02]: /reference/schemas/resource/properties/exist? return: description: >- Defines whether the command returns a JSON blob of the DSC Resource's state after the set diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index 30fdd9585..1a902bc3c 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -420,12 +420,14 @@ properties: characters are permitted. get: $ref: ///resource/manifest.get.yaml - export: - $ref: ///resource/manifest.export.yaml set: $ref: ///resource/manifest.set.yaml test: $ref: ///resource/manifest.test.yaml + delete: + $ref: ///resource/manifest.delete.yaml + export: + $ref: ///resource/manifest.export.yaml validate: $ref: ///resource/manifest.validate.yaml adapter: From 333fa8c20cc5fd32d81d2eb1904e579189849e62 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Mon, 15 Apr 2024 10:30:18 -0500 Subject: [PATCH 10/15] (SCHEMA) Add `Microsoft.DSC` config metadata schema This change updates the `metadata` property of the configuration document schema to include the validated `Microsoft.DSC` property, with the `requiredSecurityContext` child property, as implemented in #351. This change updates both the source and composed schemas. --- schemas/2024/04/bundled/config/document.json | 32 +++- .../04/bundled/config/document.vscode.json | 97 ++++++++---- schemas/2024/04/config/document.json | 4 +- schemas/2024/04/config/document.metadata.json | 28 ++++ schemas/src/config/document.metadata.yaml | 141 ++++++++++++++++++ schemas/src/config/document.yaml | 51 +------ 6 files changed, 265 insertions(+), 88 deletions(-) create mode 100644 schemas/2024/04/config/document.metadata.json create mode 100644 schemas/src/config/document.metadata.yaml diff --git a/schemas/2024/04/bundled/config/document.json b/schemas/2024/04/bundled/config/document.json index cde4f9cb4..a4af3ad61 100644 --- a/schemas/2024/04/bundled/config/document.json +++ b/schemas/2024/04/bundled/config/document.json @@ -49,9 +49,7 @@ } }, "metadata": { - "title": "Configuration metadata", - "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", - "type": "object" + "$ref": "/PowerShell/DSC/main/schemas/2024/04/config/document.metadata.json" } }, "$defs": { @@ -317,6 +315,34 @@ } } }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.metadata.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.metadata.json", + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. Except for the `Microsoft.DSC` property, this metadata isn't validated. You can pass any data into this property of a configuration document.", + "type": "object", + "properties": { + "Microsoft.DSC": { + "type": "object", + "title": "DSC metadata", + "description": "The `Microsoft.DSC` metadata property contains directives and information that DSC itself uses when processing a configuration document. Unlike other metadata key-value pairs, DSC validates these properties.", + "unevaluatedProperties": false, + "properties": { + "requiredSecurityContext": { + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ], + "default": "Current", + "title": "Required security context", + "description": "This property defines the security context a configuration requires. If you invoke a DSC operation against the configuration document in a security context that conflicts with this metadata, DSC raises an error when it validates the configuration document.\nThe default security context is `Current`." + } + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/dataTypes.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/dataTypes.json", diff --git a/schemas/2024/04/bundled/config/document.vscode.json b/schemas/2024/04/bundled/config/document.vscode.json index a7e9e71f4..34bbff866 100644 --- a/schemas/2024/04/bundled/config/document.vscode.json +++ b/schemas/2024/04/bundled/config/document.vscode.json @@ -122,38 +122,7 @@ "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": "***\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", - "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)", - "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}" - } - } - }, - { - "label": " New metadata property (array)", - "markdownDescription": "Defines a new key-value pair for the metadata where the value is an array.\n\n```yaml\nmetadataName:\n - firstValue\n - secondValue\n```", - "body": { - "${1:metadataName}": [ - "${2:firstValue}", - "${3:secondValue}" - ] - } - } - ] + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/config/document.metadata.json" } }, "$defs": { @@ -500,6 +469,70 @@ } } ] + }, + "document.metadata.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.metadata.json", + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. Except for the `Microsoft.DSC` property, this metadata isn't validated. You can pass any data into this property of a configuration document.", + "type": "object", + "properties": { + "Microsoft.DSC": { + "type": "object", + "title": "DSC metadata", + "description": "The `Microsoft.DSC` metadata property contains directives and information that DSC itself uses when processing a configuration document. Unlike other metadata key-value pairs, DSC validates these properties.", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe `Microsoft.DSC` metadata property contains directives and information that DSC itself\nuses when processing a configuration document. Unlike other metadata key-value pairs, DSC\nvalidates these properties.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/metadata?view=dsc-3.0&preserve-view=true#microsoft.dsc\n", + "unevaluatedProperties": false, + "properties": { + "requiredSecurityContext": { + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ], + "default": "Current", + "title": "Required security context", + "description": "This property defines the security context a configuration requires. If you invoke a DSC operation against the configuration document in a security context that conflicts with this metadata, DSC raises an error when it validates the configuration document.\nThe default security context is `Current`.", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property defines the security context a configuration requires. If you invoke a DSC\noperation against the configuration document in a security context that conflicts with\nthis metadata, DSC raises an error when it validates the configuration document.\n\nThe default security context is `Current`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/metadata?view=dsc-3.0&preserve-view=true#microsoft.dsc\n", + "markdownEnumDescriptions": [ + "\n\n> ### Current security context\n>\n> Indicates that the configuration document is usable under any security context. You\n> can invoke DSC operations against the document when elevated as root or an\n> administrator and as a normal user or account.\n", + "\n\n> ### Elevated security context\n>\n> Indicates that the configuration document is usable only in an elevated security\n> context. You can invoke DSC operations against the document when elevated as root or\n> an administrator. When you invoke DSC operations against the document as a\n> non-elevated user or account, DSC raises an error when it validates the configuration\n> document.\n", + "\n\n> ### Restricted security context\n>\n> Indicates that the configuration document is usable only in a non-elevated security\n> context. You can invoke DSC operations against the document as a non-elevated user or\n> account. When you invoke DSC operations against the document as root or an\n> administrator, DSC raises an error when it validates the configuration document.\n" + ] + } + } + } + }, + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines a set of key-value pairs for the configuration. Except for the `Microsoft.DSC`\nproperty, this metadata isn't validated. You can pass any data into this property of a\nconfiguration document.\n\nThe `Microsoft.DSC` metadata property contains metadata directives and information that DSC\nitself uses when processing the configuration document. For more information, see\n[Microsoft.DSC][02]\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/metadata?view=dsc-3.0&preserve-view=true\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/metadata?view=dsc-3.0&preserve-view=true#microsoft.dsc\n", + "defaultSnippets": [ + { + "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)", + "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}" + } + } + }, + { + "label": " New metadata property (array)", + "markdownDescription": "Defines a new key-value pair for the metadata where the value is an array.\n\n```yaml\nmetadataName:\n - firstValue\n - secondValue\n```", + "body": { + "${1:metadataName}": [ + "${2:firstValue}", + "${3:secondValue}" + ] + } + } + ] } }, "definitions": { diff --git a/schemas/2024/04/config/document.json b/schemas/2024/04/config/document.json index 7a428085d..797fa5ced 100644 --- a/schemas/2024/04/config/document.json +++ b/schemas/2024/04/config/document.json @@ -49,9 +49,7 @@ } }, "metadata": { - "title": "Configuration metadata", - "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", - "type": "object" + "$ref": "/PowerShell/DSC/main/schemas/2024/04/config/document.metadata.json" } } } diff --git a/schemas/2024/04/config/document.metadata.json b/schemas/2024/04/config/document.metadata.json new file mode 100644 index 000000000..ebe379711 --- /dev/null +++ b/schemas/2024/04/config/document.metadata.json @@ -0,0 +1,28 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.metadata.json", + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. Except for the `Microsoft.DSC` property, this metadata isn't validated. You can pass any data into this property of a configuration document.", + "type": "object", + "properties": { + "Microsoft.DSC": { + "type": "object", + "title": "DSC metadata", + "description": "The `Microsoft.DSC` metadata property contains directives and information that DSC itself uses when processing a configuration document. Unlike other metadata key-value pairs, DSC validates these properties.", + "unevaluatedProperties": false, + "properties": { + "requiredSecurityContext": { + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ], + "default": "Current", + "title": "Required security context", + "description": "This property defines the security context a configuration requires. If you invoke a DSC operation against the configuration document in a security context that conflicts with this metadata, DSC raises an error when it validates the configuration document.\nThe default security context is `Current`." + } + } + } + } +} diff --git a/schemas/src/config/document.metadata.yaml b/schemas/src/config/document.metadata.yaml new file mode 100644 index 000000000..7d0e7f530 --- /dev/null +++ b/schemas/src/config/document.metadata.yaml @@ -0,0 +1,141 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///config/document.metadata.yaml + +title: Configuration metadata +description: >- + Defines a set of key-value pairs for the configuration. Except for the `Microsoft.DSC` + property, this metadata isn't validated. You can pass any data into this property of a + configuration document. + +type: object +properties: + Microsoft.DSC: + type: object + title: DSC metadata + description: >- + The `Microsoft.DSC` metadata property contains directives and information that DSC itself + uses when processing a configuration document. Unlike other metadata key-value pairs, DSC + validates these properties. + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + The `Microsoft.DSC` metadata property contains directives and information that DSC itself + uses when processing a configuration document. Unlike other metadata key-value pairs, DSC + validates these properties. + + [01]: /reference/schemas/config/metadata?#microsoft.dsc + + unevaluatedProperties: false + properties: + requiredSecurityContext: + type: string + enum: + - Current + - Elevated + - Restricted + default: Current + title: Required security context + description: >- + This property defines the security context a configuration requires. If you invoke a DSC + operation against the configuration document in a security context that conflicts with + this metadata, DSC raises an error when it validates the configuration document. + + The default security context is `Current`. + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + This property defines the security context a configuration requires. If you invoke a DSC + operation against the configuration document in a security context that conflicts with + this metadata, DSC raises an error when it validates the configuration document. + + The default security context is `Current`. + + [01]: /reference/schemas/config/metadata?#microsoft.dsc + markdownEnumDescriptions: + - | # Current + + + > ### Current security context + > + > Indicates that the configuration document is usable under any security context. You + > can invoke DSC operations against the document when elevated as root or an + > administrator and as a normal user or account. + + - | # Elevated + + + > ### Elevated security context + > + > Indicates that the configuration document is usable only in an elevated security + > context. You can invoke DSC operations against the document when elevated as root or + > an administrator. When you invoke DSC operations against the document as a + > non-elevated user or account, DSC raises an error when it validates the configuration + > document. + + - | # Restricted + + + > ### Restricted security context + > + > Indicates that the configuration document is usable only in a non-elevated security + > context. You can invoke DSC operations against the document as a non-elevated user or + > account. When you invoke DSC operations against the document as root or an + > administrator, DSC raises an error when it validates the configuration document. + +# VS Code only +markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines a set of key-value pairs for the configuration. Except for the `Microsoft.DSC` + property, this metadata isn't validated. You can pass any data into this property of a + configuration document. + + The `Microsoft.DSC` metadata property contains metadata directives and information that DSC + itself uses when processing the configuration document. For more information, see + [Microsoft.DSC][02] + + [01]: /reference/schemas/config/metadata? + [02]: /reference/schemas/config/metadata?#microsoft.dsc +defaultSnippets: + - label: ' New metadata property' + markdownDescription: |- + Defines a key-value pair for the metadata: + + ```yaml + metadataName: value + ``` + body: + ${1:metadataName}: ${2:value} + + - label: ' New metadata property (object)' + markdownDescription: |- + Defines a new key-value pair for the metadata where the value is an object. + + ```yaml + metadataName: + key: value + ``` + body: + ${1:metadataName}: + ${2:key}: ${3:value} + + - label: ' New metadata property (array)' + 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} diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index c311bd188..ebb39ba97 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -335,53 +335,4 @@ properties: [01]: /reference/schemas/config/document?#resources metadata: - title: Configuration metadata - description: >- - Defines a set of key-value pairs for the configuration. This metadata - isn't validated. - type: object - # VS Code only - markdownDescription: | - *** - [_Online Documentation_][01] - *** - - Defines a set of key-value pairs for the configuration. This metadata isn't validated. - - [01]: /reference/schemas/config/document?#metadata-1 - defaultSnippets: - - label: ' New metadata property' - markdownDescription: |- - Defines a key-value pair for the metadata: - - ```yaml - metadataName: value - ``` - body: - ${1:metadataName}: ${2:value} - - - label: ' New metadata property (object)' - markdownDescription: |- - Defines a new key-value pair for the metadata where the value is an object. - - ```yaml - metadataName: - key: value - ``` - body: - ${1:metadataName}: - ${2:key}: ${3:value} - - - label: ' New metadata property (array)' - 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} + $ref: ///config/document.metadata.yaml From 4c21aa7d7546d82c0f4637924a4700a0cd4d7105 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Mon, 15 Apr 2024 11:53:52 -0500 Subject: [PATCH 11/15] (SCHEMA) Update `_exist` guidance for `delete` This change updates guidance for resources that implement the `delete` method to always define the `_exist` property in the JSON schema for the resource's properties, now that DSC can automatically determine whether to delete an instance as implemented in #382. This change updates both the source and composed schemas. --- schemas/2024/04/bundled/resource/manifest.vscode.json | 2 +- schemas/src/resource/manifest.delete.yaml | 4 ++++ schemas/src/resource/properties/exist.yaml | 6 +++++- 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/schemas/2024/04/bundled/resource/manifest.vscode.json b/schemas/2024/04/bundled/resource/manifest.vscode.json index 9af97a9a3..f9fa37ede 100644 --- a/schemas/2024/04/bundled/resource/manifest.vscode.json +++ b/schemas/2024/04/bundled/resource/manifest.vscode.json @@ -638,7 +638,7 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json", "title": "Delete method", "description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.", - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to delete an instance. Define this method for\nresources as an alternative to handling the [`_exist`][02] property in a `set` operation, which\ncan lead to highly complex code. If the `set` method for the resource is able to handle deleting\nan instance when `_exist` is `false`, set the [`handlesExist`][03] property of the set method\ndefinition to `true` instead.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?view=dsc-3.0&preserve-view=true\n[03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#handlesExist\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to delete an instance. Define this method for\nresources as an alternative to handling the [`_exist`][02] property in a `set` operation, which\ncan lead to highly complex code. If the `set` method for the resource is able to handle deleting\nan instance when `_exist` is `false`, set the [`handlesExist`][03] property of the set method\ndefinition to `true` instead.\n\nIf you define the delete method in a resource manifest, ensure that you also define the\n[`_exist`][02] property in the [JSON schema for the resource's properties][04].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?view=dsc-3.0&preserve-view=true\n[03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#handlesExist\n[04]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ "executable", diff --git a/schemas/src/resource/manifest.delete.yaml b/schemas/src/resource/manifest.delete.yaml index cf630f355..710c49300 100644 --- a/schemas/src/resource/manifest.delete.yaml +++ b/schemas/src/resource/manifest.delete.yaml @@ -21,9 +21,13 @@ markdownDescription: | # VS Code only an instance when `_exist` is `false`, set the [`handlesExist`][03] property of the set method definition to `true` instead. + If you define the delete method in a resource manifest, ensure that you also define the + [`_exist`][02] property in the [JSON schema for the resource's properties][04]. + [01]: /reference/schemas/resource/manifest/delete? [02]: /reference/schemas/resource/properties/exist? [03]: /reference/schemas/resource/manifest/set?#handlesExist + [04]: /reference/schemas/resource/manifest/schema/property? type: object required: diff --git a/schemas/src/resource/properties/exist.yaml b/schemas/src/resource/properties/exist.yaml index d254909ac..7fad6b4a0 100644 --- a/schemas/src/resource/properties/exist.yaml +++ b/schemas/src/resource/properties/exist.yaml @@ -16,9 +16,13 @@ markdownDescription: | [_Online Documentation_][01] *** - Indicates whether the DSC Resource instance should exist. + Indicates whether the DSC Resource instance should exist. For DSC Resources that define the + [delete method in their manifest][02], DSC calls the `delete` method for the resource when an + instance defines `_exist` as `false` and the instance exists. + [01]: /reference/schemas/resource/properties/exist? + [02]: /reference/schemas/resource/manifest/delete? markdownEnumDescriptions: - | # false _Instance shouldn't exist._ From c604cecaf20a6f4d3d139415efe38cb4db643ae3 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Tue, 16 Apr 2024 10:43:48 -0500 Subject: [PATCH 12/15] (SCHEMA) Update for JSON input arguments This change updates the definition of the command arguments from an array of strings to an array that can include strings and a single object representing a JSON input argument, as implemented in #385. The shared definition includes default snippets to simplify adding arguments to an `args` list, but not validation for the maximum number of JSON input arguments. It updates the definition for the schema command and adapter list command to expect arrays of strings instead of the shared definition for the command arguments, as those commands never get JSON data for input and their struct definition in Rust expects an optional vector of strings, not command arguments. It updates the definition for the `delete`, `export`, `get`, `set`, `test`, and `validate` commands to: 1. Make `input` optional, if it was required before, because that matches the struct definitions and DSC no longer requires the `input` kind when `args` includes a JSON input argument. 1. Add validation using three branches of the `oneOf` keyword, to handle mixed support for the `contains`, `minContains`, and `maxContains` keywords across the JSON and YAML support in VS Code. It raises specific error messages now when: - `input` isn't defined and `args` doesn't include a JSON input argument, or includes more than one JSON input argument. - `input` is defined and `args` includes more than one JSON input argument. 1. Update the default snippets to enable users to quickly define the command without any arguments, with only string arguments, and with a JSON input argument. 1. Update the in-editor help and clarify that the command must define `input`, a JSON input argument in `args`, or both. This change updates both the source and composed schemas. --- .../04/bundled/outputs/resource/list.json | 356 +++++++++-- .../2024/04/bundled/resource/manifest.json | 356 +++++++++-- .../04/bundled/resource/manifest.vscode.json | 578 +++++++++++++++--- schemas/2024/04/definitions/commandArgs.json | 32 +- .../2024/04/resource/manifest.adapter.json | 7 +- schemas/2024/04/resource/manifest.delete.json | 53 +- schemas/2024/04/resource/manifest.export.json | 53 +- schemas/2024/04/resource/manifest.get.json | 47 +- schemas/2024/04/resource/manifest.schema.json | 7 +- schemas/2024/04/resource/manifest.set.json | 53 +- schemas/2024/04/resource/manifest.test.json | 52 +- .../2024/04/resource/manifest.validate.json | 52 +- schemas/src/definitions/commandArgs.yaml | 89 ++- schemas/src/resource/manifest.adapter.yaml | 12 +- schemas/src/resource/manifest.delete.yaml | 142 ++++- schemas/src/resource/manifest.export.yaml | 142 ++++- schemas/src/resource/manifest.get.yaml | 132 +++- schemas/src/resource/manifest.schema.yaml | 19 +- schemas/src/resource/manifest.set.yaml | 139 ++++- schemas/src/resource/manifest.test.yaml | 145 ++++- schemas/src/resource/manifest.validate.yaml | 148 ++++- 21 files changed, 2250 insertions(+), 364 deletions(-) diff --git a/schemas/2024/04/bundled/outputs/resource/list.json b/schemas/2024/04/bundled/outputs/resource/list.json index edcf8da8b..d8c2989cf 100644 --- a/schemas/2024/04/bundled/outputs/resource/list.json +++ b/schemas/2024/04/bundled/outputs/resource/list.json @@ -266,17 +266,50 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" } }, - "examples": [ + "oneOf": [ { - "executable": "registry", - "args": [ - "config", - "get" + "required": [ + "input" ], - "input": "stdin" + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } }, { - "executable": "osinfo" + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] }, @@ -287,8 +320,7 @@ "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", "type": "object", "required": [ - "executable", - "input" + "executable" ], "properties": { "executable": { @@ -317,16 +349,50 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" } }, - "examples": [ + "oneOf": [ { - "executable": "registry", - "args": [ - "config", - "set" + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" ], - "input": "stdin", - "implementsPretest": true, - "return": "state" + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] }, @@ -337,8 +403,7 @@ "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", "type": "object", "required": [ - "executable", - "input" + "executable" ], "properties": { "executable": { @@ -356,15 +421,50 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" } }, - "examples": [ + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, { - "executable": "registry", - "args": [ - "config", - "test" + "required": [ + "input" ], - "input": "stdin", - "return": "state" + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] }, @@ -375,8 +475,7 @@ "description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.", "type": "object", "required": [ - "executable", - "input" + "executable" ], "properties": { "executable": { @@ -389,17 +488,49 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" } }, - "examples": [ + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, { - "executable": "registry", - "args": [ - "config", - "delete", - "--input", - "{json}" + "required": [ + "input" ], - "input": { - "arg": "{json}" + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } } } ] @@ -407,7 +538,7 @@ "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", - "title": "Get Method", + "title": "Export Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", "type": "object", "required": [ @@ -419,8 +550,57 @@ }, "args": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" } - } + }, + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -437,15 +617,55 @@ }, "args": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" } }, - "examples": [ + "oneOf": [ { - "executable": "dsc", - "args": [ - "config", - "validate" - ] + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] }, @@ -472,7 +692,12 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" }, "args": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + "type": "array", + "items": { + "type": "string" + }, + "title": "Command arguments", + "description": "Defines the list of arguments to pass to the command to return the list of supported DSC Resources." } } }, @@ -533,7 +758,12 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" }, "args": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + "type": "array", + "items": { + "type": "string" + }, + "title": "Command arguments", + "description": "Defines the list of arguments to pass to the command to return the JSON Schema for the resource." } } }, @@ -709,10 +939,38 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json", "title": "Executable Command Arguments", - "description": "The list of arguments to pass to the command.", + "description": "The list of arguments to pass to the command. The arguments can be any number of strings. If you want to pass the JSON object representing the property bag for the resource to an argument, you can define a single item in the array as a JSON object, indicating the name of the argument with the `jsonInputArg` string property and whether the argument is mandatory for the command with the `mandatory` boolean property.", "type": "array", "items": { - "type": "string" + "oneOf": [ + { + "type": "string", + "title": "String argument", + "description": "Any item in the argument array can be a string representing a static argument to pass to the command." + }, + { + "type": "object", + "title": "JSON input argument", + "description": "Defines an argument for the command that accepts the JSON input object as a string. DSC passes the JSON input to the named argument when available. You can define the `mandatory` property to indicate whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the JSON input argument. You can only define one JSON input argument per arguments array.", + "required": [ + "jsonInputArg" + ], + "unevaluatedProperties": false, + "properties": { + "jsonInputArg": { + "title": "JSON input argument name", + "description": "Defines the argument that accepts the JSON property bag for the resource as input.", + "type": "string" + }, + "mandatory": { + "title": "Mandatory argument", + "description": "Defines whether the argument is mandatory. If this property is set to `true`, DSC passes an empty string when no JSON input is provided. The default value is `false`.", + "type": "boolean", + "default": false + } + } + } + ] } }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json": { diff --git a/schemas/2024/04/bundled/resource/manifest.json b/schemas/2024/04/bundled/resource/manifest.json index 01e26c9d1..8b4999fff 100644 --- a/schemas/2024/04/bundled/resource/manifest.json +++ b/schemas/2024/04/bundled/resource/manifest.json @@ -156,17 +156,50 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" } }, - "examples": [ + "oneOf": [ { - "executable": "registry", - "args": [ - "config", - "get" + "required": [ + "input" ], - "input": "stdin" + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } }, { - "executable": "osinfo" + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] }, @@ -177,8 +210,7 @@ "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", "type": "object", "required": [ - "executable", - "input" + "executable" ], "properties": { "executable": { @@ -207,16 +239,50 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" } }, - "examples": [ + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, { - "executable": "registry", - "args": [ - "config", - "set" + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" ], - "input": "stdin", - "implementsPretest": true, - "return": "state" + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] }, @@ -227,8 +293,7 @@ "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", "type": "object", "required": [ - "executable", - "input" + "executable" ], "properties": { "executable": { @@ -246,15 +311,50 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" } }, - "examples": [ + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, { - "executable": "registry", - "args": [ - "config", - "test" + "required": [ + "input" ], - "input": "stdin", - "return": "state" + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] }, @@ -265,8 +365,7 @@ "description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.", "type": "object", "required": [ - "executable", - "input" + "executable" ], "properties": { "executable": { @@ -279,17 +378,49 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" } }, - "examples": [ + "oneOf": [ { - "executable": "registry", - "args": [ - "config", - "delete", - "--input", - "{json}" + "required": [ + "input" ], - "input": { - "arg": "{json}" + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } } } ] @@ -297,7 +428,7 @@ "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", - "title": "Get Method", + "title": "Export Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", "type": "object", "required": [ @@ -309,8 +440,57 @@ }, "args": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" } - } + }, + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + } + ] }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -327,15 +507,55 @@ }, "args": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" } }, - "examples": [ + "oneOf": [ { - "executable": "dsc", - "args": [ - "config", - "validate" - ] + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] }, @@ -362,7 +582,12 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" }, "args": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + "type": "array", + "items": { + "type": "string" + }, + "title": "Command arguments", + "description": "Defines the list of arguments to pass to the command to return the list of supported DSC Resources." } } }, @@ -423,7 +648,12 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" }, "args": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + "type": "array", + "items": { + "type": "string" + }, + "title": "Command arguments", + "description": "Defines the list of arguments to pass to the command to return the JSON Schema for the resource." } } }, @@ -599,10 +829,38 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json", "title": "Executable Command Arguments", - "description": "The list of arguments to pass to the command.", + "description": "The list of arguments to pass to the command. The arguments can be any number of strings. If you want to pass the JSON object representing the property bag for the resource to an argument, you can define a single item in the array as a JSON object, indicating the name of the argument with the `jsonInputArg` string property and whether the argument is mandatory for the command with the `mandatory` boolean property.", "type": "array", "items": { - "type": "string" + "oneOf": [ + { + "type": "string", + "title": "String argument", + "description": "Any item in the argument array can be a string representing a static argument to pass to the command." + }, + { + "type": "object", + "title": "JSON input argument", + "description": "Defines an argument for the command that accepts the JSON input object as a string. DSC passes the JSON input to the named argument when available. You can define the `mandatory` property to indicate whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the JSON input argument. You can only define one JSON input argument per arguments array.", + "required": [ + "jsonInputArg" + ], + "unevaluatedProperties": false, + "properties": { + "jsonInputArg": { + "title": "JSON input argument name", + "description": "Defines the argument that accepts the JSON property bag for the resource as input.", + "type": "string" + }, + "mandatory": { + "title": "Mandatory argument", + "description": "Defines whether the argument is mandatory. If this property is set to `true`, DSC passes an empty string when no JSON input is provided. The default value is `false`.", + "type": "boolean", + "default": false + } + } + } + ] } }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json": { diff --git a/schemas/2024/04/bundled/resource/manifest.vscode.json b/schemas/2024/04/bundled/resource/manifest.vscode.json index f9fa37ede..fbe6c6218 100644 --- a/schemas/2024/04/bundled/resource/manifest.vscode.json +++ b/schemas/2024/04/bundled/resource/manifest.vscode.json @@ -383,10 +383,57 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json", "title": "Executable Command Arguments", - "description": "The list of arguments to pass to the command.", + "description": "The list of arguments to pass to the command. The arguments can be any number of strings. If you want to pass the JSON object representing the property bag for the resource to an argument, you can define a single item in the array as a JSON object, indicating the name of the argument with the `jsonInputArg` string property and whether the argument is mandatory for the command with the `mandatory` boolean property.", "type": "array", "items": { - "type": "string" + "defaultSnippets": [ + { + "label": "String argument", + "markdownDescription": "Add a string argument to the command, like `config` or `--config`.", + "body": "${1:argument_name}" + }, + { + "label": "JSON input argument", + "markdownDescription": "Add a JSON input argument to the command. A command can only define one JSON input argument\nin the `args` list. When you define a JSON input argument, DSC passes the input data for\nthe command to the specified argument as a string representing the data as a compressed\nJSON object. The compressed JSON object doesn't have any spaces or newlines between the\nobject properties and values.\n\nIf the command doesn't define the `input` property, it must define a JSON input argument.\n\nIf the command defines both the `input` property and a JSON input argument, DSC sends the\ninput data to the command in both ways. For example, if the command defines `input` as\n`stdin` and has a JSON input argument in `args`, DSC sends the input data as a compressed\nJSON object over stdin and to the the specified argument.", + "body": { + "jsonInputArg": "${1:argument_name}", + "mandatory": "^$2" + } + } + ], + "oneOf": [ + { + "type": "string", + "title": "String argument", + "description": "Any item in the argument array can be a string representing a static argument to pass to the command.", + "markdownDescription": "Any item in the argument array can be a string representing a static argument to pass to\nthe command.\n" + }, + { + "type": "object", + "title": "JSON input argument", + "description": "Defines an argument for the command that accepts the JSON input object as a string. DSC passes the JSON input to the named argument when available. You can define the `mandatory` property to indicate whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the JSON input argument. You can only define one JSON input argument per arguments array.", + "markdownDescription": "Defines an argument for the command that accepts the JSON input object as a string. DSC\npasses the JSON input to the named argument when available. You can define the `mandatory`\nproperty to indicate whether DSC should always pass the argument to the command, even when\nthere's no JSON input for the command. In that case, DSC passes an empty string to the\nJSON input argument. You can only define one JSON input argument per arguments array.\n\nIf you define a JSON input argument and an `input` kind for a command, DSC sends the JSON\ndata both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n", + "required": [ + "jsonInputArg" + ], + "unevaluatedProperties": false, + "properties": { + "jsonInputArg": { + "title": "JSON input argument name", + "description": "Defines the argument that accepts the JSON property bag for the resource as input.", + "markdownDescription": "Defines the argument that accepts the JSON property bag for the resource as input.\n", + "type": "string" + }, + "mandatory": { + "title": "Mandatory argument", + "description": "Defines whether the argument is mandatory. If this property is set to `true`, DSC passes an empty string when no JSON input is provided. The default value is `false`.", + "markdownDescription": "Defines whether the argument is mandatory. If this property is set to `true`, DSC\npasses an empty string when no JSON input is provided. The default value is `false`.\n", + "type": "boolean", + "default": false + } + } + } + ] } }, "inputKind.json": { @@ -423,7 +470,7 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to get the current state of an instance.\n\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\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" @@ -435,38 +482,73 @@ }, "args": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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" + "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\": \"myresource\",\n \"args\": [\"config\", \"get\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config get\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property. When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"get\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config get --properties \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/2024/04/definitions/inputKind.json", - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. If this value isn't defined, DSC doesn't send the resource any input when\ninvoking the `get` operation.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#input\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#input\n" } }, - "examples": [ + "oneOf": [ { - "executable": "registry", - "args": [ - "config", - "get" + "required": [ + "input" ], - "input": "stdin" + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `get` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } }, { - "executable": "osinfo" + "required": [ + "input" + ], + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `get` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ], "defaultSnippets": [ { "label": " Define without arguments", - "markdownDescription": "Define the get command for the resource when no arguments are required.\n", + "markdownDescription": "Define the `get` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", "body": { "input": "${1|stdin,env|}", "executable": "${2:executable_name}" } }, { - "label": " Define with arguments", - "markdownDescription": "Define the get command for the resource when at least one argument is required.\n", + "label": " Define with string arguments", + "markdownDescription": "Define the `get` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", "body": { "input": "${1|stdin,env|}", "executable": "${2:executable_name}", @@ -474,6 +556,19 @@ "${3:--first-argument}" ] } + }, + { + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `get` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", + "body": { + "executable": "${1:executable_name}", + "args": [ + { + "jsonInputArg": "${2:argument_name}", + "mandatory": "^$3" + } + ] + } } ] }, @@ -482,11 +577,10 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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", + "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\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\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", - "input" + "executable" ], "properties": { "executable": { @@ -495,11 +589,11 @@ }, "args": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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" + "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\": \"myresource\",\n \"args\": [\"config\", \"set\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config set\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property.` When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"set\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config set --properties \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/2024/04/definitions/inputKind.json", - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\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", @@ -525,34 +619,70 @@ ] } }, - "examples": [ + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `set` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, { - "executable": "registry", - "args": [ - "config", - "set" + "required": [ + "input" ], - "input": "stdin", - "implementsPretest": true, - "return": "state" + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `set` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ], "defaultSnippets": [ { "label": " Define without arguments", - "markdownDescription": "Define the `set` command for the resource when no arguments are required.\n", + "markdownDescription": "Define the `set` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", "body": { - "input": "${1|input,env|}", + "input": "${1|stdin,env|}", "implementsPretest": "^${2|true,false|}", "return": "${3|state,stateAndDiff|}", "executable": "${4:executable_name}" } }, { - "label": " Define with arguments", - "markdownDescription": "Define the `set` command for the resource when at least one argument is required.\n", + "label": " Define with string arguments", + "markdownDescription": "Define the `set` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", "body": { - "input": "${1|input,env|}", + "input": "${1|stdin,env|}", "implementsPretest": "^${2|true,false|}", "return": "${3|state,stateAndDiff|}", "executable": "${4:executable_name}", @@ -560,6 +690,21 @@ "${5:--first-argument}" ] } + }, + { + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `set` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", + "body": { + "implementsPretest": "^${1|true,false|}", + "return": "${2|state,stateAndDiff|}", + "executable": "${3:executable_name}", + "args": [ + { + "jsonInputArg": "${4:argument_name}", + "mandatory": "^$5" + } + ] + } } ] }, @@ -568,24 +713,23 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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", + "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\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\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", - "input" + "executable" ], "properties": { "executable": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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" + "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/test?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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" + "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\": \"myresource\",\n \"args\": [\"config\", \"test\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config test\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property.` When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"test\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config test --properties \n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserve-view=true#args\n" }, "input": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json", - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserve-view=true#input\n" }, "return": { "title": "Test Command Return Type", @@ -598,38 +742,89 @@ ] } }, - "examples": [ + "oneOf": [ { - "executable": "registry", - "args": [ - "config", - "test" + "required": [ + "input" ], - "input": "stdin", - "return": "state" + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `test` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `test` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ], "defaultSnippets": [ { "label": " Define without arguments", - "markdownDescription": "Define the `test` command for the resource when no arguments are required.\n", + "markdownDescription": "Define the `test` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", "body": { - "input": "${1|input,env|}", + "input": "${1|stdin,env|}", "return": "${2|state,stateAndDiff|}", "executable": "${3:executable_name}" } }, { - "label": " Define with arguments", - "markdownDescription": "Define the `test` command for the resource when at least one argument is required.\n", + "label": " Define with string arguments", + "markdownDescription": "Define the `test` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", "body": { - "input": "${1|input,env|}", + "input": "${1|stdin,env|}", "return": "${2|state,stateAndDiff|}", "executable": "${3:executable_name}", "args": [ "${4:--first-argument}" ] } + }, + { + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `test` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", + "body": { + "return": "${1|state,stateAndDiff|}", + "executable": "${2:executable_name}", + "args": [ + { + "jsonInputArg": "${3:argument_name}", + "mandatory": "^$4" + } + ] + } } ] }, @@ -638,11 +833,10 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json", "title": "Delete method", "description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.", - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to delete an instance. Define this method for\nresources as an alternative to handling the [`_exist`][02] property in a `set` operation, which\ncan lead to highly complex code. If the `set` method for the resource is able to handle deleting\nan instance when `_exist` is `false`, set the [`handlesExist`][03] property of the set method\ndefinition to `true` instead.\n\nIf you define the delete method in a resource manifest, ensure that you also define the\n[`_exist`][02] property in the [JSON schema for the resource's properties][04].\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?view=dsc-3.0&preserve-view=true\n[03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#handlesExist\n[04]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true\n", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to delete an instance. Define this method for\nresources as an alternative to handling the [`_exist`][02] property in a `set` operation, which\ncan lead to highly complex code. If the `set` method for the resource is able to handle deleting\nan instance when `_exist` is `false`, set the [`handlesExist`][03] property of the set method\ndefinition to `true` instead.\n\nIf you define the delete method in a resource manifest, ensure that you also define the\n[`_exist`][02] property in the [JSON schema for the resource's properties][04].\n\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?view=dsc-3.0&preserve-view=true\n[03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#handlesExist\n[04]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true\n", "type": "object", "required": [ - "executable", - "input" + "executable" ], "properties": { "executable": { @@ -651,45 +845,92 @@ }, "args": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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\", \"delete\"]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nregistry config delete\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true#args\n" + "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\": \"myresource\",\n \"args\": [\"config\", \"delete\"]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config delete\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property.` When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"set\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config set --properties \n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true#args\n" }, "input": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json", - "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC should pass input to the command, either as environment variables or JSON\nover `stdin`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?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`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true#input\n" } }, - "examples": [ + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, { - "executable": "registry", - "args": [ - "config", - "delete", - "--input", - "{json}" + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `delete` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" ], - "input": { - "arg": "{json}" + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `delete` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } } } ], "defaultSnippets": [ { "label": " Define without arguments", - "markdownDescription": "Define the `validate` command for the resource when no arguments are required.\n", + "markdownDescription": "Define the `delete` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", "body": { - "executable": "${1:executable_name}", - "input": "${2:stdin}" + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}" } }, { - "label": " Define with arguments", - "markdownDescription": "Define the `validate` command for the resource when at least one argument is required.\n", + "label": " Define with string arguments", + "markdownDescription": "Define the `delete` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + }, + { + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `delete` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", "body": { "executable": "${1:executable_name}", "args": [ - "${2:--first-argument}" - ], - "input": "${3:stdin}" + { + "jsonInputArg": "${2:argument_name}", + "mandatory": "^$3" + } + ] } } ] @@ -697,9 +938,9 @@ "manifest.export.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", - "title": "Get Method", + "title": "Export Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", - "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", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to get the current state of every instance.\n\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\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" @@ -711,24 +952,91 @@ }, "args": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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" + "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\": \"myresource\",\n \"args\": [\"config\", \"export\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config export\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property.` When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"export\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config export --properties \n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true#args\n" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true#input\n" } }, + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `export` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `export` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + } + ], "defaultSnippets": [ { "label": " Define without arguments", - "markdownDescription": "Define the export command for the resource when no arguments are required.\n", + "markdownDescription": "Define the `export` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", "body": { - "executable": "${1:executable_name}" + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}" } }, { - "label": " Define with arguments", - "markdownDescription": "Define the export command for the resource when at least one argument is required.\n", + "label": " Define with string arguments", + "markdownDescription": "Define the `export` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + }, + { + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `export` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", "body": { "executable": "${1:executable_name}", "args": [ - "${2:--first-argument}" + { + "jsonInputArg": "${2:argument_name}", + "mandatory": "^3" + } ] } } @@ -739,7 +1047,7 @@ "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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", + "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\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\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" @@ -747,37 +1055,95 @@ "properties": { "executable": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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" + "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/validate?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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" + "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\": \"myresource\",\n \"args\": [\"config\", \"validate\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config validate\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property.` When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"validate\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config validate --properties \n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserve-view=true#args\n" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserve-view=true#input\n" } }, - "examples": [ + "oneOf": [ { - "executable": "dsc", - "args": [ - "config", - "validate" - ] + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `validate` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `validate` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ], "defaultSnippets": [ { "label": " Define without arguments", - "markdownDescription": "Define the `validate` command for the resource when no arguments are required.\n", + "markdownDescription": "Define the `validate` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}" + } + }, + { + "label": " Define with string arguments", + "markdownDescription": "Define the `validate` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", "body": { - "executable": "${1:executable_name}" + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] } }, { - "label": " Define with arguments", - "markdownDescription": "Define the `validate` command for the resource when at least one argument is required.\n", + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `validate` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", "body": { "executable": "${1:executable_name}", "args": [ - "${2:--first-argument}" + { + "jsonInputArg": "${2:argument_name}", + "mandatory": "^$3" + } ] } } @@ -809,7 +1175,12 @@ "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/adapter?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json", + "type": "array", + "items": { + "type": "string" + }, + "title": "Command arguments", + "description": "Defines the list of arguments to pass to the command to return the list of supported DSC Resources.", "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/adapter?view=dsc-3.0&preserve-view=true#args\n" } } @@ -849,7 +1220,7 @@ "label": " Define without arguments", "markdownDescription": "Define the adapter config kind and `list` command for the resource when no arguments are\nrequired.\n", "body": { - "config": "$1", + "config": "${1|full,sequence}", "list": { "executable": "${2:executable_name}" } @@ -859,7 +1230,7 @@ "label": " Define with arguments", "markdownDescription": "Define the adapter config kind and `list` command for the resource when at least one\nargument is required.\n", "body": { - "config": "$1", + "config": "${1|full,sequence}", "list": { "executable": "${2:executable_name}", "args": [ @@ -899,11 +1270,16 @@ "properties": { "executable": { "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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" + "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/schema/property?view=dsc-3.0&preserve-view=true#executable\n" }, "args": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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" + "type": "array", + "items": { + "type": "string" + }, + "title": "Command arguments", + "description": "Defines the list of arguments to pass to the command to return the JSON Schema for the resource.", + "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\": \"myresource\",\n \"args\": [\"schema\", \"show\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource schema show\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#args\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", diff --git a/schemas/2024/04/definitions/commandArgs.json b/schemas/2024/04/definitions/commandArgs.json index c4d08edf8..8fc032824 100644 --- a/schemas/2024/04/definitions/commandArgs.json +++ b/schemas/2024/04/definitions/commandArgs.json @@ -2,9 +2,37 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json", "title": "Executable Command Arguments", - "description": "The list of arguments to pass to the command.", + "description": "The list of arguments to pass to the command. The arguments can be any number of strings. If you want to pass the JSON object representing the property bag for the resource to an argument, you can define a single item in the array as a JSON object, indicating the name of the argument with the `jsonInputArg` string property and whether the argument is mandatory for the command with the `mandatory` boolean property.", "type": "array", "items": { - "type": "string" + "oneOf": [ + { + "type": "string", + "title": "String argument", + "description": "Any item in the argument array can be a string representing a static argument to pass to the command." + }, + { + "type": "object", + "title": "JSON input argument", + "description": "Defines an argument for the command that accepts the JSON input object as a string. DSC passes the JSON input to the named argument when available. You can define the `mandatory` property to indicate whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the JSON input argument. You can only define one JSON input argument per arguments array.", + "required": [ + "jsonInputArg" + ], + "unevaluatedProperties": false, + "properties": { + "jsonInputArg": { + "title": "JSON input argument name", + "description": "Defines the argument that accepts the JSON property bag for the resource as input.", + "type": "string" + }, + "mandatory": { + "title": "Mandatory argument", + "description": "Defines whether the argument is mandatory. If this property is set to `true`, DSC passes an empty string when no JSON input is provided. The default value is `false`.", + "type": "boolean", + "default": false + } + } + } + ] } } diff --git a/schemas/2024/04/resource/manifest.adapter.json b/schemas/2024/04/resource/manifest.adapter.json index 7dd76ac33..978bcab03 100644 --- a/schemas/2024/04/resource/manifest.adapter.json +++ b/schemas/2024/04/resource/manifest.adapter.json @@ -21,7 +21,12 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" }, "args": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + "type": "array", + "items": { + "type": "string" + }, + "title": "Command arguments", + "description": "Defines the list of arguments to pass to the command to return the list of supported DSC Resources." } } }, diff --git a/schemas/2024/04/resource/manifest.delete.json b/schemas/2024/04/resource/manifest.delete.json index 02c160e5b..db739e522 100644 --- a/schemas/2024/04/resource/manifest.delete.json +++ b/schemas/2024/04/resource/manifest.delete.json @@ -5,8 +5,7 @@ "description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.", "type": "object", "required": [ - "executable", - "input" + "executable" ], "properties": { "executable": { @@ -19,17 +18,49 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" } }, - "examples": [ + "oneOf": [ { - "executable": "registry", - "args": [ - "config", - "delete", - "--input", - "{json}" + "required": [ + "input" ], - "input": { - "arg": "{json}" + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } } } ] diff --git a/schemas/2024/04/resource/manifest.export.json b/schemas/2024/04/resource/manifest.export.json index bfcca164a..b7be7752c 100644 --- a/schemas/2024/04/resource/manifest.export.json +++ b/schemas/2024/04/resource/manifest.export.json @@ -1,7 +1,7 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", - "title": "Get Method", + "title": "Export Method", "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", "type": "object", "required": [ @@ -13,6 +13,55 @@ }, "args": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" + } + }, + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } - } + ] } diff --git a/schemas/2024/04/resource/manifest.get.json b/schemas/2024/04/resource/manifest.get.json index 3764ded7c..8a6e56ff1 100644 --- a/schemas/2024/04/resource/manifest.get.json +++ b/schemas/2024/04/resource/manifest.get.json @@ -18,17 +18,50 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" } }, - "examples": [ + "oneOf": [ { - "executable": "registry", - "args": [ - "config", - "get" + "required": [ + "input" ], - "input": "stdin" + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } }, { - "executable": "osinfo" + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] } diff --git a/schemas/2024/04/resource/manifest.schema.json b/schemas/2024/04/resource/manifest.schema.json index 2f1590ceb..d4b47e5c5 100644 --- a/schemas/2024/04/resource/manifest.schema.json +++ b/schemas/2024/04/resource/manifest.schema.json @@ -29,7 +29,12 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandExecutable.json" }, "args": { - "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + "type": "array", + "items": { + "type": "string" + }, + "title": "Command arguments", + "description": "Defines the list of arguments to pass to the command to return the JSON Schema for the resource." } } }, diff --git a/schemas/2024/04/resource/manifest.set.json b/schemas/2024/04/resource/manifest.set.json index d8889ff31..39d75d835 100644 --- a/schemas/2024/04/resource/manifest.set.json +++ b/schemas/2024/04/resource/manifest.set.json @@ -5,8 +5,7 @@ "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", "type": "object", "required": [ - "executable", - "input" + "executable" ], "properties": { "executable": { @@ -35,16 +34,50 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" } }, - "examples": [ + "oneOf": [ { - "executable": "registry", - "args": [ - "config", - "set" + "required": [ + "input" ], - "input": "stdin", - "implementsPretest": true, - "return": "state" + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] } diff --git a/schemas/2024/04/resource/manifest.test.json b/schemas/2024/04/resource/manifest.test.json index 1426f44e4..430a0ba5b 100644 --- a/schemas/2024/04/resource/manifest.test.json +++ b/schemas/2024/04/resource/manifest.test.json @@ -5,8 +5,7 @@ "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", "type": "object", "required": [ - "executable", - "input" + "executable" ], "properties": { "executable": { @@ -24,15 +23,50 @@ "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json" } }, - "examples": [ + "oneOf": [ { - "executable": "registry", - "args": [ - "config", - "test" + "required": [ + "input" ], - "input": "stdin", - "return": "state" + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] } diff --git a/schemas/2024/04/resource/manifest.validate.json b/schemas/2024/04/resource/manifest.validate.json index ebb64e3d4..2f52a1583 100644 --- a/schemas/2024/04/resource/manifest.validate.json +++ b/schemas/2024/04/resource/manifest.validate.json @@ -13,15 +13,55 @@ }, "args": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json" } }, - "examples": [ + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, { - "executable": "dsc", - "args": [ - "config", - "validate" - ] + "required": [ + "input" + ], + "properties": { + "args": { + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } } ] } diff --git a/schemas/src/definitions/commandArgs.yaml b/schemas/src/definitions/commandArgs.yaml index 815f746ab..9411c1cd5 100644 --- a/schemas/src/definitions/commandArgs.yaml +++ b/schemas/src/definitions/commandArgs.yaml @@ -4,7 +4,92 @@ $id: ///definitions/commandArgs.yaml title: Executable Command Arguments description: >- - The list of arguments to pass to the command. + The list of arguments to pass to the command. The arguments can be any number of strings. If you + want to pass the JSON object representing the property bag for the resource to an argument, you + can define a single item in the array as a JSON object, indicating the name of the argument with + the `jsonInputArg` string property and whether the argument is mandatory for the command with the + `mandatory` boolean property. type: array items: - type: string + defaultSnippets: + - label: String argument + markdownDescription: |- + Add a string argument to the command, like `config` or `--config`. + body: ${1:argument_name} + - label: JSON input argument + markdownDescription: |- + Add a JSON input argument to the command. A command can only define one JSON input argument + in the `args` list. When you define a JSON input argument, DSC passes the input data for + the command to the specified argument as a string representing the data as a compressed + JSON object. The compressed JSON object doesn't have any spaces or newlines between the + object properties and values. + + If the command doesn't define the `input` property, it must define a JSON input argument. + + If the command defines both the `input` property and a JSON input argument, DSC sends the + input data to the command in both ways. For example, if the command defines `input` as + `stdin` and has a JSON input argument in `args`, DSC sends the input data as a compressed + JSON object over stdin and to the the specified argument. + body: + jsonInputArg: ${1:argument_name} + mandatory: ^$2 + oneOf: + - type: string + title: String argument + description: >- + Any item in the argument array can be a string representing a static argument to pass to + the command. + markdownDescription: | + Any item in the argument array can be a string representing a static argument to pass to + the command. + - type: object + title: JSON input argument + description: >- + Defines an argument for the command that accepts the JSON input object as a string. DSC + passes the JSON input to the named argument when available. You can define the `mandatory` + property to indicate whether DSC should always pass the argument to the command, even when + there's no JSON input for the command. In that case, DSC passes an empty string to the + JSON input argument. You can only define one JSON input argument per arguments array. + markdownDescription: | + Defines an argument for the command that accepts the JSON input object as a string. DSC + passes the JSON input to the named argument when available. You can define the `mandatory` + property to indicate whether DSC should always pass the argument to the command, even when + there's no JSON input for the command. In that case, DSC passes an empty string to the + JSON input argument. You can only define one JSON input argument per arguments array. + + If you define a JSON input argument and an `input` kind for a command, DSC sends the JSON + data both ways: + + - If you define `input` as `env` and a JSON input argument, DSC sets an environment variable + for each property in the JSON input and passes the JSON input object as a string to the + defined argument. + - If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over + stdin and as a string to the defined argument. + - If you define a JSON input argument without defining the `input` property, DSC only passes + the JSON input as a string to the defined argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't + pass the input JSON to the resource. This makes the manifest invalid. You must define the + `input` property, a JSON input argument in the `args` property array, or both. + + required: + - jsonInputArg + unevaluatedProperties: false + properties: + jsonInputArg: + title: JSON input argument name + description: >- + Defines the argument that accepts the JSON property bag for the resource as input. + markdownDescription: | + Defines the argument that accepts the JSON property bag for the resource as input. + type: string + mandatory: + title: Mandatory argument + description: >- + Defines whether the argument is mandatory. If this property is set to `true`, DSC + passes an empty string when no JSON input is provided. The default value is `false`. + markdownDescription: | + Defines whether the argument is mandatory. If this property is set to `true`, DSC + passes an empty string when no JSON input is provided. The default value is `false`. + type: boolean + default: false diff --git a/schemas/src/resource/manifest.adapter.yaml b/schemas/src/resource/manifest.adapter.yaml index 39cf0f938..663ae54f1 100644 --- a/schemas/src/resource/manifest.adapter.yaml +++ b/schemas/src/resource/manifest.adapter.yaml @@ -51,7 +51,13 @@ properties: [01]: /reference/schemas/resource/manifest/adapter?#executable args: - $ref: ///definitions/commandArgs.yaml + type: array + items: + type: string + title: Command arguments + description: >- + Defines the list of arguments to pass to the command to return the list of supported DSC + Resources. markdownDescription: | *** [_Online Documentation_][01] @@ -128,7 +134,7 @@ defaultSnippets: # VS Code only Define the adapter config kind and `list` command for the resource when no arguments are required. body: - config: $1 + config: ${1|full,sequence} list: executable: ${2:executable_name} @@ -137,7 +143,7 @@ defaultSnippets: # VS Code only Define the adapter config kind and `list` command for the resource when at least one argument is required. body: - config: $1 + config: ${1|full,sequence} list: executable: ${2:executable_name} args: diff --git a/schemas/src/resource/manifest.delete.yaml b/schemas/src/resource/manifest.delete.yaml index 710c49300..4484b5c4f 100644 --- a/schemas/src/resource/manifest.delete.yaml +++ b/schemas/src/resource/manifest.delete.yaml @@ -24,6 +24,21 @@ markdownDescription: | # VS Code only If you define the delete method in a resource manifest, ensure that you also define the [`_exist`][02] property in the [JSON schema for the resource's properties][04]. + DSC sends data to the command in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't pass + the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or + both. + [01]: /reference/schemas/resource/manifest/delete? [02]: /reference/schemas/resource/properties/exist? [03]: /reference/schemas/resource/manifest/set?#handlesExist @@ -32,7 +47,6 @@ markdownDescription: | # VS Code only type: object required: - executable - - input properties: executable: $ref: ///definitions/commandExecutable.yaml @@ -61,7 +75,7 @@ properties: ```json { - "executable": "registry", + "executable": "myresource", "args": ["config", "delete"] } ``` @@ -69,7 +83,35 @@ properties: DSC invokes the command for the resource as: ```bash - registry config delete + myresource config delete + ``` + + If you want to pass the JSON object representing the property bag for a resource instance to + an argument, you can define a single item in the array as a JSON object. Indicate the name of + the argument with the `jsonInputArg` string property and whether the argument is mandatory + for the command with the `mandatory` boolean property.` When the `mandatory` property is + defined as `true`, DSC passes an empty string to the argument when no JSON input is + available. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass + the argument at all when no JSON input is available. The default value for the `mandatory` + property is `false`. + + For example, given the following definition: + + ```json + { + "executable": "myresource" + "args": [ + "config", + "set", + { "jsonInputArg": "--properties" } + ] + } + ``` + + DSC invokes the command for the resource as: + + ```bash + myresource config set --properties ``` [01]: /reference/schemas/resource/manifest/delete?#args @@ -81,33 +123,89 @@ properties: *** Defines how DSC should pass input to the command, either as environment variables or JSON - over `stdin`. + over `stdin`. This property is optional when you define an object in the `args` list. If + you define a JSON input argument and an `input`, DSC sends the JSON data both ways: + + - If you define `input` as `env` and a JSON input argument, DSC sets an environment variable + for each property in the JSON input and passes the JSON input object as a string to the + defined argument. + - If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over + stdin and as a string to the defined argument. + - If you define a JSON input argument without defining the `input` property, DSC only passes + the JSON input as a string to the defined argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't + pass the input JSON to the resource. This makes the manifest invalid. You must define the + `input` property, a JSON input argument in the `args` property array, or both. [01]: /reference/schemas/resource/manifest/delete?#input -examples: - - executable: registry - args: - - config - - delete - - --input - - '{json}' - input: - arg: '{json}' +# Need to use a oneOf with three possibilities because YAML extension in VS Code doesn't understand +# minContains - so we can't use a single if/else/then. Note that JSON, but not YAML, will fail when +# the manifest defines more than one JSON input argument. If/when the YAML extension is updated to +# support 2019-09 and later, we can simplify this to two schemas. +# +# We use long lines for error messages, which can't use Markdown. +oneOf: + - # Delete command with explicit input kind - when `input` is defined and `args` is only strings. + # This subschema never triggers an error in testing. + required: [input] + not: + properties: { args: { contains: { type: object } } } + - # Delete command with JSON input argument - when `input` isn't defined and `args` doesn't include + # a JSON input argument. Only raises an error when `args` has zero JSON input arguments or more + # than one. + not: { required: [input] } + properties: + args: + errorMessage: |- + The `delete` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see: + + /reference/schemas/resource/manifest/delete? + contains: { type: object } + minContains: 1 + maxContains: 1 + - # Delete command with explicit input kind and JSON input argument - when `input` is defined and + # args includes a JSON input argument. Only raises an error when `input` is defined and `args` + # contains more than one JSON input argument. + required: [input] + properties: + args: + errorMessage: |- + You can only specify one JSON input argument for the `delete` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument. + + For more information, see: + + /reference/schemas/resource/manifest/delete? + contains: { type: object } + minContains: 1 + maxContains: 1 defaultSnippets: # VS Code only - label: ' Define without arguments' markdownDescription: | - Define the `validate` command for the resource when no arguments are required. + Define the `delete` command for the resource when no arguments are required and the JSON + input is sent over stdin or as environment variables. body: - executable: ${1:executable_name} - input: ${2:stdin} - - - label: ' Define with arguments' - markdownDescription: | - Define the `validate` command for the resource when at least one argument is required. + input: ${1|stdin,env|} + executable: ${2:executable_name} + - label: ' Define with string arguments' + markdownDescription: |- + Define the `delete` command for the resource when at least one argument is required and the + JSON input is sent over stdin or as environment variables. + body: + input: ${1|stdin,env|} + executable: ${2:executable_name} + args: + - ${3:--first-argument} + - label: ' Define with a JSON input argument' + markdownDescription: |- + Define the `delete` command for the resource where the JSON input is passed as a one-line + JSON object string to the specified argument. body: executable: ${1:executable_name} args: - - ${2:--first-argument} - input: ${3:stdin} + - jsonInputArg: ${2:argument_name} + mandatory: ^$3 diff --git a/schemas/src/resource/manifest.export.yaml b/schemas/src/resource/manifest.export.yaml index 97da24408..28ea53875 100644 --- a/schemas/src/resource/manifest.export.yaml +++ b/schemas/src/resource/manifest.export.yaml @@ -2,7 +2,7 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: ///resource/manifest.export.yaml -title: Get Method +title: Export Method description: >- Defines how DSC must call the DSC Resource to get the current state of every instance. markdownDescription: | # VS Code only @@ -12,6 +12,21 @@ markdownDescription: | # VS Code only Defines how DSC must call the DSC Resource to get the current state of every instance. + DSC sends data to the command in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't pass + the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or + both. + [01]: /reference/schemas/resource/manifest/export? type: object @@ -45,7 +60,7 @@ properties: ```json { - "executable": "registry", + "executable": "myresource", "args": ["config", "export"], } ``` @@ -53,22 +68,129 @@ properties: DSC invokes the command for the resource as: ```bash - registry config export + myresource config export + ``` + + If you want to pass the JSON object representing the property bag for a resource instance to + an argument, you can define a single item in the array as a JSON object. Indicate the name of + the argument with the `jsonInputArg` string property and whether the argument is mandatory + for the command with the `mandatory` boolean property.` When the `mandatory` property is + defined as `true`, DSC passes an empty string to the argument when no JSON input is + available. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass + the argument at all when no JSON input is available. The default value for the `mandatory` + property is `false`. + + For example, given the following definition: + + ```json + { + "executable": "myresource" + "args": [ + "config", + "export", + { "jsonInputArg": "--properties" } + ] + } + ``` + + DSC invokes the command for the resource as: + + ```bash + myresource config export --properties ``` [01]: /reference/schemas/resource/manifest/export?#args + input: + $ref: ///definitions/inputKind.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines how DSC should pass input to the command, either as environment variables or JSON + over `stdin`. This property is optional when you define an object in the `args` list. If + you define a JSON input argument and an `input`, DSC sends the JSON data both ways: + + - If you define `input` as `env` and a JSON input argument, DSC sets an environment variable + for each property in the JSON input and passes the JSON input object as a string to the + defined argument. + - If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over + stdin and as a string to the defined argument. + - If you define a JSON input argument without defining the `input` property, DSC only passes + the JSON input as a string to the defined argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't + pass the input JSON to the resource. This makes the manifest invalid. You must define the + `input` property, a JSON input argument in the `args` property array, or both. + + [01]: /reference/schemas/resource/manifest/export?#input + +# Need to use a oneOf with three possibilities because YAML extension in VS Code doesn't understand +# minContains - so we can't use a single if/else/then. Note that JSON, but not YAML, will fail when +# the manifest defines more than one JSON input argument. If/when the YAML extension is updated to +# support 2019-09 and later, we can simplify this to two schemas. +# +# We use long lines for error messages, which can't use Markdown. +oneOf: + - # Export command with explicit input kind - when `input` is defined and `args` is only strings. + # This subschema never triggers an error in testing. + required: [input] + not: + properties: { args: { contains: { type: object } } } + - # Export command with JSON input argument - when `input` isn't defined and `args` doesn't include + # a JSON input argument. Only raises an error when `args` has zero JSON input arguments or more + # than one. + not: { required: [input] } + properties: + args: + errorMessage: |- + The `export` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see: + + /reference/schemas/resource/manifest/export? + contains: { type: object } + minContains: 1 + maxContains: 1 + - # Export command with explicit input kind and JSON input argument - when `input` is defined and + # args includes a JSON input argument. Only raises an error when `input` is defined and `args` + # contains more than one JSON input argument. + required: [input] + properties: + args: + errorMessage: |- + You can only specify one JSON input argument for the `export` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument. + + For more information, see: + + /reference/schemas/resource/manifest/export? + contains: { type: object } + minContains: 1 + maxContains: 1 defaultSnippets: # VS Code only - label: ' Define without arguments' markdownDescription: | - Define the export command for the resource when no arguments are required. + Define the `export` command for the resource when no arguments are required and the JSON + input is sent over stdin or as environment variables. body: - executable: ${1:executable_name} - - - label: ' Define with arguments' - markdownDescription: | - Define the export command for the resource when at least one argument is required. + input: ${1|stdin,env|} + executable: ${2:executable_name} + - label: ' Define with string arguments' + markdownDescription: |- + Define the `export` command for the resource when at least one argument is required and the + JSON input is sent over stdin or as environment variables. + body: + input: ${1|stdin,env|} + executable: ${2:executable_name} + args: + - ${3:--first-argument} + - label: ' Define with a JSON input argument' + markdownDescription: |- + Define the `export` command for the resource where the JSON input is passed as a one-line + JSON object string to the specified argument. body: executable: ${1:executable_name} args: - - ${2:--first-argument} + - jsonInputArg: ${2:argument_name} + mandatory: ^3 diff --git a/schemas/src/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml index b84c7682d..873e43673 100644 --- a/schemas/src/resource/manifest.get.yaml +++ b/schemas/src/resource/manifest.get.yaml @@ -11,6 +11,21 @@ markdownDescription: | # VS Code only *** Defines how DSC must call the DSC Resource to get the current state of an instance. + + DSC sends data to the command in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't pass + the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or + both. [01]: /reference/schemas/resource/manifest/get? @@ -45,7 +60,7 @@ properties: ```json { - "executable": "registry", + "executable": "myresource", "args": ["config", "get"], } ``` @@ -53,7 +68,35 @@ properties: DSC invokes the command for the resource as: ```bash - registry config get + myresource config get + ``` + + If you want to pass the JSON object representing the property bag for a resource instance to + an argument, you can define a single item in the array as a JSON object. Indicate the name of + the argument with the `jsonInputArg` string property and whether the argument is mandatory + for the command with the `mandatory` boolean property. When the `mandatory` property is + defined as `true`, DSC passes an empty string to the argument when no JSON input is + available. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass + the argument at all when no JSON input is available. The default value for the `mandatory` + property is `false`. + + For example, given the following definition: + + ```json + { + "executable": "myresource" + "args": [ + "config", + "get", + { "jsonInputArg": "--properties" } + ] + } + ``` + + DSC invokes the command for the resource as: + + ```bash + myresource config get --properties ``` [01]: /reference/schemas/resource/manifest/get?#args @@ -65,32 +108,89 @@ 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 `get` operation. + over `stdin`. This property is optional when you define an object in the `args` list. If + you define a JSON input argument and an `input`, DSC sends the JSON data both ways: + + - If you define `input` as `env` and a JSON input argument, DSC sets an environment variable + for each property in the JSON input and passes the JSON input object as a string to the + defined argument. + - If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over + stdin and as a string to the defined argument. + - If you define a JSON input argument without defining the `input` property, DSC only passes + the JSON input as a string to the defined argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't + pass the input JSON to the resource. This makes the manifest invalid. You must define the + `input` property, a JSON input argument in the `args` property array, or both. [01]: /reference/schemas/resource/manifest/get?#input -examples: - - executable: registry - args: - - config - - get - input: stdin - - executable: osinfo +# Need to use a oneOf with three possibilities because YAML extension in VS Code doesn't understand +# minContains - so we can't use a single if/else/then. Note that JSON, but not YAML, will fail when +# the manifest defines more than one JSON input argument. If/when the YAML extension is updated to +# support 2019-09 and later, we can simplify this to two schemas. +# +# We use long lines for error messages, which can't use Markdown. +oneOf: + - # Get command with explicit input kind - when `input` is defined and `args` is only strings. + # This subschema never triggers an error in testing. + required: [input] + not: + properties: { args: { contains: { type: object } } } + - # Get command with JSON input argument - when `input` isn't defined and `args` doesn't include + # a JSON input argument. Only raises an error when `args` has zero JSON input arguments or more + # than one. + not: { required: [input] } + properties: + args: + errorMessage: |- + The `get` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see: + + /reference/schemas/resource/manifest/get? + contains: { type: object } + minContains: 1 + maxContains: 1 + - # Get command with explicit input kind and JSON input argument - when `input` is defined and + # args includes a JSON input argument. Only raises an error when `input` is defined and `args` + # contains more than one JSON input argument. + required: [input] + properties: + args: + errorMessage: |- + You can only specify one JSON input argument for the `get` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument. + + For more information, see: + + /reference/schemas/resource/manifest/get? + contains: { type: object } + minContains: 1 + maxContains: 1 defaultSnippets: # VS Code only - label: ' Define without arguments' markdownDescription: | - Define the get command for the resource when no arguments are required. + Define the `get` command for the resource when no arguments are required and the JSON + input is sent over stdin or as environment variables. body: input: ${1|stdin,env|} executable: ${2:executable_name} - - - label: ' Define with arguments' - markdownDescription: | - Define the get command for the resource when at least one argument is required. + - label: ' Define with string arguments' + markdownDescription: |- + Define the `get` command for the resource when at least one argument is required and the + JSON input is sent over stdin or as environment variables. body: input: ${1|stdin,env|} executable: ${2:executable_name} args: - ${3:--first-argument} + - label: ' Define with a JSON input argument' + markdownDescription: |- + Define the `get` command for the resource where the JSON input is passed as a one-line + JSON object string to the specified argument. + body: + executable: ${1:executable_name} + args: + - jsonInputArg: ${2:argument_name} + mandatory: ^$3 diff --git a/schemas/src/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml index 3e52770db..6041ca9a8 100644 --- a/schemas/src/resource/manifest.schema.yaml +++ b/schemas/src/resource/manifest.schema.yaml @@ -37,9 +37,15 @@ properties: is only required when the command isn't recognizable by the operating system as an executable. - [01]: /reference/schemas/resource/manifest/set?#executable + [01]: /reference/schemas/resource/manifest/schema/property?#executable args: - $ref: ///definitions/commandArgs.yaml + type: array + items: + type: string + title: Command arguments + description: >- + Defines the list of arguments to pass to the command to return the JSON Schema for the + resource. markdownDescription: | *** [_Online Documentation_][01] @@ -52,18 +58,19 @@ properties: ```json { - "executable": "registry", - "args": ["schema", "resource"], + "executable": "myresource", + "args": ["schema", "show"], } ``` DSC invokes the command for the resource as: ```bash - registry schema resource + myresource schema show ``` - [01]: /reference/schemas/resource/manifest/set?#args + [01]: /reference/schemas/resource/manifest/schema/property?#args + # VS Code only markdownDescription: | *** diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 8bdf233cd..93a6fadb8 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -14,12 +14,26 @@ markdownDescription: | # VS Code only 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. + DSC sends data to the command in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't pass + the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or + both. + [01]: /reference/schemas/resource/manifest/set? type: object required: - executable - - input properties: executable: $ref: ///definitions/commandExecutable.yaml @@ -48,7 +62,7 @@ properties: ```json { - "executable": "registry", + "executable": "myresource", "args": ["config", "set"], } ``` @@ -56,7 +70,35 @@ properties: DSC invokes the command for the resource as: ```bash - registry config set + myresource config set + ``` + + If you want to pass the JSON object representing the property bag for a resource instance to + an argument, you can define a single item in the array as a JSON object. Indicate the name of + the argument with the `jsonInputArg` string property and whether the argument is mandatory + for the command with the `mandatory` boolean property.` When the `mandatory` property is + defined as `true`, DSC passes an empty string to the argument when no JSON input is + available. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass + the argument at all when no JSON input is available. The default value for the `mandatory` + property is `false`. + + For example, given the following definition: + + ```json + { + "executable": "myresource" + "args": [ + "config", + "set", + { "jsonInputArg": "--properties" } + ] + } + ``` + + DSC invokes the command for the resource as: + + ```bash + myresource config set --properties ``` [01]: /reference/schemas/resource/manifest/set?#args @@ -68,7 +110,20 @@ properties: *** Defines how DSC should pass input to the command, either as environment variables or JSON - over `stdin`. + over `stdin`. This property is optional when you define an object in the `args` list. If + you define a JSON input argument and an `input`, DSC sends the JSON data both ways: + + - If you define `input` as `env` and a JSON input argument, DSC sets an environment variable + for each property in the JSON input and passes the JSON input object as a string to the + defined argument. + - If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over + stdin and as a string to the defined argument. + - If you define a JSON input argument without defining the `input` property, DSC only passes + the JSON input as a string to the defined argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't + pass the input JSON to the resource. This makes the manifest invalid. You must define the + `input` property, a JSON input argument in the `args` property array, or both. [01]: /reference/schemas/resource/manifest/set?#input implementsPretest: @@ -137,32 +192,78 @@ properties: > Indicates that the resource returns the instance's final state and an array of property > names that the resource modified. -examples: - - executable: registry - args: - - config - - set - input: stdin - implementsPretest: true - return: state +# Need to use a oneOf with three possibilities because YAML extension in VS Code doesn't understand +# minContains - so we can't use a single if/else/then. Note that JSON, but not YAML, will fail when +# the manifest defines more than one JSON input argument. If/when the YAML extension is updated to +# support 2019-09 and later, we can simplify this to two schemas. +# +# We use long lines for error messages, which can't use Markdown. +oneOf: + - # Set command with explicit input kind - when `input` is defined and `args` is only strings. + # This subschema never triggers an error in testing. + required: [input] + not: + properties: { args: { contains: { type: object } } } + - # Set command with JSON input argument - when `input` isn't defined and `args` doesn't include + # a JSON input argument. Only raises an error when `args` has zero JSON input arguments or more + # than one. + not: { required: [input] } + properties: + args: + errorMessage: |- + The `set` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see: + + /reference/schemas/resource/manifest/set? + contains: { type: object } + minContains: 1 + maxContains: 1 + - # Set command with explicit input kind and JSON input argument - when `input` is defined and + # args includes a JSON input argument. Only raises an error when `input` is defined and `args` + # contains more than one JSON input argument. + required: [input] + properties: + args: + errorMessage: |- + You can only specify one JSON input argument for the `set` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument. + + For more information, see: + + /reference/schemas/resource/manifest/set? + contains: { type: object } + minContains: 1 + maxContains: 1 defaultSnippets: # VS Code only - label: ' Define without arguments' markdownDescription: | - Define the `set` command for the resource when no arguments are required. + Define the `set` command for the resource when no arguments are required and the JSON + input is sent over stdin or as environment variables. body: - input: ${1|input,env|} + input: ${1|stdin,env|} implementsPretest: ^${2|true,false|} return: ${3|state,stateAndDiff|} executable: ${4:executable_name} - - - label: ' Define with arguments' - markdownDescription: | - Define the `set` command for the resource when at least one argument is required. + - label: ' Define with string arguments' + markdownDescription: |- + Define the `set` command for the resource when at least one argument is required and the + JSON input is sent over stdin or as environment variables. body: - input: ${1|input,env|} + input: ${1|stdin,env|} implementsPretest: ^${2|true,false|} return: ${3|state,stateAndDiff|} executable: ${4:executable_name} args: - ${5:--first-argument} + - label: ' Define with a JSON input argument' + markdownDescription: |- + Define the `set` command for the resource where the JSON input is passed as a one-line + JSON object string to the specified argument. + body: + implementsPretest: ^${1|true,false|} + return: ${2|state,stateAndDiff|} + executable: ${3:executable_name} + args: + - jsonInputArg: ${4:argument_name} + mandatory: ^$5 diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index 99e68138c..d0325a1e2 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -14,13 +14,27 @@ markdownDescription: | # VS Code only 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. + DSC sends data to the command in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't pass + the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or + both. + [01]: /reference/schemas/resource/manifest/test? type: object required: - executable - - input properties: executable: $ref: ///definitions/commandExecutable.yaml @@ -34,7 +48,7 @@ properties: is only required when the command isn't recognizable by the operating system as an executable. - [01]: /reference/schemas/resource/manifest/set?#executable + [01]: /reference/schemas/resource/manifest/test?#executable args: $ref: ///definitions/commandArgs.yaml markdownDescription: | @@ -49,7 +63,7 @@ properties: ```json { - "executable": "registry", + "executable": "myresource", "args": ["config", "test"], } ``` @@ -57,10 +71,38 @@ properties: DSC invokes the command for the resource as: ```bash - registry config test + myresource config test ``` - [01]: /reference/schemas/resource/manifest/set?#args + If you want to pass the JSON object representing the property bag for a resource instance to + an argument, you can define a single item in the array as a JSON object. Indicate the name of + the argument with the `jsonInputArg` string property and whether the argument is mandatory + for the command with the `mandatory` boolean property.` When the `mandatory` property is + defined as `true`, DSC passes an empty string to the argument when no JSON input is + available. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass + the argument at all when no JSON input is available. The default value for the `mandatory` + property is `false`. + + For example, given the following definition: + + ```json + { + "executable": "myresource" + "args": [ + "config", + "test", + { "jsonInputArg": "--properties" } + ] + } + ``` + + DSC invokes the command for the resource as: + + ```bash + myresource config test --properties + ``` + + [01]: /reference/schemas/resource/manifest/test?#args input: $ref: ///definitions/inputKind.yaml markdownDescription: | @@ -69,9 +111,22 @@ properties: *** Defines how DSC should pass input to the command, either as environment variables or JSON - over `stdin`. - - [01]: /reference/schemas/resource/manifest/set?#input + over `stdin`. This property is optional when you define an object in the `args` list. If + you define a JSON input argument and an `input`, DSC sends the JSON data both ways: + + - If you define `input` as `env` and a JSON input argument, DSC sets an environment variable + for each property in the JSON input and passes the JSON input object as a string to the + defined argument. + - If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over + stdin and as a string to the defined argument. + - If you define a JSON input argument without defining the `input` property, DSC only passes + the JSON input as a string to the defined argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't + pass the input JSON to the resource. This makes the manifest invalid. You must define the + `input` property, a JSON input argument in the `args` property array, or both. + + [01]: /reference/schemas/resource/manifest/test?#input return: title: Test Command Return Type description: >- @@ -99,29 +154,75 @@ 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 - args: - - config - - test - input: stdin - return: state +# Need to use a oneOf with three possibilities because YAML extension in VS Code doesn't understand +# minContains - so we can't use a single if/else/then. Note that JSON, but not YAML, will fail when +# the manifest defines more than one JSON input argument. If/when the YAML extension is updated to +# support 2019-09 and later, we can simplify this to two schemas. +# +# We use long lines for error messages, which can't use Markdown. +oneOf: + - # Test command with explicit input kind - when `input` is defined and `args` is only strings. + # This subschema never triggers an error in testing. + required: [input] + not: + properties: { args: { contains: { type: object } } } + - # Test command with JSON input argument - when `input` isn't defined and `args` doesn't include + # a JSON input argument. Only raises an error when `args` has zero JSON input arguments or more + # than one. + not: { required: [input] } + properties: + args: + errorMessage: |- + The `test` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see: + + /reference/schemas/resource/manifest/test? + contains: { type: object } + minContains: 1 + maxContains: 1 + - # Test command with explicit input kind and JSON input argument - when `input` is defined and + # args includes a JSON input argument. Only raises an error when `input` is defined and `args` + # contains more than one JSON input argument. + required: [input] + properties: + args: + errorMessage: |- + You can only specify one JSON input argument for the `test` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument. + + For more information, see: + + /reference/schemas/resource/manifest/test? + contains: { type: object } + minContains: 1 + maxContains: 1 defaultSnippets: # VS Code only - label: ' Define without arguments' markdownDescription: | - Define the `test` command for the resource when no arguments are required. + Define the `test` command for the resource when no arguments are required and the JSON + input is sent over stdin or as environment variables. body: - input: ${1|input,env|} + input: ${1|stdin,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. + - label: ' Define with string arguments' + markdownDescription: |- + Define the `test` command for the resource when at least one argument is required and the + JSON input is sent over stdin or as environment variables. body: - input: ${1|input,env|} + input: ${1|stdin,env|} return: ${2|state,stateAndDiff|} executable: ${3:executable_name} args: - ${4:--first-argument} + - label: ' Define with a JSON input argument' + markdownDescription: |- + Define the `test` command for the resource where the JSON input is passed as a one-line + JSON object string to the specified argument. + body: + return: ${1|state,stateAndDiff|} + executable: ${2:executable_name} + args: + - jsonInputArg: ${3:argument_name} + mandatory: ^$4 diff --git a/schemas/src/resource/manifest.validate.yaml b/schemas/src/resource/manifest.validate.yaml index f40bdacc6..764f8bdae 100644 --- a/schemas/src/resource/manifest.validate.yaml +++ b/schemas/src/resource/manifest.validate.yaml @@ -15,6 +15,21 @@ markdownDescription: | # VS Code only 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. + DSC sends data to the command in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't pass + the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or + both. + [01]: /reference/schemas/resource/manifest/validate? type: object @@ -33,7 +48,7 @@ properties: is only required when the command isn't recognizable by the operating system as an executable. - [01]: /reference/schemas/resource/manifest/set?#executable + [01]: /reference/schemas/resource/manifest/validate?#executable args: $ref: ///definitions/commandArgs.yaml markdownDescription: | @@ -48,7 +63,7 @@ properties: ```json { - "executable": "registry", + "executable": "myresource", "args": ["config", "validate"], } ``` @@ -56,28 +71,129 @@ properties: DSC invokes the command for the resource as: ```bash - registry config validate + myresource config validate ``` - [01]: /reference/schemas/resource/manifest/set?#args + If you want to pass the JSON object representing the property bag for a resource instance to + an argument, you can define a single item in the array as a JSON object. Indicate the name of + the argument with the `jsonInputArg` string property and whether the argument is mandatory + for the command with the `mandatory` boolean property.` When the `mandatory` property is + defined as `true`, DSC passes an empty string to the argument when no JSON input is + available. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass + the argument at all when no JSON input is available. The default value for the `mandatory` + property is `false`. -examples: - - executable: dsc - args: - - config - - validate + For example, given the following definition: + + ```json + { + "executable": "myresource" + "args": [ + "config", + "validate", + { "jsonInputArg": "--properties" } + ] + } + ``` + + DSC invokes the command for the resource as: + + ```bash + myresource config validate --properties + ``` + + [01]: /reference/schemas/resource/manifest/validate?#args + input: + $ref: ///definitions/inputKind.yaml + markdownDescription: | + *** + [_Online Documentation_][01] + *** + + Defines how DSC should pass input to the command, either as environment variables or JSON + over `stdin`. This property is optional when you define an object in the `args` list. If + you define a JSON input argument and an `input`, DSC sends the JSON data both ways: + + - If you define `input` as `env` and a JSON input argument, DSC sets an environment variable + for each property in the JSON input and passes the JSON input object as a string to the + defined argument. + - If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over + stdin and as a string to the defined argument. + - If you define a JSON input argument without defining the `input` property, DSC only passes + the JSON input as a string to the defined argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't + pass the input JSON to the resource. This makes the manifest invalid. You must define the + `input` property, a JSON input argument in the `args` property array, or both. + + [01]: /reference/schemas/resource/manifest/validate?#input + +# Need to use a oneOf with three possibilities because YAML extension in VS Code doesn't understand +# minContains - so we can't use a single if/else/then. Note that JSON, but not YAML, will fail when +# the manifest defines more than one JSON input argument. If/when the YAML extension is updated to +# support 2019-09 and later, we can simplify this to two schemas. +# +# We use long lines for error messages, which can't use Markdown. +oneOf: + - # Validate command with explicit input kind - when `input` is defined and `args` is only strings. + # This subschema never triggers an error in testing. + required: [input] + not: + properties: { args: { contains: { type: object } } } + - # Validate command with JSON input argument - when `input` isn't defined and `args` doesn't include + # a JSON input argument. Only raises an error when `args` has zero JSON input arguments or more + # than one. + not: { required: [input] } + properties: + args: + errorMessage: |- + The `validate` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command. + + You must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see: + + /reference/schemas/resource/manifest/validate? + contains: { type: object } + minContains: 1 + maxContains: 1 + - # Validate command with explicit input kind and JSON input argument - when `input` is defined and + # args includes a JSON input argument. Only raises an error when `input` is defined and `args` + # contains more than one JSON input argument. + required: [input] + properties: + args: + errorMessage: |- + You can only specify one JSON input argument for the `validate` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument. + + For more information, see: + + /reference/schemas/resource/manifest/validate? + contains: { type: object } + minContains: 1 + maxContains: 1 defaultSnippets: # VS Code only - label: ' Define without arguments' markdownDescription: | - Define the `validate` command for the resource when no arguments are required. + Define the `validate` command for the resource when no arguments are required and the JSON + input is sent over stdin or as environment variables. body: - executable: ${1:executable_name} - - - label: ' Define with arguments' - markdownDescription: | - Define the `validate` command for the resource when at least one argument is required. + input: ${1|stdin,env|} + executable: ${2:executable_name} + - label: ' Define with string arguments' + markdownDescription: |- + Define the `validate` command for the resource when at least one argument is required and the + JSON input is sent over stdin or as environment variables. + body: + input: ${1|stdin,env|} + executable: ${2:executable_name} + args: + - ${3:--first-argument} + - label: ' Define with a JSON input argument' + markdownDescription: |- + Define the `validate` command for the resource where the JSON input is passed as a one-line + JSON object string to the specified argument. body: executable: ${1:executable_name} args: - - ${2:--first-argument} + - jsonInputArg: ${2:argument_name} + mandatory: ^$3 From 14a6fdd197944537cf6b6773598a67e621f6df77 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Tue, 16 Apr 2024 15:49:04 -0500 Subject: [PATCH 13/15] (SCHEMA) Update schemas for `metadata` in output This changes defines the metadata properties that DSC returns in the results for the `dsc config *` commands, as implemented in #405. It defines each metadata property as a separate file in a new folder for metadata schemas for easier reuse, as well as two definitions of the `metadata` property used across different result objects, one for the top-level of a configuration and one for resource instances in that result. This change also required a minor fix to the build script to account for array items that are objects solely defined by a `$ref` keyword and to find and compose schemas from the new `metadata` folder. The change includes the rename for the `requiredSecurityContext` metadata property to `securityContext`. --- schemas/2024/04/bundled/config/document.json | 22 ++- .../04/bundled/config/document.vscode.json | 27 ++- .../2024/04/bundled/outputs/config/get.json | 158 ++++++++++++++++++ .../2024/04/bundled/outputs/config/set.json | 158 ++++++++++++++++++ .../2024/04/bundled/outputs/config/test.json | 158 ++++++++++++++++++ .../2024/04/bundled/outputs/resource/get.json | 37 ++++ .../2024/04/bundled/outputs/resource/set.json | 37 ++++ .../04/bundled/outputs/resource/test.json | 37 ++++ schemas/2024/04/config/document.metadata.json | 10 +- .../04/metadata/Microsoft.DSC/duration.json | 8 + .../metadata/Microsoft.DSC/endDatetime.json | 8 + .../metadata/Microsoft.DSC/executionType.json | 11 ++ .../04/metadata/Microsoft.DSC/operation.json | 13 ++ .../Microsoft.DSC/securityContext.json | 12 ++ .../metadata/Microsoft.DSC/startDatetime.json | 8 + .../04/metadata/Microsoft.DSC/version.json | 7 + .../metadata/configurationDocumentResult.json | 49 ++++++ .../04/metadata/resourceInstanceResult.json | 25 +++ schemas/2024/04/outputs/config/get.json | 4 + schemas/2024/04/outputs/config/set.json | 4 + schemas/2024/04/outputs/config/test.json | 4 + .../2024/04/outputs/resource/get.full.json | 4 + .../2024/04/outputs/resource/set.full.json | 4 + .../2024/04/outputs/resource/test.full.json | 4 + schemas/build.ps1 | 6 +- schemas/src/config/document.metadata.yaml | 9 +- .../src/metadata/Microsoft.DSC/duration.yaml | 19 +++ .../metadata/Microsoft.DSC/endDatetime.yaml | 18 ++ .../metadata/Microsoft.DSC/executionType.yaml | 18 ++ .../src/metadata/Microsoft.DSC/operation.yaml | 18 ++ .../Microsoft.DSC/securityContext.yaml | 21 +++ .../metadata/Microsoft.DSC/startDatetime.yaml | 18 ++ .../src/metadata/Microsoft.DSC/version.yaml | 13 ++ .../metadata/configurationDocumentResult.yaml | 47 ++++++ .../src/metadata/resourceInstanceResult.yaml | 28 ++++ schemas/src/outputs/config/get.yaml | 3 + schemas/src/outputs/config/set.yaml | 3 + schemas/src/outputs/config/test.yaml | 3 + schemas/src/outputs/resource/get.full.yaml | 5 +- schemas/src/outputs/resource/set.full.yaml | 5 +- schemas/src/outputs/resource/test.full.yaml | 5 +- 41 files changed, 1012 insertions(+), 36 deletions(-) create mode 100644 schemas/2024/04/metadata/Microsoft.DSC/duration.json create mode 100644 schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json create mode 100644 schemas/2024/04/metadata/Microsoft.DSC/executionType.json create mode 100644 schemas/2024/04/metadata/Microsoft.DSC/operation.json create mode 100644 schemas/2024/04/metadata/Microsoft.DSC/securityContext.json create mode 100644 schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json create mode 100644 schemas/2024/04/metadata/Microsoft.DSC/version.json create mode 100644 schemas/2024/04/metadata/configurationDocumentResult.json create mode 100644 schemas/2024/04/metadata/resourceInstanceResult.json create mode 100644 schemas/src/metadata/Microsoft.DSC/duration.yaml create mode 100644 schemas/src/metadata/Microsoft.DSC/endDatetime.yaml create mode 100644 schemas/src/metadata/Microsoft.DSC/executionType.yaml create mode 100644 schemas/src/metadata/Microsoft.DSC/operation.yaml create mode 100644 schemas/src/metadata/Microsoft.DSC/securityContext.yaml create mode 100644 schemas/src/metadata/Microsoft.DSC/startDatetime.yaml create mode 100644 schemas/src/metadata/Microsoft.DSC/version.yaml create mode 100644 schemas/src/metadata/configurationDocumentResult.yaml create mode 100644 schemas/src/metadata/resourceInstanceResult.yaml diff --git a/schemas/2024/04/bundled/config/document.json b/schemas/2024/04/bundled/config/document.json index a4af3ad61..f7f30849d 100644 --- a/schemas/2024/04/bundled/config/document.json +++ b/schemas/2024/04/bundled/config/document.json @@ -328,15 +328,9 @@ "description": "The `Microsoft.DSC` metadata property contains directives and information that DSC itself uses when processing a configuration document. Unlike other metadata key-value pairs, DSC validates these properties.", "unevaluatedProperties": false, "properties": { - "requiredSecurityContext": { - "type": "string", - "enum": [ - "Current", - "Elevated", - "Restricted" - ], + "securityContext": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", "default": "Current", - "title": "Required security context", "description": "This property defines the security context a configuration requires. If you invoke a DSC operation against the configuration document in a security context that conflicts with this metadata, DSC raises an error when it validates the configuration document.\nThe default security context is `Current`." } } @@ -387,6 +381,18 @@ "type": "string", "pattern": "^[a-zA-Z0-9 ]+$", "minLength": 1 + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", + "title": "Security context", + "description": "Defines the security context that DSC was run under. If the value for this metadata property is `Elevated`, DSC was run as root (non-Windows) or an elevated session with Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in a non-elevated session.", + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ] } } } diff --git a/schemas/2024/04/bundled/config/document.vscode.json b/schemas/2024/04/bundled/config/document.vscode.json index 34bbff866..3188fe437 100644 --- a/schemas/2024/04/bundled/config/document.vscode.json +++ b/schemas/2024/04/bundled/config/document.vscode.json @@ -484,15 +484,9 @@ "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThe `Microsoft.DSC` metadata property contains directives and information that DSC itself\nuses when processing a configuration document. Unlike other metadata key-value pairs, DSC\nvalidates these properties.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/metadata?view=dsc-3.0&preserve-view=true#microsoft.dsc\n", "unevaluatedProperties": false, "properties": { - "requiredSecurityContext": { - "type": "string", - "enum": [ - "Current", - "Elevated", - "Restricted" - ], + "securityContext": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", "default": "Current", - "title": "Required security context", "description": "This property defines the security context a configuration requires. If you invoke a DSC operation against the configuration document in a security context that conflicts with this metadata, DSC raises an error when it validates the configuration document.\nThe default security context is `Current`.", "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property defines the security context a configuration requires. If you invoke a DSC\noperation against the configuration document in a security context that conflicts with\nthis metadata, DSC raises an error when it validates the configuration document.\n\nThe default security context is `Current`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/config/metadata?view=dsc-3.0&preserve-view=true#microsoft.dsc\n", "markdownEnumDescriptions": [ @@ -597,6 +591,23 @@ "patternErrorMessage": "Invalid value for instance name. An instance name must be a non-empty string containing only\nletters, numbers, and spaces.\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" } + }, + "metadata": { + "Microsoft.DSC": { + "securityContext.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", + "title": "Security context", + "description": "Defines the security context that DSC was run under. If the value for this metadata property is `Elevated`, DSC was run as root (non-Windows) or an elevated session with Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in a non-elevated session.", + "markdownDescription": "Defines the security context that DSC was run under. If the value for this metadata property is\n`Elevated`, DSC was run as `root` (non-Windows) or an elevated session with Administrator\nprivileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in\na non-elevated session.", + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ] + } + } } } } diff --git a/schemas/2024/04/bundled/outputs/config/get.json b/schemas/2024/04/bundled/outputs/config/get.json index 93756eadc..012b8b7b1 100644 --- a/schemas/2024/04/bundled/outputs/config/get.json +++ b/schemas/2024/04/bundled/outputs/config/get.json @@ -5,11 +5,15 @@ "description": "Represents the data structure returned by the `dsc config get` command.", "type": "object", "required": [ + "metadata", "results", "messages", "hadErrors" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json" + }, "results": { "title": "Results", "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", @@ -26,6 +30,55 @@ } }, "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json", + "title": "Configuration result metadata", + "description": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of a DSC operation, including the version of DSC used, when the operation started and ended, and the security context the operation was invoked under.", + "type": "object", + "required": [ + "version", + "operation", + "executionType", + "startDatetime", + "endDatetime", + "duration", + "securityContext" + ], + "properties": { + "version": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json" + }, + "operation": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json" + }, + "executionType": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json" + }, + "startDatetime": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json" + }, + "endDatetime": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json" + }, + "duration": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + }, + "securityContext": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json" + } + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json", @@ -33,11 +86,15 @@ "description": "Describes the return data for the full result of the `get` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config get` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource get` command.", "type": "object", "required": [ + "metadata", "name", "result", "type" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, "name": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" }, @@ -66,6 +123,107 @@ "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", "type": "boolean" }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json", + "title": "DSC Version", + "description": "Defines the version of DSC that ran the command. This value is always the semantic version of the DSC command, like `3.0.0-preview.7`.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json", + "title": "Operation", + "description": "Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or `Export`.", + "type": "string", + "enum": [ + "Get", + "Set", + "Test", + "Export" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json", + "title": "Execution type", + "description": "Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument.", + "type": "string", + "enum": [ + "Actual", + "WhatIf" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json", + "title": "Start date and time", + "description": "Defines the start date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "type": "string", + "format": "date-time" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json", + "title": "Start date and time", + "description": "Defines the end date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "type": "string", + "format": "date-time" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", + "title": "Security context", + "description": "Defines the security context that DSC was run under. If the value for this metadata property is `Elevated`, DSC was run as root (non-Windows) or an elevated session with Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in a non-elevated session.", + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", diff --git a/schemas/2024/04/bundled/outputs/config/set.json b/schemas/2024/04/bundled/outputs/config/set.json index b9431577e..b6c85052e 100644 --- a/schemas/2024/04/bundled/outputs/config/set.json +++ b/schemas/2024/04/bundled/outputs/config/set.json @@ -5,11 +5,15 @@ "description": "Represents the data structure returned by the `dsc config set` command.", "type": "object", "required": [ + "metadata", "results", "messages", "hadErrors" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json" + }, "results": { "title": "Results", "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", @@ -26,6 +30,55 @@ } }, "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json", + "title": "Configuration result metadata", + "description": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of a DSC operation, including the version of DSC used, when the operation started and ended, and the security context the operation was invoked under.", + "type": "object", + "required": [ + "version", + "operation", + "executionType", + "startDatetime", + "endDatetime", + "duration", + "securityContext" + ], + "properties": { + "version": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json" + }, + "operation": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json" + }, + "executionType": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json" + }, + "startDatetime": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json" + }, + "endDatetime": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json" + }, + "duration": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + }, + "securityContext": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json" + } + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json", @@ -33,11 +86,15 @@ "description": "Describes the return data for the full result of the `set` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config set` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource set` command.", "type": "object", "required": [ + "metadata", "name", "result", "type" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, "name": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" }, @@ -66,6 +123,107 @@ "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", "type": "boolean" }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json", + "title": "DSC Version", + "description": "Defines the version of DSC that ran the command. This value is always the semantic version of the DSC command, like `3.0.0-preview.7`.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json", + "title": "Operation", + "description": "Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or `Export`.", + "type": "string", + "enum": [ + "Get", + "Set", + "Test", + "Export" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json", + "title": "Execution type", + "description": "Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument.", + "type": "string", + "enum": [ + "Actual", + "WhatIf" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json", + "title": "Start date and time", + "description": "Defines the start date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "type": "string", + "format": "date-time" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json", + "title": "Start date and time", + "description": "Defines the end date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "type": "string", + "format": "date-time" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", + "title": "Security context", + "description": "Defines the security context that DSC was run under. If the value for this metadata property is `Elevated`, DSC was run as root (non-Windows) or an elevated session with Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in a non-elevated session.", + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", diff --git a/schemas/2024/04/bundled/outputs/config/test.json b/schemas/2024/04/bundled/outputs/config/test.json index fbe17a556..4918bb394 100644 --- a/schemas/2024/04/bundled/outputs/config/test.json +++ b/schemas/2024/04/bundled/outputs/config/test.json @@ -5,11 +5,15 @@ "description": "Represents the data structure returned by the `dsc config test` command.", "type": "object", "required": [ + "metadata", "results", "messages", "hadErrors" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json" + }, "results": { "title": "Results", "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", @@ -26,6 +30,55 @@ } }, "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json", + "title": "Configuration result metadata", + "description": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of a DSC operation, including the version of DSC used, when the operation started and ended, and the security context the operation was invoked under.", + "type": "object", + "required": [ + "version", + "operation", + "executionType", + "startDatetime", + "endDatetime", + "duration", + "securityContext" + ], + "properties": { + "version": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json" + }, + "operation": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json" + }, + "executionType": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json" + }, + "startDatetime": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json" + }, + "endDatetime": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json" + }, + "duration": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + }, + "securityContext": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json" + } + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json", @@ -33,11 +86,15 @@ "description": "Describes the return data for the full result of the `test` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config test` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource test` command.", "type": "object", "required": [ + "metadata", "name", "result", "type" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, "name": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" }, @@ -66,6 +123,107 @@ "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", "type": "boolean" }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json", + "title": "DSC Version", + "description": "Defines the version of DSC that ran the command. This value is always the semantic version of the DSC command, like `3.0.0-preview.7`.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json", + "title": "Operation", + "description": "Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or `Export`.", + "type": "string", + "enum": [ + "Get", + "Set", + "Test", + "Export" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json", + "title": "Execution type", + "description": "Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument.", + "type": "string", + "enum": [ + "Actual", + "WhatIf" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json", + "title": "Start date and time", + "description": "Defines the start date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "type": "string", + "format": "date-time" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json", + "title": "Start date and time", + "description": "Defines the end date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "type": "string", + "format": "date-time" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", + "title": "Security context", + "description": "Defines the security context that DSC was run under. If the value for this metadata property is `Elevated`, DSC was run as root (non-Windows) or an elevated session with Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in a non-elevated session.", + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string.\n\nFor reference, see https://semver.org/\n", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "A valid semantic version ([semver][01]) string.\n\nThis value uses the [suggested regular expression][02] to validate whether the string is valid\nsemver. This is the same pattern, made multi-line for easier readability:\n\n```regex\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n\n[01]: https://semver.org/\n[02]: https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", diff --git a/schemas/2024/04/bundled/outputs/resource/get.json b/schemas/2024/04/bundled/outputs/resource/get.json index 4ae0a08e3..48229ab7b 100644 --- a/schemas/2024/04/bundled/outputs/resource/get.json +++ b/schemas/2024/04/bundled/outputs/resource/get.json @@ -39,11 +39,15 @@ "description": "Describes the return data for the full result of the `get` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config get` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource get` command.", "type": "object", "required": [ + "metadata", "name", "result", "type" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, "name": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" }, @@ -55,6 +59,31 @@ } } }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", @@ -88,6 +117,14 @@ } } ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" } } } diff --git a/schemas/2024/04/bundled/outputs/resource/set.json b/schemas/2024/04/bundled/outputs/resource/set.json index efe0397df..1da8bf7b9 100644 --- a/schemas/2024/04/bundled/outputs/resource/set.json +++ b/schemas/2024/04/bundled/outputs/resource/set.json @@ -55,11 +55,15 @@ "description": "Describes the return data for the full result of the `set` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config set` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource set` command.", "type": "object", "required": [ + "metadata", "name", "result", "type" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, "name": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" }, @@ -71,6 +75,31 @@ } } }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", @@ -104,6 +133,14 @@ } } ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" } } } diff --git a/schemas/2024/04/bundled/outputs/resource/test.json b/schemas/2024/04/bundled/outputs/resource/test.json index 4eedeaa80..04bfa9650 100644 --- a/schemas/2024/04/bundled/outputs/resource/test.json +++ b/schemas/2024/04/bundled/outputs/resource/test.json @@ -61,11 +61,15 @@ "description": "Describes the return data for the full result of the `test` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config test` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource test` command.", "type": "object", "required": [ + "metadata", "name", "result", "type" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, "name": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" }, @@ -77,6 +81,31 @@ } } }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + }, "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", @@ -110,6 +139,14 @@ } } ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" } } } diff --git a/schemas/2024/04/config/document.metadata.json b/schemas/2024/04/config/document.metadata.json index ebe379711..a2323cf06 100644 --- a/schemas/2024/04/config/document.metadata.json +++ b/schemas/2024/04/config/document.metadata.json @@ -11,15 +11,9 @@ "description": "The `Microsoft.DSC` metadata property contains directives and information that DSC itself uses when processing a configuration document. Unlike other metadata key-value pairs, DSC validates these properties.", "unevaluatedProperties": false, "properties": { - "requiredSecurityContext": { - "type": "string", - "enum": [ - "Current", - "Elevated", - "Restricted" - ], + "securityContext": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", "default": "Current", - "title": "Required security context", "description": "This property defines the security context a configuration requires. If you invoke a DSC operation against the configuration document in a security context that conflicts with this metadata, DSC raises an error when it validates the configuration document.\nThe default security context is `Current`." } } diff --git a/schemas/2024/04/metadata/Microsoft.DSC/duration.json b/schemas/2024/04/metadata/Microsoft.DSC/duration.json new file mode 100644 index 000000000..827f17066 --- /dev/null +++ b/schemas/2024/04/metadata/Microsoft.DSC/duration.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" +} diff --git a/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json b/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json new file mode 100644 index 000000000..f1d48c84d --- /dev/null +++ b/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json", + "title": "Start date and time", + "description": "Defines the end date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "type": "string", + "format": "date-time" +} diff --git a/schemas/2024/04/metadata/Microsoft.DSC/executionType.json b/schemas/2024/04/metadata/Microsoft.DSC/executionType.json new file mode 100644 index 000000000..4cb638536 --- /dev/null +++ b/schemas/2024/04/metadata/Microsoft.DSC/executionType.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json", + "title": "Execution type", + "description": "Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument.", + "type": "string", + "enum": [ + "Actual", + "WhatIf" + ] +} diff --git a/schemas/2024/04/metadata/Microsoft.DSC/operation.json b/schemas/2024/04/metadata/Microsoft.DSC/operation.json new file mode 100644 index 000000000..4c93c3b1b --- /dev/null +++ b/schemas/2024/04/metadata/Microsoft.DSC/operation.json @@ -0,0 +1,13 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json", + "title": "Operation", + "description": "Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or `Export`.", + "type": "string", + "enum": [ + "Get", + "Set", + "Test", + "Export" + ] +} diff --git a/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json b/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json new file mode 100644 index 000000000..d6be4ae17 --- /dev/null +++ b/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", + "title": "Security context", + "description": "Defines the security context that DSC was run under. If the value for this metadata property is `Elevated`, DSC was run as root (non-Windows) or an elevated session with Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in a non-elevated session.", + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ] +} diff --git a/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json b/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json new file mode 100644 index 000000000..4b8552c09 --- /dev/null +++ b/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json", + "title": "Start date and time", + "description": "Defines the start date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "type": "string", + "format": "date-time" +} diff --git a/schemas/2024/04/metadata/Microsoft.DSC/version.json b/schemas/2024/04/metadata/Microsoft.DSC/version.json new file mode 100644 index 000000000..ef51262f2 --- /dev/null +++ b/schemas/2024/04/metadata/Microsoft.DSC/version.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json", + "title": "DSC Version", + "description": "Defines the version of DSC that ran the command. This value is always the semantic version of the DSC command, like `3.0.0-preview.7`.", + "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" +} diff --git a/schemas/2024/04/metadata/configurationDocumentResult.json b/schemas/2024/04/metadata/configurationDocumentResult.json new file mode 100644 index 000000000..7ccfc9acc --- /dev/null +++ b/schemas/2024/04/metadata/configurationDocumentResult.json @@ -0,0 +1,49 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json", + "title": "Configuration result metadata", + "description": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of a DSC operation, including the version of DSC used, when the operation started and ended, and the security context the operation was invoked under.", + "type": "object", + "required": [ + "version", + "operation", + "executionType", + "startDatetime", + "endDatetime", + "duration", + "securityContext" + ], + "properties": { + "version": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json" + }, + "operation": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json" + }, + "executionType": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json" + }, + "startDatetime": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json" + }, + "endDatetime": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json" + }, + "duration": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + }, + "securityContext": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json" + } + } + } + } +} diff --git a/schemas/2024/04/metadata/resourceInstanceResult.json b/schemas/2024/04/metadata/resourceInstanceResult.json new file mode 100644 index 000000000..a2f297c98 --- /dev/null +++ b/schemas/2024/04/metadata/resourceInstanceResult.json @@ -0,0 +1,25 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } +} diff --git a/schemas/2024/04/outputs/config/get.json b/schemas/2024/04/outputs/config/get.json index f57221eb4..0f6203a77 100644 --- a/schemas/2024/04/outputs/config/get.json +++ b/schemas/2024/04/outputs/config/get.json @@ -5,11 +5,15 @@ "description": "Represents the data structure returned by the `dsc config get` command.", "type": "object", "required": [ + "metadata", "results", "messages", "hadErrors" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json" + }, "results": { "title": "Results", "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", diff --git a/schemas/2024/04/outputs/config/set.json b/schemas/2024/04/outputs/config/set.json index 8aba9d68c..274ce2ab8 100644 --- a/schemas/2024/04/outputs/config/set.json +++ b/schemas/2024/04/outputs/config/set.json @@ -5,11 +5,15 @@ "description": "Represents the data structure returned by the `dsc config set` command.", "type": "object", "required": [ + "metadata", "results", "messages", "hadErrors" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json" + }, "results": { "title": "Results", "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", diff --git a/schemas/2024/04/outputs/config/test.json b/schemas/2024/04/outputs/config/test.json index 4e5cfc5a8..4ecd31376 100644 --- a/schemas/2024/04/outputs/config/test.json +++ b/schemas/2024/04/outputs/config/test.json @@ -5,11 +5,15 @@ "description": "Represents the data structure returned by the `dsc config test` command.", "type": "object", "required": [ + "metadata", "results", "messages", "hadErrors" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json" + }, "results": { "title": "Results", "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", diff --git a/schemas/2024/04/outputs/resource/get.full.json b/schemas/2024/04/outputs/resource/get.full.json index 54bb4336d..97fc3e483 100644 --- a/schemas/2024/04/outputs/resource/get.full.json +++ b/schemas/2024/04/outputs/resource/get.full.json @@ -5,11 +5,15 @@ "description": "Describes the return data for the full result of the `get` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config get` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource get` command.", "type": "object", "required": [ + "metadata", "name", "result", "type" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, "name": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" }, diff --git a/schemas/2024/04/outputs/resource/set.full.json b/schemas/2024/04/outputs/resource/set.full.json index 20349d948..ffa587d5e 100644 --- a/schemas/2024/04/outputs/resource/set.full.json +++ b/schemas/2024/04/outputs/resource/set.full.json @@ -5,11 +5,15 @@ "description": "Describes the return data for the full result of the `set` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config set` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource set` command.", "type": "object", "required": [ + "metadata", "name", "result", "type" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, "name": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" }, diff --git a/schemas/2024/04/outputs/resource/test.full.json b/schemas/2024/04/outputs/resource/test.full.json index 144de4053..7f30ad7bd 100644 --- a/schemas/2024/04/outputs/resource/test.full.json +++ b/schemas/2024/04/outputs/resource/test.full.json @@ -5,11 +5,15 @@ "description": "Describes the return data for the full result of the `test` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config test` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource test` command.", "type": "object", "required": [ + "metadata", "name", "result", "type" ], "properties": { + "metadata": { + "$ref": "/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, "name": { "$ref": "/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" }, diff --git a/schemas/build.ps1 b/schemas/build.ps1 index fd996ef66..b063e967c 100644 --- a/schemas/build.ps1 +++ b/schemas/build.ps1 @@ -335,7 +335,7 @@ begin { $RelativeUriReferencePattern = @( '(?m)' '^' - '(?\s+\$ref:\s+)' + '(?\s*(-\s+)?\$ref:\s+)' '(?/.+)' '$' ) -join '' @@ -425,7 +425,8 @@ begin { $RefUri.Trim() "'" ) -join '' - $MungingSchema = $MungingSchema -replace [regex]::Escape($Whole), $NewValue + Write-Verbose "Replacing '$($Whole.Trim())' with '$($NewValue.Trim())'..." + $MungingSchema = $MungingSchema -replace [regex]::Escape($Whole.Trim()), $NewValue.Trim() } $MergedSchema = $MungingSchema | yayaml\ConvertFrom-Yaml } else { @@ -662,6 +663,7 @@ process { $RegistryParameters = @{ SchemaDirectories = @( "$OutputDirectory/config" + "$OutputDirectory/metadata" "$OutputDirectory/definitions" "$OutputDirectory/outputs" "$OutputDirectory/resource" diff --git a/schemas/src/config/document.metadata.yaml b/schemas/src/config/document.metadata.yaml index 7d0e7f530..5146112e5 100644 --- a/schemas/src/config/document.metadata.yaml +++ b/schemas/src/config/document.metadata.yaml @@ -30,14 +30,9 @@ properties: unevaluatedProperties: false properties: - requiredSecurityContext: - type: string - enum: - - Current - - Elevated - - Restricted + securityContext: + $ref: ///metadata/Microsoft.DSC/securityContext.yaml default: Current - title: Required security context description: >- This property defines the security context a configuration requires. If you invoke a DSC operation against the configuration document in a security context that conflicts with diff --git a/schemas/src/metadata/Microsoft.DSC/duration.yaml b/schemas/src/metadata/Microsoft.DSC/duration.yaml new file mode 100644 index 000000000..65758df4a --- /dev/null +++ b/schemas/src/metadata/Microsoft.DSC/duration.yaml @@ -0,0 +1,19 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///metadata/Microsoft.DSC/duration.yaml +# Documentation +title: Duration +description: >- + Defines the duration of a DSC operation against a configuration document or resource instance as + a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` + represents a duration of about `0.61` seconds. For more information, see: + https://datatracker.ietf.org/doc/html/rfc3339#appendix-A +markdownDescription: |- + Defines the duration of a DSC operation against a configuration document or resource instance as + a string following the format defined in [ISO8601 ABNF for `duration`][01]. For example, + `PT0.611216S` represents a duration of about `0.61` seconds. + + [01]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A +# Definition +type: string +format: duration diff --git a/schemas/src/metadata/Microsoft.DSC/endDatetime.yaml b/schemas/src/metadata/Microsoft.DSC/endDatetime.yaml new file mode 100644 index 000000000..d58ef7d9e --- /dev/null +++ b/schemas/src/metadata/Microsoft.DSC/endDatetime.yaml @@ -0,0 +1,18 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///metadata/Microsoft.DSC/endDatetime.yaml +# Documentation +title: Start date and time +description: >- + Defines the end date and time for the DSC operation as a timestamp following the format defined + in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`. +markdownDescription: |- + Defines the end date and time for the DSC operation as a timestamp following the format defined + in [RFC3339, section 5.6 (see `date-time`)][01]. + + For example: `2024-04-14T08:49:51.395686600-07:00` + + [01]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 +# Definition +type: string +format: date-time diff --git a/schemas/src/metadata/Microsoft.DSC/executionType.yaml b/schemas/src/metadata/Microsoft.DSC/executionType.yaml new file mode 100644 index 000000000..6b5deb001 --- /dev/null +++ b/schemas/src/metadata/Microsoft.DSC/executionType.yaml @@ -0,0 +1,18 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///metadata/Microsoft.DSC/executionType.yaml +# Documentation +title: Execution type +description: >- + Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` + mode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set` + operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument. +markdownDescription: |- + Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` + mode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set` + operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument. +# Definition +type: string +enum: + - Actual + - WhatIf diff --git a/schemas/src/metadata/Microsoft.DSC/operation.yaml b/schemas/src/metadata/Microsoft.DSC/operation.yaml new file mode 100644 index 000000000..3efa329f3 --- /dev/null +++ b/schemas/src/metadata/Microsoft.DSC/operation.yaml @@ -0,0 +1,18 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///metadata/Microsoft.DSC/operation.yaml +# Documentation +title: Operation +description: >- + Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or + `Export`. +markdownDescription: |- + Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or + `Export`. +# Definition +type: string +enum: + - Get + - Set + - Test + - Export diff --git a/schemas/src/metadata/Microsoft.DSC/securityContext.yaml b/schemas/src/metadata/Microsoft.DSC/securityContext.yaml new file mode 100644 index 000000000..16c05e3c9 --- /dev/null +++ b/schemas/src/metadata/Microsoft.DSC/securityContext.yaml @@ -0,0 +1,21 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///metadata/Microsoft.DSC/securityContext.yaml +# Documentation +title: Security context +description: >- + Defines the security context that DSC was run under. If the value for this metadata property is + `Elevated`, DSC was run as root (non-Windows) or an elevated session with Administrator + privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in + a non-elevated session. +markdownDescription: |- + Defines the security context that DSC was run under. If the value for this metadata property is + `Elevated`, DSC was run as `root` (non-Windows) or an elevated session with Administrator + privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in + a non-elevated session. +# Definition +type: string +enum: + - Current + - Elevated + - Restricted diff --git a/schemas/src/metadata/Microsoft.DSC/startDatetime.yaml b/schemas/src/metadata/Microsoft.DSC/startDatetime.yaml new file mode 100644 index 000000000..0d0c97f24 --- /dev/null +++ b/schemas/src/metadata/Microsoft.DSC/startDatetime.yaml @@ -0,0 +1,18 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///metadata/Microsoft.DSC/startDatetime.yaml +# Documentation +title: Start date and time +description: >- + Defines the start date and time for the DSC operation as a timestamp following the format defined + in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`. +markdownDescription: |- + Defines the start date and time for the DSC operation as a timestamp following the format defined + in [RFC3339, section 5.6 (see `date-time`)][01]. + + For example: `2024-04-14T08:49:51.395686600-07:00` + + [01]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 +# Definition +type: string +format: date-time diff --git a/schemas/src/metadata/Microsoft.DSC/version.yaml b/schemas/src/metadata/Microsoft.DSC/version.yaml new file mode 100644 index 000000000..ca6cf9132 --- /dev/null +++ b/schemas/src/metadata/Microsoft.DSC/version.yaml @@ -0,0 +1,13 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///metadata/Microsoft.DSC/version.yaml +# Documentation +title: DSC Version +description: >- + Defines the version of DSC that ran the command. This value is always the semantic version of the + DSC command, like `3.0.0-preview.7`. +markdownDescription: |- + Defines the version of DSC that ran the command. This value is always the semantic version of the + DSC command, like `3.0.0-preview.7`. +# Definition +$ref: ///definitions/semver.yaml diff --git a/schemas/src/metadata/configurationDocumentResult.yaml b/schemas/src/metadata/configurationDocumentResult.yaml new file mode 100644 index 000000000..c21b31bbb --- /dev/null +++ b/schemas/src/metadata/configurationDocumentResult.yaml @@ -0,0 +1,47 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///metadata/configurationDocumentResult.yaml +# Documentation +title: Configuration result metadata +description: >- + Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or + `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe + the context of the operation. +markdownDescription: |- + Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or + `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe + the context of the operation. +# Definition +type: object +required: [Microsoft.DSC] +properties: + Microsoft.DSC: + title: DSC context metadata + description: >- + The child properties for this metadata describe the context of a DSC operation, including + the version of DSC used, when the operation started and ended, and the security context the + operation was invoked under. + type: object + required: + - version + - operation + - executionType + - startDatetime + - endDatetime + - duration + - securityContext + properties: + version: + $ref: ///metadata/Microsoft.DSC/version.yaml + operation: + $ref: ///metadata/Microsoft.DSC/operation.yaml + executionType: + $ref: ///metadata/Microsoft.DSC/executionType.yaml + startDatetime: + $ref: ///metadata/Microsoft.DSC/startDatetime.yaml + endDatetime: + $ref: ///metadata/Microsoft.DSC/endDatetime.yaml + duration: + $ref: ///metadata/Microsoft.DSC/duration.yaml + securityContext: + $ref: ///metadata/Microsoft.DSC/securityContext.yaml diff --git a/schemas/src/metadata/resourceInstanceResult.yaml b/schemas/src/metadata/resourceInstanceResult.yaml new file mode 100644 index 000000000..f21a28511 --- /dev/null +++ b/schemas/src/metadata/resourceInstanceResult.yaml @@ -0,0 +1,28 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///metadata/resourceInstanceResult.yaml +# Documentation +title: Resource instance result metadata +description: >- + Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or + `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe + the context of the operation. +markdownDescription: |- + Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or + `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe + the context of the operation. +# Definition +type: object +required: [Microsoft.DSC] +properties: + Microsoft.DSC: + title: DSC context metadata + description: >- + The child properties for this metadata describe the context of the DSC operation against a + resource instance, including the duration of the operation. + type: object + required: + - duration + properties: + duration: + $ref: ///metadata/Microsoft.DSC/duration.yaml diff --git a/schemas/src/outputs/config/get.yaml b/schemas/src/outputs/config/get.yaml index 4415bf17d..f1786b65f 100644 --- a/schemas/src/outputs/config/get.yaml +++ b/schemas/src/outputs/config/get.yaml @@ -8,10 +8,13 @@ description: >- type: object required: + - metadata - results - messages - hadErrors properties: + metadata: + $ref: ///metadata/configurationDocumentResult.yaml results: title: Results description: >- diff --git a/schemas/src/outputs/config/set.yaml b/schemas/src/outputs/config/set.yaml index 62b71b728..3482c6d28 100644 --- a/schemas/src/outputs/config/set.yaml +++ b/schemas/src/outputs/config/set.yaml @@ -8,10 +8,13 @@ description: >- type: object required: + - metadata - results - messages - hadErrors properties: + metadata: + $ref: ///metadata/configurationDocumentResult.yaml results: title: Results description: >- diff --git a/schemas/src/outputs/config/test.yaml b/schemas/src/outputs/config/test.yaml index 12a888e96..1134b8cff 100644 --- a/schemas/src/outputs/config/test.yaml +++ b/schemas/src/outputs/config/test.yaml @@ -8,10 +8,13 @@ description: >- type: object required: + - metadata - results - messages - hadErrors properties: + metadata: + $ref: ///metadata/configurationDocumentResult.yaml results: title: Results description: >- diff --git a/schemas/src/outputs/resource/get.full.yaml b/schemas/src/outputs/resource/get.full.yaml index 4e8607c14..055677683 100644 --- a/schemas/src/outputs/resource/get.full.yaml +++ b/schemas/src/outputs/resource/get.full.yaml @@ -14,13 +14,16 @@ description: |- type: object required: + - metadata - name - result - type properties: + metadata: + $ref: ///metadata/resourceInstanceResult.yaml name: $ref: ///definitions/instanceName.yaml type: $ref: ///definitions/resourceType.yaml result: - $ref: ///outputs/resource/get.yaml \ No newline at end of file + $ref: ///outputs/resource/get.yaml diff --git a/schemas/src/outputs/resource/set.full.yaml b/schemas/src/outputs/resource/set.full.yaml index a270409fa..fa1501404 100644 --- a/schemas/src/outputs/resource/set.full.yaml +++ b/schemas/src/outputs/resource/set.full.yaml @@ -14,13 +14,16 @@ description: |- type: object required: + - metadata - name - result - type properties: + metadata: + $ref: ///metadata/resourceInstanceResult.yaml name: $ref: ///definitions/instanceName.yaml type: $ref: ///definitions/resourceType.yaml result: - $ref: ///outputs/resource/set.yaml \ No newline at end of file + $ref: ///outputs/resource/set.yaml diff --git a/schemas/src/outputs/resource/test.full.yaml b/schemas/src/outputs/resource/test.full.yaml index 8f6befaac..0b8f47770 100644 --- a/schemas/src/outputs/resource/test.full.yaml +++ b/schemas/src/outputs/resource/test.full.yaml @@ -14,13 +14,16 @@ description: |- type: object required: + - metadata - name - result - type properties: + metadata: + $ref: ///metadata/resourceInstanceResult.yaml name: $ref: ///definitions/instanceName.yaml type: $ref: ///definitions/resourceType.yaml result: - $ref: ///outputs/resource/test.yaml \ No newline at end of file + $ref: ///outputs/resource/test.yaml From d56669b36b8083872be4575544e59eeb6444e7f2 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Tue, 16 Apr 2024 15:53:52 -0500 Subject: [PATCH 14/15] (SCHEMA) Add VSCode schemas for output and update examples Prior to this change, the output schemas were bundled, but not with in the format compatible with VS Code. This change adds the VS Code compatible bundle format to the composed schemas configuration. This enables us to show new examples of output data with IntelliSense to make inspecting the output structure easier and more interactive. This change also reorganizes the schema examples folder to use subfolders for configuration documents, resource manifests, and the new output data objects. --- .../04/bundled/outputs/config/get.vscode.json | 354 ++++ .../04/bundled/outputs/config/set.vscode.json | 370 ++++ .../bundled/outputs/config/test.vscode.json | 376 ++++ .../bundled/outputs/resource/get.vscode.json | 158 ++ .../bundled/outputs/resource/list.vscode.json | 1751 +++++++++++++++++ .../outputs/resource/schema.vscode.json | 8 + .../bundled/outputs/resource/set.vscode.json | 174 ++ .../bundled/outputs/resource/test.vscode.json | 180 ++ .../04/bundled/outputs/schema.vscode.json | 8 + .../example.dsc.config.yaml} | 0 schemas/examples/output/config.get.yaml | 50 + schemas/examples/output/config.test.yaml | 63 + .../foo.dsc.resource.json | 0 .../foo.dsc.resource.yaml | 0 schemas/schemas.config.yaml | 18 +- 15 files changed, 3501 insertions(+), 9 deletions(-) create mode 100644 schemas/2024/04/bundled/outputs/config/get.vscode.json create mode 100644 schemas/2024/04/bundled/outputs/config/set.vscode.json create mode 100644 schemas/2024/04/bundled/outputs/config/test.vscode.json create mode 100644 schemas/2024/04/bundled/outputs/resource/get.vscode.json create mode 100644 schemas/2024/04/bundled/outputs/resource/list.vscode.json create mode 100644 schemas/2024/04/bundled/outputs/resource/schema.vscode.json create mode 100644 schemas/2024/04/bundled/outputs/resource/set.vscode.json create mode 100644 schemas/2024/04/bundled/outputs/resource/test.vscode.json create mode 100644 schemas/2024/04/bundled/outputs/schema.vscode.json rename schemas/examples/{foo.dsc.config.yaml => configuration_document/example.dsc.config.yaml} (100%) create mode 100644 schemas/examples/output/config.get.yaml create mode 100644 schemas/examples/output/config.test.yaml rename schemas/examples/{ => resource_manifest}/foo.dsc.resource.json (100%) rename schemas/examples/{ => resource_manifest}/foo.dsc.resource.yaml (100%) diff --git a/schemas/2024/04/bundled/outputs/config/get.vscode.json b/schemas/2024/04/bundled/outputs/config/get.vscode.json new file mode 100644 index 000000000..6a9abbfe5 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/config/get.vscode.json @@ -0,0 +1,354 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/get.json", + "title": "DSC Configuration get command result", + "description": "Represents the data structure returned by the `dsc config get` command.", + "type": "object", + "required": [ + "metadata", + "results", + "messages", + "hadErrors" + ], + "properties": { + "metadata": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json" + }, + "results": { + "title": "Results", + "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json" + } + }, + "messages": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json" + }, + "hadErrors": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json" + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2024": { + "04": { + "metadata": { + "configurationDocumentResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json", + "title": "Configuration result metadata", + "description": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "markdownDescription": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or\n`dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe\nthe context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of a DSC operation, including the version of DSC used, when the operation started and ended, and the security context the operation was invoked under.", + "type": "object", + "required": [ + "version", + "operation", + "executionType", + "startDatetime", + "endDatetime", + "duration", + "securityContext" + ], + "properties": { + "version": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json" + }, + "operation": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json" + }, + "executionType": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json" + }, + "startDatetime": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json" + }, + "endDatetime": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json" + }, + "duration": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + }, + "securityContext": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json" + } + } + } + } + }, + "Microsoft.DSC": { + "version.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json", + "title": "DSC Version", + "description": "Defines the version of DSC that ran the command. This value is always the semantic version of the DSC command, like `3.0.0-preview.7`.", + "markdownDescription": "Defines the version of DSC that ran the command. This value is always the semantic version of the\nDSC command, like `3.0.0-preview.7`.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "operation.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json", + "title": "Operation", + "description": "Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or `Export`.", + "markdownDescription": "Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or\n`Export`.", + "type": "string", + "enum": [ + "Get", + "Set", + "Test", + "Export" + ] + }, + "executionType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json", + "title": "Execution type", + "description": "Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument.", + "markdownDescription": "Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf`\nmode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set`\noperations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument.", + "type": "string", + "enum": [ + "Actual", + "WhatIf" + ] + }, + "startDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json", + "title": "Start date and time", + "description": "Defines the start date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "markdownDescription": "Defines the start date and time for the DSC operation as a timestamp following the format defined\nin [RFC3339, section 5.6 (see `date-time`)][01].\n\nFor example: `2024-04-14T08:49:51.395686600-07:00`\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6", + "type": "string", + "format": "date-time" + }, + "endDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json", + "title": "Start date and time", + "description": "Defines the end date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "markdownDescription": "Defines the end date and time for the DSC operation as a timestamp following the format defined\nin [RFC3339, section 5.6 (see `date-time`)][01].\n\nFor example: `2024-04-14T08:49:51.395686600-07:00`\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6", + "type": "string", + "format": "date-time" + }, + "duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "markdownDescription": "Defines the duration of a DSC operation against a configuration document or resource instance as\na string following the format defined in [ISO8601 ABNF for `duration`][01]. For example,\n`PT0.611216S` represents a duration of about `0.61` seconds.\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" + }, + "securityContext.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", + "title": "Security context", + "description": "Defines the security context that DSC was run under. If the value for this metadata property is `Elevated`, DSC was run as root (non-Windows) or an elevated session with Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in a non-elevated session.", + "markdownDescription": "Defines the security context that DSC was run under. If the value for this metadata property is\n`Elevated`, DSC was run as `root` (non-Windows) or an elevated session with Administrator\nprivileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in\na non-elevated session.", + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ] + } + }, + "resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "markdownDescription": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or\n`dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe\nthe context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + } + }, + "outputs": { + "resource": { + "get.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json", + "title": "dsc resource get result (full)", + "description": "Describes the return data for the full result of the `get` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config get` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource get` command.", + "type": "object", + "required": [ + "metadata", + "name", + "result", + "type" + ], + "properties": { + "metadata": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, + "name": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.json" + } + } + }, + "get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the actual state of a non-nested instance or an array of objects that describe the actual state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json" + } + } + ] + }, + "get.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json", + "title": "dsc resource get result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource get` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource get` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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" + } + } + } + } + }, + "definitions": { + "messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/message.json" + } + }, + "hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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" + }, + "instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "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": "***\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" + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", + "markdownDescription": "***\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" + }, + "message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } + } + } + } + } + } + } + } +} diff --git a/schemas/2024/04/bundled/outputs/config/set.vscode.json b/schemas/2024/04/bundled/outputs/config/set.vscode.json new file mode 100644 index 000000000..0583de6b8 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/config/set.vscode.json @@ -0,0 +1,370 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/set.json", + "title": "DSC Configuration set command result", + "description": "Represents the data structure returned by the `dsc config set` command.", + "type": "object", + "required": [ + "metadata", + "results", + "messages", + "hadErrors" + ], + "properties": { + "metadata": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json" + }, + "results": { + "title": "Results", + "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json" + } + }, + "messages": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json" + }, + "hadErrors": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json" + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2024": { + "04": { + "metadata": { + "configurationDocumentResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json", + "title": "Configuration result metadata", + "description": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "markdownDescription": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or\n`dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe\nthe context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of a DSC operation, including the version of DSC used, when the operation started and ended, and the security context the operation was invoked under.", + "type": "object", + "required": [ + "version", + "operation", + "executionType", + "startDatetime", + "endDatetime", + "duration", + "securityContext" + ], + "properties": { + "version": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json" + }, + "operation": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json" + }, + "executionType": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json" + }, + "startDatetime": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json" + }, + "endDatetime": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json" + }, + "duration": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + }, + "securityContext": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json" + } + } + } + } + }, + "Microsoft.DSC": { + "version.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json", + "title": "DSC Version", + "description": "Defines the version of DSC that ran the command. This value is always the semantic version of the DSC command, like `3.0.0-preview.7`.", + "markdownDescription": "Defines the version of DSC that ran the command. This value is always the semantic version of the\nDSC command, like `3.0.0-preview.7`.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "operation.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json", + "title": "Operation", + "description": "Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or `Export`.", + "markdownDescription": "Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or\n`Export`.", + "type": "string", + "enum": [ + "Get", + "Set", + "Test", + "Export" + ] + }, + "executionType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json", + "title": "Execution type", + "description": "Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument.", + "markdownDescription": "Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf`\nmode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set`\noperations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument.", + "type": "string", + "enum": [ + "Actual", + "WhatIf" + ] + }, + "startDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json", + "title": "Start date and time", + "description": "Defines the start date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "markdownDescription": "Defines the start date and time for the DSC operation as a timestamp following the format defined\nin [RFC3339, section 5.6 (see `date-time`)][01].\n\nFor example: `2024-04-14T08:49:51.395686600-07:00`\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6", + "type": "string", + "format": "date-time" + }, + "endDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json", + "title": "Start date and time", + "description": "Defines the end date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "markdownDescription": "Defines the end date and time for the DSC operation as a timestamp following the format defined\nin [RFC3339, section 5.6 (see `date-time`)][01].\n\nFor example: `2024-04-14T08:49:51.395686600-07:00`\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6", + "type": "string", + "format": "date-time" + }, + "duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "markdownDescription": "Defines the duration of a DSC operation against a configuration document or resource instance as\na string following the format defined in [ISO8601 ABNF for `duration`][01]. For example,\n`PT0.611216S` represents a duration of about `0.61` seconds.\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" + }, + "securityContext.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", + "title": "Security context", + "description": "Defines the security context that DSC was run under. If the value for this metadata property is `Elevated`, DSC was run as root (non-Windows) or an elevated session with Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in a non-elevated session.", + "markdownDescription": "Defines the security context that DSC was run under. If the value for this metadata property is\n`Elevated`, DSC was run as `root` (non-Windows) or an elevated session with Administrator\nprivileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in\na non-elevated session.", + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ] + } + }, + "resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "markdownDescription": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or\n`dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe\nthe context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + } + }, + "outputs": { + "resource": { + "set.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json", + "title": "dsc resource set result (full)", + "description": "Describes the return data for the full result of the `set` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config set` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource set` command.", + "type": "object", + "required": [ + "metadata", + "name", + "result", + "type" + ], + "properties": { + "metadata": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, + "name": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.json" + } + } + }, + "set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the enforced state of a non-nested instance or an array of objects that describe the enforced state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json" + } + } + ] + }, + "set.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json", + "title": "dsc resource set result (simple)", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource set` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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" + } + } + } + } + } + }, + "definitions": { + "messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/message.json" + } + }, + "hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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" + }, + "instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "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": "***\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" + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", + "markdownDescription": "***\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" + }, + "message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } + } + } + } + } + } + } + } +} diff --git a/schemas/2024/04/bundled/outputs/config/test.vscode.json b/schemas/2024/04/bundled/outputs/config/test.vscode.json new file mode 100644 index 000000000..84012fe33 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/config/test.vscode.json @@ -0,0 +1,376 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/test.json", + "title": "DSC Configuration test command result", + "description": "Represents the data structure returned by the `dsc config test` command.", + "type": "object", + "required": [ + "metadata", + "results", + "messages", + "hadErrors" + ], + "properties": { + "metadata": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json" + }, + "results": { + "title": "Results", + "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json" + } + }, + "messages": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json" + }, + "hadErrors": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json" + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2024": { + "04": { + "metadata": { + "configurationDocumentResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/configurationDocumentResult.json", + "title": "Configuration result metadata", + "description": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "markdownDescription": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or\n`dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe\nthe context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of a DSC operation, including the version of DSC used, when the operation started and ended, and the security context the operation was invoked under.", + "type": "object", + "required": [ + "version", + "operation", + "executionType", + "startDatetime", + "endDatetime", + "duration", + "securityContext" + ], + "properties": { + "version": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json" + }, + "operation": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json" + }, + "executionType": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json" + }, + "startDatetime": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json" + }, + "endDatetime": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json" + }, + "duration": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + }, + "securityContext": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json" + } + } + } + } + }, + "Microsoft.DSC": { + "version.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json", + "title": "DSC Version", + "description": "Defines the version of DSC that ran the command. This value is always the semantic version of the DSC command, like `3.0.0-preview.7`.", + "markdownDescription": "Defines the version of DSC that ran the command. This value is always the semantic version of the\nDSC command, like `3.0.0-preview.7`.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "operation.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json", + "title": "Operation", + "description": "Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or `Export`.", + "markdownDescription": "Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or\n`Export`.", + "type": "string", + "enum": [ + "Get", + "Set", + "Test", + "Export" + ] + }, + "executionType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json", + "title": "Execution type", + "description": "Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument.", + "markdownDescription": "Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf`\nmode. This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set`\noperations, this value is `WhatIf` when DSC is invoked with the `--whatIf` argument.", + "type": "string", + "enum": [ + "Actual", + "WhatIf" + ] + }, + "startDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json", + "title": "Start date and time", + "description": "Defines the start date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "markdownDescription": "Defines the start date and time for the DSC operation as a timestamp following the format defined\nin [RFC3339, section 5.6 (see `date-time`)][01].\n\nFor example: `2024-04-14T08:49:51.395686600-07:00`\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6", + "type": "string", + "format": "date-time" + }, + "endDatetime.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDatetime.json", + "title": "Start date and time", + "description": "Defines the end date and time for the DSC operation as a timestamp following the format defined in RFC3339, section 5.6 as `date-time`, like `2024-04-14T08:49:51.395686600-07:00`.", + "markdownDescription": "Defines the end date and time for the DSC operation as a timestamp following the format defined\nin [RFC3339, section 5.6 (see `date-time`)][01].\n\nFor example: `2024-04-14T08:49:51.395686600-07:00`\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6", + "type": "string", + "format": "date-time" + }, + "duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "markdownDescription": "Defines the duration of a DSC operation against a configuration document or resource instance as\na string following the format defined in [ISO8601 ABNF for `duration`][01]. For example,\n`PT0.611216S` represents a duration of about `0.61` seconds.\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" + }, + "securityContext.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json", + "title": "Security context", + "description": "Defines the security context that DSC was run under. If the value for this metadata property is `Elevated`, DSC was run as root (non-Windows) or an elevated session with Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in a non-elevated session.", + "markdownDescription": "Defines the security context that DSC was run under. If the value for this metadata property is\n`Elevated`, DSC was run as `root` (non-Windows) or an elevated session with Administrator\nprivileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in\na non-elevated session.", + "type": "string", + "enum": [ + "Current", + "Elevated", + "Restricted" + ] + } + }, + "resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "markdownDescription": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or\n`dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe\nthe context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + } + }, + "outputs": { + "resource": { + "test.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json", + "title": "dsc resource test result (full)", + "description": "Describes the return data for the full result of the `test` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config test` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource test` command.", + "type": "object", + "required": [ + "metadata", + "name", + "result", + "type" + ], + "properties": { + "metadata": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, + "name": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json" + } + } + }, + "test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command. The return data is either a single object that describes the tested state of a non-nested instance or an array of objects that describe the tested state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json" + } + } + ] + }, + "test.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json", + "title": "dsc resource test result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource test` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource test` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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" + } + } + } + } + } + }, + "definitions": { + "messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/message.json" + } + }, + "hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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" + }, + "instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "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": "***\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" + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", + "markdownDescription": "***\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" + }, + "message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } + } + } + } + } + } + } + } +} diff --git a/schemas/2024/04/bundled/outputs/resource/get.vscode.json b/schemas/2024/04/bundled/outputs/resource/get.vscode.json new file mode 100644 index 000000000..db8cf71b8 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/resource/get.vscode.json @@ -0,0 +1,158 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the actual state of a non-nested instance or an array of objects that describe the actual state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json" + } + } + ], + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2024": { + "04": { + "outputs": { + "resource": { + "get.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json", + "title": "dsc resource get result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource get` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource get` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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" + } + } + }, + "get.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json", + "title": "dsc resource get result (full)", + "description": "Describes the return data for the full result of the `get` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config get` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource get` command.", + "type": "object", + "required": [ + "metadata", + "name", + "result", + "type" + ], + "properties": { + "metadata": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, + "name": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.json" + } + } + }, + "get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the actual state of a non-nested instance or an array of objects that describe the actual state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.full.json" + } + } + ] + } + } + }, + "metadata": { + "resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "markdownDescription": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or\n`dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe\nthe context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + }, + "Microsoft.DSC": { + "duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "markdownDescription": "Defines the duration of a DSC operation against a configuration document or resource instance as\na string following the format defined in [ISO8601 ABNF for `duration`][01]. For example,\n`PT0.611216S` represents a duration of about `0.61` seconds.\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" + } + } + }, + "definitions": { + "instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "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": "***\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" + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", + "markdownDescription": "***\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" + } + } + } + } + } + } + } + } + } +} diff --git a/schemas/2024/04/bundled/outputs/resource/list.vscode.json b/schemas/2024/04/bundled/outputs/resource/list.vscode.json new file mode 100644 index 000000000..6f1e92492 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/resource/list.vscode.json @@ -0,0 +1,1751 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/list.json", + "title": "dsc resource list result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource list` command.", + "type": "object", + "properties": { + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "kind": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json" + }, + "version": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json" + }, + "capabilities": { + "title": "Resource capabilities", + "description": "Defines the list of DSC operations the resource is compatible with. If the resource doesn't list a given operation, like `Set` or `Export`, the resource can't be used for those operations. The exception to this is `Test` - DSC uses synthetic testing for resources that don't have the `Test` capability.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "Get", + "Set", + "SetHandlesExist", + "Test", + "Delete", + "Export" + ] + } + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "path": { + "title": "Path", + "description": "Indicates the path to the DSC Resource on the file system.", + "type": "string" + }, + "directory": { + "title": "Directory", + "description": "Indicates the path to the folder containing the DSC Resource on the file system.", + "type": "string" + }, + "implementedAs": { + "title": "Implemented as", + "description": "Indicates how the DSC Resource was implemented.", + "oneOf": [ + { + "title": "Standard implementation", + "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", + "type": "string", + "enum": [ + "Command" + ] + }, + { + "title": "Custom implementation", + "description": "Indicates that the DSC Resource uses a custom implementation.", + "type": "object", + "required": [ + "custom" + ], + "properties": { + "custom": { + "title": "Custom implementation name", + "description": "The name of the custom implementation.", + "type": "string" + } + } + } + ] + }, + "author": { + "title": "Author", + "description": "Indicates the name of the person or organization that developed and maintains the DSC Resource.", + "type": [ + "string", + "null" + ] + }, + "properties": { + "title": "Properties", + "description": "Defines the DSC Resource's property names.", + "type": "array", + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "requireAdapter": { + "title": "Required DSC Resource Adapter", + "description": "Defines the fully qualified type name of the DSC Resource Adapter the DSC Resource depends on.", + "oneOf": [ + { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + { + "type": "null" + } + ] + }, + "manifest": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json" + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2024": { + "04": { + "definitions": { + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", + "markdownDescription": "***\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" + }, + "resourceKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json", + "title": "Resource kind", + "description": "Defines whether the resource is a normal DSC Resource, a group resource, or an adapter resource. This property is only required for group resources.", + "type": "string", + "enum": [ + "Resource", + "Adapter", + "Group" + ], + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the resource is a normal DSC Resource, a group resource, or an adapter\nresource. This property is only required for group resources.\n\nDSC infers the default value for this property based on whether the [adapter][02] property is\ndefined in the manifest:\n\n- If the `adapter` property is defined in the manifest, the default `kind` is `Adapter`.\n- If the `adapter` property is not defined in the manifest, the default `kind` is `Resource`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#kind\n", + "markdownEnumDescriptions": [ + "\n\nIndicates that the manifest is for a standard command-based DSC Resource.\n", + "\n\nIndicates that the manifest is for an adapter resource that enables the use of\nnon-command-based resources with DSC.\n", + "\n\nIndicates that the manifest is for a group resource that processes an array of nested\nresource instances.\n" + ] + }, + "semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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/2024/04/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command. The arguments can be any number of strings. If you want to pass the JSON object representing the property bag for the resource to an argument, you can define a single item in the array as a JSON object, indicating the name of the argument with the `jsonInputArg` string property and whether the argument is mandatory for the command with the `mandatory` boolean property.", + "type": "array", + "items": { + "defaultSnippets": [ + { + "label": "String argument", + "markdownDescription": "Add a string argument to the command, like `config` or `--config`.", + "body": "${1:argument_name}" + }, + { + "label": "JSON input argument", + "markdownDescription": "Add a JSON input argument to the command. A command can only define one JSON input argument\nin the `args` list. When you define a JSON input argument, DSC passes the input data for\nthe command to the specified argument as a string representing the data as a compressed\nJSON object. The compressed JSON object doesn't have any spaces or newlines between the\nobject properties and values.\n\nIf the command doesn't define the `input` property, it must define a JSON input argument.\n\nIf the command defines both the `input` property and a JSON input argument, DSC sends the\ninput data to the command in both ways. For example, if the command defines `input` as\n`stdin` and has a JSON input argument in `args`, DSC sends the input data as a compressed\nJSON object over stdin and to the the specified argument.", + "body": { + "jsonInputArg": "${1:argument_name}", + "mandatory": "^$2" + } + } + ], + "oneOf": [ + { + "type": "string", + "title": "String argument", + "description": "Any item in the argument array can be a string representing a static argument to pass to the command.", + "markdownDescription": "Any item in the argument array can be a string representing a static argument to pass to\nthe command.\n" + }, + { + "type": "object", + "title": "JSON input argument", + "description": "Defines an argument for the command that accepts the JSON input object as a string. DSC passes the JSON input to the named argument when available. You can define the `mandatory` property to indicate whether DSC should always pass the argument to the command, even when there's no JSON input for the command. In that case, DSC passes an empty string to the JSON input argument. You can only define one JSON input argument per arguments array.", + "markdownDescription": "Defines an argument for the command that accepts the JSON input object as a string. DSC\npasses the JSON input to the named argument when available. You can define the `mandatory`\nproperty to indicate whether DSC should always pass the argument to the command, even when\nthere's no JSON input for the command. In that case, DSC passes an empty string to the\nJSON input argument. You can only define one JSON input argument per arguments array.\n\nIf you define a JSON input argument and an `input` kind for a command, DSC sends the JSON\ndata both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n", + "required": [ + "jsonInputArg" + ], + "unevaluatedProperties": false, + "properties": { + "jsonInputArg": { + "title": "JSON input argument name", + "description": "Defines the argument that accepts the JSON property bag for the resource as input.", + "markdownDescription": "Defines the argument that accepts the JSON property bag for the resource as input.\n", + "type": "string" + }, + "mandatory": { + "title": "Mandatory argument", + "description": "Defines whether the argument is mandatory. If this property is set to `true`, DSC passes an empty string when no JSON input is provided. The default value is `false`.", + "markdownDescription": "Defines whether the argument is mandatory. If this property is set to `true`, DSC\npasses an empty string when no JSON input is provided. The default value is `false`.\n", + "type": "boolean", + "default": false + } + } + } + ] + } + }, + "inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/inputKind.json", + "title": "Executable Command Input Type", + "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": [ + "env", + "stdin" + ], + "markdownEnumDescriptions": [ + "_Environment variables_\n\n> Indicates that the resource expects the properties of an instance to be specified as\n> environment variables with the same names and casing.\n>\n> This option only supports the following data types for instance properties:\n>\n> - `boolean`\n> - `integer`\n> - `number`\n> - `string`\n> - `array` of `integer` values\n> - `array` of `number` values\n> - `array` of `string` values\n>\n> For non-array values, DSC sets the environment variable to the specified value as-is. When\n> the data type is an array of values, DSC sets the environment variable as a comma-delimited\n> string. For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo`\n> environment variable as `\"1,2,3\"`.\n>\n> If the resource needs to support complex properties with an `object` value or multi-type\n> arrays, set this to `stdin` instead.\n", + "_JSON over `stdin`_\n\n> Indicates that the resource expects a JSON blob representing an instance from `stdin`.\n> The JSON must adhere to the instance schema.\n" + ] + }, + "returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." + } + }, + "resource": { + "manifest.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\n[_Online Documentation_][01]\n***\n\nDefines the information DSC and integrating require to process and call a command-based DSC\nResource. For DSC to use a manifest on a system, the manifest file must:\n\n1. Be discoverable in the `PATH` environment variable.\n1. Follow the naming convention `.dsc.resource.json`.\n1. Be valid for this schema.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true\n", + "defaultSnippets": [ + { + "label": " Define a resource", + "markdownDescription": "Defines a standard resource that:\n\n- Can get the current state of an instance\n- Can set an instance to the desired state\n- Relies on DSC's synthetic testing to determine whether an instance is in the desired state\n- Defines an embedded JSON schema.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "set": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "implementsPretest": "^${11:false}", + "return": "${12:state}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "${14:name}": { + "title": "${15:property title}", + "description": "${16:explanation of property purpose and usage}", + "type": "${17|string,integer,number,array,object,null|}" + } + } + } + } + } + }, + { + "label": " Define a resource (group)", + "markdownDescription": "Defines a group resource that expects a list of resource instances and operates on them.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "test": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "return": "${12:state}" + }, + "set": { + "executable": "${13:executable name}", + "args": [ + "${14:argument}" + ], + "input": "${15:stdin}", + "implementsPretest": "^${16:false}", + "return": "${17:state}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${18|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "resources": { + "title": "${19:Resources}", + "description": "${20:Defines a list of resource instances to process}", + "type": "array", + "items": { + "${escape_dollar:$}ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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 (adapter)", + "markdownDescription": "Defines an adapter resource that enables users to define non-command-based DSC Resources in\nthe configuration.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "test": { + "executable": "${8:executable name}", + "args": [ + "${9:argument}" + ], + "input": "${10:stdin}", + "return": "${12:state}" + }, + "set": { + "executable": "${13:executable name}", + "args": [ + "${14:argument}" + ], + "input": "${15:stdin}", + "implementsPretest": "^${16:false}", + "return": "${17:state}" + }, + "adapter": { + "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/2024/04/config/document.resource.json" + } + }, + "${26:name}": { + "title": "${27:property title}", + "description": "${28:explanation of property purpose and usage}", + "type": "${29|string,integer,number,array,object,null|}" + } + } + } + } + } + }, + { + "label": " Define a resource (assertion-only)", + "markdownDescription": "Defines an assertion resource that can get the current state of an instance but not configure\nit. By default, the resource relies on DSC's synthetic testing feature. If the resource\nimplements the `test` operation itself, define the `test` property.", + "body": { + "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "type": "${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\\.]dsc[\\.]resource/$1/}}", + "version": "${3:0.1.0}", + "description": "${4:Synopsis for the resource's purpose}", + "get": { + "executable": "${5:executable name}", + "args": [ + "${6:argument}" + ], + "input": "${7:stdin}" + }, + "schema": { + "embedded": { + "${escape_dollar:$}schema": "${13|https://json-schema.org/draft/2020-12/schema,https://json-schema.org/draft/2019-09/schema,http://json-schema.org/draft-07/schema#|}", + "type": "object", + "properties": { + "${14:name}": { + "title": "${15:property title}", + "description": "${16:explanation of property purpose and usage}", + "type": "${17|string,integer,number,array,object,null|}" + } + } + } + } + } + } + ], + "type": "object", + "required": [ + "$schema", + "type", + "version", + "get" + ], + "properties": { + "$schema": { + "title": "Manifest Schema", + "description": "This property must be the canonical URL of the Command-based DSC Resource Manifest schema that the manifest is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json", + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json" + ], + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nThis property must be one of the canonical URLs for the version of the Command-based DSC\nResource Manifest schema that the manifest is implemented for.\n\nFor every version of the schema, there are three valid urls:\n\n```yaml\n.../resource/manifest.json\n```\n\n> The URL to the canonical non-bundled schema. When it's used for validation, the validating\n> client needs to retrieve this schema and every schema it references.\n\n```yaml\n.../bundled/resource/manifest.json\n```\n\n> The URL to the bundled schema. When it's used for validation, the validating client only\n> needs to retrieve this schema.\n> \n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n\n```yaml\n.../bundled/resource/manifest.vscode.json\n```\n\n> The URL to the enhanced authoring schema. This schema is much larger than the other\n> schemas, as it includes additional definitions that provide contextual help and snippets\n> that the others don't include.\n> \n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/root?view=dsc-3.0&preserve-view=true#schema\n", + "markdownEnumDescriptions": [ + "\n\n> #### `2024/04` non-bundled\n>\n> Indicates that the resource manifest adheres to the `2024/04` schema. This URL\n> points to the canonical non-bundled schema. When it's used for validation, the\n> validating client needs to retrieve this schema and every schema it references.\n", + "\n\n> #### `2024/04` bundled\n>\n> Indicates that the resource manifest adheres to the `2024/04` schema. This URL\n> points to the bundled schema. When it's used for validation, the validating client\n> only needs to retrieve this schema.\n>\n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n", + "\n\n> #### `2024/04` enhanced authoring\n>\n> Indicates that the resource manifest adheres to the `2024/04` schema. This URL\n> points to the enhanced authoring schema. This schema is much larger than the other\n> schemas, as it includes additional definitions that provide contextual help and\n> snippets that the others don't include.\n>\n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n", + "\n\n> #### `2023/10` non-bundled\n>\n> Indicates that the resource manifest adheres to the `2023/10` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.5` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the canonical non-bundled schema. When it's used for validation, the\n> validating client needs to retrieve this schema and every schema it references.\n", + "\n\n> #### `2023/10` bundled\n>\n>Indicates that the resource manifest adheres to the `2023/10` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.5` and earlier.\n> Migrate to using the `2024/04` of the schema.\n>\n> This URL points to the bundled schema. When it's used for validation, the validating\n> client only needs to retrieve this schema.\n>\n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n", + "\n\n> #### `2023/10` enhanced authoring\n>\n>Indicates that the resource manifest adheres to the `2023/10` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.5` and earlier.\n> Migrate to using the `2024/04` of the schema.\n>\n> This URL points to the enhanced authoring schema. This schema is much larger than the\n> other schemas, as it includes additional definitions that provide contextual help and\n> snippets that the others don't include.\n>\n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n", + "\n\n> #### `2023/08` non-bundled\n>\n> Indicates that the resource manifest adheres to the `2023/08` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.3` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the canonical non-bundled schema. When it's used for validation, the\n> validating client needs to retrieve this schema and every schema it references.\n", + "\n\n> #### `2023/08` bundled\n>\n> Indicates that the resource manifest adheres to the `2023/08` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.3` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the bundled schema. When it's used for validation, the validating\n> client only needs to retrieve this schema.\n>\n> This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can\n> still validate the document when it uses this schema, other tools may error or behave\n> in unexpected ways.\n", + "\n\n> #### `2023/08` enhanced authoring\n>\n> Indicates that the resource manifest adheres to the `2023/08` schema. This version\n> is deprecated, and should only be used for compatibility with `alpha.3` and earlier.\n> Migrate to using the `2024/04` of the schema \n>\n> This URL points to the enhanced authoring schema. This schema is much larger than the\n> other schemas, as it includes additional definitions that provide contextual help and\n> snippets that the others don't include.\n>\n> This schema uses keywords that are only recognized by VS Code. While DSC can still\n> validate the document when it uses this schema, other tools may error or behave in\n> unexpected ways.\n" + ] + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/semver.json", + "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": "***\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" + }, + "kind": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json" + }, + "tags": { + "title": "Tags", + "description": "Defines a list of searchable terms for the resource.", + "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": { + "type": "string", + "pattern": "^\\w+$", + "patternErrorMessage": "Invalid tag. Tags must be a string of alphanumeric characters and underscores. No other\ncharacters are permitted.\n" + } + }, + "get": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json" + }, + "set": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json" + }, + "test": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json" + }, + "delete": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json" + }, + "export": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json" + }, + "validate": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json" + }, + "adapter": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$", + "patternErrorMessage": "Invalid exit code. Must be a string representing an integer greater than or equal to `0`.\n" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + }, + "unevaluatedProperties": false, + "default": { + "0": "Success", + "1": "Error" + }, + "examples": [ + { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "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": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json" + } + } + }, + "manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to get the current state of an instance.\n\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\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/2024/04/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/2024/04/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\": \"myresource\",\n \"args\": [\"config\", \"get\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config get\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property. When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"get\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config get --properties \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/2024/04/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`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true#input\n" + } + }, + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `get` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `get` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/get?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `get` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}" + } + }, + { + "label": " Define with string arguments", + "markdownDescription": "Define the `get` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + }, + { + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `get` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", + "body": { + "executable": "${1:executable_name}", + "args": [ + { + "jsonInputArg": "${2:argument_name}", + "mandatory": "^$3" + } + ] + } + } + ] + }, + "manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\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" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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/2024/04/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\": \"myresource\",\n \"args\": [\"config\", \"set\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config set\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property.` When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"set\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config set --properties \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/2024/04/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`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#input\n" + }, + "implementsPretest": { + "title": "Resource Performs Pre-Test", + "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", + "type": "boolean", + "default": false, + "markdownDescription": "***\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" + }, + "handlesExist": { + "title": "Resource handles _exist property", + "description": "Defines whether the DSC Resource has its own built-in handling for the `_exist` common property. Set this value to `true` if the DSC Resource handles instance deletion internally when receiving a `set` command where the instance defines the `_exist` property as `false`.", + "type": "boolean", + "default": false, + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the DSC Resource has its own built-in handling for the [`_exist`][02] common\nproperty. Set this value to `true` if the DSC Resource handles instance deletion internally\nwhen receiving a `set` command where the instance defines the `_exist` property as `false`.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#handlesExist\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?view=dsc-3.0&preserve-view=true\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/2024/04/definitions/returnKind.json", + "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": [ + "_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" + ] + } + }, + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `set` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `set` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `set` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", + "body": { + "input": "${1|stdin,env|}", + "implementsPretest": "^${2|true,false|}", + "return": "${3|state,stateAndDiff|}", + "executable": "${4:executable_name}" + } + }, + { + "label": " Define with string arguments", + "markdownDescription": "Define the `set` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", + "body": { + "input": "${1|stdin,env|}", + "implementsPretest": "^${2|true,false|}", + "return": "${3|state,stateAndDiff|}", + "executable": "${4:executable_name}", + "args": [ + "${5:--first-argument}" + ] + } + }, + { + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `set` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", + "body": { + "implementsPretest": "^${1|true,false|}", + "return": "${2|state,stateAndDiff|}", + "executable": "${3:executable_name}", + "args": [ + { + "jsonInputArg": "${4:argument_name}", + "mandatory": "^$5" + } + ] + } + } + ] + }, + "manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\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" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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/test?view=dsc-3.0&preserve-view=true#executable\n" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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\": \"myresource\",\n \"args\": [\"config\", \"test\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config test\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property.` When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"test\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config test --properties \n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserve-view=true#args\n" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?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/2024/04/definitions/returnKind.json", + "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": [ + "_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" + ] + } + }, + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `test` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `test` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/test?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `test` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", + "body": { + "input": "${1|stdin,env|}", + "return": "${2|state,stateAndDiff|}", + "executable": "${3:executable_name}" + } + }, + { + "label": " Define with string arguments", + "markdownDescription": "Define the `test` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", + "body": { + "input": "${1|stdin,env|}", + "return": "${2|state,stateAndDiff|}", + "executable": "${3:executable_name}", + "args": [ + "${4:--first-argument}" + ] + } + }, + { + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `test` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", + "body": { + "return": "${1|state,stateAndDiff|}", + "executable": "${2:executable_name}", + "args": [ + { + "jsonInputArg": "${3:argument_name}", + "mandatory": "^$4" + } + ] + } + } + ] + }, + "manifest.delete.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json", + "title": "Delete method", + "description": "Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources as an alternative to handling the `_exist` property in a `set` operation, which can lead to highly complex code. If the `set` operation for the resource is able to handle deleting an instance when `_exist` is `false`, set the `handlesExist` property of the set method definition to `true` instead.", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to delete an instance. Define this method for\nresources as an alternative to handling the [`_exist`][02] property in a `set` operation, which\ncan lead to highly complex code. If the `set` method for the resource is able to handle deleting\nan instance when `_exist` is `false`, set the [`handlesExist`][03] property of the set method\ndefinition to `true` instead.\n\nIf you define the delete method in a resource manifest, ensure that you also define the\n[`_exist`][02] property in the [JSON schema for the resource's properties][04].\n\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true\n[02]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?view=dsc-3.0&preserve-view=true\n[03]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/set?view=dsc-3.0&preserve-view=true#handlesExist\n[04]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true\n", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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/delete?view=dsc-3.0&preserve-view=true#executable\n" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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\": \"myresource\",\n \"args\": [\"config\", \"delete\"]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config delete\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property.` When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"set\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config set --properties \n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true#args\n" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true#input\n" + } + }, + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `delete` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `delete` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/delete?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `delete` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}" + } + }, + { + "label": " Define with string arguments", + "markdownDescription": "Define the `delete` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + }, + { + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `delete` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", + "body": { + "executable": "${1:executable_name}", + "args": [ + { + "jsonInputArg": "${2:argument_name}", + "mandatory": "^$3" + } + ] + } + } + ] + }, + "manifest.export.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json", + "title": "Export Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of every instance.", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource to get the current state of every instance.\n\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\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/2024/04/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/2024/04/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\": \"myresource\",\n \"args\": [\"config\", \"export\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config export\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property.` When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"export\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config export --properties \n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true#args\n" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true#input\n" + } + }, + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `export` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `export` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/export?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `export` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}" + } + }, + { + "label": " Define with string arguments", + "markdownDescription": "Define the `export` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + }, + { + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `export` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", + "body": { + "executable": "${1:executable_name}", + "args": [ + { + "jsonInputArg": "${2:argument_name}", + "mandatory": "^3" + } + ] + } + } + ] + }, + "manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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": "***\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\nDSC sends data to the command in three ways:\n\n1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed\n JSON object without spaces or newlines between the object properties.\n1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment\n variable for each property in the input data object, using the name and value of the property.\n1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string\n representing the data as a compressed JSON object to the specified argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't pass\nthe input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or\nboth.\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/2024/04/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/validate?view=dsc-3.0&preserve-view=true#executable\n" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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\": \"myresource\",\n \"args\": [\"config\", \"validate\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config validate\n```\n\nIf you want to pass the JSON object representing the property bag for a resource instance to\nan argument, you can define a single item in the array as a JSON object. Indicate the name of\nthe argument with the `jsonInputArg` string property and whether the argument is mandatory\nfor the command with the `mandatory` boolean property.` When the `mandatory` property is\ndefined as `true`, DSC passes an empty string to the argument when no JSON input is\navailable. When the `mandatory` property is undefined or defined as `false`, DSC doesn't pass\nthe argument at all when no JSON input is available. The default value for the `mandatory`\nproperty is `false`.\n\nFor example, given the following definition:\n\n```json\n{\n \"executable\": \"myresource\"\n \"args\": [\n \"config\",\n \"validate\",\n { \"jsonInputArg\": \"--properties\" }\n ]\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource config validate --properties \n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserve-view=true#args\n" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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`. This property is optional when you define an object in the `args` list. If\nyou define a JSON input argument and an `input`, DSC sends the JSON data both ways:\n\n- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable\n for each property in the JSON input and passes the JSON input object as a string to the\n defined argument.\n- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over\n stdin and as a string to the defined argument.\n- If you define a JSON input argument without defining the `input` property, DSC only passes\n the JSON input as a string to the defined argument.\n\nIf you don't define the `input` property and don't define a JSON input argument, DSC can't\npass the input JSON to the resource. This makes the manifest invalid. You must define the\n`input` property, a JSON input argument in the `args` property array, or both.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserve-view=true#input\n" + } + }, + "oneOf": [ + { + "required": [ + "input" + ], + "not": { + "properties": { + "args": { + "contains": { + "type": "object" + } + } + } + } + }, + { + "not": { + "required": [ + "input" + ] + }, + "properties": { + "args": { + "errorMessage": "The `validate` command doesn't define either the `input` property or a JSON input argument, or it defines more than one JSON input argument. If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the input JSON to the resource. You can only define one JSON input argument for a command.\n\nYou must define the `input` property, one JSON input argument in the `args` property array, or both. For more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + }, + { + "required": [ + "input" + ], + "properties": { + "args": { + "errorMessage": "You can only specify one JSON input argument for the `validate` command. Remove the extra JSON input argument. When you use the JSON input argument, DSC sends the full JSON object as a string to the named argument.\n\nFor more information, see:\n\nhttps://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/validate?view=dsc-3.0&preserve-view=true", + "contains": { + "type": "object" + }, + "minContains": 1, + "maxContains": 1 + } + } + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the `validate` command for the resource when no arguments are required and the JSON\ninput is sent over stdin or as environment variables.\n", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}" + } + }, + { + "label": " Define with string arguments", + "markdownDescription": "Define the `validate` command for the resource when at least one argument is required and the\nJSON input is sent over stdin or as environment variables.", + "body": { + "input": "${1|stdin,env|}", + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + }, + { + "label": " Define with a JSON input argument", + "markdownDescription": "Define the `validate` command for the resource where the JSON input is passed as a one-line\nJSON object string to the specified argument.", + "body": { + "executable": "${1:executable_name}", + "args": [ + { + "jsonInputArg": "${2:argument_name}", + "mandatory": "^$3" + } + ] + } + } + ] + }, + "manifest.adapter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json", + "title": "Adapter", + "description": "Defines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter enables users to manage resources that don't have their own manifests with DSC.", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter 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/adapter?view=dsc-3.0&preserve-view=true\n", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Adapter to list its supported DSC Resources.", + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines how DSC must call the DSC Resource Adapter to list its supported DSC Resources.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/adapter?view=dsc-3.0&preserve-view=true#list\n", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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/adapter?view=dsc-3.0&preserve-view=true#executable\n" + }, + "args": { + "type": "array", + "items": { + "type": "string" + }, + "title": "Command arguments", + "description": "Defines the list of arguments to pass to the command to return the list of supported DSC Resources.", + "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/adapter?view=dsc-3.0&preserve-view=true#args\n" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the adapter expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ], + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nDefines whether the adapter 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/adapter?view=dsc-3.0&preserve-view=true#config\n", + "markdownEnumDescriptions": [ + "_Full and unprocessed config as a JSON blob_\n\n> Indicates that the adapter 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 adapter expects each resource's configuration as a [JSON Line][01]\n> over `stdin`.\n\n[01]: https://jsonlines.org/\n" + ] + } + }, + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } + } + ], + "defaultSnippets": [ + { + "label": " Define without arguments", + "markdownDescription": "Define the adapter config kind and `list` command for the resource when no arguments are\nrequired.\n", + "body": { + "config": "${1|full,sequence}", + "list": { + "executable": "${2:executable_name}" + } + } + }, + { + "label": " Define with arguments", + "markdownDescription": "Define the adapter config kind and `list` command for the resource when at least one\nargument is required.\n", + "body": { + "config": "${1|full,sequence}", + "list": { + "executable": "${2:executable_name}", + "args": [ + "${3:--first-argument}" + ] + } + } + } + ] + }, + "manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": [ + "command" + ] + }, + { + "required": [ + "embedded" + ] + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/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/schema/property?view=dsc-3.0&preserve-view=true#executable\n" + }, + "args": { + "type": "array", + "items": { + "type": "string" + }, + "title": "Command arguments", + "description": "Defines the list of arguments to pass to the command to return the JSON Schema for the resource.", + "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\": \"myresource\",\n \"args\": [\"schema\", \"show\"],\n}\n```\n\nDSC invokes the command for the resource as:\n\n```bash\nmyresource schema show\n```\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/manifest/schema/property?view=dsc-3.0&preserve-view=true#args\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": "***\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", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object", + "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", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ], + "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": [ + "_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": { + "title": "DSC Resource instance schema ID", + "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": "***\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": "***\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": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "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": { + "_exist": { + "title": "Standard Property: _exist", + "description": "Indicates that the DSC Resource uses the standard `_exist` property to specify whether an instance should exist as a boolean value that defaults to `true`.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json" + }, + "markdownDescription": "***\n[_Online Documentation_][01]\n***\n\nIndicates that the resource can enforce whether instances exist, handling whether an\ninstance should be added, updated, or removed during a set operation. The default\nvalue is `true`.\n\nResources that define this property declare that the implementation adheres to the\nfollowing behavior contract:\n\n1. When the desired state for `_exist` is `true`, the resource expects the instance\n to exist. If it doesn't exist, the resource creates or adds the instance during\n the set operation.\n1. When the desired state for `_exist` is `false`, the resource expects the instance\n to not exist. If it does exist, the resource deletes or removes the instance\n during the set operation.\n\n[01]: https://learn.microsoft.com/powershell/dsc/reference/schemas/resource/properties/exist?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 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/2024/04/resource/properties/inDesiredState.json" + }, + "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", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json" + }, + "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 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/2024/04/resource/properties/rebootRequested.json" + }, + "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|}" + } + } + } + ] + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri", + "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": [ + { + "command": { + "executable": "registry", + "args": [ + "schema" + ] + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ], + "markdownDescription": "***\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|}" + } + } + } + } + } + ] + } + } + } + } + } + } + } + } + } +} diff --git a/schemas/2024/04/bundled/outputs/resource/schema.vscode.json b/schemas/2024/04/bundled/outputs/resource/schema.vscode.json new file mode 100644 index 000000000..46a2bd905 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/resource/schema.vscode.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc resource schema` command. This command always returns the DSC Resource's JSON schema document.", + "type": "object", + "$defs": {} +} diff --git a/schemas/2024/04/bundled/outputs/resource/set.vscode.json b/schemas/2024/04/bundled/outputs/resource/set.vscode.json new file mode 100644 index 000000000..b724bafd4 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/resource/set.vscode.json @@ -0,0 +1,174 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the enforced state of a non-nested instance or an array of objects that describe the enforced state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json" + } + } + ], + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2024": { + "04": { + "outputs": { + "resource": { + "set.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json", + "title": "dsc resource set result (simple)", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource set` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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" + } + } + } + }, + "set.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json", + "title": "dsc resource set result (full)", + "description": "Describes the return data for the full result of the `set` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config set` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource set` command.", + "type": "object", + "required": [ + "metadata", + "name", + "result", + "type" + ], + "properties": { + "metadata": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, + "name": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.json" + } + } + }, + "set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/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. The return data is either a single object that describes the enforced state of a non-nested instance or an array of objects that describe the enforced state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.full.json" + } + } + ] + } + } + }, + "metadata": { + "resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "markdownDescription": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or\n`dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe\nthe context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + }, + "Microsoft.DSC": { + "duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "markdownDescription": "Defines the duration of a DSC operation against a configuration document or resource instance as\na string following the format defined in [ISO8601 ABNF for `duration`][01]. For example,\n`PT0.611216S` represents a duration of about `0.61` seconds.\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" + } + } + }, + "definitions": { + "instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "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": "***\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" + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", + "markdownDescription": "***\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" + } + } + } + } + } + } + } + } + } +} diff --git a/schemas/2024/04/bundled/outputs/resource/test.vscode.json b/schemas/2024/04/bundled/outputs/resource/test.vscode.json new file mode 100644 index 000000000..248e1dea9 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/resource/test.vscode.json @@ -0,0 +1,180 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command. The return data is either a single object that describes the tested state of a non-nested instance or an array of objects that describe the tested state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json" + } + } + ], + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2024": { + "04": { + "outputs": { + "resource": { + "test.simple.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json", + "title": "dsc resource test result (simple)", + "description": "Describes the return data for a single DSC Resource instance from the `dsc resource test` command. This data is returned for instances that aren't group resources, adapter resources, or nested inside a group or adapter resource.\nWhen you use `dsc resource test` for a group or adapter resource, the command returns an array of full test result objects that include the name and type for the nested instances.", + "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" + } + } + } + }, + "test.full.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json", + "title": "dsc resource test result (full)", + "description": "Describes the return data for the full result of the `test` operation for a\nresource instance. This data is returned:\n\n- For every instance in a configuration document when you use the\n `dsc config test` command.\n\n- For nested instances of a group or adapter resource when you use the\n `dsc resource test` command.", + "type": "object", + "required": [ + "metadata", + "name", + "result", + "type" + ], + "properties": { + "metadata": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json" + }, + "name": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json" + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json" + }, + "result": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json" + } + } + }, + "test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command. The return data is either a single object that describes the tested state of a non-nested instance or an array of objects that describe the tested state of the nested instances for a group or adapter resource.", + "anyOf": [ + { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.simple.json" + }, + { + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.full.json" + } + } + ] + } + } + }, + "metadata": { + "resourceInstanceResult.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/resourceInstanceResult.json", + "title": "Resource instance result metadata", + "description": "Defines metadata DSC returns for a DSC configuration operation against a resource instance in a configuration document, as from the `dsc config get` or `dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe the context of the operation.", + "markdownDescription": "Defines metadata DSC returns for a configuration operation, as from the `dsc config get` or\n`dsc config set` commands. The metadata properties under the `Microsoft.DSC` property describe\nthe context of the operation.", + "type": "object", + "required": [ + "Microsoft.DSC" + ], + "properties": { + "Microsoft.DSC": { + "title": "DSC context metadata", + "description": "The child properties for this metadata describe the context of the DSC operation against a resource instance, including the duration of the operation.", + "type": "object", + "required": [ + "duration" + ], + "properties": { + "duration": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json" + } + } + } + } + }, + "Microsoft.DSC": { + "duration.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json", + "title": "Duration", + "description": "Defines the duration of a DSC operation against a configuration document or resource instance as a string following the format defined in ISO8601 ABNF for `duration`. For example, `PT0.611216S` represents a duration of about `0.61` seconds. For more information, see: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "markdownDescription": "Defines the duration of a DSC operation against a configuration document or resource instance as\na string following the format defined in [ISO8601 ABNF for `duration`][01]. For example,\n`PT0.611216S` represents a duration of about `0.61` seconds.\n\n[01]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A", + "type": "string", + "format": "duration" + } + } + }, + "definitions": { + "instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. Must be a non-empty string containing only letters, numbers, and spaces.", + "type": "string", + "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": "***\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" + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$", + "markdownDescription": "***\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" + } + } + } + } + } + } + } + } + } +} diff --git a/schemas/2024/04/bundled/outputs/schema.vscode.json b/schemas/2024/04/bundled/outputs/schema.vscode.json new file mode 100644 index 000000000..2214fb830 --- /dev/null +++ b/schemas/2024/04/bundled/outputs/schema.vscode.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc schema` command. This command always returns a JSON schema document.", + "type": "object", + "$defs": {} +} diff --git a/schemas/examples/foo.dsc.config.yaml b/schemas/examples/configuration_document/example.dsc.config.yaml similarity index 100% rename from schemas/examples/foo.dsc.config.yaml rename to schemas/examples/configuration_document/example.dsc.config.yaml diff --git a/schemas/examples/output/config.get.yaml b/schemas/examples/output/config.get.yaml new file mode 100644 index 000000000..9d79c1bb8 --- /dev/null +++ b/schemas/examples/output/config.get.yaml @@ -0,0 +1,50 @@ +# yaml-language-server: $schema=../../2024/04/bundled/outputs/config/get.vscode.json +# +# Shows output from `dsc config get --path dsc/examples/osinfo_registry.dsc.yaml +# +metadata: + Microsoft.DSC: + version: 3.0.0-preview.7 + operation: Get + executionType: Actual + startDatetime: 2024-04-16T15:29:19.776934500-05:00 + endDatetime: 2024-04-16T15:29:20.052168700-05:00 + duration: PT0.275234200S + securityContext: Restricted +results: +- metadata: + Microsoft.DSC: + duration: PT0.053120900S + name: os + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22631 + edition: Windows 11 Enterprise + bitness: '64' +- metadata: + Microsoft.DSC: + duration: PT0.137957200S + name: windows product name + type: Microsoft.Windows/Registry + result: + actualState: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: ProductName + valueData: + String: Windows 10 Enterprise +- metadata: + Microsoft.DSC: + duration: PT0.035664200S + name: system root + type: Microsoft.Windows/Registry + result: + actualState: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: SystemRoot + valueData: + String: C:\WINDOWS +messages: [] +hadErrors: false diff --git a/schemas/examples/output/config.test.yaml b/schemas/examples/output/config.test.yaml new file mode 100644 index 000000000..587c5cae4 --- /dev/null +++ b/schemas/examples/output/config.test.yaml @@ -0,0 +1,63 @@ +# yaml-language-server: $schema=../../2024/04/bundled/outputs/config/get.vscode.json +# +# Shows output from `dsc config get --path dsc/examples/osinfo_registry.dsc.yaml +# +metadata: + Microsoft.DSC: + version: 3.0.0-preview.7 + operation: Test + executionType: Actual + startDatetime: 2024-04-16T15:31:15.556395700-05:00 + endDatetime: 2024-04-16T15:31:15.820044900-05:00 + duration: PT0.263649200S + securityContext: Restricted +results: +- metadata: + Microsoft.DSC: + duration: PT0.061508200S + name: os + type: Microsoft/OSInfo + result: + desiredState: {} + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22631 + edition: Windows 11 Enterprise + bitness: '64' + inDesiredState: true + differingProperties: [] +- metadata: + Microsoft.DSC: + duration: PT0.142056900S + name: windows product name + type: Microsoft.Windows/Registry + result: + desiredState: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: ProductName + actualState: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: ProductName + valueData: + String: Windows 10 Enterprise + inDesiredState: true + differingProperties: [] +- metadata: + Microsoft.DSC: + duration: PT0.033704600S + name: system root + type: Microsoft.Windows/Registry + result: + desiredState: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: SystemRoot + actualState: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: SystemRoot + valueData: + String: C:\WINDOWS + inDesiredState: true + differingProperties: [] +messages: [] +hadErrors: false diff --git a/schemas/examples/foo.dsc.resource.json b/schemas/examples/resource_manifest/foo.dsc.resource.json similarity index 100% rename from schemas/examples/foo.dsc.resource.json rename to schemas/examples/resource_manifest/foo.dsc.resource.json diff --git a/schemas/examples/foo.dsc.resource.yaml b/schemas/examples/resource_manifest/foo.dsc.resource.yaml similarity index 100% rename from schemas/examples/foo.dsc.resource.yaml rename to schemas/examples/resource_manifest/foo.dsc.resource.yaml diff --git a/schemas/schemas.config.yaml b/schemas/schemas.config.yaml index 3f4ced149..f8d2a3688 100644 --- a/schemas/schemas.config.yaml +++ b/schemas/schemas.config.yaml @@ -20,44 +20,44 @@ bundle_schemas: - ConfigFilePath: outputs/schema.json Name: schema OutputDirectory: bundled/outputs - OutputFormat: ['Json'] + OutputFormat: ['Json', 'JsonVSCode'] - ConfigFilePath: outputs/config/get.json Name: get OutputDirectory: bundled/outputs/config - OutputFormat: ['Json'] + OutputFormat: ['Json', 'JsonVSCode'] - ConfigFilePath: outputs/config/set.json Name: set OutputDirectory: bundled/outputs/config - OutputFormat: ['Json'] + OutputFormat: ['Json', 'JsonVSCode'] - ConfigFilePath: outputs/config/test.json Name: test OutputDirectory: bundled/outputs/config - OutputFormat: ['Json'] + OutputFormat: ['Json', 'JsonVSCode'] - ConfigFilePath: outputs/resource/get.json Name: get OutputDirectory: bundled/outputs/resource - OutputFormat: ['Json'] + OutputFormat: ['Json', 'JsonVSCode'] - ConfigFilePath: outputs/resource/list.json Name: list OutputDirectory: bundled/outputs/resource - OutputFormat: ['Json'] + OutputFormat: ['Json', 'JsonVSCode'] - ConfigFilePath: outputs/resource/schema.json Name: schema OutputDirectory: bundled/outputs/resource - OutputFormat: ['Json'] + OutputFormat: ['Json', 'JsonVSCode'] - ConfigFilePath: outputs/resource/set.json Name: set OutputDirectory: bundled/outputs/resource - OutputFormat: ['Json'] + OutputFormat: ['Json', 'JsonVSCode'] - ConfigFilePath: outputs/resource/test.json Name: test OutputDirectory: bundled/outputs/resource - OutputFormat: ['Json'] + OutputFormat: ['Json', 'JsonVSCode'] From 87ca2a96d92124593fe38d796db733e028c78cbd Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Tue, 16 Apr 2024 15:55:01 -0500 Subject: [PATCH 15/15] (MAINT) Fix assertion example Prior to this change, the example configuration document for assertions was invalid, using the `_ensure` property instead of `_exist`. This change updates the document to be valid. --- dsc/examples/assertion.dsc.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dsc/examples/assertion.dsc.yaml b/dsc/examples/assertion.dsc.yaml index a746bcb33..aebff4f5e 100644 --- a/dsc/examples/assertion.dsc.yaml +++ b/dsc/examples/assertion.dsc.yaml @@ -5,7 +5,7 @@ resources: type: Microsoft.Windows/Registry properties: keyPath: HKCU\example - _ensure: Present + _exist: true dependsOn: - "[resourceId('Microsoft.DSC/Assertion','my assertions')]" - name: my assertions