(GH-642) Add schemas module, update for schema handling in v3

michaeltlombardi · michaeltlombardi · commit 498eb6ac304b · 2025-02-25T13:35:18.000-06:00
This commit only touches the `dsc` and `dsc_lib` crates. A future
commit will update the examples, manifests, and tests throughout
the repository for the updated schema URIs. Tests against this
commit specifically will not pass, but the changes to the library
are broken out here for easier review.

This change defines a new module in the library for interacting
with and managing JSON Schemas for DSC. The code in this module
is made public for use in other repository crates, but shouldn't
be used by crates outside of this repository.

It defines new enumerations:

- `SchemaUriPrefix` for handling URIs pointing to either the GitHub repository
  or friendly `aka.ms` locations.
- `SchemaForm` for the different forms the DSC schemas are published to (canonical,
  bundled, and enhanced for VS Code)
- `RecognizedSchemaVersion` for managing the version folders schemas
  are publsihed to for and after GA.

It defines a few helper functions for constructing the various URIs for a
schema. These helper functions may be useful for testing, but should
primarily be used through the new `DscRepoSchema` trait, which requires
a type to define the base name and folder path for its schema and whether
the schema should be published in its bundled form (only applies to top-level
schemas, not subschemas).

The trait provides default implementations for retrieving the schema URIs and
a function to return a generated JSON Schema for the `$schema` keyword, used
by both configuration documents and resource manifests.

As we canonicalize and improve the schemas, this trait should make it simpler
to manage the schemas across new versions and should be the container for
JSON Schema enhancements specific to the DSC schemas.

This change updates the configuration document and resource manifest definitions
to implement the `DscRepoSchema` trait and replaces the per-type enumerations
for schema version URIs by passing the `recognized_schema_uris_subschema` to
the schemars `schema_with` attribute.
diff --git a/dsc_lib/locales/en-us.toml b/dsc_lib/locales/en-us.toml
@@ -1,5 +1,9 @@
 _version = 1
 
+[configure.config_doc]
+configurationDocumentSchemaTitle = "Configuration document schema URI"
+configurationDocumentSchemaDescription = "Defines the JSON Schema the configuration document adheres to."
+
 [configure.constraints]
 minLengthIsNull = "Parameter '%{name}' has minimum length constraint but is null"
 notMinLength = "Parameter '%{name}' has minimum length constraint of %{min_length} but is %{length}"
@@ -144,6 +148,10 @@ diffKeyNotObject = "diff: key '%{key}' is not an object"
 diffArraySize = "diff: arrays have different lengths"
 diffMissingItem = "diff: actual array missing expected item"
 
+[dscresources.resource_manifest]
+resourceManifestSchemaTitle = "Resource manifest schema URI"
+resourceManifestSchemaDescription = "Defines the JSON Schema the resource manifest adheres to."
+
 [functions]
 invalidArgType = "Invalid argument type"
 invalidArguments = "Invalid argument(s)"
diff --git a/dsc_lib/src/configure/config_doc.rs b/dsc_lib/src/configure/config_doc.rs
@@ -1,10 +1,13 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+use rust_i18n::t;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value};
-use std::{collections::HashMap, hash::Hash};
+use std::collections::HashMap;
+
+use crate::schemas::DscRepoSchema;
 
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[serde(rename_all = "camelCase")]
@@ -75,7 +78,8 @@ pub struct Metadata {
 #[serde(deny_unknown_fields)]
 pub struct Configuration {
     #[serde(rename = "$schema")]
-    pub schema: DocumentSchemaUri,
+    #[schemars(schema_with = "Configuration::recognized_schema_uris_subschema")]
+    pub schema: String,
     #[serde(rename = "contentVersion")]
     pub content_version: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -143,41 +147,31 @@ pub struct Resource {
     pub metadata: Option<HashMap<String, Value>>,
 }
 
-// Defines the valid and recognized canonical URIs for the configuration schema
-#[derive(Debug, Default, Clone, Copy, Hash, Eq, PartialEq, Deserialize, Serialize, JsonSchema)]
-pub enum DocumentSchemaUri {
-    #[default]
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json")]
-    Version2024_04,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json")]
-    Bundled2024_04,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json")]
-    VSCode2024_04,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json")]
-    Version2023_10,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.json")]
-    Bundled2023_10,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.vscode.json")]
-    VSCode2023_10,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json")]
-    Version2023_08,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.json")]
-    Bundled2023_08,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json")]
-    VSCode2023_08,
-}
-
 impl Default for Configuration {
     fn default() -> Self {
         Self::new()
     }
 }
 
+impl DscRepoSchema for Configuration {
+    const SCHEMA_FILE_BASE_NAME: &'static str = "document";
+    const SCHEMA_FOLDER_PATH: &'static str = "config";
+    const SCHEMA_SHOULD_BUNDLE: bool = true;
+
+    fn schema_metadata() -> schemars::schema::Metadata {
+        schemars::schema::Metadata {
+            title: Some(t!("configure.config_doc.configurationDocumentSchemaTitle").into()),
+            description: Some(t!("configure.config_doc.configurationDocumentSchemaDescription").into()),
+            ..Default::default()
+        }
+    }
+}
+
 impl Configuration {
     #[must_use]
     pub fn new() -> Self {
         Self {
-            schema: DocumentSchemaUri::Version2024_04,
+            schema: Self::default_schema_id_uri(),
             content_version: Some("1.0.0".to_string()),
             parameters: None,
             variables: None,
diff --git a/dsc_lib/src/configure/depends_on.rs b/dsc_lib/src/configure/depends_on.rs
@@ -108,7 +108,7 @@ mod tests {
     #[test]
     fn test_simple_order() {
         let config_yaml: &str = r#"
-        $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: Second
           type: Test/Null
@@ -128,7 +128,7 @@ mod tests {
     #[test]
     fn test_duplicate_name() {
         let config_yaml: &str = r#"
-        $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: First
           type: Test/Null
@@ -149,7 +149,7 @@ mod tests {
     #[test]
     fn test_missing_dependency() {
         let config_yaml: &str = r#"
-        $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: Second
           type: Test/Null
@@ -166,7 +166,7 @@ mod tests {
     #[test]
     fn test_multiple_same_dependency() {
         let config_yaml: &str = r#"
-        $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: Second
           type: Test/Null
@@ -191,7 +191,7 @@ mod tests {
     #[test]
     fn test_circular_dependency() {
         let config_yaml: &str = r#"
-        $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: Second
           type: Test/Null
@@ -212,7 +212,7 @@ mod tests {
     #[test]
     fn test_multiple_dependencies() {
         let config_yaml: &str = r#"
-        $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: Third
           type: Test/Null
@@ -236,7 +236,7 @@ mod tests {
     #[test]
     fn test_complex_circular_dependency() {
         let config_yaml: &str = r#"
-        $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: Third
           type: Test/Null
@@ -262,7 +262,7 @@ mod tests {
     #[test]
     fn test_complex_dependency() {
         let config_yaml: &str = r#"
-        $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: Third
           type: Test/Null
diff --git a/dsc_lib/src/dscresources/resource_manifest.rs b/dsc_lib/src/dscresources/resource_manifest.rs
@@ -1,13 +1,14 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+use rust_i18n::t;
 use schemars::JsonSchema;
 use semver::Version;
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use std::collections::HashMap;
 
-use crate::dscerror::DscError;
+use crate::{dscerror::DscError, schemas::DscRepoSchema};
 
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[serde(rename_all = "camelCase")]
@@ -23,7 +24,8 @@ pub enum Kind {
 pub struct ResourceManifest {
     /// The version of the resource manifest schema.
     #[serde(rename = "$schema")]
-    pub schema_version: ManifestSchemaUri,
+    #[schemars(schema_with = "ResourceManifest::recognized_schema_uris_subschema")]
+    pub schema_version: String,
     /// The namespaced name of the resource.
     #[serde(rename = "type")]
     pub resource_type: String,
@@ -70,30 +72,6 @@ pub struct ResourceManifest {
     pub schema: Option<SchemaKind>,
 }
 
-// Defines the valid and recognized canonical URIs for the manifest schema
-#[derive(Debug, Default, Clone, Copy, Hash, Eq, PartialEq, Deserialize, Serialize, JsonSchema)]
-pub enum ManifestSchemaUri {
-    #[default]
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json")]
-    Version2024_04,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json")]
-    Bundled2024_04,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json")]
-    VSCode2024_04,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json")]
-    Version2023_10,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json")]
-    Bundled2023_10,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json")]
-    VSCode2023_10,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json")]
-    Version2023_08,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json")]
-    Bundled2023_08,
-    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json")]
-    VSCode2023_08,
-}
-
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[serde(untagged)]
 pub enum ArgKind {
@@ -256,6 +234,20 @@ pub struct ListMethod {
     pub args: Option<Vec<String>>,
 }
 
+impl DscRepoSchema for ResourceManifest {
+    const SCHEMA_FILE_BASE_NAME: &'static str = "manifest";
+    const SCHEMA_FOLDER_PATH: &'static str = "resource";
+    const SCHEMA_SHOULD_BUNDLE: bool = true;
+
+    fn schema_metadata() -> schemars::schema::Metadata {
+        schemars::schema::Metadata {
+            title: Some(t!("dscresources.resource_manifest.resourceManifestSchemaTitle").into()),
+            description: Some(t!("dscresources.resource_manifest.resourceManifestSchemaDescription").into()),
+            ..Default::default()
+        }
+    }
+}
+
 /// Import a resource manifest from a JSON value.
 ///
 /// # Arguments
diff --git a/dsc_lib/src/lib.rs b/dsc_lib/src/lib.rs
@@ -16,6 +16,7 @@ pub mod functions;
 pub mod parser;
 pub mod progress;
 pub mod util;
+pub mod schemas;
 
 i18n!("locales", fallback = "en-us");
 
diff --git a/dsc_lib/src/schemas/mod.rs b/dsc_lib/src/schemas/mod.rs
