(SCHEMA) Update schemas for v3.1.0 release

schemas/build.ps1

@@ -675,6 +675,7 @@ process {
             "$OutputDirectory/config"
             "$OutputDirectory/metadata"
             "$OutputDirectory/definitions"
+            "$OutputDirectory/extension"
             "$OutputDirectory/outputs"
             "$OutputDirectory/resource"
         )

schemas/schemas.config.yaml

@@ -1,9 +1,15 @@
 host:             https://raw.githubusercontent.com
 prefix:           PowerShell/DSC/main/schemas
-version:          v3.0
+version:          v3.1.0
 docs_base_url:    https://learn.microsoft.com/powershell/dsc
 docs_version_pin: view=dsc-3.0&preserve-view=true
 bundle_schemas:
+  # Resource manifest bundle
+  - ConfigFilePath:  extension/manifest.json
+    Name:            manifest
+    OutputDirectory: bundled/extension
+    OutputFormat:    ['Json', 'JsonVSCode']
+
   # Resource manifest bundle
   - ConfigFilePath:  resource/manifest.json
     Name:            manifest
@@ -37,6 +43,11 @@ bundle_schemas:
     OutputDirectory: bundled/outputs/config
     OutputFormat:    ['Json', 'JsonVSCode']
 
+  - ConfigFilePath:  outputs/extension/list.json
+    Name:            list
+    OutputDirectory: bundled/outputs/extension
+    OutputFormat:    ['Json', 'JsonVSCode']
+
   - ConfigFilePath:  outputs/resource/get.json
     Name:            get
     OutputDirectory: bundled/outputs/resource
@@ -61,3 +72,59 @@ bundle_schemas:
     Name:            test
     OutputDirectory: bundled/outputs/resource
     OutputFormat:    ['Json', 'JsonVSCode']
+
+  # stdout schema bundles
+  - ConfigFilePath:  extension/stdout/discover.json
+    Name:            discover
+    OutputDirectory: bundled/extension/stdout
+    OutputFormat:    ['Json', 'JsonVSCode']
+
+  - ConfigFilePath:  resource/stdout/delete.json
+    Name:            delete
+    OutputDirectory: bundled/resource/stdout
+    OutputFormat:    ['Json', 'JsonVSCode']
+
+  - ConfigFilePath:  resource/stdout/export.json
+    Name:            export
+    OutputDirectory: bundled/resource/stdout
+    OutputFormat:    ['Json', 'JsonVSCode']
+
+  - ConfigFilePath:  resource/stdout/get.json
+    Name:            get
+    OutputDirectory: bundled/resource/stdout
+    OutputFormat:    ['Json', 'JsonVSCode']
+
+  - ConfigFilePath:  resource/stdout/list.json
+    Name:            list
+    OutputDirectory: bundled/resource/stdout
+    OutputFormat:    ['Json', 'JsonVSCode']
+
+  - ConfigFilePath:  resource/stdout/resolve.json
+    Name:            resolve
+    OutputDirectory: bundled/resource/stdout
+    OutputFormat:    ['Json', 'JsonVSCode']
+
+  - ConfigFilePath:  resource/stdout/schema.json
+    Name:            schema
+    OutputDirectory: bundled/resource/stdout
+    OutputFormat:    ['Json', 'JsonVSCode']
+
+  - ConfigFilePath:  resource/stdout/set.json
+    Name:            set
+    OutputDirectory: bundled/resource/stdout
+    OutputFormat:    ['Json', 'JsonVSCode']
+
+  - ConfigFilePath:  resource/stdout/test.json
+    Name:            test
+    OutputDirectory: bundled/resource/stdout
+    OutputFormat:    ['Json', 'JsonVSCode']
+
+  - ConfigFilePath:  resource/stdout/validate.json
+    Name:            validate
+    OutputDirectory: bundled/resource/stdout
+    OutputFormat:    ['Json', 'JsonVSCode']
+
+  - ConfigFilePath:  resource/stdout/whatIf.json
+    Name:            whatIf
+    OutputDirectory: bundled/resource/stdout
+    OutputFormat:    ['Json', 'JsonVSCode']

schemas/src/definitions/extensionCapabilities.yaml

@@ -0,0 +1,40 @@
+# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema
+$schema: https://json-schema.org/draft/2020-12/schema
+$id:     <HOST>/<PREFIX>/<VERSION>/definitions/extensionCapabilities.yaml
+
+title: Resource capabilities
+description: >-
+  Define the operations DSC can invoke for an extension and how the extension behaves when invoked.
+
+markdownDescription: |-
+  ***
+  [_Online Documentation_][00]
+  ***
+
+  DSC extensions always have at least one capability. Extension capabilities define the operations
+  DSC can invoke for an extension and how the extension behaves when invoked.
+
+  <!-- Link reference definitions -->
+  [00]: <DOCS_BASE_URL>/reference/schemas/definitions/extensionCapabilities?<DOCS_VERSION_PIN>
+
+type: array
+items:
+  type: string
+  enum:
+    - discover
+  markdownEnumDescriptions:
+    - |- # discover
+      ***
+      [_Online Documentation_][00]
+      ***
+
+      An extension with the `discover` capability supports retrieving the path to DSC resource
+      manifests that aren't included in the `PATH` or `DSC_RESOURCE_PATH`, like manifests for
+      software installed as AppX packages.
+
+      An extension has this capability when its manifest defines the [discover][02]
+      property.
+
+      <!-- Link reference definitions -->
+      [00]: <DOCS_BASE_URL>/reference/schemas/definitions/extensionCapabilities?<DOCS_VERSION_PIN>#discover
+      [02]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/discover?<DOCS_VERSION_PIN>

schemas/src/definitions/extensionType.yaml

@@ -0,0 +1,42 @@
+# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: <HOST>/<PREFIX>/<VERSION>/definitions/extensionType.yaml
+
+title: DSC extension fully qualified type name
+description: |
+  The namespaced name of the DSC extension, using the syntax:
+
+  <owner>[.<group>][.<area>][.<subarea>]/<name>
+
+  For example:
+
+    - Microsoft/Example
+    - Microsoft.DSC/Docs
+    - Microsoft.Windows.Appx/Discover
+
+type: string
+pattern: ^\w+(\.\w+){0,3}\/\w+$
+
+# VS Code only
+markdownDescription: |
+  ***
+  [_Online Documentation_][01]
+  ***
+
+  The namespaced name of the DSC extension, using the syntax:
+
+  ```yaml
+  owner[{.namespace}]/name
+  ```
+
+  For example:
+
+  - `Microsoft/Example`
+  - `Microsoft.DSC/Docs`
+  - `Microsoft.Windows.Appx/Discover`
+
+  [01]: <DOCS_BASE_URL>/reference/schemas/definitions/extensiontype?<DOCS_VERSION_PIN>
+patternErrorMessage: |
+  Invalid type name. Valid extension type names always define an owner and a name separated by a
+  slash, like `Microsoft/Example`. Type names may optionally include the group, area, and subarea
+  segments to namespace the resource under the owner, like `Microsoft.Windows.Appx/Discover`.

schemas/src/definitions/resourceKind.yaml

@@ -13,6 +13,7 @@ enum:
   - adapter
   - group
   - importer
+  - exporter
 
 # VS Code only
 
@@ -56,3 +57,12 @@ markdownEnumDescriptions:
       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.
+  - | # exporter
+      <!-- force a line break -->
+
+      Indicates that the manifest is for a resource that only implements the **Export** operation
+      to use for inventory and fact-gathering scenarios. For exporter resources, DSC expects the
+      resource to return one or more resource definitions to recursively export, rather than the
+      actual state of instances.
+
+      For more information about the expected output, see [Export resource operation stdout][02].

schemas/src/definitions/resourceType.yaml

@@ -6,15 +6,16 @@ title: DSC resource fully qualified type name
 description: |
   The namespaced name of the DSC resource, using the syntax:
 
-  owner[.group][.area]/name
+  <owner>[.<group>][.<area>][.<subarea>]/<name>
 
   For example:
 
-    - Microsoft.SqlServer/Database
-    - Microsoft.SqlServer.Database/User
+  - Microsoft/OSInfo
+  - Microsoft.SqlServer/Database
+  - Microsoft.SqlServer.Database/User
 
 type: string
-pattern: ^\w+(\.\w+){0,2}\/\w+$
+pattern: ^\w+(\.\w+){0,3}\/\w+$
 
 # VS Code only
 markdownDescription: |
@@ -25,16 +26,17 @@ markdownDescription: |
   The namespaced name of the DSC resource, using the syntax:
 
   ```yaml
-  owner[.group][.area]/name
+  <owner>[.<group>][.<area>][.<subarea>]/<name>
   ```
 
   For example:
 
+  - `Microsoft/OSInfo`
   - `Microsoft.SqlServer/Database`
   - `Microsoft.SqlServer.Database/User`
 
   [01]: <DOCS_BASE_URL>/reference/schemas/definitions/resourcetype?<DOCS_VERSION_PIN>
 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`.
+  slash, like `Microsoft/OSInfo`. Type names may optionally include the group, area, and subarea
+  segments to namespace the resource under the owner, like `Microsoft.Windows/Registry`.

schemas/src/extension/manifest.discover.yaml

@@ -0,0 +1,85 @@
+# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema
+$schema: https://json-schema.org/draft/2020-12/schema
+$id:     <HOST>/<PREFIX>/<VERSION>/extension/manifest.discover.yaml
+
+title: Discover operation command
+description: >-
+  Defines how DSC must call the DSC extension to discover the paths to resource manifests.
+markdownDescription: | # VS Code only
+  ***
+  [_Online Documentation_][00]
+  ***
+
+  Defines how DSC must call the DSC extension to discover the paths to resource manifests. An
+  extension that defines this field in its manifest has the `discover` capability.
+
+  By default, DSC only discovers resource manifests in the `PATH` environment variable. If the
+  `DSC_RESOURCE_PATH` environment variable is defined, DSC searches those paths for resource
+  manifests instead.
+
+  If initial discovery finds any extension manifests that have the `discover` capability, DSC uses
+  those extensions to discover resources that aren't available in `PATH` or `DSC_RESOURCE_PATH`.
+
+  For more information about the output DSC expects the extension to emit for this command, see
+  [Discover extension operation stdout][01].
+
+  [00]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/discover?<DOCS_VERSION_PIN>
+  [00]: <DOCS_BASE_URL>/reference/schemas/extension/stdout/discover?<DOCS_VERSION_PIN>
+
+type: object
+required:
+  - executable
+properties:
+  executable:
+    $ref: /<PREFIX>/<VERSION>/definitions/commandExecutable.yaml
+    markdownDescription: |
+      ***
+      [_Online Documentation_][01]
+      ***
+
+      Defines the name of the command to run. The value must be the name of a command discoverable
+      in the system's `PATH` environment variable or the full path to the command. A file extension
+      is only required when the command isn't recognizable by the operating system as an
+      executable.
+
+      [01]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/discover?<DOCS_VERSION_PIN>#executable
+  args:
+    $ref: /<PREFIX>/<VERSION>/definitions/commandArgs.yaml
+    markdownDescription: |
+      ***
+      [_Online Documentation_][01]
+      ***
+
+      Defines an array of strings to pass as arguments to the command. DSC passes the arguments to
+      the command in the order they're specified.
+
+      For example, the given the following definition:
+
+      ```json
+      {
+        "executable": "myextension",
+        "args":       ["discover", "--all"],
+      }
+      ```
+
+      DSC invokes the command for the resource as:
+
+      ```bash
+      myextension discover --all
+      ```
+
+      [01]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/discover?<DOCS_VERSION_PIN>#args
+
+defaultSnippets: # VS Code only
+  - label: ' Define without arguments'
+    markdownDescription: |
+      Define the `discover` command for the extension when no arguments are required.
+    body:
+      executable: ${2:executable_name}
+  - label: ' Define with arguments'
+    markdownDescription: |-
+      Define the `discover` command for the extension when at least one argument is required.
+    body:
+      executable: ${2:executable_name}
+      args:
+        - ${3:--first-argument}