(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.

Author: michaeltlombardi

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:     <HOST>/<PREFIX>/<VERSION>/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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/delete?<DOCS_VERSION_PIN>
+
+type: 'null'

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:     <HOST>/<PREFIX>/<VERSION>/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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/export?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/command?<DOCS_VERSION_PIN>
+  [02]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/embedded?<DOCS_VERSION_PIN>
+
+type: object

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:     <HOST>/<PREFIX>/<VERSION>/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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/get?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/command?<DOCS_VERSION_PIN>
+  [02]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/embedded?<DOCS_VERSION_PIN>
+
+type: object

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:     <HOST>/<PREFIX>/<VERSION>/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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/list?<DOCS_VERSION_PIN>
+
+type: object
+required:
+  - type
+  - kind
+  - version
+  - capabilities
+  - path
+  - directory
+  - implementedAs
+  - properties
+  - requireAdapter
+properties:
+  type:
+    $ref: /<PREFIX>/<VERSION>/definitions/resourceType.yaml
+  kind:
+    $ref: /<PREFIX>/<VERSION>/definitions/resourceKind.yaml
+  version:
+    $ref: /<PREFIX>/<VERSION>/definitions/semver.yaml
+  capabilities:
+    $ref: /<PREFIX>/<VERSION>/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: /<PREFIX>/<VERSION>/definitions/resourceType.yaml

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:     <HOST>/<PREFIX>/<VERSION>/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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/resolve?<DOCS_VERSION_PIN>
+
+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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/resolve?<DOCS_VERSION_PIN>#configuration
+    $ref: /<PREFIX>/<VERSION>/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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/resolve?<DOCS_VERSION_PIN>#parameters
+    type: object

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:     <HOST>/<PREFIX>/<VERSION>/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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/export?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/command?<DOCS_VERSION_PIN>
+  [02]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/embedded?<DOCS_VERSION_PIN>
+
+type: object
+required:
+      - $schema
+      - type
+      - properties

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:     <HOST>/<PREFIX>/<VERSION>/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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/set?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>#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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/set?<DOCS_VERSION_PIN>#null-output
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>#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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/set?<DOCS_VERSION_PIN>#state-output
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>#return
+      [02]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/command?<DOCS_VERSION_PIN>
+      [03]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/embedded?<DOCS_VERSION_PIN>
+    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]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/set?<DOCS_VERSION_PIN>#diff-output
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>#return
+    type: array
+    uniqueItems: true
+    items:
+      type: string