From 7185c2912f311c11df236537f7e247b0205af6a6 Mon Sep 17 00:00:00 2001 From: Mikey Lombardi Date: Tue, 1 Apr 2025 14:47:50 -0500 Subject: [PATCH 1/8] (SCHEMA) Update schema source for terminology This change updates casing and terms to match the glossary. These changes are colocated to make reviewing actual schema changes simpler. --- schemas/src/config/document.parameter.yaml | 4 +- schemas/src/config/document.resource.yaml | 24 ++++---- schemas/src/config/document.yaml | 20 +++---- schemas/src/definitions/hadErrors.yaml | 2 +- schemas/src/definitions/instanceName.yaml | 6 +- schemas/src/definitions/message.yaml | 6 +- schemas/src/definitions/messages.yaml | 2 +- .../src/definitions/parameters/dataTypes.yaml | 2 +- .../parameters/validValueTypes.yaml | 2 +- schemas/src/definitions/resourceKind.yaml | 2 +- schemas/src/definitions/resourceType.yaml | 8 +-- schemas/src/outputs/config/get.yaml | 6 +- schemas/src/outputs/config/set.yaml | 6 +- schemas/src/outputs/config/test.yaml | 6 +- schemas/src/outputs/resource/get.simple.yaml | 6 +- schemas/src/outputs/resource/get.yaml | 2 +- schemas/src/outputs/resource/list.yaml | 30 +++++----- schemas/src/outputs/resource/schema.yaml | 6 +- schemas/src/outputs/resource/set.simple.yaml | 12 ++-- schemas/src/outputs/resource/set.yaml | 2 +- schemas/src/outputs/resource/test.simple.yaml | 12 ++-- schemas/src/outputs/resource/test.yaml | 2 +- schemas/src/outputs/schema.yaml | 4 +- schemas/src/resource/manifest.adapter.yaml | 10 ++-- schemas/src/resource/manifest.delete.yaml | 4 +- schemas/src/resource/manifest.export.yaml | 4 +- schemas/src/resource/manifest.get.yaml | 4 +- schemas/src/resource/manifest.resolve.yaml | 2 +- schemas/src/resource/manifest.schema.yaml | 58 +++++++++---------- schemas/src/resource/manifest.set.yaml | 36 ++++++------ schemas/src/resource/manifest.test.yaml | 12 ++-- schemas/src/resource/manifest.validate.yaml | 8 +-- schemas/src/resource/manifest.whatIf.yaml | 36 ++++++------ schemas/src/resource/manifest.yaml | 35 ++++++----- schemas/src/resource/properties/exist.yaml | 4 +- schemas/src/resource/properties/purge.yaml | 12 ++-- 36 files changed, 199 insertions(+), 198 deletions(-) diff --git a/schemas/src/config/document.parameter.yaml b/schemas/src/config/document.parameter.yaml index f543cfb5..c187708e 100644 --- a/schemas/src/config/document.parameter.yaml +++ b/schemas/src/config/document.parameter.yaml @@ -2,14 +2,14 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: ///config/document.parameter.yaml title: Parameter -description: Defines a runtime option for a DSC Configuration Document. +description: Defines a runtime option for a DSC configuration document. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines a runtime option for a DSC Configuration Document. + Defines a runtime option for a DSC configuration document. [01]: /reference/schemas/config/parameter? diff --git a/schemas/src/config/document.resource.yaml b/schemas/src/config/document.resource.yaml index 9f83e6a1..80b49473 100644 --- a/schemas/src/config/document.resource.yaml +++ b/schemas/src/config/document.resource.yaml @@ -1,8 +1,8 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema $id: ///config/document.resource.yaml -title: DSC Resource instance -description: Defines an instance of a DSC Resource in a configuration. +title: DSC resource instance +description: Defines an instance of a DSC resource in a configuration. type: object required: @@ -16,7 +16,7 @@ properties: dependsOn: title: Instance depends on description: >- - Defines a list of DSC Resource instances that DSC must successfully process before processing + 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. @@ -47,7 +47,7 @@ properties: [_Online Documentation_][01] *** - Defines a list of DSC Resource instances that DSC must successfully process before processing + 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. @@ -67,8 +67,8 @@ properties: properties: title: Managed instance properties description: >- - Defines the properties of the DSC Resource this instance manages. This property's value must - be an object. DSC validates the property's value against the DSC Resource's schema. + Defines the properties of the DSC resource this instance manages. This property's value must + be an object. DSC validates the property's value against the DSC resource's schema. type: object # VS Code only markdownDescription: | @@ -76,8 +76,8 @@ properties: [_Online Documentation_][01] *** - Defines the properties of the DSC Resource this instance manages. This property's value must - be an object. DSC validates the property's value against the DSC Resource's schema. + Defines the properties of the DSC resource this instance manages. This property's value must + be an object. DSC validates the property's value against the DSC resource's schema. [01]: /reference/schemas/config/resource?#properties-1 @@ -87,9 +87,9 @@ markdownDescription: | [_Online Documentation_][01] *** - Defines an instance of a DSC Resource in a configuration. + Defines an instance of a DSC resource in a configuration. - The `resources` property of a DSC Configuration document always includes at least one DSC Resource + The `resources` property of a DSC configuration document always includes at least one DSC resource instance. Together, the instances in a configuration define the desired state that DSC can get, test, and set on a machine. @@ -98,7 +98,7 @@ markdownDescription: | defaultSnippets: - label: ' New resource instance' markdownDescription: |- - Defines a new instance of a DSC Resource for the configuration. + Defines a new instance of a DSC resource for the configuration. ```yaml type: owner[.group][.area]/name @@ -114,7 +114,7 @@ defaultSnippets: - label: ' New dependent resource instance' markdownDescription: |- - Defines a new instance of a DSC Resource for the configuration that depends on another + Defines a new instance of a DSC resource for the configuration that depends on another instance. ```yaml diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index ebb39ba9..777a2f22 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -1,17 +1,17 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema $id: ///config/document.yaml -title: DSC Configuration Document schema -description: Describes a valid DSC Configuration Document. +title: DSC configuration document schema +description: Describes a valid DSC configuration document. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Describes a valid DSC Configuration Document. + Describes a valid DSC configuration document. - DSC Configurations enable users to define state by combining different DSC Resources. A + DSC configurations enable users to define state by combining different DSC resources. A configuration document uses parameters and variables to pass to a set of one or more resources that define a desired state. @@ -26,7 +26,7 @@ properties: $schema: title: Schema description: >- - This property must be the canonical URL of the DSC Configuration Document schema that the + This property must be the canonical URL of the DSC configuration document schema that the document is implemented for. type: string format: uri @@ -46,7 +46,7 @@ properties: [_Online Documentation_][01] *** - This property must be the canonical URL of the DSC Configuration Document schema that the + This property must be the canonical URL of the DSC configuration document schema that the document is implemented for. For every version of the schema, there are three valid urls: @@ -206,7 +206,7 @@ properties: > unexpected ways. parameters: - title: DSC Configuration document 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. @@ -318,8 +318,8 @@ properties: - ${3:secondValue} resources: - title: DSC Configuration document resources - description: Defines a list of DSC Resource instances for the configuration to manage. + title: DSC configuration document resources + description: Defines a list of DSC resource instances for the configuration to manage. type: array minItems: 1 items: @@ -330,7 +330,7 @@ properties: [_Online Documentation_][01] *** - Defines a list of DSC Resource instances for the configuration to manage. + Defines a list of DSC resource instances for the configuration to manage. [01]: /reference/schemas/config/document?#resources diff --git a/schemas/src/definitions/hadErrors.yaml b/schemas/src/definitions/hadErrors.yaml index f5ab2b40..ca9352b5 100644 --- a/schemas/src/definitions/hadErrors.yaml +++ b/schemas/src/definitions/hadErrors.yaml @@ -4,5 +4,5 @@ $id: ///definitions/hadErrors.yaml title: Had Errors description: >- - Indicates whether any of the DSC Resources returned a non-zero exit code. + Indicates whether any of the DSC resources returned a non-zero exit code. type: boolean \ No newline at end of file diff --git a/schemas/src/definitions/instanceName.yaml b/schemas/src/definitions/instanceName.yaml index 9ec752ed..616fb6d0 100644 --- a/schemas/src/definitions/instanceName.yaml +++ b/schemas/src/definitions/instanceName.yaml @@ -4,7 +4,7 @@ $id: ///definitions/instanceName.yaml title: Instance name description: >- - The short, human-readable name for a DSC Resource instance. Must be unique within a DSC + 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 ]+$ @@ -19,8 +19,8 @@ markdownDescription: | [_Online Documentation_][01] *** - Defines the short, human-readable name for a DSC Resource instance. This property must be unique - within a DSC Configuration document. If any resource instances share the same name, DSC raises an + Defines the short, human-readable name for a DSC resource instance. This property must be unique + within a DSC configuration document. If any resource instances share the same name, DSC raises an error. The instance name must be a non-empty string containing only letters, numbers, and spaces. diff --git a/schemas/src/definitions/message.yaml b/schemas/src/definitions/message.yaml index 722c5e0a..0e3007b9 100644 --- a/schemas/src/definitions/message.yaml +++ b/schemas/src/definitions/message.yaml @@ -4,7 +4,7 @@ $id: ///definitions/message.yaml title: Message description: >- - A message emitted by a DSC Resource with associated metadata. + A message emitted by a DSC resource with associated metadata. type: object required: @@ -17,14 +17,14 @@ properties: 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. + as defined in the DSC configuration document. type: string type: $ref: ///definitions/resourceType.yaml message: title: Message content description: >- - The actual content of the message as emitted by the DSC Resource. + The actual content of the message as emitted by the DSC resource. type: string minLength: 1 level: diff --git a/schemas/src/definitions/messages.yaml b/schemas/src/definitions/messages.yaml index 24663794..78e43df5 100644 --- a/schemas/src/definitions/messages.yaml +++ b/schemas/src/definitions/messages.yaml @@ -4,7 +4,7 @@ $id: ///definitions/messages.yaml title: Messages description: >- - A list of structured messages emitted by the DSC Resources during an + A list of structured messages emitted by the DSC resources during an operation. type: array diff --git a/schemas/src/definitions/parameters/dataTypes.yaml b/schemas/src/definitions/parameters/dataTypes.yaml index da25c957..19284f94 100644 --- a/schemas/src/definitions/parameters/dataTypes.yaml +++ b/schemas/src/definitions/parameters/dataTypes.yaml @@ -75,7 +75,7 @@ markdownEnumDescriptions: - | # int _Integer values are numbers without a fractional part._ - > Integer values may be limited by integrating tools or the DSC Resources they're used with. + > Integer values may be limited by integrating tools or the DSC resources they're used with. > DSC itself supports integer values between `-9223372036854775808` and `9223372036854775807`. > > For more information, see the [_Online Documentation_][01]. diff --git a/schemas/src/definitions/parameters/validValueTypes.yaml b/schemas/src/definitions/parameters/validValueTypes.yaml index d6419fde..8aff1ad6 100644 --- a/schemas/src/definitions/parameters/validValueTypes.yaml +++ b/schemas/src/definitions/parameters/validValueTypes.yaml @@ -4,7 +4,7 @@ $id: ///definitions/parameters/validValueTypes.yaml $comment: | This schema fragment makes it a little easier to compose the valid properties - for DSC Configuration document parameters. As-written, values must be one of + for DSC configuration document parameters. As-written, values must be one of those on this list - the schema definition for dataType excludes `null` and numbers with fractional parts, like `3.5`. diff --git a/schemas/src/definitions/resourceKind.yaml b/schemas/src/definitions/resourceKind.yaml index 953b0760..1b1180f7 100644 --- a/schemas/src/definitions/resourceKind.yaml +++ b/schemas/src/definitions/resourceKind.yaml @@ -4,7 +4,7 @@ $id: ///definitions/resourceKind.yaml title: Resource kind description: >- - Defines whether the resource is a normal DSC Resource, a group resource, or an adapter + 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 diff --git a/schemas/src/definitions/resourceType.yaml b/schemas/src/definitions/resourceType.yaml index f993f1e1..4ad44892 100644 --- a/schemas/src/definitions/resourceType.yaml +++ b/schemas/src/definitions/resourceType.yaml @@ -2,9 +2,9 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: ///definitions/resourceType.yaml -title: DSC Resource fully qualified type name +title: DSC resource fully qualified type name description: | - The namespaced name of the DSC Resource, using the syntax: + The namespaced name of the DSC resource, using the syntax: owner[.group][.area]/name @@ -22,7 +22,7 @@ markdownDescription: | [_Online Documentation_][01] *** - The namespaced name of the DSC Resource, using the syntax: + The namespaced name of the DSC resource, using the syntax: ```yaml owner[.group][.area]/name @@ -37,4 +37,4 @@ markdownDescription: | patternErrorMessage: | Invalid type name. Valid resource type names always define an owner and a name separated by a slash, like `Microsoft/OSInfo`. Type names may optionally include a group and area to namespace - the resource under the owner, like `Microsoft.Windows/Registry`. \ No newline at end of file + the resource under the owner, like `Microsoft.Windows/Registry`. diff --git a/schemas/src/outputs/config/get.yaml b/schemas/src/outputs/config/get.yaml index f1786b65..a90b50e4 100644 --- a/schemas/src/outputs/config/get.yaml +++ b/schemas/src/outputs/config/get.yaml @@ -2,7 +2,7 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: ///outputs/config/get.yaml -title: DSC Configuration get command result +title: Result for `dsc config get` command description: >- Represents the data structure returned by the `dsc config get` command. @@ -18,8 +18,8 @@ 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. + 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: ///outputs/resource/get.full.yaml diff --git a/schemas/src/outputs/config/set.yaml b/schemas/src/outputs/config/set.yaml index 3482c6d2..22837c93 100644 --- a/schemas/src/outputs/config/set.yaml +++ b/schemas/src/outputs/config/set.yaml @@ -2,7 +2,7 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: ///outputs/config/set.yaml -title: DSC Configuration set command result +title: Result for `dsc config set` command description: >- Represents the data structure returned by the `dsc config set` command. @@ -18,8 +18,8 @@ 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. + 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: ///outputs/resource/set.full.yaml diff --git a/schemas/src/outputs/config/test.yaml b/schemas/src/outputs/config/test.yaml index 1134b8cf..709b3a8b 100644 --- a/schemas/src/outputs/config/test.yaml +++ b/schemas/src/outputs/config/test.yaml @@ -2,7 +2,7 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: ///outputs/config/test.yaml -title: DSC Configuration test command result +title: Result for `dsc config test` command description: >- Represents the data structure returned by the `dsc config test` command. @@ -18,8 +18,8 @@ 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. + 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: ///outputs/resource/test.full.yaml diff --git a/schemas/src/outputs/resource/get.simple.yaml b/schemas/src/outputs/resource/get.simple.yaml index 5dd357a9..448fe385 100644 --- a/schemas/src/outputs/resource/get.simple.yaml +++ b/schemas/src/outputs/resource/get.simple.yaml @@ -3,7 +3,7 @@ $id: ///outputs/resource/get.simple.yaml title: dsc resource get result (simple) description: >- - Describes the return data for a single DSC Resource instance from the + 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. @@ -19,7 +19,7 @@ properties: actualState: title: Actual state description: >- - This property always represents the current state of the DSC Resource + 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. + against the DSC resource's schema. type: object \ No newline at end of file diff --git a/schemas/src/outputs/resource/get.yaml b/schemas/src/outputs/resource/get.yaml index 79d12d46..6ac2a9c2 100644 --- a/schemas/src/outputs/resource/get.yaml +++ b/schemas/src/outputs/resource/get.yaml @@ -4,7 +4,7 @@ $id: ///outputs/resource/get.yaml title: dsc resource get result description: >- - Describes the return data for a DSC Resource instance from the + 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 diff --git a/schemas/src/outputs/resource/list.yaml b/schemas/src/outputs/resource/list.yaml index 90838aaf..20971ca8 100644 --- a/schemas/src/outputs/resource/list.yaml +++ b/schemas/src/outputs/resource/list.yaml @@ -4,7 +4,7 @@ $id: ///outputs/resource/list.yaml title: dsc resource list result description: >- - Describes the return data for a DSC Resource instance from the + Describes the return data for a DSC resource instance from the `dsc resource list` command. type: object @@ -40,32 +40,32 @@ properties: - export - resolve description: - title: Resource Description + title: Resource description description: >- - A short synopsis of the DSC Resource's purpose. + A short synopsis of the DSC resource's purpose. # Should this include a maximum length or a pattern that forbids newlines? type: string path: # This value seems to mean something different for the Test* resources title: Path description: >- - Indicates the path to the DSC Resource on the file system. + Indicates the path to the DSC resource on the file system. type: string directory: # This value seems to mean something different for the Test* resources title: Directory description: >- - Indicates the path to the folder containing the DSC Resource on the file + 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. + Indicates how the DSC resource was implemented. oneOf: - title: Standard implementation description: >- - Indicates that the DSC Resource is implemented as one of the standard + Indicates that the DSC resource is implemented as one of the standard implementations built into DSC. type: string enum: @@ -74,7 +74,8 @@ properties: # Need to understand how this works to document it more usefully - title: Custom implementation description: >- - Indicates that the DSC Resource uses a custom implementation. + Indicates that the DSC resource uses a custom implementation. Only + adapted resources define this value. type: object required: - custom @@ -82,14 +83,15 @@ properties: custom: title: Custom implementation name description: >- - The name of the custom implementation. + The name of the custom implementation. This name is determined by + the resource adapter. type: string author: # Only the Test* resources seem to have this field populated. title: Author description: >- Indicates the name of the person or organization that developed and - maintains the DSC Resource. + maintains the DSC resource. type: - string - 'null' @@ -97,16 +99,16 @@ properties: # Only the Test* resources seem to have this field populated. title: Properties description: >- - Defines the DSC Resource's property names. + Defines the DSC resource's property names. type: array items: type: string pattern: ^\w+$ requireAdapter: - title: Required DSC Resource Adapter + title: Required DSC resource adapter description: >- - Defines the fully qualified type name of the DSC Resource Adapter the - DSC Resource depends on. + Defines the fully qualified type name of the DSC resource adapter the + DSC resource depends on. oneOf: - $ref: ///definitions/resourceType.yaml - type: 'null' diff --git a/schemas/src/outputs/resource/schema.yaml b/schemas/src/outputs/resource/schema.yaml index d010ff51..3f3c2576 100644 --- a/schemas/src/outputs/resource/schema.yaml +++ b/schemas/src/outputs/resource/schema.yaml @@ -2,9 +2,9 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: ///outputs/resource/schema.yaml -title: DSC Resource schema result +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. + Describes the return data for a DSC resource from the `dsc resource schema` + command. This command always returns the DSC resource's JSON schema document. type: object diff --git a/schemas/src/outputs/resource/set.simple.yaml b/schemas/src/outputs/resource/set.simple.yaml index 46ddccf1..8f114463 100644 --- a/schemas/src/outputs/resource/set.simple.yaml +++ b/schemas/src/outputs/resource/set.simple.yaml @@ -4,7 +4,7 @@ $id: ///outputs/resource/set.simple.yaml title: dsc resource set result (simple) description: >- - Describes the return data for a DSC Resource instance from the + 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. @@ -22,22 +22,22 @@ properties: beforeState: title: State before enforcing description: >- - This property always represents the desired state of the DSC Resource + 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. + 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 + 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. + 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 + 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 diff --git a/schemas/src/outputs/resource/set.yaml b/schemas/src/outputs/resource/set.yaml index 5bed8c7e..384096fd 100644 --- a/schemas/src/outputs/resource/set.yaml +++ b/schemas/src/outputs/resource/set.yaml @@ -4,7 +4,7 @@ $id: ///outputs/resource/set.yaml title: dsc resource set result description: >- - Describes the return data for a DSC Resource instance from the + 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 diff --git a/schemas/src/outputs/resource/test.simple.yaml b/schemas/src/outputs/resource/test.simple.yaml index 717d3084..eedff5fe 100644 --- a/schemas/src/outputs/resource/test.simple.yaml +++ b/schemas/src/outputs/resource/test.simple.yaml @@ -4,7 +4,7 @@ $id: ///outputs/resource/test.simple.yaml title: dsc resource test result (simple) description: >- - Describes the return data for a single DSC Resource instance from the + 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. @@ -23,16 +23,16 @@ properties: desiredState: title: Desired state description: >- - This property always represents the desired state of the DSC Resource + 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 + 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. + value against the DSC resource's schema. type: object inDesiredState: title: Instance is in the desired state @@ -43,7 +43,7 @@ properties: 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 + 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: [] diff --git a/schemas/src/outputs/resource/test.yaml b/schemas/src/outputs/resource/test.yaml index 34317d1e..70531121 100644 --- a/schemas/src/outputs/resource/test.yaml +++ b/schemas/src/outputs/resource/test.yaml @@ -4,7 +4,7 @@ $id: ///outputs/resource/test.yaml title: dsc resource test result description: >- - Describes the return data for a DSC Resource instance from the + 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 diff --git a/schemas/src/outputs/schema.yaml b/schemas/src/outputs/schema.yaml index dd4d9a8e..350128e5 100644 --- a/schemas/src/outputs/schema.yaml +++ b/schemas/src/outputs/schema.yaml @@ -2,9 +2,9 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: ///outputs/schema.yaml -title: DSC Resource schema result +title: DSC resource schema result description: >- - Describes the return data for a DSC Resource from the `dsc schema` + Describes the return data for a DSC resource from the `dsc schema` command. This command always returns a JSON schema document. type: object diff --git a/schemas/src/resource/manifest.adapter.yaml b/schemas/src/resource/manifest.adapter.yaml index 663ae54f..55cb096b 100644 --- a/schemas/src/resource/manifest.adapter.yaml +++ b/schemas/src/resource/manifest.adapter.yaml @@ -4,14 +4,14 @@ $id: ///resource/manifest.adapter.yaml title: Adapter description: >- - Defines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter 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 Adapter. A DSC Resource Adapter 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/adapter? @@ -24,13 +24,13 @@ properties: list: title: List Command description: >- - Defines how DSC must call the DSC Resource Adapter 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 Adapter 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/adapter?#list type: object @@ -57,7 +57,7 @@ properties: title: Command arguments description: >- Defines the list of arguments to pass to the command to return the list of supported DSC - Resources. + resources. markdownDescription: | *** [_Online Documentation_][01] diff --git a/schemas/src/resource/manifest.delete.yaml b/schemas/src/resource/manifest.delete.yaml index 4484b5c4..c15ecc95 100644 --- a/schemas/src/resource/manifest.delete.yaml +++ b/schemas/src/resource/manifest.delete.yaml @@ -4,7 +4,7 @@ $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 + 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 @@ -15,7 +15,7 @@ markdownDescription: | # VS Code only [_Online Documentation_][01] *** - Defines how DSC must call the DSC Resource to delete an instance. Define this method for + 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 diff --git a/schemas/src/resource/manifest.export.yaml b/schemas/src/resource/manifest.export.yaml index 28ea5387..903b0291 100644 --- a/schemas/src/resource/manifest.export.yaml +++ b/schemas/src/resource/manifest.export.yaml @@ -4,13 +4,13 @@ $id: ///resource/manifest.export.yaml title: Export Method description: >- - Defines how DSC must call the DSC Resource to get the current state of every instance. + Defines how DSC must call the DSC resource to get the current state of every instance. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines how DSC must call the DSC Resource to get the current state of every instance. + 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: diff --git a/schemas/src/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml index 873e4367..9e972f89 100644 --- a/schemas/src/resource/manifest.get.yaml +++ b/schemas/src/resource/manifest.get.yaml @@ -4,13 +4,13 @@ $id: ///resource/manifest.get.yaml title: Get Method description: >- - Defines how DSC must call the DSC Resource to get the current state of an instance. + Defines how DSC must call the DSC resource to get the current state of an instance. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines how DSC must call the DSC Resource to get the current state of an instance. + 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: diff --git a/schemas/src/resource/manifest.resolve.yaml b/schemas/src/resource/manifest.resolve.yaml index a856dd65..ff7ede94 100644 --- a/schemas/src/resource/manifest.resolve.yaml +++ b/schemas/src/resource/manifest.resolve.yaml @@ -4,7 +4,7 @@ $id: ///resource/manifest.resolve.yaml title: Resolve method description: >- - Defines how DSC must call the DSC Resource to resolve a nested configuration document from an + Defines how DSC must call the DSC resource to resolve a nested configuration document from an external source. Define this method for importer resources where the resource kind is set to `Import`. diff --git a/schemas/src/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml index dfba5091..a78b7020 100644 --- a/schemas/src/resource/manifest.schema.yaml +++ b/schemas/src/resource/manifest.schema.yaml @@ -4,12 +4,12 @@ $id: ///resource/manifest.schema.yaml title: Instance Schema description: >- - Defines how DSC must validate a JSON blob representing an instance of the DSC Resource. + Defines how DSC must validate a JSON blob representing an instance of the DSC resource. # While the current implementation is somewhat confusing in the schema, I # think it's actually easier to document. Mainly, the complexity comes from # the expected object having exactly one property with exclusive key names. -# If a DSC Resource could specify a combination of these values, the schema +# If a DSC resource could specify a combination of these values, the schema # would be less complex. type: object oneOf: @@ -19,8 +19,8 @@ properties: command: title: Instance Schema Command description: >- - Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob - representing an instance of the DSC Resource. + Defines how DSC must call the DSC resource to get the JSON Schema for validating a JSON blob + representing an instance of the DSC resource. type: object required: - executable @@ -77,8 +77,8 @@ properties: [_Online Documentation_][01] *** - Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob - representing an instance of the DSC Resource. + Defines how DSC must call the DSC resource to get the JSON Schema for validating a JSON blob + representing an instance of the DSC resource. [01]: /reference/schemas/resource/manifest/schema/property?#command defaultSnippets: @@ -100,14 +100,14 @@ properties: title: Embedded Instance Schema description: >- Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the - DSC Resource. + DSC resource. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the - DSC Resource. + DSC resource. [01]: /reference/schemas/resource/manifest/schema/embedded? type: object @@ -119,24 +119,24 @@ properties: type: title: Instance Type description: >- - Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always + Defines the JSON type for an instance of the DSC resource. DSC resource instances always have the `object` type. - # Ensures the DSC Resource is always an object + # Ensures the DSC resource is always an object const: object markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always + Defines the JSON type for an instance of the DSC resource. DSC resource instances always have the `object` type. [01]: /reference/schemas/resource/manifest/schema/embedded?#type $schema: - # Ensures the DSC Resource always uses a schema we can understand - title: DSC Resource instance schema dialect + # Ensures the DSC resource always uses a schema we can understand + title: DSC resource instance schema dialect description: >- - Defines which dialect of JSON Schema the DSC Resource is using to validate instances. + Defines which dialect of JSON Schema the DSC resource is using to validate instances. type: string format: uri-reference enum: @@ -149,7 +149,7 @@ properties: [_Online Documentation_][01] *** - Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always + Defines the JSON type for an instance of the DSC resource. DSC resource instances always have the `object` type. DSC only supports JSON Schema Draft 07 and later. [01]: /reference/schemas/resource/manifest/schema/embedded?#type @@ -185,9 +185,9 @@ properties: [01]: https://json-schema.org/specification-links.html#draft-7 $id: - title: DSC Resource instance 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 + Defines the unique ID for the DSC resource's instance schema. If the instance schema is published to its own public URI, set this keyword to that URI. # Currently optional - maybe we should require this? type: string @@ -197,7 +197,7 @@ properties: [_Online Documentation_][01] *** - Defines the unique ID for the DSC Resource's instance schema. If the instance schema is + Defines the unique ID for the DSC resource's instance schema. If the instance schema is published to its own public URI, set this keyword to that URI. [01]: /reference/schemas/resource/manifest/schema/property?#id @@ -339,7 +339,7 @@ properties: _exist: title: 'Standard Property: _exist' description: >- - Indicates that the DSC Resource uses the standard `_exist` property to specify + 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: ///resource/properties/exist.yaml @@ -367,9 +367,9 @@ properties: _inDesiredState: title: 'Standard Property: _inDesiredState' description: >- - Indicates that the DSC Resource returns this value for it's own `test` method. This + 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. + shouldn't be included if the DSC resource relies on DSC's synthetic testing. const: $ref: ///resource/properties/inDesiredState.yaml # VS Code only @@ -378,16 +378,16 @@ properties: [_Online Documentation_][01] *** - Indicates that the DSC Resource returns this value for it's own `test` method. This + Indicates that the DSC resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't - be included if the DSC Resource relies on DSC's synthetic testing. + be included if the DSC resource relies on DSC's synthetic testing. [01]: /reference/schemas/resource/properties/indesiredstate? _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 + Indicates that the DSC resource uses the standard `_purge` property to specify + whether the DSC resource should remove all non-specified members when it manages an array of members or values. const: $ref: ///resource/properties/purge.yaml @@ -397,8 +397,8 @@ properties: [_Online Documentation_][01] *** - Indicates that the DSC Resource uses the standard `_purge` property to specify - whether the DSC Resource should remove all non-specified members when it manages + Indicates that the DSC resource uses the standard `_purge` property to specify + whether the DSC resource should remove all non-specified members when it manages an array of members or values. [01]: /reference/schemas/resource/properties/purge? @@ -416,7 +416,7 @@ properties: [_Online Documentation_][01] *** - Indicates that the DSC Resource uses the standard `_rebootRequested` property to + Indicates that the DSC resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes. [01]: /reference/schemas/resource/properties/rebootrequested? @@ -469,7 +469,7 @@ markdownDescription: | [_Online Documentation_][01] *** - Defines how DSC must validate a JSON blob representing an instance of the DSC Resource. + Defines how DSC must validate a JSON blob representing an instance of the DSC resource. The JSON schema can be defined dynamically with the `command` property or statically with the `embedded` property. diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 93a6fadb..4b92ce61 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -4,15 +4,15 @@ $id: ///resource/manifest.set.yaml title: Set Method description: >- - Defines how DSC must call the DSC Resource to set the desired state of an instance and how to - process the output from the DSC Resource. + Defines how DSC must call the DSC resource to set the desired state of an instance and how to + process the output from the DSC resource. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines how DSC must call the DSC Resource to set the desired state of an instance and how to - process the output from the DSC Resource. + 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: @@ -127,10 +127,10 @@ properties: [01]: /reference/schemas/resource/manifest/set?#input implementsPretest: - title: Resource Performs Pre-Test + 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 + 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 @@ -140,16 +140,16 @@ properties: [_Online Documentation_][01] *** - Defines whether the DSC Resource performs its own test to ensure idempotency when calling the - `set` command. Set this value to `true` if the DSC Resource tests input before modifying + Defines whether the DSC resource performs its own test to ensure idempotency when calling the + `set` command. Set this value to `true` if the DSC resource tests input before modifying system state. [01]: /reference/schemas/resource/manifest/set?#implementspretest handlesExist: - title: Resource handles _exist property + 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 + 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 @@ -159,16 +159,16 @@ properties: [_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 + 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 - operation or the state and an array of the properties the DSC Resource modified. + Defines whether the command returns a JSON blob of the DSC resource's state after the set + operation or the state and an array of the properties the DSC resource modified. $ref: ///definitions/returnKind.yaml # VS Code only markdownDescription: | @@ -176,8 +176,8 @@ properties: [_Online Documentation_][01] *** - Defines whether the command returns a JSON blob of the DSC Resource's state after the set - operation or the state and an array of the properties the DSC Resource modified. + Defines whether the command returns a JSON blob of the DSC resource's state after the set + operation or the state and an array of the properties the DSC resource modified. [01]: /reference/schemas/resource/manifest/set?#return markdownEnumDescriptions: diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index d0325a1e..91844244 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -4,15 +4,15 @@ $id: ///resource/manifest.test.yaml title: Test Method description: >- - Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how - to process the output from the DSC Resource. + Defines how DSC must call the DSC resource to test if an instance is in the desired state and how + to process the output from the DSC resource. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how - to process the output from the DSC Resource. + 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: @@ -130,7 +130,7 @@ properties: return: title: Test Command Return Type description: >- - Defines whether the command returns a JSON blob of the DSC Resource's current state or the + Defines whether the command returns a JSON blob of the DSC resource's current state or the state and an array of the properties that are out of the desired state. $ref: ///definitions/returnKind.yaml # VS Code only @@ -139,7 +139,7 @@ properties: [_Online Documentation_][01] *** - Defines whether the command returns a JSON blob of the DSC Resource's current state or the + Defines whether the command returns a JSON blob of the DSC resource's current state or the state and an array of the properties that are out of the desired state. [01]: /reference/schemas/resource/manifest/test?#return diff --git a/schemas/src/resource/manifest.validate.yaml b/schemas/src/resource/manifest.validate.yaml index 764f8bda..2aec765c 100644 --- a/schemas/src/resource/manifest.validate.yaml +++ b/schemas/src/resource/manifest.validate.yaml @@ -4,16 +4,16 @@ $id: ///resource/manifest.validate.yaml title: Validate Method description: >- - Defines how DSC must call the DSC Resource to validate the state of an instance. This method is - mandatory for DSC Group Resources. It's ignored for all other DSC Resources. + Defines how DSC must call the DSC resource to validate the state of an instance. This method is + mandatory for DSC group resources. It's ignored for all other DSC resources. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines how DSC must call the DSC Resource to validate the state of an instance. This method is - mandatory for DSC Group Resources. It's ignored for all other DSC Resources. + 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: diff --git a/schemas/src/resource/manifest.whatIf.yaml b/schemas/src/resource/manifest.whatIf.yaml index 711c8602..5d0cd4da 100644 --- a/schemas/src/resource/manifest.whatIf.yaml +++ b/schemas/src/resource/manifest.whatIf.yaml @@ -4,15 +4,15 @@ $id: ///resource/manifest.whatIf.yaml title: What-if method description: >- - Defines how DSC must call the DSC Resource to indicate whether and how the set command will - modify an instance and how to process the output from the DSC Resource. + Defines how DSC must call the DSC resource to indicate whether and how the set command will + modify an instance and how to process the output from the DSC resource. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines how DSC must call the DSC Resource to indicate whether and how the set command will - modify an instance and how to process the output from the DSC Resource. If a resource doesn't + Defines how DSC must call the DSC resource to indicate whether and how the set command will + modify an instance and how to process the output from the DSC resource. If a resource doesn't define this method in the manifest, DSC synthesizes this behavior by converting the result of the test operation for the resource into the [set result][02]. @@ -134,10 +134,10 @@ properties: [01]: /reference/schemas/resource/manifest/whatif?#input implementsPretest: - title: Resource Performs Pre-Test + title: Resource performs pre-test description: >- - Defines whether the DSC Resource performs its own test to ensure idempotency when calling the - `set --what-if` command. Set this value to `true` if the DSC Resource tests input before + Defines whether the DSC resource performs its own test to ensure idempotency when calling the + `set --what-if` command. Set this value to `true` if the DSC resource tests input before processing how it will modify system state. type: boolean default: false @@ -147,16 +147,16 @@ properties: [_Online Documentation_][01] *** - Defines whether the DSC Resource performs its own test to ensure idempotency when calling the - `set --what-if` command . Set this value to `true` if the DSC Resource tests input before + Defines whether the DSC resource performs its own test to ensure idempotency when calling the + `set --what-if` command . Set this value to `true` if the DSC resource tests input before processing how it will modify system state. [01]: /reference/schemas/resource/manifest/whatif?#implementspretest handlesExist: - title: Resource handles _exist property + 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 + 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 --what-if` command where the instance defines the `_exist` property as `false`. type: boolean @@ -167,8 +167,8 @@ properties: [_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 + 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 --what-if` command where the instance defines the `_exist` property as `false`. @@ -176,8 +176,8 @@ properties: [02]: /reference/schemas/resource/properties/exist? return: description: >- - Defines whether the command returns a JSON blob of the DSC Resource's expected state after a - set operation in what-if mode or the state and an array of the properties the DSC Resource + Defines whether the command returns a JSON blob of the DSC resource's expected state after a + set operation in what-if mode or the state and an array of the properties the DSC resource would modify. $ref: ///definitions/returnKind.yaml # VS Code only @@ -186,8 +186,8 @@ properties: [_Online Documentation_][01] *** - Defines whether the command returns a JSON blob of the DSC Resource's expected state after a - set operation in what-if mode or the state and an array of the properties the DSC Resource + Defines whether the command returns a JSON blob of the DSC resource's expected state after a + set operation in what-if mode or the state and an array of the properties the DSC resource would modify. [01]: /reference/schemas/resource/manifest/whatif?#return diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index 1139f6ad..bf4c6a88 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -2,17 +2,16 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: ///resource/manifest.yaml -title: Command-based DSC Resource Manifest +title: DSC resource manifest description: >- - Defines the information DSC and integrating require to process and call a command-based DSC - Resource. + Defines the information DSC and integrating require to process and call a DSC command resource. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines the information DSC and integrating require to process and call a command-based DSC - Resource. For DSC to use a manifest on a system, the manifest file must: + Defines the information DSC and integrating require to process and call a DSC command resource. + For DSC to use a manifest on a system, the manifest file must: 1. Be discoverable in the `PATH` environment variable. 1. Follow the naming convention `.dsc.resource.json`. @@ -96,8 +95,8 @@ defaultSnippets: - label: ' Define a resource (adapter)' markdownDescription: |- - Defines an adapter resource that enables users to define non-command-based DSC Resources in - the configuration. + Defines an adapter resource that enables users to define non-command DSC resources in the + configuration. body: ${escape_dollar:$}schema: ///bundled/resource/manifest.yaml type: '${1:owner.area.group}/${2:${TM_FILENAME_BASE/^(.*?)[\.]dsc[\.]resource/$1/}}' @@ -197,7 +196,7 @@ properties: $schema: title: Manifest Schema description: >- - This property must be the canonical URL of the Command-based DSC Resource Manifest schema + 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 @@ -217,8 +216,8 @@ properties: [_Online Documentation_][01] *** - This property must be one of the canonical URLs for the version of the Command-based DSC - Resource Manifest schema that the manifest is implemented for. + This property must be one of the canonical URLs for the version of the DSC resource manifest + schema that the manifest is implemented for. For every version of the schema, there are three valid urls: @@ -379,7 +378,7 @@ properties: version: title: Resource Semantic Version description: >- - The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, + The semantic version (semver) of the DSC resource. This version identifies the DSC resource, not the version of the application it manages. $ref: ///definitions/semver.yaml markdownDescription: | # VS Code only @@ -387,7 +386,7 @@ properties: [_Online Documentation_][01] *** - The semantic version ([semver][02]) of the DSC Resource. This version identifies the DSC + The semantic version ([semver][02]) of the DSC resource. This version identifies the DSC Resource, not the version of the application it manages. This value uses the [suggested regular expression][03] to validate whether the string is valid @@ -411,14 +410,14 @@ properties: description: title: Resource Description description: >- - A short synopsis of the DSC Resource's purpose. + A short synopsis of the DSC resource's purpose. type: string markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines a short synopsis of the DSC Resource's purpose. + Defines a short synopsis of the DSC resource's purpose. [01]: /reference/schemas/resource/manifest/root?#description-1 kind: @@ -468,9 +467,9 @@ properties: # command/method objects too? title: Exit Codes description: >- - This property defines a map of valid exit codes for the DSC Resource. DSC always interprets + 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. + property to indicate human-readable semantic meanings for the DSC resource's exit codes. type: object propertyNames: pattern: "^-?[0-9]+$" @@ -495,9 +494,9 @@ properties: [_Online Documentation_][01] *** - This property defines a map of valid exit codes for the DSC Resource. DSC always interprets + 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. + property to indicate human-readable semantic meanings for the DSC resource's exit codes. Define the keys in this property as strings representing a valid 32-bit signed integer. You can't use alternate formats for the exit code. For example, instead of the hexadecimal value diff --git a/schemas/src/resource/properties/exist.yaml b/schemas/src/resource/properties/exist.yaml index 7fad6b4a..b226365e 100644 --- a/schemas/src/resource/properties/exist.yaml +++ b/schemas/src/resource/properties/exist.yaml @@ -4,7 +4,7 @@ $id: ///resource/properties/exist.yaml title: Instance should exist description: >- - Indicates whether the DSC Resource instance should exist. + Indicates whether the DSC resource instance should exist. type: boolean default: true @@ -16,7 +16,7 @@ markdownDescription: | [_Online Documentation_][01] *** - Indicates whether the DSC Resource instance should exist. For DSC Resources that define the + 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. diff --git a/schemas/src/resource/properties/purge.yaml b/schemas/src/resource/properties/purge.yaml index 9ba4330e..db9a0348 100644 --- a/schemas/src/resource/properties/purge.yaml +++ b/schemas/src/resource/properties/purge.yaml @@ -4,9 +4,9 @@ $id: ///resource/properties/purge.yaml title: Purge description: >- - Indicates that only the components described in the DSC Resource should exist. If other - components exist, the DSC Resource is out of the desired state. When enforcing desired state, the - DSC Resource removes unmanaged components. + Indicates that only the components described in the DSC resource should exist. If other + components exist, the DSC resource is out of the desired state. When enforcing desired state, the + DSC resource removes unmanaged components. type: - boolean @@ -19,8 +19,8 @@ markdownDescription: | [_Online Documentation_][01] *** - Indicates that only the components described in the DSC Resource should exist. If other - components exist, the DSC Resource is out of the desired state. When enforcing desired state, the - DSC Resource removes unmanaged components. + Indicates that only the components described in the DSC resource should exist. If other + components exist, the DSC resource is out of the desired state. When enforcing desired state, the + DSC resource removes unmanaged components. [01]: /reference/schemas/resource/properties/purge? From 0dde1cd7f4f9d72ea12e7e3ac825772217424af6 Mon Sep 17 00:00:00 2001 From: Mikey Lombardi Date: Tue, 1 Apr 2025 14:53:38 -0500 Subject: [PATCH 2/8] (GH-717) Fix minimum item counts for `resources` in config doc This change sets the `minItems` keyword to `0` for the `resources` property of a configuration document. Prior to this change, the schema specified a value of `1`, which was inaccurate. This change fixes #717 --- schemas/src/config/document.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index 777a2f22..acdd140c 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -321,7 +321,7 @@ properties: title: DSC configuration document resources description: Defines a list of DSC resource instances for the configuration to manage. type: array - minItems: 1 + minItems: 0 items: $ref: ///config/document.resource.yaml # VS Code only From 285abf8cdc6ac7220a653cc813b58cff5976f3ca Mon Sep 17 00:00:00 2001 From: Mikey Lombardi Date: Tue, 1 Apr 2025 14:56:56 -0500 Subject: [PATCH 3/8] (GH-708) Fix enums for `kind` Prior to this change, the enums in the schema source for the `kind` property of a DSC resource wasn't updated to reflect the change for camelCasing and naming. This change updates the enumeration values and the associated documentation keywords and fixes #708. --- schemas/src/definitions/resourceKind.yaml | 41 ++++++++++++---------- schemas/src/resource/manifest.resolve.yaml | 8 ++--- 2 files changed, 26 insertions(+), 23 deletions(-) diff --git a/schemas/src/definitions/resourceKind.yaml b/schemas/src/definitions/resourceKind.yaml index 1b1180f7..e111ef5e 100644 --- a/schemas/src/definitions/resourceKind.yaml +++ b/schemas/src/definitions/resourceKind.yaml @@ -9,10 +9,10 @@ description: >- type: string enum: - - Resource - - Adapter - - Group - - Import + - resource + - adapter + - group + - importer # VS Code only @@ -21,35 +21,38 @@ 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. + Defines how DSC should interpret the resource - as a typical resource, an adapter, a group, or an + importer. This property is required for group, exporter, and importer 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`. + - 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`. + + For more information about the different kinds of DSC resources, see [DSC resource kinds][01] [01]: /reference/schemas/resource/manifest/root?#kind + [01]: /concepts/resources/kinds? markdownEnumDescriptions: - - | # Resource + - | # resource - Indicates that the manifest is for a standard command-based DSC Resource. - - | # Adapter + Indicates that the manifest is for a typical DSC command 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 resource that enables the use of non-command resources + with DSC. + - | # group - Indicates that the manifest is for a group resource that processes an array of nested - resource instances. - - | # Import + Indicates that the manifest is for a resource that processes an array of nested resource + instances. + - | # importer - Indicates that the manifest is for an import resource that resolves an external source to DSC - resource instances. The resolved instances are processed as nested instances for the import + Indicates that the manifest is for a resource that resolves an external source to DSC + resource instances. DSC processes the resolved instances as nested instances for the importer resource. diff --git a/schemas/src/resource/manifest.resolve.yaml b/schemas/src/resource/manifest.resolve.yaml index ff7ede94..84e0c5a0 100644 --- a/schemas/src/resource/manifest.resolve.yaml +++ b/schemas/src/resource/manifest.resolve.yaml @@ -6,16 +6,16 @@ title: Resolve method description: >- Defines how DSC must call the DSC resource to resolve a nested configuration document from an external source. Define this method for importer resources where the resource kind is set to - `Import`. + `importer`. markdownDescription: | # VS Code only *** [_Online Documentation_][01] *** - Defines how DSC must call the DSC Resource to resolve an external source to nested DSC - Configuration Document. Define this method for [importer resources][02] and set the [kind][03] - property in the manifest root to `Import`. + Defines how DSC must call the DSC resource to resolve an external source to nested DSC + configuration document. Define this method for [importer resources][02] and set the [kind][03] + property in the manifest root to `importer`. DSC sends data to the command in three ways: From e900cac014f93004c704c9ec64691877b66358e7 Mon Sep 17 00:00:00 2001 From: Mikey Lombardi Date: Tue, 1 Apr 2025 14:59:21 -0500 Subject: [PATCH 4/8] (SCHEMA) Decompose capabilities into separate schema for reuse This change breaks out the capabilities schema from the `dsc resource list` output schema into a separate definition file. This enables us to reference the schema without using a JSON Pointer and provides us with a page for documenting the capabilities directly. This is a required precursor for a future change that defines stdout schemas for resource operations. --- .../src/definitions/resourceCapabilities.yaml | 244 ++++++++++++++++++ schemas/src/outputs/resource/list.yaml | 19 +- 2 files changed, 245 insertions(+), 18 deletions(-) create mode 100644 schemas/src/definitions/resourceCapabilities.yaml diff --git a/schemas/src/definitions/resourceCapabilities.yaml b/schemas/src/definitions/resourceCapabilities.yaml new file mode 100644 index 00000000..bb3f5cd4 --- /dev/null +++ b/schemas/src/definitions/resourceCapabilities.yaml @@ -0,0 +1,244 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///definitions/resourceCapabilities.yaml + +title: Resource capabilities +description: >- + Define the operations you can invoke for a resource and how the resource behaves when invoked. + +markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + DSC resources always have at least one capability. Resource capabilities define the operations + you can invoke for a resource and how the resource behaves when invoked. + + For more information about the operations you can invoke for a resource, see + [DSC resource operations][01]. + + + [00]: /reference/schemas/definitions/resourceCapabilities? + [00]: /concepts/resources/operations? + +type: array +items: + type: string + enum: + - get + - set + - setHandlesExist + - whatIf + - test + - delete + - export + - resolve + markdownEnumDescriptions: + - |- # get + *** + [_Online Documentation_][00] + *** + + A resource with the `get` capability supports retrieving the current state of an instance + with the [Get][01] operation. + + A command resource has this capability when its resource manifest defines the [get][02] + property. + + + [00]: /reference/schemas/definitions/resourceCapabilities?#get + [01]: /concepts/resources/operations?#get-operation + [02]: /reference/schemas/resource/manifest/get? + + - |- # set + *** + [_Online Documentation_][00] + *** + + A resource with the `set` capability supports enforcing the desired state of an instance with + the [Set][01] operation. Resources without this capability can't be used with the + [dsc resource set][02] or [dsc config set][03] commands unless they're defined in a + `Microsoft.DSC/Assertion` group as a nested instance. + + A command resource has this capability when its resource manifest defines the [set][04] + property. + + + [00]: /reference/schemas/definitions/resourceCapabilities?#set + [01]: /concepts/resources/operations?#set-operation + [02]: /reference/cli/resource/set? + [03]: /reference/cli/config/set? + [04]: /reference/schemas/resource/manifest/set? + + - |- # setHandlesExist + *** + [_Online Documentation_][00] + *** + + A resource with the `setHandlesExist` capability indicates that you can use the [Set][01] + operation to delete an instance. Resources with this capability must have the [_exist][02] + canonical resource property. Resources that don't have the `_exist` property never have this + capability. + + When a resource has the `_exist` property but not the `setHandlesExist` capability: + + - If the resource has the `delete` capability, DSC invokes the [Delete][03] operation instead + of **Set** when the desired state for an instance defines `_exist` as false. + - If the resource doesn't have the `delete` capability, DSC raises an error during a **Set** + operation when the desired state for an instance defines `_exist` as false. + + A command resource has this capability when its resource manifest defines the + [set.handlesExist][04] subproperty as `true`. + + + [00]: /reference/schemas/definitions/resourceCapabilities?#sethandlesexist + [01]: /concepts/resources/operations#set-operation + [02]: /reference/schemas/resource/properties/exist + [03]: /concepts/resources/operations#delete-operation + [04]: /reference/schemas/resource/manifest/set#handlesexist + + - |- # whatIf + *** + [_Online Documentation_][00] + *** + + A resource with the `whatIf` capability indicates that you can use the [Set][01] operation in + what-if mode to have the resource return explicit information about how it would modify state + in an actual **Set** operation. + + When a resource doesn't have this capability, DSC synthesizes how the resource would change + an instance by converting the **Test** result for the instance into a **Set** result. The + synthetic operation can't indicate potential issues or changes that can't be determined by + comparing the result of the **Test** operation against the resource's desired state. For + example, the credentials used to test a resource might be valid for that operation, but not + have permissions to actually modify the system state. Only a resource with this capability + can fully report whether and how the resource would change system state. + + A resource has this capability when it defines the [whatIf][02] property. + + + [00]: /reference/schemas/definitions/resourceCapabilities?#whatif + [01]: /concepts/resources/operations?#set-operation + [02]: /reference/schemas/resource/manifest/whatif? + + - |- # test + *** + [_Online Documentation_][00] + *** + + A resource with the `test` capability indicates that it implements the [Test][01] operation + directly. Resources with this capability must have the [_inDesiredState][02] canonical + resource property. Resources that don't have the `_inDesiredState` property never have this + capability. + + When a resource doesn't have this capability, DSC uses a synthetic test for instances of the + resource. DSC performs the synthetic test by: + + 1. Invoking the **Get** operation on the resource to retrieve the actual state of the + instance. + 1. Synthetically testing each property for the desired state of an instance against the + actual state returned. The synthetic test uses strict, case-sensitive equivalence. + 1. If the desired state for a property and the actual state aren't the same, DSC marks the + property as out of the desired state. + 1. If any properties are out of the desired state, DSC reports the entire instance as not + being in the desired state. + + Synthetic testing can't account for all resource behaviors. For example, if a package + resource allows users to define a version range for the package, the **Get** operation + returns the actual version of the package, like `1.2.3`. If the user specified the version + range `~1` (NPM syntax indicating the package should be latest released semantic version with + major version `1`), DSC would compare the desired state `~1` against the actual state `1.2.3` + and consider the package to be in the incorrect state, even if `1.2.3` is actually the latest + release matching the version pin. + + Any resource that has properties which can't use a strict case-sensitive comparison check + should have this capability. + + A command resource has this capability when its resource manifest defines the [test][03] + property. + + + [00]: /reference/schemas/definitions/resourceCapabilities?#test + [01]: /concepts/resources/operations?#test-operation + [02]: /reference/schemas/resource/properties/inDesiredState? + [03]: /reference/schemas/resource/manifest/test? + + - |- # delete + *** + [_Online Documentation_][00] + *** + + A resource with the `delete` capability supports removing an instance with the [Delete][01] + operation and the [dsc resource delete][02] command. + + This capability isn't mutually exclusive with the `setHandlesExist` property. A resource can handle + the `_exist` property in **Set** operations and be called directly with `dsc resource delete` to + remove an instance. + + For resources with the `delete` capability and the [_exist][03] canonical resource property: + + - If the resource doesn't have the `setHandlesExist` capability, DSC invokes the **Delete** + operation for the resource instead of **Set** when the desired state defines `_exist` as + `false`. + - If the resource does have the `setHandlesExist` capability, DSC invokes the **Set** operation for + the resource when the desired state defines `_exist` as `false`. + + Resources with the `delete` capability that don't have the `_exist` canonical resource property + must implement their **Set** operation to handle removing instances. DSC can't infer existence + semantics without the `_exist` property. + + A command resource has this capability when its resource manifest defines the [delete][04] + property. + + + [00]: /reference/schemas/definitions/resourceCapabilities?#delete + [01]: /concepts/resources/operations?#delete-operation + [02]: /reference/cli/resource/delete? + [03]: /reference/schemas/resource/properties/exist? + [04]: /reference/schemas/resource/manifest/delete? + + + - |- # export + *** + [_Online Documentation_][00] + *** + + A resource with the `export` capability supports enumerating every instance of the resource + with the [Export][01] operation. + + You can use resources with this capability with the following commands: + + - [dsc config export][02] to return a configuration document representing the actual state + for every instance of each resource defined in the input document. + - [dsc resource export][03] to return a configuration document representing the actual state + for every instance of the input resource. + - `dsc resource get` with the [--all][04] option to return the actual state of every instance + of the input resource. + + A command resource has this capability when its resource manifest defines the [export][05] + property. + + + [00]: /reference/schemas/definitions/resourceCapabilities?#export + [01]: /concepts/resources/operations#export-operation + [02]: /reference/cli/config/export? + [03]: /reference/cli/resource/export? + [04]: /reference/cli/resource/get?#--all + [05]: /reference/schemas/resource/manifest/export? + + - |- # resolve + *** + [_Online Documentation_][00] + *** + + A resource with the `resolve` capability supports resolving nested resource instances from an + external source. This capability is primarily used by [importer resources][01] to enable users to + compose configuration documents. + + A command resource has this capability when its resource manifest defines the [resolve][0220] + property. + + + [00]: /reference/schemas/definitions/resourceCapabilities?#resolve + [01]: /concepts/resources/kinds?#importer-resources + [02]: /reference/schemas/resource/manifest/resolve? diff --git a/schemas/src/outputs/resource/list.yaml b/schemas/src/outputs/resource/list.yaml index 20971ca8..407f01cc 100644 --- a/schemas/src/outputs/resource/list.yaml +++ b/schemas/src/outputs/resource/list.yaml @@ -21,24 +21,7 @@ properties: # 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 - - setHandlesExist - - whatIf - - test - - delete - - export - - resolve + $ref: ///definitions/resourceCapabilities.yaml description: title: Resource description description: >- From 921b37d53e8ffa85a6b8f2b6ab102600ad63d1e1 Mon Sep 17 00:00:00 2001 From: Mikey Lombardi Date: Tue, 1 Apr 2025 16:27:57 -0500 Subject: [PATCH 5/8] (SCHEMA) Update `returnKind` and associated properties Prior to this change, the `returnKind` shared definition set a default value. This was inaccurate, because `set.return` has different behavior when `return` isn't defined - DSC invokes the **Get** operation to construct the result after the **Set** operation for the resource concludes. This change removes the default from the shared definition, adds it to the `test.return` property, and clarifies the behavior for the `set.return` property. Finally, this change also makes `whatIf.return` mandatory, as the synthetic after-state doesn't make sense for this operation, even if DSC will technically accept it. --- schemas/src/definitions/returnKind.yaml | 1 - schemas/src/resource/manifest.set.yaml | 4 ++++ schemas/src/resource/manifest.test.yaml | 1 + schemas/src/resource/manifest.whatIf.yaml | 10 ++++++++++ 4 files changed, 15 insertions(+), 1 deletion(-) diff --git a/schemas/src/definitions/returnKind.yaml b/schemas/src/definitions/returnKind.yaml index 30085de2..25025029 100644 --- a/schemas/src/definitions/returnKind.yaml +++ b/schemas/src/definitions/returnKind.yaml @@ -7,7 +7,6 @@ type: string enum: - state - stateAndDiff -default: state $comment: |- While the enumeration for return kind is the same for the `set` and `test` diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 4b92ce61..77cbf15c 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -179,6 +179,10 @@ properties: 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. + When a manifest doesn't define `set.return`, DSC doesn't expect the resource to emit any + JSON to stdout. Instead, DSC invokes the **Get** operation for the resource to construct + the result object, retrieving the actual state of the resource after the **Set** operation. + [01]: /reference/schemas/resource/manifest/set?#return markdownEnumDescriptions: - | # state diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index 91844244..f6e64757 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -133,6 +133,7 @@ properties: Defines whether the command returns a JSON blob of the DSC resource's current state or the state and an array of the properties that are out of the desired state. $ref: ///definitions/returnKind.yaml + default: state # VS Code only markdownDescription: | *** diff --git a/schemas/src/resource/manifest.whatIf.yaml b/schemas/src/resource/manifest.whatIf.yaml index 5d0cd4da..59a0bab2 100644 --- a/schemas/src/resource/manifest.whatIf.yaml +++ b/schemas/src/resource/manifest.whatIf.yaml @@ -40,6 +40,7 @@ markdownDescription: | # VS Code only type: object required: - executable + - return properties: executable: $ref: ///definitions/commandExecutable.yaml @@ -190,6 +191,15 @@ properties: set operation in what-if mode or the state and an array of the properties the DSC resource would modify. + Unlike the `set.return` property, you must specify a value for `whatIf.return` for the + resource to function correctly. When you don't define `set.return` in your resource manifest, + DSC invokes the **Get** operation on the resource after the **Set** operation to construct + the result with the final state of the resource. + + For what-if operations, the resource doesn't actually change the system, so invoking the + **Get** operation after the what-if command executes will always show the final state to + be the same as the before state. + [01]: /reference/schemas/resource/manifest/whatif?#return markdownEnumDescriptions: - | # state From 1ecf17a215b8d5d81b4223c76af16df746fbfe26 Mon Sep 17 00:00:00 2001 From: Mikey Lombardi Date: Tue, 1 Apr 2025 16:30:06 -0500 Subject: [PATCH 6/8] (SCHEMA) Add stdout schemas for resource operation commands Prior to this change, the instructions and information about how resources should return data to DSC for any given operation was somewhat vague and not always helpful. This change defines a new set of schemas for the various operations, so resource authors can review their implementations and validate them against these schemas. --- schemas/src/resource/stdout/delete.yaml | 17 ++++ schemas/src/resource/stdout/export.yaml | 30 ++++++ schemas/src/resource/stdout/get.yaml | 30 ++++++ schemas/src/resource/stdout/list.yaml | 86 +++++++++++++++++ schemas/src/resource/stdout/resolve.yaml | 58 ++++++++++++ schemas/src/resource/stdout/schema.yaml | 31 +++++++ schemas/src/resource/stdout/set.yaml | 107 ++++++++++++++++++++++ schemas/src/resource/stdout/test.yaml | 89 ++++++++++++++++++ schemas/src/resource/stdout/validate.yaml | 49 ++++++++++ schemas/src/resource/stdout/whatIf.yaml | 88 ++++++++++++++++++ 10 files changed, 585 insertions(+) create mode 100644 schemas/src/resource/stdout/delete.yaml create mode 100644 schemas/src/resource/stdout/export.yaml create mode 100644 schemas/src/resource/stdout/get.yaml create mode 100644 schemas/src/resource/stdout/list.yaml create mode 100644 schemas/src/resource/stdout/resolve.yaml create mode 100644 schemas/src/resource/stdout/schema.yaml create mode 100644 schemas/src/resource/stdout/set.yaml create mode 100644 schemas/src/resource/stdout/test.yaml create mode 100644 schemas/src/resource/stdout/validate.yaml create mode 100644 schemas/src/resource/stdout/whatIf.yaml diff --git a/schemas/src/resource/stdout/delete.yaml b/schemas/src/resource/stdout/delete.yaml new file mode 100644 index 00000000..8577904a --- /dev/null +++ b/schemas/src/resource/stdout/delete.yaml @@ -0,0 +1,17 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/stdout/get.yaml + +title: Delete resource operation stdout +description: >- + DSC does not expect the **Delete** operation for a resource to return any JSON to stdout. +markdownDescription: | # VS Code only + *** + [_Online Documentation_][00] + *** + + DSC does not expect the **Delete** operation for a resource to return any JSON to stdout. + + [00]: /reference/schemas/resource/stdout/delete? + +type: 'null' \ No newline at end of file diff --git a/schemas/src/resource/stdout/export.yaml b/schemas/src/resource/stdout/export.yaml new file mode 100644 index 00000000..e605413f --- /dev/null +++ b/schemas/src/resource/stdout/export.yaml @@ -0,0 +1,30 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/stdout/export.yaml + +title: Export resource operation stdout +description: >- + Represents the actual state of a resource instance in DSC. DSC expects every JSON Line emitted to + stdout for the **Export** operation to adhere to this schema. +markdownDescription: | # VS Code only + *** + [_Online Documentation_][00] + *** + + Represents the actual state of a resource instance in DSC. DSC expects every JSON Line emitted to + stdout for the **Export** operation to adhere to this schema. + + The output must be a JSON object. The object must be a valid representation of an instance of the + resource. + + Command resources define their instance schema with the [schema.command][01] or + [schema.embedded][02] fields in their resource manifest. If a command resource returns JSON that + is invalid against the resource instance schema, DSC raises an error. + + Adapted resource instances are validated by their adapter when the adapter invokes them. + + [00]: /reference/schemas/resource/stdout/export? + [01]: /reference/schemas/resource/manifest/schema/command? + [02]: /reference/schemas/resource/manifest/schema/embedded? + +type: object diff --git a/schemas/src/resource/stdout/get.yaml b/schemas/src/resource/stdout/get.yaml new file mode 100644 index 00000000..8568e904 --- /dev/null +++ b/schemas/src/resource/stdout/get.yaml @@ -0,0 +1,30 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/stdout/get.yaml + +title: Get resource operation stdout +description: >- + Represents the actual state of a resource instance in DSC. DSC expects the JSON Line emitted to + stdout for the **Get** operation to adhere to this schema. +markdownDescription: | # VS Code only + *** + [_Online Documentation_][00] + *** + + Represents the actual state of a resource instance in DSC. DSC expects the JSON Line emitted to + stdout for the **Get** operation to adhere to this schema. + + The output must be a JSON object. The object must be a valid representation of an instance of the + resource. + + Command resources define their instance schema with the [schema.command][01] or + [schema.embedded][02] fields in their resource manifest. If a command resource returns JSON that + is invalid against the resource instance schema, DSC raises an error. + + Adapted resource instances are validated by their adapter when the adapter invokes them. + + [00]: /reference/schemas/resource/stdout/get? + [01]: /reference/schemas/resource/manifest/schema/command? + [02]: /reference/schemas/resource/manifest/schema/embedded? + +type: object diff --git a/schemas/src/resource/stdout/list.yaml b/schemas/src/resource/stdout/list.yaml new file mode 100644 index 00000000..16cc96fe --- /dev/null +++ b/schemas/src/resource/stdout/list.yaml @@ -0,0 +1,86 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/stdout/list.yaml + +title: List resource operation stdout +description: >- + Defines the representation of an adapted resource in DSC. DSC expects every JSON Line emitted to + stdout for the **List** operation to adhere to this schema. +markdownDescription: | # VS Code only + *** + [_Online Documentation_][00] + *** + + Defines the representation of an adapted resource in DSC. DSC expects every JSON Line emitted to + stdout for the **List** operation to adhere to this schema. + + DSC includes the following adapter resources: + + - `Microsoft.DSC/PowerShell` run PowerShell and enables you to use PowerShell DSC (PSDSC) + resources implemented as PowerShell classes in DSC. + - `Microsoft.Windows/WindowsPowerShell` runs Windows PowerShell and enables you to use any + available PSDSC resources in DSC. This adapter is only available when you install DSC on + Windows. + - `Microsoft.Windows/WMI` enables you to use WMI classes as resources in DSC. This adapter is + only available when you install DSC on Windows. + + [00]: /reference/schemas/resource/stdout/list? + +type: object +required: + - type + - kind + - version + - capabilities + - path + - directory + - implementedAs + - properties + - requireAdapter +properties: + type: + $ref: ///definitions/resourceType.yaml + kind: + $ref: ///definitions/resourceKind.yaml + version: + $ref: ///definitions/semver.yaml + capabilities: + $ref: ///definitions/resourceCapabilities.yaml + path: + title: Path + description: >- + Indicates the path to the adapted resource on the file system. + type: string + directory: + title: Directory + description: >- + Indicates the path to the folder containing the adapted resource on the file system. + implementedAs: + title: Custom implementation name + description: >- + Indicates that the adapted resource uses a custom implementation. The name can be used to + distinguish between different implementations for the adapted resources. + type: string + author: + title: Author + description: >- + Indicates the name of the person or organization that developed and maintains the adapted + Resource. + type: + - string + - 'null' + pattern: ^\w+( \w+)* + properties: + title: Properties + description: >- + Defines the adapted resource's property names. + type: array + items: + type: string + pattern: ^\w+$ + requireAdapter: + title: Required adapter + description: >- + Defines the fully qualified type name of the adapter that the adapted resource depends on. An + adapter should always set this value to its own fully qualified resource type name. + $ref: ///definitions/resourceType.yaml diff --git a/schemas/src/resource/stdout/resolve.yaml b/schemas/src/resource/stdout/resolve.yaml new file mode 100644 index 00000000..18ddca4e --- /dev/null +++ b/schemas/src/resource/stdout/resolve.yaml @@ -0,0 +1,58 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/stdout/resolve.yaml + +title: Resolve resource operation stdout +description: >- + Defines the representation of a resolved configuration document. DSC expects the JSON Line emitted to + stdout for the **Resolve** operation to adhere to this schema. +markdownDescription: | # VS Code only + *** + [_Online Documentation_][00] + *** + + Defines the representation of a resolved configuration document. DSC expects the JSON Line + emitted to stdout for the **Resolve** operation to adhere to this schema. + + [00]: /reference/schemas/resource/stdout/resolve? + +type: object +required: [configuration] + +properties: + configuration: + title: Resolved configuration document + description: >- + Defines the resolved configuration document. + markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + Defines the resolved configuration document. If the configuration document defines any + parameters, values for those parameters may be retrieved from the `parameters` property of + the **Resolve** operation output. + + [00]: /reference/schemas/resource/stdout/resolve?#configuration + $ref: ///config/document.yaml + parameters: + title: Resolved parameters + description: >- + The `parameters` property defines the set of resolved parameter values for the resolved + configuration document. + markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + The `parameters` property defines the set of resolved parameter values for the resolved + configuration document. If the `parameters` property is omitted from the output for the + **Resolve** operation, DSC doesn't pass any parameters to the resolved configuration + when invoking operations on it. + + Each property of this object represents a different resolved parameter. The property name + identifies the name of a parameter. The property value is the resolved value for the + parameter. + + [00]: /reference/schemas/resource/stdout/resolve?#parameters + type: object \ No newline at end of file diff --git a/schemas/src/resource/stdout/schema.yaml b/schemas/src/resource/stdout/schema.yaml new file mode 100644 index 00000000..510b941d --- /dev/null +++ b/schemas/src/resource/stdout/schema.yaml @@ -0,0 +1,31 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/stdout/schema.yaml + +title: Schema resource command stdout +description: >- + Represents the JSON Schema that validates instances of the resource. DSC expects a resource that + defines the `schema.command` field in its resource manifest to return this value for that + command. +markdownDescription: | # VS Code only + *** + [_Online Documentation_][00] + *** + + Represents the JSON Schema that validates instances of the resource. DSC expects a resource that + defines the [`schema.command`][01] field in its resource manifest to return this value for that + command. + + The output must be a JSON object. The object must be a valid JSON Schema. For more information + about what DSC expects for resource instance JSON Schemas, see + [DSC Resource manifest embedded schema reference][02], which describes the expectations in full. + + [00]: /reference/schemas/resource/stdout/export? + [01]: /reference/schemas/resource/manifest/schema/command? + [02]: /reference/schemas/resource/manifest/schema/embedded? + +type: object +required: + - $schema + - type + - properties \ No newline at end of file diff --git a/schemas/src/resource/stdout/set.yaml b/schemas/src/resource/stdout/set.yaml new file mode 100644 index 00000000..48ff9889 --- /dev/null +++ b/schemas/src/resource/stdout/set.yaml @@ -0,0 +1,107 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/stdout/set.yaml + +title: Set resource operation stdout +description: >- + Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation. + +markdownDescription: | # VS Code only + *** + [_Online Documentation_][00] + *** + + Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation. + + DSC expects this output for both actual **Set** operations and **Set** operations in `whatIf` + mode. If the resource has the `whatIf` capability, the output should be the same for both modes. + + DSC expects different output from the command resource depending on the definition of + [set.return][01] in the resource manifest: + + - If the field isn't defined, DSC doesn't expect the resource to return any JSON to stdout. + Instead, DSC invokes the **Get** operation on the resource after the **Set** operation + concludes and synthesizes the **Set** result, including the after state of the resource and + the list of changed properties. + - If the field is defined as `state`, DSC expects the resource to emit a JSON Line to stdout + representing the actual state of the resource instance after the **Set** operation changes the + system. + - If the field is defined as `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The + first JSON Line should be an object representing the actual state of the resource after the + **Set** operation. The second JSON Line should be an array representing the names of the + resource properties that the operation changed on the system. + + [00]: /reference/schemas/resource/stdout/set? + [01]: /reference/schemas/resource/manifest/set?#return + +oneOf: + - title: Null output + description: >- + When a command resource doesn't define `set.return` in its resource manifest, DSC doesn't + expect the resource to emit any JSON to stdout for the **Set** operation. + markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + When a command resource doesn't define [set.return][01] in its resource manifest, DSC doesn't expect + the resource to emit any JSON to stdout for the **Set** operation. + + [00]: /reference/schemas/resource/stdout/set?#null-output + [01]: /reference/schemas/resource/manifest/set?#return + type: 'null' + - title: state output + description: >- + When a resource defines `set.return` in its manifest as `state` or `stateAndDiff`, DSC + expects the resource to emit a JSON Line to stdout representing the actual state of the + resource instance after the **Set** operation changes the system. + markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + When a command resource defines [set.return][01] in its manifest as `state` or + `stateAndDiff`, DSC expects the resource to emit a JSON Line to stdout representing the + actual state of the resource instance after the **Set** operation changes the system. + + The output must be a JSON object. The object must be a valid representation of an instance of + the resource. + + Command resources define their instance schema with the [schema.command][02] or + [schema.embedded][03] fields in their resource manifest. If a command resource returns JSON + that is invalid against the resource instance schema, DSC raises an error. + + Adapted resource instances are validated by their adapter when the adapter invokes them. + + [00]: /reference/schemas/resource/stdout/set?#state-output + [01]: /reference/schemas/resource/manifest/set?#return + [02]: /reference/schemas/resource/manifest/schema/command? + [03]: /reference/schemas/resource/manifest/schema/embedded? + type: object + - title: diff output + description: >- + When a command resource defines `set.return` in its manifest as `stateAndDiff`, DSC expects + the resource to emit a second JSON Line to stdout representing the names of the resource + properties that the operation changed on the system. + markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + When a command resource defines [set.return][01] in its manifest as `stateAndDiff`, DSC + expects the resource to emit a second JSON Line to stdout representing the names of the + resource properties that the operation changed on the system. + + This output must be emitted after the JSON Line representing the state of the resource + instance after the operation changes the system. + + The output must be a JSON array. The array may be empty, or it may contain one or more + strings. Each string in the array must be the name of one of the resource's properties. Each + string in the array must be unique. + + [00]: /reference/schemas/resource/stdout/set?#diff-output + [01]: /reference/schemas/resource/manifest/set?#return + type: array + uniqueItems: true + items: + type: string \ No newline at end of file diff --git a/schemas/src/resource/stdout/test.yaml b/schemas/src/resource/stdout/test.yaml new file mode 100644 index 00000000..1144b819 --- /dev/null +++ b/schemas/src/resource/stdout/test.yaml @@ -0,0 +1,89 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/stdout/test.yaml + +title: Test resource operation stdout +description: >- + Defines the JSON DSC expects a resource to emit to stdout for the **Test** operation. + +markdownDescription: | # VS Code only + *** + [_Online Documentation_][00] + *** + + Defines the JSON DSC expects a resource to emit to stdout for the **Test** operation. + + DSC expects different output from the command resource depending on the definition of + [test.return][01] in the resource manifest: + + - If the field is omitted or defined as `state` (the default value), DSC expects the resource to + emit a JSON Line to stdout representing the actual state of the resource instance with the + [_inDesiredState][02] canonical resource property included in the returned object. + - If the field is defined as `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The + first JSON Line should be an object representing the actual state of the resource instance with + the `_inDesiredState` included in the returned object. The second JSON Line should be an array + representing the names of the resource properties that aren't in the desired state. + + [00]: /reference/schemas/resource/stdout/test? + [01]: /reference/schemas/resource/manifest/test?#return + +oneOf: + - title: state output + description: >- + For the **Test** operation, DSC always expects the resource to emit a JSON Line to stdout + representing the actual state of the resource instance with the `_inDesiredState` canonical + resource property included in the returned object. + + markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + For the **Test** operation, DSC always expects the resource to emit a JSON Line to stdout + representing the actual state of the resource instance with the [_inDesiredState][01] + canonical resource property included in the returned object. + + The output must be a JSON object. The object must be a valid representation of an instance of + the resource. + + Command resources define their instance schema with the [schema.command][02] or + [schema.embedded][03] fields in their resource manifest. If a command resource returns JSON + that is invalid against the resource instance schema, DSC raises an error. + + Adapted resource instances are validated by their adapter when the adapter invokes them. + + [00]: /reference/schemas/resource/stdout/test?#state-output + [01]: /reference/schemas/resource/properties/inDesiredState? + [02]: /reference/schemas/resource/manifest/schema/command? + [03]: /reference/schemas/resource/manifest/schema/embedded? + type: object + - title: diff output + description: >- + When a command resource defines `test.return` in its manifest as `stateAndDiff`, DSC expects + the resource to emit a second JSON Line to stdout representing the names of the resource + properties that the operation changed on the system. + markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + When a command resource defines [test.return][01] in its manifest as `stateAndDiff`, DSC + expects the resource to emit a second JSON Line to stdout representing the names of the + resource properties that aren't in the desired state. + + This output must be emitted after the JSON Line representing the actual state of the resource + instance with the [_inDesiredState][02] canonical resource property included in the returned + object. + + The output must be a JSON array. The array may be empty, or it may contain one or more + strings. Each string in the array must be the name of one of the resource's properties. Each + string in the array must be unique. The array should never include the `_inDesiredState` + property. + + [00]: /reference/schemas/resource/stdout/test?#diff-output + [01]: /reference/schemas/resource/manifest/test?#return + [02]: /reference/schemas/resource/properties/inDesiredState? + type: array + uniqueItems: true + items: + type: string \ No newline at end of file diff --git a/schemas/src/resource/stdout/validate.yaml b/schemas/src/resource/stdout/validate.yaml new file mode 100644 index 00000000..a913bc30 --- /dev/null +++ b/schemas/src/resource/stdout/validate.yaml @@ -0,0 +1,49 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/stdout/validate.yaml + +title: Validate resource operation stdout +description: >- + Defines the JSON DSC expects a resource to emit to stdout for the **Validate** operation. +markdownDescription: | # VS Code only + *** + [_Online Documentation_][00] + *** + + Defines the JSON DSC expects a resource to emit to stdout for the **Validate** operation. + + DSC expects the resource to return a JSON object that indicates whether the instance is valid and + optionally a string indicating how the resource is invalid. + + [00]: /reference/schemas/resource/stdout/validate? + +type: object +required: [valid] +properties: + valid: + title: Instance validity + description: >- + Indicates whether the instance is valid for the resource. + markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + Indicates whether the instance is valid for the resource. When the value is `true`, the + instance is valid for the resource. + + [00]: /reference/schemas/resource/stdout/validate?#valid + reason: + title: Reason instance is invalid + description: >- + Describes how and why the instance is invalid for the resource. + markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + Describes how and why the instance is invalid for the resource. Always define this property + in the output object when `valid` is `false`. Don't define this property in the output object + when `valid` is `true`. + + [00]: /reference/schemas/resource/stdout/validate?#reason \ No newline at end of file diff --git a/schemas/src/resource/stdout/whatIf.yaml b/schemas/src/resource/stdout/whatIf.yaml new file mode 100644 index 00000000..1465f99d --- /dev/null +++ b/schemas/src/resource/stdout/whatIf.yaml @@ -0,0 +1,88 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: ///resource/stdout/set.yaml + +title: Set (what-if mode) resource operation stdout +description: >- + Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation in what-if + mode. + +markdownDescription: | # VS Code only + *** + [_Online Documentation_][00] + *** + + Defines the JSON DSC expects a resource to emit to stdout for the **Set** operation in what-if + mode. + + DSC expects different output from the command resource depending on the definition of + [whatIf.return][01] in the resource manifest: + + - If the field is defined as `state`, DSC expects the resource to emit a JSON Line to stdout + representing the actual state of the resource instance after the **Set** operation changes the + system. + - If the field is defined as `stateAndDiff`, DSC expects the resource to emit two JSON Lines. The + first JSON Line should be an object representing the actual state of the resource after the + **Set** operation. The second JSON Line should be an array representing the names of the + resource properties that the operation changed on the system. + + [00]: /reference/schemas/resource/stdout/whatIf? + [01]: /reference/schemas/resource/manifest/whatif?#return + +oneOf: + - title: state output + description: >- + When a resource defines `whatIf.return` in its manifest as `state` or `stateAndDiff`, DSC + expects the resource to emit a JSON Line to stdout representing the predicted actual state of + the resource instance after the **Set** operation changes the system. + markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + When a command resource defines [whatIf.return][01] in its manifest as `state` or + `stateAndDiff`, DSC expects the resource to emit a JSON Line to stdout representing the + expected actual state of the resource instance after the **Set** operation changes the + system. + + The output must be a JSON object. The object must be a valid representation of an instance of + the resource. + + Command resources define their instance schema with the [schema.command][02] or + [schema.embedded][03] fields in their resource manifest. If a command resource returns JSON + that is invalid against the resource instance schema, DSC raises an error. + + Adapted resource instances are validated by their adapter when the adapter invokes them. + + [00]: /reference/schemas/resource/stdout/whatIf?#state-output + [01]: /reference/schemas/resource/manifest/whatif?#return + [02]: /reference/schemas/resource/manifest/schema/command? + [03]: /reference/schemas/resource/manifest/schema/embedded? + type: object + - title: diff output + description: >- + When a command resource defines `whatIf.return` in its manifest as `stateAndDiff`, DSC expects + the resource to emit a second JSON Line to stdout representing the names of the resource + properties that the operation changed on the system. + markdownDescription: |- + *** + [_Online Documentation_][00] + *** + + When a command resource defines [whatIf.return][01] in its manifest as `stateAndDiff`, DSC + expects the resource to emit a second JSON Line to stdout representing the names of the + resource properties that the operation changed on the system. + + This output must be emitted after the JSON Line representing the state of the resource + instance after the operation changes the system. + + The output must be a JSON array. The array may be empty, or it may contain one or more + strings. Each string in the array must be the name of one of the resource's properties. Each + string in the array must be unique. + + [00]: /reference/schemas/resource/stdout/whatIf?#diff-output + [01]: /reference/schemas/resource/manifest/whatif?#return + type: array + uniqueItems: true + items: + type: string \ No newline at end of file From d1c33ab3a3099672dde18781d9704abf9a3f083b Mon Sep 17 00:00:00 2001 From: Mikey Lombardi Date: Tue, 1 Apr 2025 17:01:40 -0500 Subject: [PATCH 7/8] (SCHEMA) Update command doc keywords to point to new stdout schemas This change updates the documentation keywords for the various resource commands to point to the newly defined stdout JSON Schemas. This change was kept separate from the implementation of those schemas to simplify review. --- schemas/src/resource/manifest.adapter.yaml | 8 ++++++-- schemas/src/resource/manifest.delete.yaml | 18 ++++++++++-------- schemas/src/resource/manifest.export.yaml | 8 ++++++-- schemas/src/resource/manifest.get.yaml | 8 ++++++-- schemas/src/resource/manifest.resolve.yaml | 8 ++++++-- schemas/src/resource/manifest.schema.yaml | 8 ++++++-- schemas/src/resource/manifest.set.yaml | 8 ++++++-- schemas/src/resource/manifest.test.yaml | 8 ++++++-- schemas/src/resource/manifest.validate.yaml | 8 ++++++-- schemas/src/resource/manifest.whatIf.yaml | 18 +++++++++++------- 10 files changed, 69 insertions(+), 31 deletions(-) diff --git a/schemas/src/resource/manifest.adapter.yaml b/schemas/src/resource/manifest.adapter.yaml index 55cb096b..4fab1d51 100644 --- a/schemas/src/resource/manifest.adapter.yaml +++ b/schemas/src/resource/manifest.adapter.yaml @@ -27,12 +27,16 @@ properties: Defines how DSC must call the DSC resource adapter to list its supported DSC resources. markdownDescription: | # VS Code only *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** Defines how DSC must call the DSC resource adapter to list its supported DSC resources. - [01]: /reference/schemas/resource/manifest/adapter?#list + For more information about the output DSC expects from the resource for this command, + see [List resource operation stdout][01]. + + [00]: /reference/schemas/resource/manifest/adapter?#list + [01]: /reference/schemas/resource/stdout/list? type: object required: - executable diff --git a/schemas/src/resource/manifest.delete.yaml b/schemas/src/resource/manifest.delete.yaml index c15ecc95..749d85bc 100644 --- a/schemas/src/resource/manifest.delete.yaml +++ b/schemas/src/resource/manifest.delete.yaml @@ -12,17 +12,19 @@ description: >- markdownDescription: | # VS Code only *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** 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 + resources as an alternative to handling the [`_exist`][01] 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 + an instance when `_exist` is `false`, set the [`handlesExist`][02] 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]. + [`_exist`][01] property in the [JSON schema for the resource's properties][03]. + + DSC doesn't expect this command to return any output to stdout. DSC sends data to the command in three ways: @@ -39,10 +41,10 @@ markdownDescription: | # VS Code only 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 - [04]: /reference/schemas/resource/manifest/schema/property? + [00]: /reference/schemas/resource/manifest/delete? + [01]: /reference/schemas/resource/properties/exist? + [02]: /reference/schemas/resource/manifest/set?#handlesExist + [03]: /reference/schemas/resource/manifest/schema/property? type: object required: diff --git a/schemas/src/resource/manifest.export.yaml b/schemas/src/resource/manifest.export.yaml index 903b0291..d33a1b04 100644 --- a/schemas/src/resource/manifest.export.yaml +++ b/schemas/src/resource/manifest.export.yaml @@ -7,11 +7,14 @@ description: >- Defines how DSC must call the DSC resource to get the current state of every instance. markdownDescription: | # VS Code only *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** Defines how DSC must call the DSC resource to get the current state of every instance. + For more information about the output DSC expects the resource to emit for this command, see + [Export resource operation stdout][01]. + 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 @@ -27,7 +30,8 @@ markdownDescription: | # VS Code only You must define the `input` property, one JSON input argument in the `args` property array, or both. - [01]: /reference/schemas/resource/manifest/export? + [00]: /reference/schemas/resource/manifest/export? + [01]: /reference/schemas/resource/stdout/export? type: object required: diff --git a/schemas/src/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml index 9e972f89..5bf8d900 100644 --- a/schemas/src/resource/manifest.get.yaml +++ b/schemas/src/resource/manifest.get.yaml @@ -7,10 +7,13 @@ description: >- Defines how DSC must call the DSC resource to get the current state of an instance. markdownDescription: | # VS Code only *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** Defines how DSC must call the DSC resource to get the current state of an instance. + + For more information about the output DSC expects the resource to emit for this command, see + [Get resource operation stdout][01]. DSC sends data to the command in three ways: @@ -27,7 +30,8 @@ markdownDescription: | # VS Code only You must define the `input` property, one JSON input argument in the `args` property array, or both. - [01]: /reference/schemas/resource/manifest/get? + [00]: /reference/schemas/resource/manifest/get? + [00]: /reference/schemas/resource/stdout/get? type: object required: diff --git a/schemas/src/resource/manifest.resolve.yaml b/schemas/src/resource/manifest.resolve.yaml index 84e0c5a0..6f3be496 100644 --- a/schemas/src/resource/manifest.resolve.yaml +++ b/schemas/src/resource/manifest.resolve.yaml @@ -10,13 +10,16 @@ description: >- markdownDescription: | # VS Code only *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** Defines how DSC must call the DSC resource to resolve an external source to nested DSC configuration document. Define this method for [importer resources][02] and set the [kind][03] property in the manifest root to `importer`. + For more information about the output DSC expects the resource to emit for this command, see + [Resolve resource operation stdout][01]. + 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 @@ -32,7 +35,8 @@ markdownDescription: | # VS Code only You must define the `input` property, one JSON input argument in the `args` property array, or both. - [01]: /reference/schemas/resource/manifest/resolve? + [00]: /reference/schemas/resource/manifest/resolve? + [01]: /reference/schemas/resource/stdout/resolve? [02]: /reference/schemas/definitions/resourceKind?#importer-resources [03]: /reference/schemas/resource/manifest/root?#kind diff --git a/schemas/src/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml index a78b7020..65e7bbb0 100644 --- a/schemas/src/resource/manifest.schema.yaml +++ b/schemas/src/resource/manifest.schema.yaml @@ -74,13 +74,17 @@ properties: # VS Code only markdownDescription: | *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** Defines how DSC must call the DSC resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC resource. - [01]: /reference/schemas/resource/manifest/schema/property?#command + For more information about the output DSC expects the resource to emit for this command, see + [Schema resource command stdout][01]. + + [00]: /reference/schemas/resource/manifest/schema/property?#command + [01]: /reference/schemas/resource/stdout/schema? defaultSnippets: - label: ' Define without arguments' markdownDescription: | diff --git a/schemas/src/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml index 77cbf15c..1c022a72 100644 --- a/schemas/src/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -8,12 +8,15 @@ description: >- process the output from the DSC resource. markdownDescription: | # VS Code only *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** 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. + For more information about the output DSC expects the resource to emit for this command, see + [Set resource operation stdout][01]. + 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 @@ -29,7 +32,8 @@ markdownDescription: | # VS Code only You must define the `input` property, one JSON input argument in the `args` property array, or both. - [01]: /reference/schemas/resource/manifest/set? + [00]: /reference/schemas/resource/manifest/set? + [01]: /reference/schemas/resource/stdout/set? type: object required: diff --git a/schemas/src/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml index f6e64757..ab780081 100644 --- a/schemas/src/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -8,12 +8,15 @@ description: >- to process the output from the DSC resource. markdownDescription: | # VS Code only *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** 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. + For more information about the output DSC expects the resource to emit for this command, see + [Test resource operation stdout][01]. + 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 @@ -29,7 +32,8 @@ markdownDescription: | # VS Code only You must define the `input` property, one JSON input argument in the `args` property array, or both. - [01]: /reference/schemas/resource/manifest/test? + [00]: /reference/schemas/resource/manifest/test? + [01]: /reference/schemas/resource/stdout/test? type: object diff --git a/schemas/src/resource/manifest.validate.yaml b/schemas/src/resource/manifest.validate.yaml index 2aec765c..76a929c3 100644 --- a/schemas/src/resource/manifest.validate.yaml +++ b/schemas/src/resource/manifest.validate.yaml @@ -9,12 +9,15 @@ description: >- markdownDescription: | # VS Code only *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** 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. + For more information about the output DSC expects the resource to emit for this command, see + [Validate resource operation stdout][01]. + 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 @@ -30,7 +33,8 @@ markdownDescription: | # VS Code only You must define the `input` property, one JSON input argument in the `args` property array, or both. - [01]: /reference/schemas/resource/manifest/validate? + [00]: /reference/schemas/resource/manifest/validate? + [01]: /reference/schemas/resource/stdout/validate? type: object required: diff --git a/schemas/src/resource/manifest.whatIf.yaml b/schemas/src/resource/manifest.whatIf.yaml index 59a0bab2..fc6f450e 100644 --- a/schemas/src/resource/manifest.whatIf.yaml +++ b/schemas/src/resource/manifest.whatIf.yaml @@ -8,15 +8,18 @@ description: >- modify an instance and how to process the output from the DSC resource. markdownDescription: | # VS Code only *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** Defines how DSC must call the DSC resource to indicate whether and how the set command will modify an instance and how to process the output from the DSC resource. If a resource doesn't - define this method in the manifest, DSC synthesizes this behavior by converting the result of - the test operation for the resource into the [set result][02]. + define this command in the manifest, DSC synthesizes this behavior by converting the result of + the test operation for the resource into the [set result][01]. - This method definition has the same structure as the [set method][03] in the resource manifest. + This command definition has the same structure as the [set command][02] in the resource manifest. + + For more information about the output DSC expects the resource to emit for this command, see + [What-if resource operation stdout][03]. DSC sends data to the command in three ways: @@ -33,9 +36,10 @@ markdownDescription: | # VS Code only You must define the `input` property, one JSON input argument in the `args` property array, or both. - [01]: /reference/schemas/resource/manifest/whatif? - [02]: /reference/schemas/outputs/resource/set? - [03]: /reference/schemas/resource/manifest/set? + [00]: /reference/schemas/resource/manifest/whatif? + [01]: /reference/schemas/outputs/resource/set? + [02]: /reference/schemas/resource/manifest/set? + [03]: /reference/schemas/resource/stdout/whatif? type: object required: From 36e770baf31926b004c3c81126d6f9442eb2e6ba Mon Sep 17 00:00:00 2001 From: Mikey Lombardi Date: Wed, 2 Apr 2025 09:55:10 -0500 Subject: [PATCH 8/8] (SCHEMA) FIx URIs for `$schema` in config document and resource manifest Prior to this change, the schemas erroneously included URIs for the preview schemas and didn't include URIs for the various version folders or `aka.ms` short link options. This change corrects the enumeration values and accompanying documentation keywords. --- schemas/src/config/document.yaml | 322 ++++++++++++++++++++++------ schemas/src/resource/manifest.yaml | 329 +++++++++++++++++++++++------ 2 files changed, 512 insertions(+), 139 deletions(-) diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index acdd140c..c8d6e44e 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -26,28 +26,45 @@ properties: $schema: title: Schema description: >- - This property must be the canonical URL of the DSC configuration document schema that the - document is implemented for. + Indicates the URI that resolves to the version of this schema that the document adheres to. + DSC uses this property when validating and processing the configuration document. type: string format: uri enum: - - ///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 + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/config/document.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.vscode.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/config/document.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/config/document.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/config/document.vscode.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/config/document.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/config/document.vscode.json + - https://aka.ms/dsc/schemas/v3/config/document.json + - https://aka.ms/dsc/schemas/v3/bundled/config/document.json + - https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json + - https://aka.ms/dsc/schemas/v3.0/config/document.json + - https://aka.ms/dsc/schemas/v3.0/bundled/config/document.json + - https://aka.ms/dsc/schemas/v3.0/bundled/config/document.vscode.json + - https://aka.ms/dsc/schemas/v3.0.0/config/document.json + - https://aka.ms/dsc/schemas/v3.0.0/bundled/config/document.json + - https://aka.ms/dsc/schemas/v3.0.0/bundled/config/document.vscode.json # VS Code only: markdownDescription: | *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** - This property must be the canonical URL of the DSC configuration document schema that the - document is implemented for. + The `$schema` property indicates the URI that resolves to the version of this schema that the + document adheres to. DSC uses this property when validating and processing the configuration + document. + + The JSON schemas for DSC are published in multiple versions and forms. This documentation is + for the latest version of the schema. As a convenience, you can specify either the full URI + for the schema hosted in GitHub or use the shorter `aka.ms` URI. You can specify the schema + for a specific semantic version, the latest schema for a minor version, or the latest schema + for a major version of DSC. For more information about schema URIs and versioning, see + [DSC JSON Schema URIs][01]. For every version of the schema, there are three valid urls: @@ -81,34 +98,43 @@ properties: > validate the document when it uses this schema, other tools may error or behave in > unexpected ways. - [01]: /reference/schemas/config/document?#schema + [00]: /reference/schemas/config/document?#schema + [01]: /reference/schemas/schema-uris? markdownEnumDescriptions: - - | # ///config/document.yaml + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/config/document.json - > #### `` non-bundled + > #### `v3` non-bundled > - > Indicates that the configuration document adheres to the `` schema. This URL + > Indicates that the configuration document adheres to the `v3` 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. - - | # ///bundled/config/document.yaml + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.json - > #### `` bundled + > #### `v3` bundled > - > Indicates that the configuration document adheres to the `` schema. This URL + > Indicates that the configuration document adheres to the `v3` 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. - - | # ///bundled/config/document.vscode.yaml + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/config/document.vscode.json - > #### `` enhanced authoring + > #### `v3` enhanced authoring > - > Indicates that the configuration document adheres to the `` schema. This URL + > Indicates that the configuration document adheres to the `v3` 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. @@ -116,95 +142,253 @@ 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 + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/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 + > #### `v3.0` non-bundled, canonical URI > - > This URL points to the canonical non-bundled schema. When it's used for validation, the + > Indicates that the configuration document adheres to the `v3.0` 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. + > + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/config/document.yaml + - - | # //2023/10/bundled/config/document.yaml + > #### `v3.0` bundled, canonical URI + > + > Indicates that the configuration document adheres to the `v3.0` 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. + > + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/config/document.vscode.yaml + + + > #### `v3.0` enhanced authoring, canonical URI + > + > Indicates that the configuration document adheres to the `v3.0` 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. + > + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.yaml - > #### `2023/10` bundled + > #### `v3.0.0` non-bundled, canonical URI + > + > Indicates that the configuration document adheres to the `v3.0.0` 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. > - > 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 URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/config/document.yaml + + + > #### `v3.0.0` bundled, canonical URI > - > 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 `v3.0.0` 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 + > + > This URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/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 + > #### `v3.0.0` enhanced authoring, canonical URI > - > 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 `v3.0.0` 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. + > + > This URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. + - | # https://aka.ms/dsc/schemas/v3/config/document.yaml + -# Old Schema - - | # //2023/08/config/document.yaml + > #### `v3` non-bundled, short URI + > + > Indicates that the configuration document adheres to the `v3` 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. + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://aka.ms/dsc/schemas/v3/bundled/config/document.yaml - > #### `2023/08` non-bundled + > #### `v3` bundled, short URI > - > 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 + > Indicates that the configuration document adheres to the `v3` schema. This URL + > points to the bundled schema. When it's used for validation, the validating client + > only needs to retrieve this 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. + > 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. + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.yaml + - - | # //2023/08/bundled/config/document.yaml + > #### `v3` enhanced authoring, short URI + > + > Indicates that the configuration document adheres to the `v3` 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. + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://aka.ms/dsc/schemas/v3.0/config/document.yaml - > #### `2023/08` bundled + > #### `v3.0` non-bundled, short URI > - > 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 + > Indicates that the configuration document adheres to the `v3.0` 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. > - > This URL points to the bundled schema. When it's used for validation, the validating - > client only needs to retrieve this schema. + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://aka.ms/dsc/schemas/v3.0/bundled/config/document.yaml + + + > #### `v3.0` bundled, short URI + > + > Indicates that the configuration document adheres to the `v3.0` 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/08/bundled/config/document.vscode.yaml + > + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://aka.ms/dsc/schemas/v3.0/bundled/config/document.vscode.yaml - > #### `2023/08` enhanced authoring + > #### `v3.0` enhanced authoring, short URI > - > 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 + > Indicates that the configuration document adheres to the `v3.0` 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 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 + > 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. + > + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://aka.ms/dsc/schemas/v3.0.0/config/document.yaml + + + > #### `v3.0.0` non-bundled, short URI + > + > Indicates that the configuration document adheres to the `v3.0.0` 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. + > + > This URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. + - | # https://aka.ms/dsc/schemas/v3.0.0/bundled/config/document.yaml + + + > #### `v3.0.0` bundled, short URI + > + > Indicates that the configuration document adheres to the `v3.0.0` 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. + > + > This URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. + - | # https://aka.ms/dsc/schemas/v3.0.0/bundled/config/document.vscode.yaml + + + > #### `v3.0.0` enhanced authoring, short URI + > + > Indicates that the configuration document adheres to the `v3.0.0` 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. - + > + > This URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. parameters: title: DSC configuration document parameters description: >- diff --git a/schemas/src/resource/manifest.yaml b/schemas/src/resource/manifest.yaml index bf4c6a88..020e1293 100644 --- a/schemas/src/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -201,23 +201,40 @@ properties: type: string format: uri enum: - - ///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 + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.vscode.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/resource/manifest.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.vscode.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/manifest.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.json + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.vscode.json + - https://aka.ms/dsc/schemas/v3/resource/manifest.json + - https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json + - https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json + - https://aka.ms/dsc/schemas/v3.0/resource/manifest.json + - https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.json + - https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.vscode.json + - https://aka.ms/dsc/schemas/v3.0.0/resource/manifest.json + - https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.json + - https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.vscode.json # VS Code Only markdownDescription: | *** - [_Online Documentation_][01] + [_Online Documentation_][00] *** - This property must be one of the canonical URLs for the version of the DSC resource manifest - schema that the manifest is implemented for. + The `$schema` property indicates the canonical URI of this schema that the manifest validates + against. This property is mandatory. DSC uses this value to validate the manifest against the + correct JSON schema. + + The JSON schemas for DSC are published in multiple versions and forms. This documentation is + for the latest version of the schema. As a convenience, you can specify either the full URI + for the schema hosted in GitHub or use the shorter `aka.ms` URI. You can specify the schema + for a specific semantic version, the latest schema for a minor version, or the latest schema + for a major version of DSC. For more information about schema URIs and versioning, see + [DSC JSON Schema URIs][01]. For every version of the schema, there are three valid urls: @@ -251,128 +268,300 @@ properties: > validate the document when it uses this schema, other tools may error or behave in > unexpected ways. - [01]: /reference/schemas/resource/manifest/root?#schema + [00]: /reference/schemas/resource/manifest/root?#schema + [01]: /reference/schemas/schema-uris? markdownEnumDescriptions: - - | # ///resource/manifest.yaml + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/manifest.yaml - > #### `` non-bundled + > #### `v3` non-bundled, canonical URI > - > Indicates that the resource manifest adheres to the `` schema. This URL + > Indicates that the resource manifest adheres to the `v3` 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. - - | # ///bundled/resource/manifest.yaml + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.yaml - > #### `` bundled + > #### `v3` bundled, canonical URI > - > Indicates that the resource manifest adheres to the `` schema. This URL + > Indicates that the resource manifest adheres to the `v3` 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. - - | # ///bundled/resource/manifest.vscode.yaml + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/bundled/resource/manifest.vscode.yaml - > #### `` enhanced authoring + > #### `v3` enhanced authoring, canonical URI > - > Indicates that the resource manifest adheres to 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. + > Indicates that the resource manifest adheres to the `v3` 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. + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/resource/manifest.yaml + - - | # //2023/10/resource/manifest.yaml + > #### `v3.0` non-bundled, canonical URI + > + > Indicates that the resource manifest adheres to the `v3.0` 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. + > + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.yaml - > #### `2023/10` non-bundled + > #### `v3.0` bundled, canonical URI + > + > Indicates that the resource manifest adheres to the `v3.0` 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/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 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. > - > 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. + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0/bundled/resource/manifest.vscode.yaml + - - | # //2023/10/bundled/resource/manifest.yaml + > #### `v3.0` enhanced authoring, canonical URI + > + > Indicates that the resource manifest adheres to the `v3.0` 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. + > + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/resource/manifest.yaml - > #### `2023/10` bundled + > #### `v3.0.0` non-bundled, canonical URI > - >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. + > Indicates that the resource manifest adheres to the `v3.0.0` 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. > - > This URL points to the bundled schema. When it's used for validation, the validating - > client only needs to retrieve this schema. + > This URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/bundled/resource/manifest.yaml + + + > #### `v3.0.0` bundled, canonical URI + > + > Indicates that the resource manifest adheres to the `v3.0.0` 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 + > + > This URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. + - | # https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/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. + > #### `v3.0.0` enhanced authoring, canonical URI > - > 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. + + > Indicates that the resource manifest adheres to the `v3.0.0` 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 + > + > This URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. + + + - | # https://aka.ms/dsc/schemas/v3/resource/manifest.yaml - > #### `2023/08` non-bundled + > #### `v3` non-bundled, short URI > - > 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 + > Indicates that the resource manifest adheres to the `v3` 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. + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.yaml + + + > #### `v3` bundled, short URI + > + > Indicates that the resource manifest adheres to the `v3` 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. + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.yaml + - - | # //2023/08/bundled/resource/manifest.yaml + > #### `v3` enhanced authoring, short URI + > + > Indicates that the resource manifest adheres to the `v3` 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. + > + > This URI is for the schemas in a major version folder. If you pin to a major version + > folder, like `v3`, the schemas you use will update with every nonbreaking release. You + > can use those schemas until you want or need to migrate to a new major version of DSC. + - | # https://aka.ms/dsc/schemas/v3.0/resource/manifest.yaml - > #### `2023/08` bundled + > #### `v3.0` non-bundled, short URI > - > 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 + > Indicates that the resource manifest adheres to the `v3.0` 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. > - > This URL points to the bundled schema. When it's used for validation, the validating - > client only needs to retrieve this schema. + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.yaml + + + > #### `v3.0` bundled, short URI + > + > Indicates that the resource manifest adheres to the `v3.0` 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/08/bundled/resource/manifest.vscode.yaml + > + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://aka.ms/dsc/schemas/v3.0/bundled/resource/manifest.vscode.yaml + + + > #### `v3.0` enhanced authoring, short URI + > + > Indicates that the resource manifest adheres to the `v3.0` 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. + > + > This URI is for the schemas in a minor version folder. If you pin to a minor version + > folder, like `v3.0`, the schemas you use will update with every patch release. Pinning + > to a minor version folder enables you to take advantage of fixes to the schemas without + > continually updating your schema URIs. However, to take advantage of any improvements + > or new features, you need to update the URI whenever a new minor version is released. + - | # https://aka.ms/dsc/schemas/v3.0.0/resource/manifest.yaml + + + > #### `v3.0.0` non-bundled, short URI + > + > Indicates that the resource manifest adheres to the `v3.0.0` 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. + > + > This URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. + - | # https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.yaml - > #### `2023/08` enhanced authoring + > #### `v3.0.0` bundled, short URI > - > 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 + > Indicates that the resource manifest adheres to the `v3.0.0` schema. This URL + > points to the bundled schema. When it's used for validation, the validating client + > only needs to retrieve this 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 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. + > + > This URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. + - | # https://aka.ms/dsc/schemas/v3.0.0/bundled/resource/manifest.vscode.yaml + + + > #### `v3.0.0` enhanced authoring, short URI + > + > Indicates that the resource manifest adheres to the `v3.0.0` 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. + > + > This URI is for the schemas in a full semantic version folder. If you pin to a full + > semantic version folder, like `v3.0.0`, you're pinning to schemas that won't change. + > However, to take advantage of any improvements or fixes to the schemas, you need to + > update the URI with each release. type: $ref: ///definitions/resourceType.yaml version: