Merge pull request #648 from michaeltlombardi/gh-642/main/schema-casing-canonicalization

(GH-642) Ensure camelCase for items in `dsc_lib`

Author: SteveL-MSFT

.github/ISSUE_TEMPLATE/Bug_Report.yml

@@ -35,7 +35,7 @@ body:
 
          ```yaml
          # repro.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: repro
            type: Test/Echo

.vscode/docs.code-snippets

@@ -42,7 +42,7 @@
 			"",
 			"```yaml",
 			"# ${1:name}.example.1.dsc.config.yaml",
-			"\\$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json",
+			"\\$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json",
 			"resources:",
 			"- name: ${7:descriptive resource name}",
 			"  type: Test/Echo",
@@ -101,7 +101,7 @@
 			"",
 			"```yaml",
 			"# $TM_FILENAME_BASE.example.$1.dsc.config.yaml",
-			"\\$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json",
+			"\\$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json",
 			"resources:",
 			"- name: ${4:descriptive resource name}",
 			"  type: Test/Echo",

archive/registry/registry.dsc.resource.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json",
+  "$schema": "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json",
   "type": "Microsoft.Windows/Registry",
   "description": "Manage Windows Registry keys and values",
   "tags": [

configurations/windows/windows_baseline.dsc.yaml

@@ -1,13 +1,13 @@
 # This configuration validates a Windows system against a security baseline configuration
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
 metadata:
   Microsoft.DSC:
-    securityContext: Elevated
+    securityContext: elevated
 resources:
 - name: Validate the OS is Windows
   type: Microsoft.DSC/Assertion
   properties:
-    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
     resources:
     - name: os
       type: Microsoft/OSInfo
@@ -18,7 +18,7 @@ resources:
   dependsOn: 
     - "[resourceId('Microsoft.DSC/Assertion','Validate the OS is Windows')]"
   properties:
-    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
     resources:
       - name: Default RDP port
         type: Microsoft.Windows/Registry

configurations/windows/windows_inventory.dsc.yaml

@@ -1,9 +1,9 @@
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
 resources:
 - name: Validate the OS is Windows
   type: Microsoft.DSC/Assertion
   properties:
-    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
     resources:
     - name: os
       type: Microsoft/OSInfo

docs/reference/cli/config/get.md

@@ -1,6 +1,6 @@
 ---
 description: Command line reference for the 'dsc config get' command
-ms.date:     06/24/2024
+ms.date:     02/28/2025
 ms.topic:    reference
 title:       dsc config get
 ---
@@ -49,12 +49,12 @@ document saved as `example.dsc.config.yaml`.
 
 ```yaml
 # example.dsc.config.yaml
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
 resources:
 - name: Windows only
   type: Microsoft.DSC/Assertion
   properties:
-    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
     resources:
     - name: os
       type: Microsoft/OSInfo

docs/reference/cli/config/set.md

@@ -1,6 +1,6 @@
 ---
 description: Command line reference for the 'dsc config set' command
-ms.date:     06/24/2024
+ms.date:     02/28/2025
 ms.topic:    reference
 title:       dsc config set
 ---
@@ -50,12 +50,12 @@ The command inspects the resource instances defined in the configuration documen
 
 ```yaml
 # example.dsc.config.yaml
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
 resources:
 - name: Windows only
   type: Microsoft.DSC/Assertion
   properties:
-    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
     resources:
     - name: os
       type: Microsoft/OSInfo

docs/reference/cli/config/test.md

@@ -1,6 +1,6 @@
 ---
 description: Command line reference for the 'dsc config test' command
-ms.date:     06/24/2024
+ms.date:     02/28/2025
 ms.topic:    reference
 title:       dsc config test
 ---
@@ -49,12 +49,12 @@ resource instances defined in the configuration document saved as `example.dsc.c
 
 ```yaml
 # example.dsc.config.yaml
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
 resources:
 - name: Windows only
   type: Microsoft.DSC/Assertion
   properties:
-    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
     resources:
     - name: os
       type: Microsoft/OSInfo

docs/reference/cli/resource/list.md

@@ -1,6 +1,6 @@
 ---
 description: Command line reference for the 'dsc resource list' command
-ms.date:     06/24/2024
+ms.date:     02/28/2025
 ms.topic:    reference
 title:       dsc resource list
 ---
@@ -309,24 +309,24 @@ a summary table for the returned resources. The summary table includes the follo
 displayed in the listed order:
 
 - **Type** - The fully qualified type name of the resource.
-- **Kind** - Whether the resource is an `Adapter`, `Group`, or typical `Resource`. For more
-  information, see [DSC Resource kind schema reference][03].
+- **Kind** - Whether the resource is an `adapter`, `group`, `importer`, or typical `Resource`. For
+  more information, see [DSC Resource kind schema reference][03].
 - **Version** - The semantic version of the resource.
 - **Caps** - A display of the resource's [capabilities][04] as flags. The capabilities are
   displayed in the following order, using a `-` instead of the appropriate letter if the resource
   doesn't have a specific capability:
 
-  - `g` indicates that the resource has the [Get capability][05].
-  - `s` indicates that the resource has the [Set capability][06]
-  - `x` indicates that the resource has the [SetHandlesExist capability][07]
-  - `w` indicates that the resource has the [WhatIf capability][08]
-  - `t` indicates that the resource has the [Test capability][09]
-  - `d` indicates that the resource has the [Delete capability][10]
-  - `e` indicates that the resource has the [Export capability][11]
-  - `r` indicates that the resource has the [Resolve capability][12]
+  - `g` indicates that the resource has the [get capability][05].
+  - `s` indicates that the resource has the [set capability][06]
+  - `x` indicates that the resource has the [setHandlesExist capability][07]
+  - `w` indicates that the resource has the [whatIf capability][08]
+  - `t` indicates that the resource has the [test capability][09]
+  - `d` indicates that the resource has the [delete capability][10]
+  - `e` indicates that the resource has the [export capability][11]
+  - `r` indicates that the resource has the [resolve capability][12]
 
   For example, the `Microsoft.Windows/Registry` resource has the following capabilities: `gs--d-`,
-  indicating it has the `Get`, `Set`, and `Delete` capabilities.
+  indicating it has the `get`, `set`, and `delete` capabilities.
 - **RequireAdapter** - The fully qualified type name of the adapter resource that DSC uses to
   invoke the returned resource.
 - **Description** - The short description of the resource's purpose and usage.

docs/reference/cli/schema/command.md

@@ -1,6 +1,6 @@
 ---
 description: Command line reference for the 'dsc schema' command
-ms.date:     06/24/2024
+ms.date:     02/28/2025
 ms.topic:    reference
 title:       dsc schema
 ---
@@ -26,6 +26,22 @@ integrating tool.
 The application uses these schemas to validate data internally when it's received or represent the
 output for one of the application's commands.
 
+> [!NOTE]
+> Currently, the schemas returned by the `dsc schema` command and those published to GitHub are
+> not the same. The published schemas more fully describe and validate the data than the schemas
+> emitted by the command. The DSC team is working to canonicalize the schemas returned from the
+> command.
+>
+> Both the published schemas and those returned from this command correctly validate the data. The
+> schemas returned from this command are less strict than the published schemas. Even though data
+> validates against the schemas returned by this command, DSC may raise errors when processing the
+> data. For example, the returned schema for versions indicates that the valid value is a string -
+> but if you specify a string that isn't a semantic version, DSC raises an error. In that case, the
+> data passed the schema validation but was incorrect.
+>
+> Until the schemas are canonicalized, consider using the published schemas when indpendently
+> testing your configuration documents and resource manifests with a JSON Schema validation tool.
+
 ## Examples
 
 ### Example 1 - Retrieve the schema for the dsc resource get command result

docs/reference/schemas/config/document.md

@@ -1,6 +1,6 @@
 ---
 description: JSON schema reference for a Desired State Configuration document.
-ms.date:     01/17/2024
+ms.date:     02/28/2025
 ms.topic:    reference
 title:       DSC Configuration document schema reference
 ---
@@ -15,7 +15,7 @@ The YAML or JSON file that defines a DSC Configuration.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.json
 Type:          object
 ```
 
@@ -29,7 +29,14 @@ A configuration document can be defined as either YAML or JSON. For ease of auth
 recommends drafting configuration documents in YAML.
 
 For DSC's authoring tools to recognize a file as a DSC Configuration document, the filename must
-end with `.dsc.config.json`, `.dsc.config.yml`, or `.dsc.config.yaml`.
+end with one of the following:
+
+- `.dsc.config.json`
+- `.dsc.config.yml`
+- `.dsc.config.yaml`.
+- `.dsc.json`
+- `.dsc.yml`
+- `.dsc.yaml`
 
 You can use configuration document functions to dynamically determine values in the document at
 runtime. For more information, see [DSC Configuration document functions reference][01]
@@ -46,29 +53,23 @@ The rest of this document describes the schema DSC uses to validation configurat
 
 Every configuration document must include these properties:
 
-- [$schema]
-- [resources]
+- [$schema](#schema)
+- [resources](#resources)
 
 ## Properties
 
 ### $schema
 
-The `$schema` property indicates the canonical URL for the version of this schema that the document
-adheres to. DSC uses this property when validating the configuration document before any
-configuration operations.
-
-There are currently 3 published versions of the schema, compatible with different versions of DSC:
-
-- `2024/04` is the latest version of the schema, compatible with DSC version 3.0.0-preview.7 and
-  later.
-- `2023/10` is the previous version of the schema, compatible with DSC versions `3.0.0-alpha.4` and
-  `3.0.0-alpha.5`.
-- `2023/08` is the first version of the schema, compatible with DSC versions `3.0.0-alpha.1` through
-  `3.0.0-alpha.3`.
+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.
 
-This documentation is for the latest version of the schema. You should update your configuration
-documents and resource manifests to the latest version of the schema. Prior versions don't work
-with new releases of DSC. The schemas remain published, but won't get any updates.
+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](../schema-uris.md).
 
 For every version of the schema, there are three valid urls:
 
@@ -79,12 +80,12 @@ For every version of the schema, there are three valid urls:
 
 - `.../bundled/config/document.json`
 
-  The URL to the bundled schema. When it's used for validation, the validating client only needs to
-  retrieve this schema.
+  The URL to the canonically 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.
+  ways if they don't fully support the 2020-12 specification.
 
 - `.../bundled/config/document.vscode.json`
 
@@ -100,15 +101,24 @@ Type:        string
 Required:    true
 Format:      URI
 ValidValues: [
-               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
-               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json
-               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json
-               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
-               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.json
-               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.vscode.json
-               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
-               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.json
-               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json
+               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
              ]
 ```
 
@@ -142,7 +152,7 @@ For more information about defining parameters in a configuration, see
 ```yaml
 Type:                object
 Required:            false
-ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json
+ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.parameter.json
 ```
 
 ### variables
@@ -178,7 +188,7 @@ For more information about defining a valid resource instance in a configuration
 Type:             array
 Required:         true
 MinimumItemCount: 1
-ValidItemSchema:  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json
+ValidItemSchema:  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.0.0/config/document.resource.json
 ```
 
 <!-- Link reference definitions -->

docs/reference/schemas/config/functions/add.md

@@ -1,6 +1,6 @@
 ---
 description: Reference for the 'add' DSC configuration document function
-ms.date:     03/19/2024
+ms.date:     02/28/2025
 ms.topic:    reference
 title:       add
 ---
@@ -30,7 +30,7 @@ This example document shows how you can use the `add()` function to return the s
 
 ```yaml
 # add.example.1.dsc.config.yaml
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
 resources:
 - name: Sum of 3 and 5
   type: Test/Echo
@@ -60,7 +60,7 @@ configuration functions that return integer values.
 
 ```yaml
 # add.example.2.dsc.config.yaml
-$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json
+$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
 resources:
 - name: Add nested function outputs
   type: Test/Echo