Update conceptual docs for v3 GA

Author: michaeltlombardi

dsc/docs-conceptual/dsc-3.0/changelog.md

@@ -3,46 +3,47 @@ description: >-
   DSC configuration documents are YAML or JSON data files that define the desired state of a system
   declaratively. They are used to retrieve, validate, and enforce the state of multiple resource
   instances.
-ms.date: 08/07/2023
-title: DSC Configuration Documents
+ms.date: 03/04/2025
+title: DSC configuration documents
 ---
 
-# DSC Configuration Documents
+# DSC configuration documents
 
 <!-- markdownlint-disable MD013 -->
 
 In Microsoft's Desired State Configuration (DSC) platform, DSC configuration documents declare the
 desired state of a system as data files. Configuration documents define a collection of
-[DSC Resource][01] instances to describe what the desired state should be, not how to put the
-system into that state. The DSC Resources handle the _how_ for the configuration document
-instances.
+[DSC resource][01] instances to describe what the desired state should be, not how to put the
+system into that state. The DSC resources handle the _how_ for each instance.
 
-DSCv3 can process configuration documents to:
+DSC can process configuration documents to:
 
 - Retrieve the current state of the defined resource instances with the `dsc config get` command.
 - Validate whether the instances are in the desired state with the `dsc config test` command.
 - Enforce the desired state for the instances with the `dsc config set` command.
+- Export a new configuration document with every instance of a set of resources with the
+  `dsc config export` command.
 
 Configuration documents are YAML or JSON files that contain a single object. The object's
-properties define how DSCv3 processes the document. The top-level properties for a document are:
+properties define how DSC processes the document. The top-level properties for a document are:
 
-- `$schema` (required) - Defines the canonical URI for the JSON Schema the document adheres to. DSC
+- `$schema` (required) - Defines the URI for the JSON Schema the document adheres to. DSC
   uses this to know how to validate and interpret the document.
 - `resources` (required) - Defines the collection of resource instances the document manages.
-- `metadata` (optional) - Defines an arbitrary set of annotations for the document. DSC doesn't
-  validate this data or use it directly. The annotations can include notes like who authored the
-  document, the last time someone updated it, or any other information. DSC doesn't use the
-  annotations. The metadata is for documentation or other tools to use.
+- `metadata` (optional) - Defines an arbitrary set of annotations for the document. Except for
+  metadata within the `Microsoft.DSC` property, DSC doesn't validate this data or use it directly.
+  The annotations can include notes like who authored the document, the last time someone updated
+  it, or any other information. DSC doesn't use the annotations. The metadata is for documentation
+  or other tools to use.
+
+  DSC applies validation to the `Microsoft.DSC` property. For more information, see the
+  [DSC Configuration document metadata schema][02] reference.
 - `parameters` (optional) - Defines a set of runtime options for the configuration. Parameters can
   be referenced by resource instances to reduce duplicate definitions or enable dynamic values.
   Parameters can have default values and can be set on any configuration operation.
 - `variables` (optional) - Defines a set of reusable values for the configuration. Variables can be
   referenced by resource instances to reduce duplicate definitions.
 
-> [!NOTE]
-> DSC isn't implemented to process the `parameters` and `variables` properties yet. They can be
-> defined in a document, but not referenced.
-
 ## Defining a configuration document
 
 Minimally, a configuration document defines the `$schema` and `resources` properties. The
@@ -53,7 +54,7 @@ For example:
 
 ```yaml
 # example.dsc.config.yaml
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
 resources:
   - name: example key value
     type: Microsoft.Windows/Registry
@@ -64,7 +65,7 @@ resources:
         String: This is an example.
 ```
 
-The example document defines a single resource instance called `example key value`. The instance
+The example document defines a single resource instance named `example key value`. The instance
 uses the `Microsoft.Windows/Registry` resource to declare the following desired state:
 
 - The `example\key` registry key should exist in the system's current user hive.
@@ -75,17 +76,21 @@ The example document is _declarative_. It describes the desired state, not how t
 into that state. It relies on the `Microsoft.Windows/Registry` resource to handle getting, testing,
 and setting the state of the registry key and value.
 
+For more information about the structure and validation of configuration documents, see
+[DSC Configuration document schema reference][03].
+
 ### Defining resource instances
 
 As shown in the prior example, configuration documents include a collection of resource instances.
-Together, the instances describe the desired state of a system. A configuration document can include any
-number of resource instances.
+Together, the instances describe the desired state of a system. A configuration document can
+include any number of resource instances.
 
 A resource instance declaration always includes:
 
 - `name` - A short, human-readable name for the instance that's unique in the document. This name
   is used for logging and it helps describe the purpose of the instance.
-- `type` - The [fully qualified type name][02] of the resource that DSC should use to manage the instance.
+- `type` - The [fully qualified type name][04] of the resource that DSC should use to manage the
+  instance.
 - `properties` - The desired state for the instance. DSC validates the values against the
   resource's instance schema.
 
@@ -96,60 +101,86 @@ incompatible state for the instance on every run.
 ## Getting the current state of a configuration
 
 The `dsc config get` command retrieves the current state of the resource instances defined in a
-configuration document. DSC also collects any message emitted by the resources during the operation
-and indicates whether any of the resources raised an error.
+configuration document. DSC also collects any message emitted by the resources during the
+operation, indicates whether any of the resources raised an error, and provides metadata about the
+operation as a whole and for each resource instance.
 
 ```sh
-cat ./example.config.dsc.yaml | dsc config get
+dsc config get --file ./example.config.dsc.yaml
 ```
 
 ```yaml
+metadata:
+  Microsoft.DSC:
+    version: 3.0.0
+    operation: get
+    executionType: actual
+    startDatetime: 2025-02-24T16:09:40.671454400-06:00
+    endDatetime: 2025-02-24T16:09:41.850086300-06:00
+    duration: PT1.1786319S
+    securityContext: restricted
 results:
-- name: example key value
+- metadata:
+    Microsoft.DSC:
+      duration: PT0.2751153S
+  name: example key value
   type: Microsoft.Windows/Registry
   result:
     actualState:
-      $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-      keyPath: ''
+      keyPath: HKCU\example\key
+      _exist: false
 messages: []
 hadErrors: false
 ```
 
 ## Testing a configuration
 
-The `dsc config test` command compares the current state of the resource instances to their desired state. The result for each instance includes:
+The `dsc config test` command compares the current state of the resource instances to their desired
+state. The result for each instance includes:
 
 - The desired state for the instance.
 - The actual state of the instance.
 - Whether the instance is in the desired state.
 - The list of properties that are out of the desired state, if any.
 
-DSC also collects any message emitted by the resources during the operation and indicates whether
-any of the resources raised an error.
+DSC also collects any message emitted by the resources during the operation, indicates whether any
+of the resources raised an error, and provides metadata about the operation as a whole and for each
+resource instance.
 
 ```sh
-cat ./example.config.dsc.yaml | dsc config test
+dsc config test --file /example.config.dsc.yaml
 ```
 
 ```yaml
+metadata:
+  Microsoft.DSC:
+    version: 3.0.0
+    operation: test
+    executionType: actual
+    startDatetime: 2025-02-24T16:11:42.798122500-06:00
+    endDatetime: 2025-02-24T16:11:43.442216400-06:00
+    duration: PT0.6440939S
+    securityContext: restricted
 results:
-- name: example key value
+- metadata:
+    Microsoft.DSC:
+      duration: PT0.2234078S
+  name: example key value
   type: Microsoft.Windows/Registry
   result:
     desiredState:
-      valueData:
-        String: This is an example.
       keyPath: HKCU\example\key
       valueName: Example
+      valueData:
+        String: This is an example.
     actualState:
-      $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-      keyPath: ''
-      _inDesiredState: false
+      keyPath: HKCU\example\key
+      _exist: false
     inDesiredState: false
     differingProperties:
-    - valueData
-    - keyPath
     - valueName
+    - valueData
+    - _exist
 messages: []
 hadErrors: false
 ```
@@ -163,42 +194,56 @@ their desired state. The result for each instance includes:
 - The state of the instance after the operation.
 - Which properties the operation changed, if any.
 
-DSC also collects any message emitted by the resources during the operation and indicates whether
-any of the resources raised an error.
+DSC also collects any message emitted by the resources during the operation, indicates whether any
+of the resources raised an error, and provides metadata about the operation as a whole and for each
+resource instance.
 
 ```sh
-cat ./example.config.dsc.yaml | dsc config set
+dsc config set --file ./example.config.dsc.yaml
 ```
 
 ```yaml
+metadata:
+  Microsoft.DSC:
+    version: 3.0.0
+    operation: set
+    executionType: actual
+    startDatetime: 2025-02-24T16:13:32.746742600-06:00
+    endDatetime: 2025-02-24T16:13:33.606785-06:00
+    duration: PT0.8600424S
+    securityContext: restricted
 results:
-- name: example key value
+- metadata:
+    Microsoft.DSC:
+      duration: PT0.4070001S
+  name: example key value
   type: Microsoft.Windows/Registry
   result:
     beforeState:
-      $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
-      keyPath: ''
+      keyPath: HKCU\example\key
+      _exist: false
     afterState:
-      $id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
       keyPath: HKCU\example\key
       valueName: Example
       valueData:
         String: This is an example.
     changedProperties:
-    - keyPath
     - valueName
     - valueData
+    - _exist
 messages: []
 hadErrors: false
 ```
 
 ## See also
 
 - [DSC Resources][01] to learn about resources.
-- [DSC Configuration document schema reference][03]
-- [Command line reference for the 'dsc config' command][04]
+- [DSC Configuration document schema reference][05]
+- [Command line reference for the 'dsc config' command][06]
 
 [01]: ./resources.md
-[02]: ./resources.md#resource-type-names
+[02]: ../reference/schemas/config/metadata.md#microsoftdsc
 [03]: ../reference/schemas/config/document.md
-[04]: ../reference/cli/config/command.md
+[04]: ./resources.md#resource-type-names
+[05]: ../reference/schemas/config/document.md
+[06]: ../reference/cli/config/command.md

dsc/docs-conceptual/dsc-3.0/concepts/configurations.md

@@ -3,16 +3,16 @@ description: >-
   DSC configuration documents and resource manifests are YAML or JSON data files that adhere to a
   published JSON schema. You can use enhanced schemas when authoring these files for an improved
   experience.
-ms.date: 09/13/2023
+ms.date: 03/04/2025
 title:   Authoring with enhanced schemas
 ---
 
 # Authoring with enhanced schemas
 
 Working with Microsoft's Desired State Configuration (DSC) platform involves writing DSC
 [configuration documents][01] and [resource manifests][02]. Configuration documents are YAML or
-JSON data files that declare the desired state of a system. Resource manifests are JSON data files
-that define a command-based DSC Resource.
+JSON data files that declare the desired state of a system. Resource manifests are JSON or YAML
+data files that define a DSC command resource.
 
 DSC validates these data files with a JSON schema. While the schemas DSC uses for validation are
 useful for authoring configuration documents and resource manifests, Microsoft also defines a set
@@ -25,14 +25,21 @@ specific to VS Code that:
 - Add default snippets to autocomplete values.
 
 > [!NOTE]
-> The enhanced schemas are non-canonical. Never specify them for the `$schema` keyword in a
-> configuration document or resource manifest. These schemas are only for improving the authoring
-> experience.
+> The enhanced schemas are non-canonical. Only specify them for the `$schema` keyword in a
+> configuration document or resource manifest when your tools support it.
+>
+> These schemas are only for improving the authoring experience. If you try to validate the
+> configuration document or resource manifest with a tool that doesn't support the extended
+> vocabulary, the tool may raise an error.
 >
 > The enhanced schemas share the same source definition as the canonical schemas and validate the
 > data in the same way. However, they include non-canonical keywords. For maximum compatibility
 > with other tools, the canonical schemas only use the core JSON schema vocabularies.
 
+For the full list of recognized and supported schema URIs, including the enhanced authoring
+schemas, see the `$schema` sections in [DSC Configuration document schema reference][03] and
+[DSC resource manifest schema reference][04].
+
 ## Enhanced schema examples
 
 ### Example 1 - Documentation on hover
@@ -113,11 +120,11 @@ specific workspace.
             "**/*.dsc.json",
             "**/*.dsc.config.json"
         ],
-        "url": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json"
+        "url": "https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json"
     }
 ],
 "yaml.schemas": {
-    "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json": "**.dsc.{yaml,yml,config.yaml,config.yml}"
+    "https://aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json": "**.dsc.{yaml,yml,config.yaml,config.yml}"
 }
 ```
 <!-- markdownlint-enable MD013 -->
@@ -133,11 +140,11 @@ following suffixes:
 - `.dsc.yml`
 
 To associate a specific configuration document formatted as YAML with the enhanced schema, add the
-following comment to the top of the configuration document:
+following comment to the top of the document:
 
 <!-- markdownlint-disable MD013 -->
 ```yml
-# yaml-language-server: $schema=https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json
+# yaml-language-server: $schema=aka.ms/dsc/schemas/v3/bundled/config/document.vscode.json
 ```
 <!-- markdownlint-enable MD013 -->
 
@@ -155,12 +162,30 @@ specific workspace.
 ```json
 "json.schemas": [
     {
-        "fileMatch": ["**/*.dsc.resource.json"],
-        "url": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json"
+        "fileMatch": ["**/*.dsc.resource.json", ],
+        "url": "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json"
     }
 ]
+"yaml.schemas": {
+    "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json": "**.dsc.resource.{yaml,yml}"
+}
 ```
 <!-- markdownlint-enable MD013 -->
 
+To associate a specific resource manifest formatted as YAML with the enhanced schema, add the
+following comment to the top of the manifest:
+
+<!-- markdownlint-disable MD013 -->
+```yml
+# yaml-language-server: $schema=https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.vscode.json
+```
+<!-- markdownlint-enable MD013 -->
+
+This option works regardless of the filename, but only for YAML files. To use the enhanced schema
+when authoring resource manifests in JSON, you must define the schema association in your
+`settings.json`.
+
 [01]: configurations.md
 [02]: ../resources/concepts/anatomy.md#dsc-resource-manifests
+[03]: ../reference/schemas/config/document.md#schema
+[04]: ../reference/schemas/resource/manifest/root.md#schema