(SCHEMA) Update command doc keywords to point to new stdout schemas

michaeltlombardi · michaeltlombardi · commit 2da58765578b · 2025-05-05T08:48:06.000-05:00
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.
diff --git 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]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/adapter?<DOCS_VERSION_PIN>#list
+      For more information about the output DSC expects from the resource for this command,
+      see [List resource operation stdout][01].
+
+      [00]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/adapter?<DOCS_VERSION_PIN>#list
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/list?<DOCS_VERSION_PIN>
     type: object
     required:
       - executable
diff --git 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]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/delete?<DOCS_VERSION_PIN>
-  [02]: <DOCS_BASE_URL>/reference/schemas/resource/properties/exist?<DOCS_VERSION_PIN>
-  [03]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>#handlesExist
-  [04]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/property?<DOCS_VERSION_PIN>
+  [00]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/delete?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/properties/exist?<DOCS_VERSION_PIN>
+  [02]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>#handlesExist
+  [03]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/property?<DOCS_VERSION_PIN>
 
 type: object
 required:
diff --git 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]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/export?<DOCS_VERSION_PIN>
+  [00]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/export?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/export?<DOCS_VERSION_PIN>
 
 type: object
 required:
diff --git 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]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/get?<DOCS_VERSION_PIN>
+  [00]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/get?<DOCS_VERSION_PIN>
+  [00]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/get?<DOCS_VERSION_PIN>
 
 type: object
 required:
diff --git 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]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/resolve?<DOCS_VERSION_PIN>
+  [00]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/resolve?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/resolve?<DOCS_VERSION_PIN>
   [02]: <DOCS_BASE_URL>/reference/schemas/definitions/resourceKind?<DOCS_VERSION_PIN>#importer-resources
   [03]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/root?<DOCS_VERSION_PIN>#kind
 
diff --git 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]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/property?<DOCS_VERSION_PIN>#command
+      For more information about the output DSC expects the resource to emit for this command, see
+      [Schema resource command stdout][01].
+
+      [00]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/schema/property?<DOCS_VERSION_PIN>#command
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/schema?<DOCS_VERSION_PIN>
     defaultSnippets:
       - label: ' Define without arguments'
         markdownDescription: |
diff --git 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]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>
+  [00]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/set?<DOCS_VERSION_PIN>
 
 type: object
 required:
diff --git 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]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/test?<DOCS_VERSION_PIN>
+  [00]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/test?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/test?<DOCS_VERSION_PIN>
 
 
 type: object
diff --git 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]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/validate?<DOCS_VERSION_PIN>
+  [00]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/validate?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/validate?<DOCS_VERSION_PIN>
 
 type: object
 required:
diff --git 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]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>
-  [02]: <DOCS_BASE_URL>/reference/schemas/outputs/resource/set?<DOCS_VERSION_PIN>
-  [03]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>
+  [00]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/whatif?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/outputs/resource/set?<DOCS_VERSION_PIN>
+  [02]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/set?<DOCS_VERSION_PIN>
+  [03]: <DOCS_BASE_URL>/reference/schemas/resource/stdout/whatif?<DOCS_VERSION_PIN>
 
 type: object
 required:
