Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the $schema URIs for manifests to 2023/10 #224

Closed
michaeltlombardi opened this issue Oct 9, 2023 · 0 comments · Fixed by #238
Closed

Update the $schema URIs for manifests to 2023/10 #224

michaeltlombardi opened this issue Oct 9, 2023 · 0 comments · Fixed by #238
Labels
Issue-Enhancement The issue is a feature or idea

Comments

@michaeltlombardi
Copy link
Collaborator

Summary of the new feature / enhancement

In the most recent set of unreleased changes, we have backwards-incompatible updates to the schemas. We have so far been updating the schemas in place during early development, but we will need to update the schemas in a more graceful way eventually.

We should practice doing so now while the impact is minimal to figure out a workflow and practice that suits our needs so that when many users and integrating developers are depending on the schemas, they can do so with confidence.

Proposed technical implementation details (optional)

We should update the schema constants for configuration documents and resource manifests from string constants to enum values:

const SCHEMA: &str = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json";

const MANIFEST_SCHEMA_VERSION: &str = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json";

This is pseudocode, since I'm not quite familiar with Rust yet, but something like:

#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
pub enum SchemaUri {
    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json")]
    Version2023_10 = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json",
    #[serde(rename = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json")]
    Version2023_08 = "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json",
}

To allow users to specify a valid schema. We should begin considering whether/how to address schema changes between versions, but I don't think we need any specific handling at this time.

@michaeltlombardi michaeltlombardi added the Issue-Enhancement The issue is a feature or idea label Oct 9, 2023
michaeltlombardi added a commit to michaeltlombardi/DSC that referenced this issue Oct 18, 2023
This change converts the string constants for the canonical schema URIs
for both the configuration document and resource manifest schemas to
enums, defining the valid URIs as variants.

For each supported version of a schema, there are three variants:

1. `Version<YYYY>_<MM>` - The canonical URI to the non-bundled schema.
    Using this schema requires retrieving every referenced schema, but
    it is also the least-munged.
1. `Bundled<YYYY>_<MM>` - The canonical URI to the bundled schema. When
   using this schema, only the bundled schema needs to be retrieved.
1. `VSCode<YYYY>_<MM>` - The canonical URI to the enhanced authoring
   schema. This schema is specifically implemented to support contextual
   help and DevX when authoring in VS Code. It is much larger than the
   other schemas.

Which gives six variants:

- `Version2023_08`, `Bundled2023_08`, and `VSCode2023_08` for 2023/08
- `Version2023_10`, `Bundled2023_10`, and `VSCode2023_10` for 2023/10

Currently, the specified schema is not actually used by DSC to validate
the document or manifest. In the future, we could use the version to
identify how to validate and process the data.
michaeltlombardi added a commit to michaeltlombardi/DSC that referenced this issue Oct 20, 2023
This change converts the string constants for the canonical schema URIs
for both the configuration document and resource manifest schemas to
enums, defining the valid URIs as variants.

For each supported version of a schema, there are three variants:

1. `Version<YYYY>_<MM>` - The canonical URI to the non-bundled schema.
    Using this schema requires retrieving every referenced schema, but
    it is also the least-munged.
1. `Bundled<YYYY>_<MM>` - The canonical URI to the bundled schema. When
   using this schema, only the bundled schema needs to be retrieved.
1. `VSCode<YYYY>_<MM>` - The canonical URI to the enhanced authoring
   schema. This schema is specifically implemented to support contextual
   help and DevX when authoring in VS Code. It is much larger than the
   other schemas.

Which gives six variants:

- `Version2023_08`, `Bundled2023_08`, and `VSCode2023_08` for 2023/08
- `Version2023_10`, `Bundled2023_10`, and `VSCode2023_10` for 2023/10

Currently, the specified schema is not actually used by DSC to validate
the document or manifest. In the future, we could use the version to
identify how to validate and process the data.
michaeltlombardi added a commit to michaeltlombardi/DSC that referenced this issue Oct 20, 2023
michaeltlombardi added a commit to michaeltlombardi/DSC that referenced this issue Oct 20, 2023
michaeltlombardi added a commit to michaeltlombardi/DSC that referenced this issue Oct 20, 2023
michaeltlombardi added a commit to michaeltlombardi/DSC that referenced this issue Oct 20, 2023
github-merge-queue bot pushed a commit that referenced this issue Oct 24, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Issue-Enhancement The issue is a feature or idea
Projects
Status: Done
Development

Successfully merging a pull request may close this issue.

1 participant