(SCHEMA) Update schemas for the provider->adapter rename

This change updates the source schemas to account for renaming DSC Resource Providers to DSC Resource Adapters in PowerShell#334. This is a breaking schema change that requires a new canonical URI, so the change also adds new schema URIs to DSC to account for the changes. The regenerated schemas will be added in the next commit.
michaeltlombardi · Apr 18, 2024 · de33b4e · de33b4e
1 parent d75cc5c
commit de33b4e
Show file tree

Hide file tree

Showing 8 changed files with 165 additions and 40 deletions.
diff --git a/dsc_lib/src/configure/config_doc.rs b/dsc_lib/src/configure/config_doc.rs
@@ -142,6 +142,12 @@ pub struct Resource {
 #[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")]
@@ -159,7 +165,7 @@ pub enum DocumentSchemaUri {
 impl Default for Configuration {
     fn default() -> Self {
         Self {
-            schema: DocumentSchemaUri::Version2023_08,
+            schema: DocumentSchemaUri::Version2024_04,
             parameters: None,
             variables: None,
             resources: Vec::new(),
@@ -172,7 +178,7 @@ impl Configuration {
     #[must_use]
     pub fn new() -> Self {
         Self {
-            schema: DocumentSchemaUri::Version2023_08,
+            schema: DocumentSchemaUri::Version2024_04,
             parameters: None,
             variables: None,
             resources: Vec::new(),

diff --git a/dsc_lib/src/dscresources/resource_manifest.rs b/dsc_lib/src/dscresources/resource_manifest.rs
@@ -66,6 +66,12 @@ pub struct ResourceManifest {
 #[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")]

diff --git a/schemas/build.ps1 b/schemas/build.ps1
@@ -3,6 +3,12 @@ using namespace System.Collections
 
 <#
     .SYNOPSIS
+        Build the DSC schema files from the source YAML files.
+    
+    .DESCRIPTION
+        This build script composes the JSON Schema files from the source YAML files, creating new
+        files in the specified output directory. It creates a schema registry to analyze the source
+        schemas and resolve references for bundling.
 #>
 
 [cmdletbinding(DefaultParameterSetName='ByConfig')]

diff --git a/schemas/schemas.config.yaml b/schemas/schemas.config.yaml
@@ -1,6 +1,6 @@
 host:             https://raw.githubusercontent.com
 prefix:           PowerShell/DSC/main/schemas
-version:          2023/10
+version:          2024/04
 docs_base_url:    https://learn.microsoft.com/powershell/dsc
 docs_version_pin: view=dsc-3.0&preserve-view=true
 bundle_schemas:

diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml
@@ -34,6 +34,9 @@ properties:
       - <HOST>/<PREFIX>/<VERSION>/config/document.yaml
       - <HOST>/<PREFIX>/<VERSION>/bundled/config/document.yaml
       - <HOST>/<PREFIX>/<VERSION>/bundled/config/document.vscode.yaml
+      - <HOST>/<PREFIX>/2023/10/config/document.yaml
+      - <HOST>/<PREFIX>/2023/10/bundled/config/document.yaml
+      - <HOST>/<PREFIX>/2023/10/bundled/config/document.vscode.yaml
       - <HOST>/<PREFIX>/2023/08/config/document.yaml
       - <HOST>/<PREFIX>/2023/08/bundled/config/document.yaml
       - <HOST>/<PREFIX>/2023/08/bundled/config/document.vscode.yaml
@@ -113,6 +116,51 @@ properties:
           > This schema uses keywords that are only recognized by VS Code. While DSC can still
           > validate the document when it uses this schema, other tools may error or behave in
           > unexpected ways.
+      - | # <HOST>/<PREFIX>/2023/10/config/document.yaml
+          <!-- force a line break -->
+
+          > #### `2023/10` non-bundled
+          >
+          > Indicates that the configuration document adheres to the `2023/10` schema. This version
+          > is deprecated, and should only be used for compatibility with `alpha.5` and earlier.
+          > Migrate to using the `<VERSION>` of the schema 
+          >
+          > This URL points to the canonical non-bundled schema. When it's used for validation, the
+          > validating client needs to retrieve this schema and every schema it references.
+
+      - | # <HOST>/<PREFIX>/2023/10/bundled/config/document.yaml
+          <!-- force a line break -->
+
+          > #### `2023/10` bundled
+          >
+          > Indicates that the configuration document adheres to the `2023/10` schema. This version
+          > is deprecated, and should only be used for compatibility with `alpha.5` and earlier.
+          > Migrate to using the `<VERSION>` of the schema 
+          >
+          > This URL points to the 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.
+      - | # <HOST>/<PREFIX>/2023/10/bundled/config/document.vscode.yaml
+          <!-- force a line break -->
+
+          > #### `2023/10` enhanced authoring
+          >
+          > Indicates that the configuration document adheres to the `2023/10` schema. This version
+          > is deprecated, and should only be used for compatibility with `alpha.5` and earlier.
+          > Migrate to using the `<VERSION>` of the schema 
+          >
+          > This URL points to the enhanced authoring schema. This schema is much larger than the
+          > other schemas, as it includes additional definitions that provide contextual help and
+          > snippets that the others don't include.
+          >
+          > This schema uses keywords that are only recognized by VS Code. While DSC can still
+          > validate the document when it uses this schema, other tools may error or behave in
+          > unexpected ways.
+
+# Old Schema
       - | # <HOST>/<PREFIX>/2023/08/config/document.yaml
           <!-- force a line break -->
 
@@ -130,9 +178,12 @@ properties:
 
           > #### `2023/08` bundled
           >
-          > Indicates that the configuration document adheres to the `2023/08` schema. This URL
-          > points to the bundled schema. When it's used for validation, the validating client
-          > only needs to retrieve this schema.
+          > Indicates that the configuration document adheres to the `2023/08` schema. This version
+          > is deprecated, and should only be used for compatibility with `alpha.3` and earlier.
+          > Migrate to using the `<VERSION>` of the schema 
+          >
+          > This URL points to the 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
@@ -142,9 +193,12 @@ properties:
 
           > #### `2023/08` enhanced authoring
           >
-          > Indicates that the configuration document adheres to the `2023/08` schema. This URL
-          > points to the enhanced authoring schema. This schema is much larger than the other
-          > schemas, as it includes additional definitions that provide contextual help and
+          > Indicates that the configuration document adheres to the `2023/08` schema. This version
+          > is deprecated, and should only be used for compatibility with `alpha.3` and earlier.
+          > Migrate to using the `<VERSION>` of the schema 
+          >
+          > This URL points to the enhanced authoring schema. This schema is much larger than the
+          > other schemas, as it includes additional definitions that provide contextual help and
           > snippets that the others don't include.
           >
           > This schema uses keywords that are only recognized by VS Code. While DSC can still

diff --git a/schemas/src/outputs/resource/list.yaml b/schemas/src/outputs/resource/list.yaml
@@ -82,9 +82,9 @@ properties:
       type: string
       pattern: ^\w+$
   requires:
-    title: Required DSC Resource Provider
+    title: Required DSC Resource Adapter
     description: >-
-      Defines the fully qualified type name of the DSC Resource Provider the
+      Defines the fully qualified type name of the DSC Resource Adapter the
       DSC Resource depends on.
     oneOf:
       - $ref: /<PREFIX>/<VERSION>/definitions/resourceType.yaml

diff --git a/schemas/src/resource/manifest.provider.yaml → schemas/src/resource/manifest.adapter.yaml b/schemas/src/resource/manifest.provider.yaml → schemas/src/resource/manifest.adapter.yaml
@@ -1,20 +1,20 @@
 # 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/manifest.provider.yaml
+$id:     <HOST>/<PREFIX>/<VERSION>/resource/manifest.adapter.yaml
 
-title: Provider
+title: Adapter
 description: >-
-  Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to
+  Defines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter enables users to
   manage resources that don't have their own manifests with DSC.
 markdownDescription: | # VS Code only
   ***
   [_Online Documentation_][01]
   ***
 
-  Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to
+  Defines the DSC Resource as a DSC Resource Adapter. A DSC Resource Adapter enables users to
   manage resources that don't have their own manifests with DSC.
 
-  [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/provider?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/adapter?<DOCS_VERSION_PIN>
 
 type: object
 required:
@@ -24,15 +24,15 @@ properties:
   list:
     title: List Command
     description: >-
-      Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.
+      Defines how DSC must call the DSC Resource Adapter to list its supported DSC Resources.
     markdownDescription: | # VS Code only
       ***
       [_Online Documentation_][01]
       ***
 
-      Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.
+      Defines how DSC must call the DSC Resource Adapter to list its supported DSC Resources.
 
-      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/provider?<DOCS_VERSION_PIN>#list
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/adapter?<DOCS_VERSION_PIN>#list
     type: object
     required:
       - executable
@@ -49,7 +49,7 @@ properties:
           is only required when the command isn't recognizable by the operating system as an
           executable.
 
-          [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/provider?<DOCS_VERSION_PIN>#executable
+          [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/adapter?<DOCS_VERSION_PIN>#executable
       args:
         $ref: /<PREFIX>/<VERSION>/definitions/commandArgs.yaml
         markdownDescription: |
@@ -75,11 +75,11 @@ properties:
           registry resources list
           ```
 
-          [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/provider?<DOCS_VERSION_PIN>#args
+          [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/adapter?<DOCS_VERSION_PIN>#args
   config:
     title: Expected Configuration
     description: >-
-      Defines whether the provider expects to receive a full and unprocessed configuration as a
+      Defines whether the adapter expects to receive a full and unprocessed configuration as a
       single JSON blob over stdin or a sequence of JSON Lines for each child resource's
       configurations.
     type: string
@@ -92,21 +92,21 @@ properties:
       [_Online Documentation_][01]
       ***
 
-      Defines whether the provider expects to receive a full and unprocessed configuration as a
+      Defines whether the adapter expects to receive a full and unprocessed configuration as a
       single JSON blob over stdin or a sequence of JSON Lines for each child resource's
       configurations.
 
-      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/provider?<DOCS_VERSION_PIN>#config
+      [01]: <DOCS_BASE_URL>/reference/schemas/resource/manifest/adapter?<DOCS_VERSION_PIN>#config
     markdownEnumDescriptions:
       - | # full
           _Full and unprocessed config as a JSON blob_
 
-          > Indicates that the provider expects a JSON blob containing the full and unprocessed
+          > Indicates that the adapter expects a JSON blob containing the full and unprocessed
           > configuration as a single JSON blob over `stdin`.
       - | # sequence
           _Resource instances as JSON Lines_
 
-          > Indicates that the provider expects each resource's configuration as a [JSON Line][01]
+          > Indicates that the adapter expects each resource's configuration as a [JSON Line][01]
           > over `stdin`.
 
           [01]: https://jsonlines.org/
@@ -125,7 +125,7 @@ examples:
 defaultSnippets: # VS Code only
   - label: ' Define without arguments'
     markdownDescription: |
-      Define the provider config kind and `list` command for the resource when no arguments are
+      Define the adapter config kind and `list` command for the resource when no arguments are
       required.
     body:
       config: $1
@@ -134,7 +134,7 @@ defaultSnippets: # VS Code only
 
   - label: ' Define with arguments'
     markdownDescription: |
-      Define the provider config kind and `list` command for the resource when at least one
+      Define the adapter config kind and `list` command for the resource when at least one
       argument is required.
     body:
       config: $1